chap2.txt

  
  2 Bits and Pieces
  
  This  chapter contains a few very basic functions which are needed for space
  group calculations and were missing in standard GAP.
  
  
  2.1 Matrices and Vectors
  
  2.1-1 SignRat
  
  > SignRat( x ) _______________________________________________________method
  Returns:  sign  of  the  rational  number x (Standard GAP currently only has
            SignInt).
  
  2.1-2 VectorModOne
  
  > VectorModOne( v ) __________________________________________________method
  Returns:  Rational vector of the same length with enties in [0,1)
  
  For a rational vector v, this returns the vector with all entries taken "mod
  1".
  
  ---------------------------  Example  ----------------------------
    gap> SignRat((-4)/(-2));
    1
    gap> SignRat(9/(-2));
    -1
    gap> VectorModOne([1/10,100/9,5/6,6/5]);
    [ 1/10, 1/9, 5/6, 1/5 ]
  ------------------------------------------------------------------
  
  2.1-3 IsSquareMat
  
  > IsSquareMat( matrix ) ______________________________________________method
  Returns:  true if matrix is a square matrix and false otherwise.
  
  2.1-4 DimensionSquareMat
  
  > DimensionSquareMat( matrix ) _______________________________________method
  Returns:  Number  of  lines  in  the  matrix matrix if it is square and fail
            otherwise
  
  ---------------------------  Example  ----------------------------
    gap> m:=[[1,2,3],[4,5,6],[9,6,12]];
    [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 9, 6, 12 ] ]
    gap> IsSquareMat(m);
    true
    gap> DimensionSquareMat(m);
    3
    gap> DimensionSquareMat([[1,2],[1,2,3]]);
    Error, Matrix is not square called from
  ------------------------------------------------------------------
  
  Affine  mappings  of  n  dimensional space are often written as a pair (A,v)
  where  A  is  a  linear  mapping  and  v  is a vector. GAP represents affine
  mappings  by  n+1  times  n+1  matrices  M  which  satisfy M_{n+1,n+1}=1 and
  M_{i,n+1}=0 for all 1<= i <= n.
  
  An  affine matrix acts on an n dimensional space which is written as a space
  of n+1 tuples with n+1st entry 1. Here we give two functions to handle these
  affine matrices.
  
  
  2.2 Affine Matrices OnRight
  
  2.2-1 LinearPartOfAffineMatOnRight
  
  > LinearPartOfAffineMatOnRight( mat ) ________________________________method
  Returns:  the  linear  part  of  the  affine matrix mat. That is, everything
            except for the last row and column.
  
  2.2-2 BasisChangeAffineMatOnRight
  
  > BasisChangeAffineMatOnRight( transform, mat ) ______________________method
  Returns:  affine matrix with same dimensions as mat
  
  A  basis change transform of an n dimensional space induces a transformation
  on  affine mappings on this space. If mat is a affine matrix (in particular,
  it  is  (n+1)x  (n+1)), this method returns the image of mat under the basis
  transformation induced by transform.
  
  ---------------------------  Example  ----------------------------
    gap> c:=[[0,1],[1,0]];
    [ [ 0, 1 ], [ 1, 0 ] ]
    gap> m:=[[1/2,0,0],[0,2/3,0],[1,0,1]];
    [ [ 1/2, 0, 0 ], [ 0, 2/3, 0 ], [ 1, 0, 1 ] ]
    gap> BasisChangeAffineMatOnRight(c,m);
    [ [ 2/3, 0, 0 ], [ 0, 1/2, 0 ], [ 0, 1, 1 ] ]
  ------------------------------------------------------------------
  
  2.2-3 TranslationOnRightFromVector
  
  > TranslationOnRightFromVector( v ) __________________________________method
  Returns:  Affine matrix
  
  Given  a  vector v with n entries, this method returns a (n+1)x (n+1) matrix
  which corresponds to the affine translation defined by v.
  
  ---------------------------  Example  ----------------------------
    gap> m:=TranslationOnRightFromVector([1,2,3]);;
    gap> Display(m);
    [ [  1,  0,  0,  0 ],
      [  0,  1,  0,  0 ],
      [  0,  0,  1,  0 ],
      [  1,  2,  3,  1 ] ]
    gap> LinearPartOfAffineMatOnRight(m);
    [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]
    gap> BasisChangeAffineMatOnRight([[3,2,1],[0,1,0],[0,0,1]],m);
    [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 3, 4, 4, 1 ] ]
  ------------------------------------------------------------------
  
  
  2.3 Geometry
  
  2.3-1 GramianOfAverageScalarProductFromFiniteMatrixGroup
  
  > GramianOfAverageScalarProductFromFiniteMatrixGroup( G ) ____________method
  Returns:  Symmetric positive definite matrix
  
  For  a  finite  matrix  group  G,  the  gramian matrix of the average scalar
  product  is  returned. This is the sum over all gg^t with gin G (actually it
  is  enough to take a generating set). The group G is orthogonal with respect
  to the scalar product induced by the returned matrix.
  
  
  2.3-2 Inequalities
  
  Inequalities  are  represented  in  the  same  way  they  are represented in
  polymaking.  The  vector (v_0,...,v_n) represents the inequality 0<= v_0+v_1
  x_1+... + v_n x_n.
  
  2.3-3 BisectorInequalityFromPointPair
  
  > BisectorInequalityFromPointPair( v1, v2[, gram] ) __________________method
  Returns:  vector of length Length(v1)+1
  
  Calculates  the  inequality  defining the half-space containing v1 such that
  v1-v2  is  perpendicular  on  the  bounding  hyperplane.  And  (v1-v2)/2  is
  contained in the bounding hyperplane.
  If  the  matrix gram is given, it is used as the gramian matrix. Otherwiese,
  the  standard  scalar product is used. It is not checked if gram is positive
  definite or symmetric.
  
  2.3-4 WhichSideOfHyperplane
  
  > WhichSideOfHyperplane( v, ineq ) ___________________________________method
  > WhichSideOfHyperplaneNC( v, ineq ) _________________________________method
  Returns:  -1 (below) 0 (in) or 1 (above).
  
  Let v be a vector of length n and ineq an inequality represented by a vector
  of  length  n+1.  Then  WhichSideOfHyperplane(v,  ineq)  returns 1 if v is a
  solution  of the inequality but not the equation given by ineq, it returns 0
  if  v  is  a  solution to the equation and -1 if it is not a solution of the
  inequality ineq.
  
  The NC version does not test the input for correctness.
  
  ---------------------------  Example  ----------------------------
    gap> BisectorInequalityFromPointPair([0,0],[1,0]);
    [ 1, -2, 0 ]
    gap> ineq:=BisectorInequalityFromPointPair([0,0],[1,0],[[5,4],[4,5]]);
    [ 5, -10, -8 ]
    gap> ineq{[2,3]}*[1/2,0];
    -5
    gap> WhichSideOfHyperplane([0,0],ineq);
    1
    gap> WhichSideOfHyperplane([1/2,0],ineq);
    0
  ------------------------------------------------------------------
  
  2.3-5 RelativePositionPointAndPolygon
  
  > RelativePositionPointAndPolygon( point, poly ) _____________________method
  Returns:  one of "VERTEX", "FACET", "OUTSIDE", "INSIDE"
  
  Let  poly  be  a  PolymakeObject and point a vector. If point is a vertex of
  poly,  the  string "VERTEX" is returned. If point lies inside poly, "INSIDE"
  is returned and if it lies in a facet, "FACET" is returned and if point does
  not lie inside poly, the function returns "OUTSIDE".
  
  
  2.4 Space Groups
  
  2.4-1 PointGroupRepresentatives
  
  > PointGroupRepresentatives( group ) ______________________________attribute
  > PointGroupRepresentatives( group ) _________________________________method
  Returns:  list of matrices
  
  Given  an  AffineCrystGroupOnLeftOrRight  group,  this  returns  a  list  of
  representatives  of  the  point  group  of  group.  That  is,  a  system  of
  representatives  for  the  factor  group  modulo  translations.  This  is an
  attribute of AffineCrystGroupOnLeftOrRight