The GAP interface to CARAT consists of two parts, low level interface routines to CARAT functions on the one hand, and comfortable high level GAP functions on the other hand. The high level functions, implemented in terms of the low level functions, provide actually methods for functions and operations declared in the GAP library.
Note that while (almost) all CARAT functions should be accessible from within GAP by the low level interface routines, high level interface routines are provided only for a small subset of the CARAT functions. Priority has been given to routines providing functionality that has previously not been available in GAP. Further high level interface routines may be added in the future.
In crystallography, the convention usually is that matrix groups act from the left on column vectors. This convention is adopted also in CARAT. The low level interface routines described below must respect this convention and provide CARAT with data in the expected format.
On the other hand, in GAP the convention is that all groups act from the right, in the case of matrix groups on row vectors. However, in order to make GAP accessible to crystallographers, functions that are important in crystallography and for which it matters which action is assumed, are provided in two variants, one for each convention. The high level routines currently provided by this package do not depend on which convention is assumed. This may change, however, when further high level routines are added in the future.
CARAT routines read their input from one or several input files, and write the result to standard output. In order to use CARAT routines from within GAP, the input must be prepared in suitably formatted input files. A CARAT command is then executed with these input files, with standard output redirected to an output file, which is read back into GAP afterwards. This section describes routines interfacing with CARAT input and output files.
Working with CARAT requires many temporary files. When the CARAT package is loaded, a temporary directory is created, where one can put such files. The routine
CaratTmpFile( filename ) F
returns a file name filename in the CARAT temporary directory, which can be used to store temporary data. Of course, it is also possible to use any other file name, for instance files in the current directory.
CaratShowFile( filename ) F
displays the contents of any text file on the terminal. This can be used to inspect the contents of CARAT input and output files.
Most CARAT data files are in either of two formats. The first CARAT file type is the Matrix File, containing one or several matrices. The following routines serve as interface to CARAT Matrix Files.
CaratWriteMatrixFile( filename, data ) F
takes a file name and a matrix or a list of matrices, and writes the matrix or matrices to the file.
CaratReadMatrixFile( filename ) F
reads a CARAT matrix file, and returns a matrix or a list of matrices read from the file.
The second CARAT file type is the Bravais File, containing information on a finite unimodular group. In GAP, the contents of a Bravais File is represented by a Bravais record, having the following components:
generators
formspace
centerings
normalizer
centralizer
size The following routines serve as interface to CARAT Bravais Files.
CaratWriteBravaisFile( filename, data ) F
takes a file name and a Bravais record, and writes the data in the Bravais record to the file.
CaratReadBravaisFile( filename ) F
reads a Bravais File, and returns the resulting Bravais record.
Certain CARAT programs produce output files containing several Bravais records, possibly preceeded by a varying number of header lines.
CaratReadMultiBravaisFile( filename ) F
reads such a multi-Bravais file, and returns a record with the components
info and groups. info is the list of header lines before the first
Bravais record starts, and groups is the list of Bravais records read from
the file.
To execute a CARAT program from within GAP, some low level, general purpose routines are provided in this package. Higher level routines for certain CARAT functions may be available in the GAP library or in other packages. These higher level functions are expected to use the following low level routines, so that changes in the low level interface will be transparent.
An arbitrary CARAT program can be executed with the routine
CaratCommand( command, args, outfile ) F
where command is the name of a CARAT program, args is a string containing the command line arguments of the CARAT program, and outfile is the name of the file to which the output is to be written. Example:
gap> CaratCommand( "Z_equiv", "file1 file2", "file.out" );
A short description of the arguments and options of any CARAT program can be obtained from the CARAT online help facility with
CaratHelp( command ) F
where command is the name of the CARAT program. CaratHelp executes
the program with the -h option, and writes the output to the
terminal. Example:
gap> CaratHelp( "Z_equiv" );
A list of all CARAT programs, along with a description of their usage and functionality, can be found in the CARAT documentation (in HTML), in the file
documentation/introduction.html
in the CARAT home directory.
CARAT implements methods for the following functions and operations declared in the GAP library. For a detailed description of these functions, please consult the GAP manual (section Matrix Groups in Characteristic 0).
BravaisGroup( G ) A
IsBravaisGroup( G ) P
BravaisSubgroups( G ) A
BravaisSupergroups( G ) A
NormalizerInGLnZBravaisGroup( G ) A
Normalizer( GL(n, Integers), G ) O
Centralizer( GL(n, Integers), G ) O
ZClassRepsQClass( G ) A
RepresentativeAction( GL(n,Integers), G1, G2 ) O
CARAT contains a catalog with Z-class representatives of all Bravais groups of dimension up to 6. These Bravais groups are accessed via a crystal family symbol.
CaratCrystalFamilies [d] V
returns a list of inequivalent crystal family symbols in dimension d.
BravaisGroupsCrystalFamily( symb ) F
returns a list of Z-class representatives of the Bravais groups in the crystal family with symbol symb.
CARAT contains a catalog with representatives of all Q-classes of finite unimodular groups up to dimension 6. This catalog can be accessd with the function
CaratQClassCatalog( grp, mode ) F
where grp is a finite unimodular group of dimension up to 6, and mode is an integer. This function returns a record with one or several of the following components, depending on the decomposition of mode = n0 + n1 * 2 + n2 * 4 into powers of 2:
qclass
familysymb
trans
group If G1 and G2 are two unimodular groups,
ConjugatorQClass( G1, G2 ) F
returns a rational matrix m such that G1^m = G2, or fail, if the groups are not in the same Q-class. Since this function uses the CARAT Q-class catalog, only groups up to dimension 6 are supported. If this dimension is exceeded, an error is reported.
CARAT manual