<html><head><title>[CARAT] 3 Interface to CARAT</title></head>
<body text="#000000" bgcolor="#ffffff">
[<a href = "chapters.htm">Up</a>] [<a href ="CHAP002.htm">Previous</a>] [<a href = "theindex.htm">Index</a>]
<h1>3 Interface to CARAT</h1><p>
<P>
<H3>Sections</H3>
<oL>
<li> <A HREF="CHAP003.htm#SECT001">Action from the left and from the right</a>
<li> <A HREF="CHAP003.htm#SECT002">CARAT input and output files</a>
<li> <A HREF="CHAP003.htm#SECT003">Executing CARAT commands</a>
<li> <A HREF="CHAP003.htm#SECT004">Methods provided by CARAT</a>
<li> <A HREF="CHAP003.htm#SECT005">CARAT Bravais Catalog</a>
<li> <A HREF="CHAP003.htm#SECT006">CARAT Q-Class Catalog</a>
</ol><p>
<p>
The GAP interface to <font face="Gill Sans,Helvetica,Arial">CARAT</font> consists of two parts, low level
interface routines to <font face="Gill Sans,Helvetica,Arial">CARAT</font> functions on the one hand, and
comfortable high level <font face="Gill Sans,Helvetica,Arial">GAP</font> 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.
<p>
Note that while (almost) all <font face="Gill Sans,Helvetica,Arial">CARAT</font> functions should be accessible
from within <font face="Gill Sans,Helvetica,Arial">GAP</font> by the low level interface routines, high level
interface routines are provided only for a small subset of the
<font face="Gill Sans,Helvetica,Arial">CARAT</font> functions. Priority has been given to routines providing
functionality that has previously not been available in <font face="Gill Sans,Helvetica,Arial">GAP</font>.
Further high level interface routines may be added in the future.
<p>
<p>
<h2><a name="SECT001">3.1 Action from the left and from the right</a></h2>
<p><p>
In crystallography, the convention usually is that matrix groups
act from the left on column vectors. This convention is adopted
also in <font face="Gill Sans,Helvetica,Arial">CARAT</font>. The low level interface routines described below
must respect this convention and provide <font face="Gill Sans,Helvetica,Arial">CARAT</font> with data in the
expected format.
<p>
On the other hand, in <font face="Gill Sans,Helvetica,Arial">GAP</font> the convention is that all groups
act from the right, in the case of matrix groups on row vectors.
However, in order to make <font face="Gill Sans,Helvetica,Arial">GAP</font> 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.
<p>
<p>
<h2><a name="SECT002">3.2 CARAT input and output files</a></h2>
<p><p>
<font face="Gill Sans,Helvetica,Arial">CARAT</font> routines read their input from one or several input files,
and write the result to standard output. In order to use <font face="Gill Sans,Helvetica,Arial">CARAT</font>
routines from within <font face="Gill Sans,Helvetica,Arial">GAP</font>, the input must be prepared in suitably
formatted input files. A <font face="Gill Sans,Helvetica,Arial">CARAT</font> command is then executed with these
input files, with standard output redirected to an output file,
which is read back into <font face="Gill Sans,Helvetica,Arial">GAP</font> afterwards. This section describes
routines interfacing with <font face="Gill Sans,Helvetica,Arial">CARAT</font> input and output files.
<p>
Working with <font face="Gill Sans,Helvetica,Arial">CARAT</font> requires many temporary files. When the <font face="Gill Sans,Helvetica,Arial">CARAT</font>
package is loaded, a temporary directory is created, where one can
put such files. The routine
<p>
<a name = "SSEC002.1"></a>
<li><code>CaratTmpFile( </code><var>filename</var><code> ) F</code>
<p>
returns a file name <var>filename</var> in the <font face="Gill Sans,Helvetica,Arial">CARAT</font> 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.
<p>
<a name = "SSEC002.2"></a>
<li><code>CaratShowFile( </code><var>filename</var><code> ) F</code>
<p>
displays the contents of any text file on the terminal. This can be
used to inspect the contents of <font face="Gill Sans,Helvetica,Arial">CARAT</font> input and output files.
<p>
Most <font face="Gill Sans,Helvetica,Arial">CARAT</font> data files are in either of two formats. The first <font face="Gill Sans,Helvetica,Arial">CARAT</font>
file type is the Matrix File, containing one or several matrices.
The following routines serve as interface to <font face="Gill Sans,Helvetica,Arial">CARAT</font> Matrix Files.
<p>
<a name = "SSEC002.3"></a>
<li><code>CaratWriteMatrixFile( </code><var>filename</var><code>, </code><var>data</var><code> ) F</code>
<p>
takes a file name and a matrix or a list of matrices, and writes the
matrix or matrices to the file.
<p>
<a name = "SSEC002.4"></a>
<li><code>CaratReadMatrixFile( </code><var>filename</var><code> ) F</code>
<p>
reads a <font face="Gill Sans,Helvetica,Arial">CARAT</font> matrix file, and returns a matrix or a list of matrices
read from the file.
<p>
The second <font face="Gill Sans,Helvetica,Arial">CARAT</font> file type is the Bravais File, containing information
on a finite unimodular group. In <font face="Gill Sans,Helvetica,Arial">GAP</font>, the contents of a Bravais File
is represented by a Bravais record, having the following components:
<p>
<dl compact>
<dt><code>generators</code> <dd> generators of the finite unimodular group
<p>
<dt><code>formspace</code> <dd> basis of the space of invariant forms (optional)
<p>
<dt><code>centerings</code> <dd> list of centering matrices (optional)
<p>
<dt><code>normalizer</code> <dd> additional generators of the normalizer in GL(n,Z) (optional)
<p>
<dt><code>centralizer</code> <dd> additional generators of the centralizer in GL(n,Z) (optional)
<p>
<dt><code>size</code> <dd> size of the unimodular group (optional)
</dl>
<p>
The following routines serve as interface to <font face="Gill Sans,Helvetica,Arial">CARAT</font> Bravais Files.
<p>
<a name = "SSEC002.5"></a>
<li><code>CaratWriteBravaisFile( </code><var>filename</var><code>, </code><var>data</var><code> ) F</code>
<p>
takes a file name and a Bravais record, and writes the data in the
Bravais record to the file.
<p>
<a name = "SSEC002.6"></a>
<li><code>CaratReadBravaisFile( </code><var>filename</var><code> ) F</code>
<p>
reads a Bravais File, and returns the resulting Bravais record.
<p>
Certain <font face="Gill Sans,Helvetica,Arial">CARAT</font> programs produce output files containing several Bravais
records, possibly preceeded by a varying number of header lines.
<p>
<a name = "SSEC002.7"></a>
<li><code>CaratReadMultiBravaisFile( </code><var>filename</var><code> ) F</code>
<p>
reads such a multi-Bravais file, and returns a record with the components
<code>info</code> and <code>groups</code>. <code>info</code> is the list of header lines before the first
Bravais record starts, and <code>groups</code> is the list of Bravais records read from
the file.
<p>
<p>
<h2><a name="SECT003">3.3 Executing CARAT commands</a></h2>
<p><p>
To execute a <font face="Gill Sans,Helvetica,Arial">CARAT</font> program from within <font face="Gill Sans,Helvetica,Arial">GAP</font>, some low level,
general purpose routines are provided in this package.
Higher level routines for certain <font face="Gill Sans,Helvetica,Arial">CARAT</font> functions may be available
in the <font face="Gill Sans,Helvetica,Arial">GAP</font> 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.
<p>
An arbitrary <font face="Gill Sans,Helvetica,Arial">CARAT</font> program can be executed with the routine
<p>
<a name = "SSEC003.1"></a>
<li><code>CaratCommand( </code><var>command</var><code>, </code><var>args</var><code>, </code><var>outfile</var><code> ) F</code>
<p>
where <var>command</var> is the name of a <font face="Gill Sans,Helvetica,Arial">CARAT</font> program, <var>args</var> is a string
containing the command line arguments of the <font face="Gill Sans,Helvetica,Arial">CARAT</font> program,
and <var>outfile</var> is the name of the file to which the output is to be
written. Example:
<p>
<pre>
gap> CaratCommand( "Z_equiv", "file1 file2", "file.out" );
</pre>
<p>
A short description of the arguments and options of any <font face="Gill Sans,Helvetica,Arial">CARAT</font>
program can be obtained from the <font face="Gill Sans,Helvetica,Arial">CARAT</font> online help facility with
<p>
<a name = "SSEC003.2"></a>
<li><code>CaratHelp( </code><var>command</var><code> ) F</code>
<p>
where <var>command</var> is the name of the <font face="Gill Sans,Helvetica,Arial">CARAT</font> program. CaratHelp executes
the program with the <code>-h</code> option, and writes the output to the
terminal. Example:
<p>
<pre>
gap> CaratHelp( "Z_equiv" );
</pre>
<p>
A list of all <font face="Gill Sans,Helvetica,Arial">CARAT</font> programs, along with a description of their
usage and functionality, can be found in the <font face="Gill Sans,Helvetica,Arial">CARAT</font> documentation
(in HTML), in the file
<p>
<pre>
documentation/introduction.html
</pre>
<p>
in the <font face="Gill Sans,Helvetica,Arial">CARAT</font> home directory.
<p>
<p>
<h2><a name="SECT004">3.4 Methods provided by CARAT</a></h2>
<p><p>
<font face="Gill Sans,Helvetica,Arial">CARAT</font> implements methods for the following functions and operations
declared in the <font face="Gill Sans,Helvetica,Arial">GAP</font> library. For a detailed description of these
functions, please consult the <font face="Gill Sans,Helvetica,Arial">GAP</font> manual (section
<a href="../../../doc/htm/ref/CHAP042.htm#SECT005">Matrix Groups in Characteristic 0</a>).
<p>
<a name = "SSEC004.1"></a>
<li><code>BravaisGroup( </code><var>G</var><code> ) A</code>
<p>
<a name = "SSEC004.2"></a>
<li><code>IsBravaisGroup( </code><var>G</var><code> ) P</code>
<p>
<a name = "SSEC004.3"></a>
<li><code>BravaisSubgroups( </code><var>G</var><code> ) A</code>
<p>
<a name = "SSEC004.4"></a>
<li><code>BravaisSupergroups( </code><var>G</var><code> ) A</code>
<p>
<a name = "SSEC004.5"></a>
<li><code>NormalizerInGLnZBravaisGroup( </code><var>G</var><code> ) A</code>
<p>
<a name = "SSEC004.6"></a>
<li><code>Normalizer( GL(</code><var>n</var><code>, Integers), </code><var>G</var><code> ) O</code>
<p>
<a name = "SSEC004.7"></a>
<li><code>Centralizer( GL(</code><var>n</var><code>, Integers), </code><var>G</var><code> ) O</code>
<p>
<a name = "SSEC004.8"></a>
<li><code>ZClassRepsQClass( </code><var>G</var><code> ) A</code>
<p>
<a name = "SSEC004.9"></a>
<li><code>RepresentativeAction( GL(</code><var>n</var><code>,Integers), </code><var>G1</var><code>, </code><var>G2</var><code> ) O</code>
<p>
<p>
<h2><a name="SECT005">3.5 CARAT Bravais Catalog</a></h2>
<p><p>
<font face="Gill Sans,Helvetica,Arial">CARAT</font> contains a catalog with <b>Z</b>-class representatives of all
Bravais groups of dimension up to 6. These Bravais groups are
accessed via a crystal family symbol.
<p>
<a name = "SSEC005.1"></a>
<li><code>CaratCrystalFamilies [d] V</code>
<p>
returns a list of inequivalent crystal family symbols in dimension <var>d</var>.
<p>
<a name = "SSEC005.2"></a>
<li><code>BravaisGroupsCrystalFamily( </code><var>symb</var><code> ) F</code>
<p>
returns a list of <b>Z</b>-class representatives of the Bravais groups
in the crystal family with symbol <var>symb</var>.
<p>
<p>
<h2><a name="SECT006">3.6 CARAT Q-Class Catalog</a></h2>
<p><p>
<font face="Gill Sans,Helvetica,Arial">CARAT</font> contains a catalog with representatives of all <i>Q</i>-classes of
finite unimodular groups up to dimension 6. This catalog can be accessd
with the function
<p>
<a name = "SSEC006.1"></a>
<li><code>CaratQClassCatalog( </code><var>grp</var><code>, </code><var>mode</var><code> ) F</code>
<p>
where <var>grp</var> is a finite unimodular group of dimension up to 6, and
<var>mode</var> is an integer. This function returns a record with one or
several of the following components, depending on the decomposition of
<i>mode</i> = <i>n</i><sub>0</sub> + <i>n</i><sub>1</sub> * 2 + <i>n</i><sub>2</sub> * 4 into powers of 2:
<p>
<dl compact>
<dt><code>qclass</code> <dd> Q-class symbol; this component is always present
<p>
<dt><code>familysymb</code> <dd> crystal family symbol (present if <i>n</i><sub>0</sub> < > 0)
<p>
<dt><code>trans</code> <dd> transformation to standard representative of Q-class:
<var>grp</var>^<var>trans</var> = <var>std</var>
(present if <i>n</i><sub>1</sub> < > 0)
<p>
<dt><code>group</code> <dd> standard representative of Q-class of <var>grp</var>
(present if <i>n</i><sub>2</sub> < > 0 )
</dl>
<p>
If <var>G1</var> and <var>G2</var> are two unimodular groups,
<p>
<a name = "SSEC006.2"></a>
<li><code>ConjugatorQClass( </code><var>G1</var><code>, </code><var>G2</var><code> ) F</code>
<p>
returns a rational matrix <var>m</var> such that <var>G1</var>^<var>m</var> = <var>G2</var>, or fail, if
the groups are not in the same Q-class. Since this function uses the
<font face="Gill Sans,Helvetica,Arial">CARAT</font> Q-class catalog, only groups up to dimension 6 are supported.
If this dimension is exceeded, an error is reported.
<p>
<p>
[<a href = "chapters.htm">Up</a>] [<a href ="CHAP002.htm">Previous</a>] [<a href = "theindex.htm">Index</a>]
<P>
<address>CARAT manual<br>November 2008
</address></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
91213ddcfbe7f54821d42c2d9e091326
>
files
>
658
