1. Introduction
  
  
  1.1 Abstract and Notation
  
  HAPcryst  is an extension for "Homological Algebra Programming" (HAP, [Ell])
  by  Graham  Ellis.  It  uses  geometric methods to calculate resolutions for
  crystallographic groups. In this manual, we will use the terms "space group"
  and "crystallographic group" synonymous. As usual in GAP, group elements are
  supposed  to act from the right. To emphasize this fact, some functions have
  names  ending  in "OnRight" (namely those, which rely on the action from the
  right).  This  is  also  meant  to  make  work with HAPcryst and cryst [EGN]
  easier.
  
  The  functions called "somethingStandardSpaceGroup" are supposed to work for
  standard  crystallographic groups on left and right some time in the future.
  Currently  only  the  versions  acting on right are implemented. As in cryst
  [EGN],  space  groups  are  represented  as  affine  linear  groups. For the
  computations  in  HAPcryst,  crystallographic groups have to be in "standard
  form".  That  is,  the translation basis has to be the standard basis of the
  space.  This  implies  that  the  linear part of a group element need not be
  orthogonal with respect to the usual scalar product.
  
  
  1.1-1 The natural action of crystallographic groups
  
  There  is  some confusion about the way crystallographic groups are written.
  This  concerns the question if we act on left or on right and if vectors are
  of the form [1,...] or [...,1].
  
  As  mentioned, HAPcryst handles affine crystallographic groups on right (and
  maybe later also on left) acting on vectors of the form [...,1].
  
  BUT:  The  functions  in HAPcryst do not take augmented vectors as input (no
  leading  or  ending ones). The handling of vectors is done internally. So in
  HAPcryst, a crystallographic group is a group of nx n matrices which acts on
  a  vector  space  of  dimension n-1 whose elements are vectors of length n-1
  (not n). Example:
  
  ---------------------------  Example  ----------------------------
    gap> G:=SpaceGroup(3,4); #This group acts on 3-Space
    SpaceGroupOnRightBBNWZ( 3, 2, 1, 1, 2 )
    gap> Display(Representative(G));
    [ [  1,  0,  0,  0 ],
      [  0,  1,  0,  0 ],
      [  0,  0,  1,  0 ],
      [  0,  0,  0,  1 ] ]
    gap> OrbitStabilizerInUnitCubeOnRight(G,[1/2,0,0]);
    rec( orbit := [ [ 1/2, 0, 0 ], [ 1/2, 1/2, 0 ] ],
      stabilizer := Group([ [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ],
              [ 0, 0, 0, 1 ] ] ]) )
  ------------------------------------------------------------------
  
  
  1.2 Requirements
  
  The following GAP packages are required
  
  --    polymaking  which  in  turn  depends  on  the  computational  geometry
        software polymake.
  
  --    HAP
  
  --    Cryst
  
  The following GAP packages are not required but highly recommended:
  
  --    carat
  
  --    CrystCat
  
  --    GAPDoc is needed to display the online manual
  
  
  1.2-1 Recommendation concerning polymake
  
  Calculating   resolutions   of   Bieberbach   groups  involves  convex  hull
  computations.  polymake  by  default  uses  cdd  to  compute  convex  hulls.
  Experiments  suggest  that  lrs  is  the  more  suitable  algorithm  for the
  computations  done  in  HAPcryst  than  the  default cdd. You can change the
  behaviour of by editing the file "yourhomedirectory/.polymake/prefer.pl". It
  should  contain  a  section like this (just make sure lrs is before cdd, the
  position of beneath_beyond does not matter):
  
  ------------------------------------------------------------------
    #########################################
    application polytope;
    
    prefer "*.convex_hull  lrs, beneath_beyond, cdd";
  ------------------------------------------------------------------
  
  
  1.3 Global Variables
  
  HAPcryst  itself  does  only  have  one global variable, namely InfoHAPcryst
  (1.3-1).  The  location of files generated for interaction with polymake are
  determined by the value of POLYMAKE_DATA_DIR (POLYMAKE_DATA_DIR???) which is
  a global variable of polymaking.
  
  1.3-1 InfoHAPcryst
  
  > InfoHAPcryst____________________________________________________info class
  
  At  a  level of 1, only the most important messages are printed. At level 2,
  additional  information  is  displayed, and level 3 is even more verbose. At
  level 0, HAPcryst remains silent.