% This file was created automatically from grpmat.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  grpmat.msk                  GAP documentation            Alexander Hulpke
%%
%A  @(#)$Id: grpmat.msk,v 1.18 2002/04/15 10:02:29 sal Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Matrix Groups}

Matrix groups are groups generated by invertible square matrices.

In the following example we temporarily increase the line length limit from
its default value 80 to 83 in order to get a nicer output format.

\beginexample
gap> m1 := [ [ Z(3)^0, Z(3)^0,   Z(3) ],
>            [   Z(3), 0*Z(3),   Z(3) ],
>            [ 0*Z(3),   Z(3), 0*Z(3) ] ];;
gap> m2 := [ [   Z(3),   Z(3), Z(3)^0 ],
>            [   Z(3), 0*Z(3),   Z(3) ],
>            [ Z(3)^0, 0*Z(3),   Z(3) ] ];;
gap> SizeScreen([ 83, ]);;
gap> m := Group( m1, m2 );
Group(
[ [ [ Z(3)^0, Z(3)^0, Z(3) ], [ Z(3), 0*Z(3), Z(3) ], [ 0*Z(3), Z(3), 0*Z(3) ] ],
  [ [ Z(3), Z(3), Z(3)^0 ], [ Z(3), 0*Z(3), Z(3) ], [ Z(3)^0, 0*Z(3), Z(3) ] ] ])
gap> SizeScreen([ 80, ]);;
\endexample

\>IsMatrixGroup( <grp> ) C



For most operations, {\GAP} only provides methods for finite matrix groups.
Many calculations in finite matrix groups are done via a `NiceMonomorphism'
(see "Nice Monomorphisms") that represents a faithful action on vectors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Attributes and Properties for Matrix Groups}

\>DimensionOfMatrixGroup( <mat-grp> ) A

The dimension of the matrix group.


\>DefaultFieldOfMatrixGroup( <mat-grp> ) A

Is a field containing all the matrix entries. It is not guaranteed to be
the smallest field with this property.


\>FieldOfMatrixGroup( <matgrp> ) A

The smallest  field containing all the  matrix entries of all elements
of the matrix group <matgrp>.  As the calculation of this can be hard,
this should only be used if  one *really*   needs     the
smallest   field,  use `DefaultFieldOfMatrixGroup' to get (for example)
the characteristic.


\beginexample
gap> DimensionOfMatrixGroup(m);
3
gap> DefaultFieldOfMatrixGroup(m);
GF(3)
\endexample

\>TransposedMatrixGroup( <matgrp> ) A

returns the transpose of the matrix group <matgrp>. The transpose of
the transpose of <matgrp> is identical to <matgrp>. 


\beginexample
gap> G := Group( [[0,-1],[1,0]] );
Group([ [ [ 0, -1 ], [ 1, 0 ] ] ])
gap> T := TransposedMatrixGroup( G );
Group([ [ [ 0, 1 ], [ -1, 0 ] ] ])
gap> IsIdenticalObj( G, TransposedMatrixGroup( T ) );
true
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%   
\Section{Actions of Matrix Groups}                                           
                                                                                
The basic operations for groups are described in Chapter~"Group
Actions",
special actions for *matrix* groups mentioned there are `OnLines',
`OnRight', and `OnSubspacesByCanonicalBasis'.

For subtleties concerning multiplication from the left or from the
right,
see~"Acting OnRight and OnLeft".



\>ProjectiveActionOnFullSpace( <G>, <F>, <n> ) F

Let <G> be a group of <n> by <n> matrices over a field contained in the
finite field <F>.
`ProjectiveActionOnFullSpace' returns the image of the projective action
of <G> on the full row space $<F>^<n>$.


\>ProjectiveActionHomomorphismMatrixGroup( <G> ) F

returns an action homomorphism for a faithful projective action of <G>
on the underlying vector space. (Note: The action is not necessarily on
the full space, if a smaller subset can be found on which the action is
faithful.)


\>BlowUpIsomorphism( <matgrp>, <B> ) F

For a matrix group <matgrp> and a basis <B> of a field extension $L / K$,
say, such that the entries of all matrices in <matgrp> lie in $L$,
`BlowUpIsomorphism' returns the isomorphism with source <matgrp>
that is defined by mapping the matrix $A$ to $`BlownUpMat'( A, <B> )$,
see~"BlownUpMat".


\beginexample
gap> g:= GL(2,4);;
gap> B:= CanonicalBasis( GF(4) );;  BasisVectors( B );
[ Z(2)^0, Z(2^2) ]
gap> iso:= BlowUpIsomorphism( g, B );;
gap> Display( Image( iso, [ [ Z(4), Z(2) ], [ 0*Z(2), Z(4)^2 ] ] ) );
 . 1 1 .
 1 1 . 1
 . . 1 1
 . . 1 .
gap> img:= Image( iso, g );
<matrix group with 2 generators>
gap> Index( GL(4,2), img );
112
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{GL and SL}

\>IsGeneralLinearGroup( <grp> ) P
\>IsGL( <grp> ) P

The General Linear group is the group of all invertible matrices over a
ring. This property tests, whether a group is isomorphic to a General
Linear group. (Note that currently only a few trivial methods are
available for this operation. We hope to improve this in the future.)

\>IsNaturalGL( <matgrp> ) P

This property tests, whether a matrix group is the General Linear group
in the right dimension over the (smallest) ring which contains all
entries of its elements. (Currently, only a trivial test that computes
the order of the group is available.)

\>IsSpecialLinearGroup( <grp> ) P
\>IsSL( <grp> ) P

The Special Linear group is the group of all invertible matrices over a
ring, whose determinant is equal to 1. This property tests, wether a
group is isomorphic to a Special Linear group. (Note that currently 
only a few trivial methods are available for this operation. We hope 
to improve this in the future.)

\>IsNaturalSL( <matgrp> ) P

This property tests, whether a matrix group is the Special Linear group
in the right dimension over the (smallest) ring which contains all
entries of its elements. (Currently, only a trivial test that computes
the order of the group is available.)

\beginexample
gap> IsNaturalGL(m);
false
\endexample

\>IsSubgroupSL( <matgrp> ) P

This property tests, whether a matrix group is a subgroup of the Special
Linear group in the right dimension over the (smallest) ring which
contains all entries of its elements.


(See also section~"Classical Groups".)


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Invariant Forms}

\>InvariantBilinearForm( <matgrp> ) A

This attribute describes a bilinear form that is invariant under the
matrix group <matgrp>.
The form is given by a record with the component `matrix'
which is a matrix <m> such that for every generator <g> of <matgrp>
the equation $<g> \cdot <m> \cdot <g>^{tr} = <m>$ holds.


\>IsFullSubgroupGLorSLRespectingBilinearForm( <matgrp> ) P

This property tests, whether a matrix group <matgrp> is the full
subgroup of GL or SL (the property `IsSubgroupSL' determines which it
is) respecting the `InvariantBilinearForm' of <matgrp>.

\>InvariantSesquilinearForm( <matgrp> ) A

This attribute describes a sesquilinear form that is invariant under the
matrix group <matgrp> over the field $F$ with $q^2$ elements, say.
The form is given by a record with the component `matrix'
which is is a matrix <m> such that for every generator <g> of <matgrp>
the equation $<g> \cdot <m> \cdot (<g>^{tr})^f$ holds,
where $f$ is the automorphism of $F$ that raises each element to the
$q$-th power.
($f$ can be obtained as a power of `FrobeniusAutomorphism( <F> )',
see~"FrobeniusAutomorphism".)


\>IsFullSubgroupGLorSLRespectingSesquilinearForm( <matgrp> ) P

This property tests, whether a matrix group <matgrp> is the full
subgroup of GL or SL (the property `IsSubgroupSL' determines which it
is) respecting the `InvariantSesquilinearForm' of <matgrp>.

\>InvariantQuadraticForm( <matgrp> ) A

For a matrix group <matgrp>, `InvariantQuadraticForm' returns a record
containing at least the component `matrix' whose value is a matrix $Q$.
The quadratic form $q$ on the natural vector space $V$ on which <matgrp>
acts is given by $q(v) = v Q v^{tr}$, and the invariance under <matgrp>
is given by the equation $q(v) = q(v M)$ for all $v\in V$ and $M$ in
<matgrp>.
(Note that the invariance of $q$ does *not* imply that the matrix $Q$
is invariant under <matgrp>.)

$q$ is defined relative to an invariant symmetric bilinear form $f$
(see~"InvariantBilinearForm"), via the equation
$q(\lambda x + \mu y) = \lambda^2 q(x) + \lambda\mu f(x,y) + \mu^2 q(y)$
(see Chapter~3.4 in~\cite{CCN85}).
If $f$ is represented by the matrix $F$ then this implies
$F = Q + Q^{tr}$.
In characteristic different from $2$, we have $q(x) = f(x,x)/2$,
so $Q$ can be chosen as the strictly upper triangular part of $F$
plus half of the diagonal part of $F$.
In characteristic $2$, $F$ does not determine $Q$ but still $Q$ can be
chosen as an upper (or lower) triangular matrix.

Whenever the `InvariantQuadraticForm' value is set in a matrix group
then also the `InvariantBilinearForm' value can be accessed,
and the two values are compatible in the above sense.


\>IsFullSubgroupGLorSLRespectingQuadraticForm( <matgrp> ) P

This property tests, whether the matrix group <matgrp> is the full
subgroup of GL or SL (the property `IsSubgroupSL' determines which it
is) respecting the `InvariantQuadraticForm' value of <matgrp>.



\beginexample
gap> g:= Sp( 2, 3 );;
gap> m:= InvariantBilinearForm( g ).matrix;
[ [ 0*Z(3), Z(3)^0 ], [ Z(3), 0*Z(3) ] ]
gap> [ 0, 1 ] * m * [ 1, -1 ];           # evaluate the bilinear form
Z(3)
gap> IsFullSubgroupGLorSLRespectingBilinearForm( g );
true
gap> g:= SU( 2, 4 );;
gap> m:= InvariantSesquilinearForm( g ).matrix;
[ [ 0*Z(2), Z(2)^0 ], [ Z(2)^0, 0*Z(2) ] ]
gap> [ 0, 1 ] * m * [ 1, 1 ];            # evaluate the bilinear form
Z(2)^0
gap> IsFullSubgroupGLorSLRespectingSesquilinearForm( g );
true
gap> g:= GO( 1, 2, 3 );;
gap> m:= InvariantBilinearForm( g ).matrix;
[ [ 0*Z(3), Z(3)^0 ], [ Z(3)^0, 0*Z(3) ] ]
gap> [ 0, 1 ] * m * [ 1, 1 ];            # evaluate the bilinear form
Z(3)^0
gap> q:= InvariantQuadraticForm( g ).matrix;
[ [ 0*Z(3), Z(3)^0 ], [ 0*Z(3), 0*Z(3) ] ]
gap> [ 0, 1 ] * q * [ 0, 1 ];            # evaluate the quadratic form
0*Z(3)
gap> IsFullSubgroupGLorSLRespectingQuadraticForm( g );
true
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Matrix Groups in Characteristic 0}

Most of the functions described in this and the following section have
implementations which use functions from the {\GAP} package Carat.
If Carat is not installed or not compiled, no suitable methods are available.

\>IsCyclotomicMatrixGroup( <G> ) P

tests whether all matrices in <G> have cyclotomic entries.

\>IsRationalMatrixGroup( <G> ) P

tests whether all matrices in <G> have rational entries.

\>IsIntegerMatrixGroup( <G> ) P

tests whether all matrices in <G> have integer entries.


\>IsNaturalGLnZ( <G> ) P

tests whether <G> is $GL_n(\Z)$ in its natural representation by
$n\times n$ integer matrices. (The dimension $n$ will be read off the
generating matrices.)

\beginexample
gap> IsNaturalGLnZ( GL( 2, Integers ) );
true
\endexample

\>IsNaturalSLnZ( <G> ) P

tests whether <G> is $SL_n(\Z)$ in its natural representation by
$n\times n$ integer matrices. (The dimension $n$ will be read off the
generating matrices.)

\beginexample
gap> IsNaturalSLnZ( SL( 2, Integers ) );
true
\endexample

\>InvariantLattice( G ) A

returns a matrix <B>, whose rows form a basis of a $\Z$-lattice that 
is invariant under the rational matrix group <G> acting from the right. 
It returns `fail' if the group is not unimodular. The columns of the
inverse of <B> span a $\Z$-lattice invariant under <G> acting from 
the left.

\>NormalizerInGLnZ( G ) A

is an attribute used to store the normalizer of <G> in $GL_n(\Z)$,
where <G> is an integer matrix group of dimension <n>. This attribute
is used by `Normalizer( GL( n, Integers ), G )'. 

\>CentralizerInGLnZ( G ) A

is an attribute used to store the centralizer of <G> in $GL_n(\Z)$,
where <G> is an integer matrix group of dimension <n>. This attribute
is used by `Centralizer( GL( n, Integers ), G )'. 

\>ZClassRepsQClass( G ) A

The conjugacy class in $GL_n(\Q)$ of the finite integer matrix 
group <G> splits into finitely many conjugacy classes in $GL_n(\Z)$.
`ZClassRepsQClass( <G> )' returns representative groups for these.

\>IsBravaisGroup( <G> ) P

test whether <G> coincides with its Bravais group (see "BravaisGroup").

\>BravaisGroup( <G> ) A

returns the Bravais group of a finite integer matrix group <G>. 
If <C> is the cone of positive definite quadratic forms <Q> invariant 
under $g \to g*Q*g^{tr}$ for all $g \in G$, then the Bravais group 
of <G> is the maximal subgroup of $GL_n(\Z)$ leaving the forms in
that same cone invariant. Alternatively, the Bravais group of <G> 
can also be defined with respect to the action $g \to g^{tr}*Q*g$
on positive definite quadratic forms <Q>. This latter definition 
is appropriate for groups <G> acting from the right on row vectors, 
whereas the former definition is appropriate for groups acting from 
the left on column vectors. Both definitions yield the same 
Bravais group.

\>BravaisSubgroups( <G> ) A

returns the subgroups of the Bravais group of <G>, which are 
themselves Bravais groups.

\>BravaisSupergroups( <G> ) A

returns the subgroups of $GL_n(\Z)$ that contain the Bravais group 
of <G> and are Bravais groups themselves.

\>NormalizerInGLnZBravaisGroup( <G> ) A

returns the normalizer of the Bravais group of <G> in the 
appropriate $GL_n(\Z)$.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Acting OnRight and OnLeft}

In {\GAP}, matrices by convention act on row vectors from the right,
whereas in crystallography the convention is to act on column vectors
from the left. The definition of certain algebraic objects important
in crystallography implicitly depends on which action is assumed.
This holds true in particular for quadratic forms invariant under
a matrix group. In a similar way, the representation of affine 
crystallographic groups, as they are provided by the {\GAP} package
CrystGap, depends on which action is assumed. Crystallographers
are used to the action from the left, whereas the action from the
right is the natural one for {\GAP}. For this reason, a number of 
functions which are important in crystallography, and whose result 
depends on which action is assumed, are provided in two versions, 
one for the usual action from the right, and one for the 
crystallographic action from the left. 

For every such function, this fact is explicitly mentioned. 
The naming scheme is as follows: If `SomeThing' is such a function, 
there will be functions `SomeThingOnRight' and `SomeThingOnLeft', 
assuming action from the right and from the left, respectively. 
In addition, there is a generic function `SomeThing', which returns 
either the result of `SomeThingOnRight' or `SomeThingOnLeft', 
depending on the global variable `CrystGroupDefaultAction'.


\>`CrystGroupDefaultAction' V

can have either of the two values `RightAction' and `LeftAction'. 
The initial value is `RightAction'. For functions which have 
variants OnRight and OnLeft, this variable determines which 
variant is returned by the generic form. The value of 
`CrystGroupDefaultAction' can be changed with with the 
function `SetCrystGroupDefaultAction'.


\>SetCrystGroupDefaultAction( <action> ) F

allows to set the value of the global variable `CrystGroupDefaultAction'.
Only the arguments `RightAction' and `LeftAction' are allowed.
Initially, the value of `CrystGroupDefaultAction' is `RightAction'



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%   
%%
%E