  
  [1X3 [33X[0;0YInterface to CARAT[133X[101X
  
  [33X[0;0YThe  [5XGAP[105X  interface  to  [5XCARAT[105X  consists  of  two parts, low level interface
  routines  to [5XCARAT[105X functions on the one hand, and comfortable high level [5XGAP[105X
  functions  on the other hand. The high level functions, implemented in terms
  of  the  low  level  functions,  actually  provide methods for functions and
  operations declared in the [5XGAP[105X library.[133X
  
  [33X[0;0YNote  that  while  (almost)  all  [5XCARAT[105X  functions should be accessible from
  within  [5XGAP[105X  by  the  low  level  interface  routines,  high level interface
  routines  are  provided  only  for  a  small  subset of the [5XCARAT[105X functions.
  Priority  has  been  given  to  routines  providing  functionality  that has
  previously  not been available in [5XGAP[105X. Further high level interface routines
  may be added in the future.[133X
  
  
  [1X3.1 [33X[0;0YAction from the left and from the right[133X[101X
  
  [33X[0;0YIn  crystallography,  the  convention usually is that matrix groups act from
  the  left  on  column vectors. This convention is adopted also in [5XCARAT[105X. The
  low  level  interface  routines described below must respect this convention
  and provide [5XCARAT[105X with data in the expected format.[133X
  
  [33X[0;0YOn  the  other  hand,  in [5XGAP[105X the convention is that all groups act from the
  right,  in  the  case  of matrix groups on row vectors. However, in order to
  make  [5XGAP[105X  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.[133X
  
  
  [1X3.2 [33X[0;0YCARAT input and output files[133X[101X
  
  [33X[0;0Y[5XCARAT[105X  routines  read their input from one or several input files, and write
  the  result  to  standard output. In order to use [5XCARAT[105X routines from within
  [5XGAP[105X,  the  input must be prepared in suitably formatted input files. A [5XCARAT[105X
  command  is  then  executed  with  these  input  files, with standard output
  redirected  to  an output file, which is read back into [5XGAP[105X afterwards. This
  section describes routines interfacing with [5XCARAT[105X input and output files.[133X
  
  [33X[0;0YWorking  with [5XCARAT[105X requires many temporary files. When the [5XCARAT[105X package is
  loaded,  a temporary directory is created, where one can put such files. The
  routine[133X
  
  [1X3.2-1 CaratTmpFile[101X
  
  [33X[1;0Y[29X[2XCaratTmpFile[102X( [3Xfilename[103X ) [32X function[133X
  
  [33X[0;0Yreturns  a file name [3Xfilename[103X in the [5XCARAT[105X 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.[133X
  
  [1X3.2-2 CaratShowFile[101X
  
  [33X[1;0Y[29X[2XCaratShowFile[102X( [3Xfilename[103X ) [32X function[133X
  
  [33X[0;0Ydisplays  the contents of any text file on the terminal. This can be used to
  inspect the contents of [5XCARAT[105X input and output files.[133X
  
  [33X[0;0YMost  [5XCARAT[105X  data  files  are in either of two formats. The first [5XCARAT[105X file
  type  is  the Matrix File, containing one or several matrices. The following
  routines serve as interface to [5XCARAT[105X Matrix Files.[133X
  
  [1X3.2-3 CaratWriteMatrixFile[101X
  
  [33X[1;0Y[29X[2XCaratWriteMatrixFile[102X( [3Xfilename[103X, [3Xdata[103X ) [32X function[133X
  
  [33X[0;0Ytakes  a file name and a matrix or a list of matrices, and writes the matrix
  or matrices to the file.[133X
  
  [1X3.2-4 CaratReadMatrixFile[101X
  
  [33X[1;0Y[29X[2XCaratReadMatrixFile[102X( [3Xfilename[103X ) [32X function[133X
  
  [33X[0;0Yreads  a  [5XCARAT[105X matrix file, and returns a matrix or a list of matrices read
  from the file.[133X
  
  [33X[0;0YThe  second [5XCARAT[105X file type is the Bravais File, containing information on a
  finite  unimodular  group.  In  [5XGAP[105X,  the  contents  of  a  Bravais File are
  represented by a Bravais record, having the following components:[133X
  
  [8X[10Xgenerators[110X[8X[108X
        [33X[0;6Ygenerators of the finite unimodular group[133X
  
  [8X[10Xformspace[110X[8X[108X
        [33X[0;6Ybasis of the space of invariant forms (optional)[133X
  
  [8X[10Xcenterings[110X[8X[108X
        [33X[0;6Ylist of centering matrices (optional)[133X
  
  [8X[10Xnormalizer[110X[8X[108X
        [33X[0;6Yadditional generators of the normalizer in [22XGL(n,ℤ)[122X (optional)[133X
  
  [8X[10Xcentralizer[110X[8X[108X
        [33X[0;6Yadditional generators of the centralizer in [22XGL(n,ℤ)[122X (optional)[133X
  
  [8X[10Xsize[110X[8X[108X
        [33X[0;6Ysize of the unimodular group (optional)[133X
  
  [33X[0;0YThe following routines serve as interface to [5XCARAT[105X Bravais Files.[133X
  
  [1X3.2-5 CaratWriteBravaisFile[101X
  
  [33X[1;0Y[29X[2XCaratWriteBravaisFile[102X( [3Xfilename[103X, [3Xdata[103X ) [32X function[133X
  
  [33X[0;0Ytakes  a  file name and a Bravais record, and writes the data in the Bravais
  record to the file.[133X
  
  [1X3.2-6 CaratReadBravaisFile[101X
  
  [33X[1;0Y[29X[2XCaratReadBravaisFile[102X( [3Xfilename[103X ) [32X function[133X
  
  [33X[0;0Yreads a Bravais File, and returns the resulting Bravais record.[133X
  
  [33X[0;0YCertain  [5XCARAT[105X  programs  produce  output  files  containing several Bravais
  records, possibly preceded by a varying number of header lines.[133X
  
  [1X3.2-7 CaratReadMultiBravaisFile[101X
  
  [33X[1;0Y[29X[2XCaratReadMultiBravaisFile[102X( [3Xfilename[103X ) [32X function[133X
  
  [33X[0;0Yreads  such  a  multi-Bravais file, and returns a record with the components
  [10Xinfo[110X  and  [10Xgroups[110X. [10Xinfo[110X is the list of header lines before the first Bravais
  record starts, and [10Xgroups[110X is the list of Bravais records read from the file.[133X
  
  
  [1X3.3 [33X[0;0YExecuting CARAT commands[133X[101X
  
  [33X[0;0YTo  execute a [5XCARAT[105X program from within [5XGAP[105X, some low level, general purpose
  routines  are  provided  in  this package. Higher level routines for certain
  [5XCARAT[105X  functions  may  be available in the [5XGAP[105X 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.[133X
  
  [33X[0;0YAn arbitrary [5XCARAT[105X program can be executed with the routine[133X
  
  [1X3.3-1 CaratCommand[101X
  
  [33X[1;0Y[29X[2XCaratCommand[102X( [3Xcommand[103X, [3Xargs[103X, [3Xoutfile[103X ) [32X function[133X
  
  [33X[0;0Ywhere  [3Xcommand[103X  is  the name of a [5XCARAT[105X program, [3Xargs[103X is a string containing
  the  command line arguments of the [5XCARAT[105X program, and [3Xoutfile[103X is the name of
  the file to which the output is to be written. Example:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XCaratCommand( "Z_equiv", "file1 file2", "file.out" );[127X[104X
  [4X[32X[104X
  
  [33X[0;0YA short description of the arguments and options of any [5XCARAT[105X program can be
  obtained from the [5XCARAT[105X online help facility with[133X
  
  [1X3.3-2 CaratHelp[101X
  
  [33X[1;0Y[29X[2XCaratHelp[102X( [3Xcommand[103X ) [32X function[133X
  
  [33X[0;0Ywhere  [3Xcommand[103X  is  the  name  of  the [5XCARAT[105X program. [10XCaratHelp[110X executes the
  program with the [10X-h[110X option, and writes the output to the terminal. Example:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XCaratHelp( "Z_equiv" );[127X[104X
  [4X[32X[104X
  
  [33X[0;0YA  list  of  all [5XCARAT[105X programs, along with a description of their usage and
  functionality,  can  be  found  in the [5XCARAT[105X documentation (in HTML), in the
  file[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28Xtex/introduction.html[128X[104X
  [4X[32X[104X
  
  [33X[0;0Yin the [5XCARAT[105X home directory.[133X
  
  
  [1X3.4 [33X[0;0YMethods provided by CARAT[133X[101X
  
  [33X[0;0Y[5XCARAT[105X implements methods for the following functions and operations declared
  in  the  [5XGAP[105X  library. For a detailed description of these functions, please
  consult  the [5XGAP[105X manual (section [14X'Reference: Matrix Groups in Characteristic
  0'[114X).[133X
  
  [1X3.4-1 BravaisGroup[101X
  
  [33X[1;0Y[29X[2XBravaisGroup[102X( [3XG[103X ) [32X attribute[133X
  [33X[1;0Y[29X[2XIsBravaisGroup[102X( [3XG[103X ) [32X property[133X
  [33X[1;0Y[29X[2XBravaisSubgroups[102X( [3XG[103X ) [32X attribute[133X
  [33X[1;0Y[29X[2XBravaisSupergroups[102X( [3XG[103X ) [32X attribute[133X
  [33X[1;0Y[29X[2XNormalizerInGLnZBravaisGroup[102X( [3XG[103X ) [32X attribute[133X
  [33X[1;0Y[29X[2XNormalizer[102X( [3XGL(n[103X, [3XIntegers)[103X, [3XG[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XCentralizer[102X( [3XGL(n[103X, [3XIntegers)[103X, [3XG[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XZClassRepsQClass[102X( [3XG[103X ) [32X attribute[133X
  [33X[1;0Y[29X[2XRepresentativeAction[102X( [3XGL(n[103X, [3XIntegers)[103X, [3XG1[103X, [3XG2[103X ) [32X operation[133X
  
  
  [1X3.5 [33X[0;0YCARAT Bravais Catalog[133X[101X
  
  [33X[0;0Y[5XCARAT[105X  contains a catalog with [22Xℤ[122X-class representatives of all Bravais groups
  of dimension up to 6. These Bravais groups are accessed via a crystal family
  symbol.[133X
  
  [1X3.5-1 CaratCrystalFamilies[101X
  
  [33X[1;0Y[29X[2XCaratCrystalFamilies[102X [32X global variable[133X
  
  [33X[0;0Y[10XCaratCrystalFamilies[[3Xd[103X[10X][110X  is a list of inequivalent crystal family symbols in
  dimension [3Xd[103X.[133X
  
  [1X3.5-2 BravaisGroupsCrystalFamily[101X
  
  [33X[1;0Y[29X[2XBravaisGroupsCrystalFamily[102X( [3Xsymb[103X ) [32X function[133X
  
  [33X[0;0Yreturns  a  list  of  [22Xℤ[122X-class  representatives  of the Bravais groups in the
  crystal family with symbol [3Xsymb[103X.[133X
  
  
  [1X3.6 [33X[0;0YCARAT Q-Class Catalog[133X[101X
  
  [33X[0;0Y[5XCARAT[105X  contains  a  catalog  with representatives of all [22Xℚ[122X-classes of finite
  unimodular  groups  up to dimension 6. This catalog can be accessed with the
  function[133X
  
  [1X3.6-1 CaratQClassCatalog[101X
  
  [33X[1;0Y[29X[2XCaratQClassCatalog[102X( [3Xgrp[103X, [3Xmode[103X ) [32X function[133X
  
  [33X[0;0Ywhere  [3Xgrp[103X is a finite unimodular group of dimension up to 6, and [3Xmode[103X is an
  integer. This function returns a record with one or several of the following
  components, depending on the decomposition of [22Xmode = n_0 + n_1 * 2 + n_2 * 4[122X
  into powers of 2:[133X
  
  [8X[10Xqclass[110X[8X[108X
        [33X[0;6Y[22Xℚ[122X-class symbol; this component is always present[133X
  
  [8X[10Xfamilysymb[110X[8X[108X
        [33X[0;6Ycrystal family symbol (present if [22Xn_0 <> 0[122X)[133X
  
  [8X[10Xtrans[110X[8X[108X
        [33X[0;6Ytransformation  to standard representative of the [22Xℚ[122X-class: [3Xgrp[103X^[3Xtrans[103X =
        [3Xstd[103X (present if [22Xn_1 <> 0[122X)[133X
  
  [8X[10Xgroup[110X[8X[108X
        [33X[0;6Ystandard representative of the [22Xℚ[122X-class of [3Xgrp[103X (present if [22Xn_2 <> 0[122X)[133X
  
  [33X[0;0YIf [3XG1[103X and [3XG2[103X are two unimodular groups,[133X
  
  [1X3.6-2 ConjugatorQClass[101X
  
  [33X[1;0Y[29X[2XConjugatorQClass[102X( [3XG1[103X, [3XG2[103X ) [32X function[133X
  
  [33X[0;0Yreturns  a rational matrix [3Xm[103X such that [3XG1[103X^[3Xm[103X = [3XG2[103X, or [9Xfail[109X, if the groups are
  not in the same [22Xℚ[122X-class. Since this function uses the [5XCARAT[105X [22Xℚ[122X-class catalog,
  only  groups up to dimension 6 are supported. If this dimension is exceeded,
  an error is reported.[133X
  
  [33X[0;0Y [133X
  
