11 Internal functions
  
  
  11.1 Matrices as G-generators of a FG-module vector space
  
  Both FpGModuleGF (Chapter 5) and FpGModuleHomomorphismGF (Chapter 6) store a
  matrix whose rows are G-generators for a module vector space (the module and
  the  homomorphism's  image respectively). The internal functions listed here
  provide common operations for dealing with these matrices.
  
  11.1-1 HAPPRIME_ValueOptionMaxFGExpansionSize
  
  > HAPPRIME_ValueOptionMaxFGExpansionSize( field, group ) __________operation
  Returns:  Integer
  
  Returns   the   maximum  matrix  expansion  size.  This  is  read  from  the
  MaxFGExpansionSize  option  from  the  GAP options stack 'Reference: Options
  Stack', computed using the MaxFGExpansionMemoryLimit option.
  
  11.1-2 HAPPRIME_KernelOfGeneratingRowsDestructive
  
  > HAPPRIME_KernelOfGeneratingRowsDestructive( gens, rowlengths, GA ) operation
  Returns:  List
  
  Returns  a  list  of  generating  vectors  for  the  kernel of the FG-module
  homomorphism  defined by the generating rows gens using the group and action
  GA.
  
  This function computes the kernel recursively by partitioning the generating
  rows into
  
  
       [ B 0 ] [ C D ]
  
  
  doing  column reduction if necessary to get the zero block at the top right.
  The matrices B> and C are small enough to be expanded, while the kernel of D
  is  calculated  by  recursion.  The  argument rowlengths lists the number of
  non-zero  blocks in each row; the rest of each row is taken to be zero. This
  allows  the  partitioning  to  be  more  efficiently  performed (i.e. column
  reduction is not always required).
  
  The GAP options stack 'Reference: Options Stack' variable MaxFGExpansionSize
  can  be  used  to  specify  the maximum allowable expanded matrix size. This
  governs  the size of the B and C matrices, and thus the number of recursions
  before  the kernel of D is also computed by recursion. A high value for will
  allow  larger  expansions  and  so  faster  computation  at the cost of more
  memory.  The  MaxFGExpansionMemoryLimit  option can also be used, which sets
  the  maximum  amount  of  memory  that  GAP  is  allowed to use (as a string
  containing  an  integer  with  the  suffix  k,  M or G to indicate kilobyes,
  megabytes  or  gigabytes  respectively). In this case, the function looks at
  the  free  memory  available  to  GAP  and computes an appropriate value for
  MaxFGExpansionSize.
  
  11.1-3 HAPPRIME_GActMatrixColumns
  
  > HAPPRIME_GActMatrixColumns( g, Vt, GA ) _________________________operation
  > HAPPRIME_GActMatrixColumnsOnRight( g, Vt, GA ) __________________operation
  Returns:  Matrix
  
  Returns  the matrix that results from the applying the group action u=gv (or
  u=vg  in  the  case  of the OnRight version of this function) to each column
  vector  in  the  matrix  Vt.  By  acting  on  columns  of a matrix (i.e. the
  transpose  of  the  normal  GAP  representation), the group action is just a
  permutation  of the rows of the matrix, which is a fast operation. The group
  and action are passed in GA using the ModuleGroupAndAction (5.4-5) record.
  
  If  the  input  matrix Vt is in a compressed matrix representation, then the
  returned matrix will also be in compressed matrix representation.
  
  11.1-4 HAPPRIME_ExpandGeneratingRow
  
  > HAPPRIME_ExpandGeneratingRow( gen, GA ) _________________________operation
  > HAPPRIME_ExpandGeneratingRows( gens, GA ) _______________________operation
  > HAPPRIME_ExpandGeneratingRowOnRight( gen, GA ) __________________operation
  > HAPPRIME_ExpandGeneratingRowsOnRight( gens, GA ) ________________operation
  Returns:  List
  
  Returns  a list of G-generators for the vector space that corresponds to the
  of G-generator gen (or generators gens). This space is formed by multiplying
  each  generator  by  each  element  of G in turn, using the group and action
  specified  in  GA  (see  ModuleGroupAndAction (5.4-5)). The returned list is
  thus |G| times larger than the input.
  
  For    a    list    of    generators    gens    [v_1,    v_2,   ...,   v_n],
  HAPPRIME_ExpandGeneratingRows returns the list [g_1v_1, g_2v_1, ..., g_1v_2,
  g_2v_2,  ...,  g_|G|v_n]  In other words, the form of the returned matrix is
  block-wise,  with the expansions of each row given in turn. This function is
  more  efficient  than  repeated use of HAPPRIME_ExpandGeneratingRow since it
  uses  the efficient HAPPRIME_GActMatrixColumns (11.1-3) to perform the group
  action on the whole set of generating rows at a time.
  
  The  function HAPPRIME_ExpandGeneratingRowsOnRight is the same as above, but
  the group action operates on the right instead.
  
  11.1-5 HAPPRIME_AddGeneratingRowToSemiEchelonBasisDestructive
  
  > HAPPRIME_AddGeneratingRowToSemiEchelonBasisDestructive( basis, gen, GA ) operation
  Returns:  Record with elements vectors and basis
  
  This  function  augments  a  vector  space  basis with another generator. It
  returns  a record consisting of two elements: vectors, a set of semi-echelon
  basis vectors for the vector space spanned by the sum of the input basis and
  all  G-multiples of the generating vector gen; and heads, a list of the head
  elements,  in  the  same  format  as  returned by SemiEchelonMat (Reference:
  SemiEchelonMat).  The  generator  gen is expanded according to the group and
  action specified in the GA record (see ModuleGroupAndAction (5.4-5)).
  
  If  the input basis is not zero, it is also modified by this function, to be
  the new basis (i.e. the same as the vectors element of the returned record).
  
  11.1-6 HAPPRIME_ReduceVectorDestructive
  
  > HAPPRIME_ReduceVectorDestructive( v, basis, heads ) _____________operation
  Returns:  Boolean
  
  Reduces  the vector v (in-place) using the semi-echelon set of vectors basis
  with    heads    heads    (as   returned   by   SemiEchelonMat   (Reference:
  SemiEchelonMat)).  Returns true if the vector is completely reduced to zero,
  or false otherwise.
  
  
  11.1-7 HAPPRIME_ReduceGeneratorsOfModuleByXX
  
  > HAPPRIME_ReduceGeneratorsOfModuleBySemiEchelon( gens, GA ) ______operation
  > HAPPRIME_ReduceGeneratorsOfModuleBySemiEchelonDestructive( gens, GA ) operation
  > HAPPRIME_ReduceGeneratorsOfModuleByLeavingOneOut( gens, GA ) ____operation
  > HAPPRIME_ReduceGeneratorsOnRightByLeavingOneOut( gens, GA ) _____operation
  Returns:  List of vectors
  
  Returns  a  subset  of the module generators gens over the group with action
  specified  in  the  GA  record  (see ModuleGroupAndAction (5.4-5)) that will
  still generate the module.
  
  The  BySemiEchelon functions gradually expand out the module generators into
  an  F-basis,  using  that  F-basis to reduce the other generators, until the
  full  vector  space  of the module is spanned. The generators needed to span
  the space are returned, and should be a small set, although not minimal. The
  Destructive  version  of this function will modify the input gens parameter.
  The  non-destructive  version  makes  a  copy  first,  so  leaves  the input
  arguments unchanged, at the expense of more memory.
  
  The ByLeavingOneOut function is tries repeatedly leaving out generators from
  the list gens to find a small subset that still generates the module. If the
  generators  are from the field GF(2), this is guaranteed to be a minimal set
  of generators. The OnRight version computes a minimal subset which generates
  the module under group multiplication on the right.
  
  11.1-8 HAPPRIME_DisplayGeneratingRows
  
  > HAPPRIME_DisplayGeneratingRows( gens, GA ) ______________________operation
  Returns:  nothing
  
  Displays  a  set of G-generating rows a human-readable form. The elements of
  each  generating vector are displayed, with each block marked by a separator
  (since the group action on a module vector will only permute elements within
  a block).
  
  This    function   is   used   by   Display   for   both   FpGModuleGF   and
  FpGModuleHomomorphismGF.
  
  NOTE: This is currently only implemented for GF(2)
  
  ---------------------------  Example  ----------------------------
    gap> HAPPRIME_DisplayGeneratingRows(
    >  ModuleGenerators(M), HAPPRIME_ModuleGroupAndAction(M));
    [...1..11|........|.......1|........|........]
    [........|........|........|.1....11|........]
    [........|........|........|........|..1.1.1.]
    [........|.1.1..1.|........|........|........]
    [........|........|......11|........|........]
    [........|........|1......1|........|........]
  ------------------------------------------------------------------
  
  11.1-9 HAPPRIME_GeneratingRowsBlockStructure
  
  > HAPPRIME_GeneratingRowsBlockStructure( gens, GA ) _______________operation
  Returns:  Matrix
  
  Returns a matrix detailing the block structure of a set of module generating
  rows.  The  group  action  on  a  generator permutes the vector in blocks of
  length  GA.actionBlockSize:  any  block that contains non-zero elements will
  still  contain  non-zero  elements after the group action; any block that is
  all  zero  will remain all zero. This operation returns a matrix giving this
  block structure: it has a one where the block is non-zero and zero where the
  block is all zero.
  
  ---------------------------  Example  ----------------------------
    gap> b := HAPPRIME_GeneratingRowsBlockStructure(
    >  ModuleGenerators(M), ModuleActionBlockSize(M));
    [ [ 1, 0, 1, 1, 1 ], [ 1, 0, 1, 1, 1 ], [ 0, 1, 1, 1, 1 ], [ 0, 0, 1, 1, 1 ] ]
  ------------------------------------------------------------------
  
  11.1-10 HAPPRIME_DisplayGeneratingRowsBlocks
  
  > HAPPRIME_DisplayGeneratingRowsBlocks( gens, actionBlockSize ) ___operation
  Returns:  nothing
  
  Displays  a  set  of  G-generating  rows a compact human-readable form. Each
  generating  rows  can  be divided into blocks of length actionBlockSize. The
  generating  rows  are  displayed in a per-block form: a * where the block is
  non-zero and . where the block is all zero.
  
  This  function  is  used  by  DisplayBlocks  (5.4-10)  (for FpGModuleGF) and
  DisplayBlocks (6.5-4) (for FpGModuleHomomorphismGF).
  
  ---------------------------  Example  ----------------------------
    gap> HAPPRIME_DisplayGeneratingRowsBlocks(
    >  ModuleGenerators(M), HAPPRIME_ModuleGroupAndAction(M));
    [*.*..]
    [...*.]
    [....*]
    [.*...]
    [..*..]
    [..*..] 
  ------------------------------------------------------------------
  
  11.1-11 HAPPRIME_IndependentGeneratingRows
  
  > HAPPRIME_IndependentGeneratingRows( blocks ) ____________________operation
  Returns:  List of lists
  
  Given a block structure as returned by HAPPRIME_GeneratingRowsBlockStructure
  (11.1-9),  this decomposes a set of generating rows into sets of independent
  rows.  These  are  returned as a list of row indices, where each set of rows
  share no blocks with any other set.
  
  ---------------------------  Example  ----------------------------
    gap> DisplayBlocks(M);
    Module over the group ring of Group( [ f1, f2, f3 ] )
     in characteristic 2 with 6 generators in FG^5.
    [**...]
    [.*...]
    [.**..]
    [.**..]
    [...*.]
    [....*]
    Generators are in minimal echelon form.
    gap> gens := ModuleGenerators(M);;
    gap> G := ModuleGroup(M);;
    gap> blocks := HAPPRIME_GeneratingRowsBlockStructure(gens, G);
    [ [ 1, 1, 0, 0, 0 ], [ 0, 1, 0, 0, 0 ], [ 0, 1, 1, 0, 0 ], [ 0, 1, 1, 0, 0 ],
      [ 0, 0, 0, 1, 0 ], [ 0, 0, 0, 0, 1 ] ]
    gap> HAPPRIME_IndependentGeneratingRows(blocks);
    [ [ 1, 2, 3, 4 ], [ 5 ], [ 6 ] ]
  ------------------------------------------------------------------
  
  11.1-12 HAPPRIME_GactFGvector
  
  > HAPPRIME_GactFGvector( g, v, MT ) _______________________________operation
  Returns:  Vector
  
  Returns  the  vector  that  is  the  result  of the action u=gv of the group
  element  g on a module vector v (according to the group multiplication table
  MT.  This  operation  is the quickest current method for a single vector. To
  perform  the same action on a set of vectors, it is faster write the vectors
  as columns of a matrix and use HAPPRIME_GActMatrixColumns (11.1-3) instead.
  
  
  11.1-13 HAPPRIME_CoefficientsOfGeneratingRowsXX
  
  > HAPPRIME_CoefficientsOfGeneratingRows( gens, GA, v ) ____________operation
  > HAPPRIME_CoefficientsOfGeneratingRows( gens, GA, coll ) _________operation
  > HAPPRIME_CoefficientsOfGeneratingRowsDestructive( gens, GA, v ) _operation
  > HAPPRIME_CoefficientsOfGeneratingRowsDestructive( gens, GA, coll ) operation
  > HAPPRIME_CoefficientsOfGeneratingRowsGF( gens, GA, v ) __________operation
  > HAPPRIME_CoefficientsOfGeneratingRowsGF( gens, GA, coll ) _______operation
  > HAPPRIME_CoefficientsOfGeneratingRowsGFDestructive( gens, GA, v ) operation
  > HAPPRIME_CoefficientsOfGeneratingRowsGFDestructive( gens, GA, coll ) operation
  > HAPPRIME_CoefficientsOfGeneratingRowsGFDestructive2( gens, GA, v ) operation
  > HAPPRIME_CoefficientsOfGeneratingRowsGFDestructive2( gens, GA, coll ) operation
  Returns:  Vector, or list of vectors
  
  For  a  single  vector  v,  this  function  returns  a  vector  x giving the
  G-coefficients  from  gens  needed  to  generate v, i.e. the solution to the
  equation  x*A=v,  where A is the expansion of gens. If there is no solution,
  fail is returned. If a list of vectors, coll, then a vector is returned that
  lists  the solution for each vector (any of which may be fail). The standard
  forms  of  this  function  use  standard  linear  algebra  to  solve for the
  coefficients.  The  Destructive version will corrupt both gens and v. The GF
  versions  use  the block structure of the generating rows to expand only the
  blocks  that are needed to find the solution before using linear algebra. If
  the generators are in echelon form, this can save memory, but is slower.
  
  The GFDestructive2 functions also assume an echelon form for the generators,
  but use back-substitution to find a set of coefficients. This can save a lot
  of memory but is again slower.
  
  
  11.1-14 HAPPRIME_GenerateFromGeneratingRowsCoefficientsXX
  
  > HAPPRIME_GenerateFromGeneratingRowsCoefficients( gens, GA, c ) __operation
  > HAPPRIME_GenerateFromGeneratingRowsCoefficients( gens, GA, coll ) operation
  > HAPPRIME_GenerateFromGeneratingRowsCoefficientsGF( gens, GA, c ) operation
  > HAPPRIME_GenerateFromGeneratingRowsCoefficientsGF( gens, GA, coll ) operation
  Returns:  Vector, or list of vectors
  
  For  a  vector  c,  returns  (as  a vector), the module element generated by
  multiplying  c  by  the  expansion  of  the  generators  gens. For a list of
  coefficient vectors coll, this returns a list of generating vectors.
  
  The  standard  versions of this function use standard linear algebra. The GF
  versions  only performs the expansion of necessary generating rows, and only
  expands  by one group element at a time, so will only need at most twice the
  amount  of  memory  as  that  to  store  gens,  which is a large saving over
  expanding  the  generators  by every group element at the same time, as in a
  naive implementation. It may also be faster.
  
  11.1-15 HAPPRIME_RemoveZeroBlocks
  
  > HAPPRIME_RemoveZeroBlocks( gens, GA ) ___________________________operation
  Returns:  Vector
  
  Removes  from  a  set  of generating vectors gens (with ModuleGroupAndAction
  (5.4-5)  GA) any blocks that are zero in every generating vector. Removal is
  done  in-place,  i.e. the input argument gens will be modified to remove the
  zero  blocks.  Zero blocks are unaffected by any row or expansion operation,
  and  can be removed to save time or memory in those operations. The function
  returns  the  original  block structure as a vector, and this can be used in
  the  function  HAPPRIME_AddZeroBlocks (11.1-16) to reinstate the zero blocks
  later,  if required. See the documentation for that function for more detail
  of the block structure vector.
  
  11.1-16 HAPPRIME_AddZeroBlocks
  
  > HAPPRIME_AddZeroBlocks( gens, blockStructure, GA ) ______________operation
  Returns:  List of vectors
  
  Adds  zero  blocks  to  a set of generating vectors gens to make it have the
  block  structure  given  in blockStructure (for a given ModuleGroupAndAction
  (5.4-5) GA). The generators gens are modified in place, and also returned.
  
  The  blockStructure  parameter  is  a  vector  of which is the length of the
  required  output  vector  and  has zeros where zero blocks should be, and is
  non-zero  elsewhere. Typically, an earlier call to HAPPRIME_RemoveZeroBlocks
  (11.1-15)  will  have been used to remove the zero blocks, and this function
  and   such   a   blockStructure   vector   is  returned  by  this  function.
  HAPPRIME_AddZeroBlocks can be used to reinstate these zero blocks.
  
  
  11.2 FG-modules
  
  FG-modules in HAPprime use the datatype FpGModuleGF (Chapter 5). Internally,
  this uses many of the functions listed in Section 11.1, and further internal
  functions are listed below.
  
  11.2-1 HAPPRIME_DirectSumForm
  
  > HAPPRIME_DirectSumForm( current, new ) __________________________operation
  Returns:  String
  
  Returns  a  string containing the form of the generator matrix if the direct
  sum  is formed between a FpGModuleGF with the form current and a FpGModuleGF
  with  the  form  new.  The  direct  sum  is formed by placing the two module
  generating  matrices  in diagonal form. Given the form of the two generating
  matrices,  this  allows  the  form  of  the  direct  sum  to  be stated. See
  ModuleGeneratorsForm (5.5-5) for information about form strings.
  
  11.2-2 HAPPRIME_PrintModuleDescription
  
  > HAPPRIME_PrintModuleDescription( M, func ) ______________________operation
  Returns:  nothing
  
  Used  by  PrintObj  (Reference:  PrintObj),  ViewObj  (Reference:  ViewObj),
  Display   (Reference:  Display)  and  DisplayBlocks  (5.4-10),  this  helper
  function prints a description of the module M. The parameter func can be one
  of  the strings "print", "view", "display" or "displayblocks", corresponding
  to the print different functions that might be called.
  
  
  11.2-3 HAPPRIME_ModuleGeneratorCoefficients
  
  > HAPPRIME_ModuleGeneratorCoefficients( M, elm ) __________________operation
  > HAPPRIME_ModuleGeneratorCoefficientsDestructive( M, elm ) _______operation
  > HAPPRIME_ModuleGeneratorCoefficients( M, coll ) _________________operation
  > HAPPRIME_ModuleGeneratorCoefficientsDestructive( M, coll ) ______operation
  Returns:  Vector
  
  Returns  the  coefficients needed to make the module element elm as a linear
  and  G-combination  of  the  module  generators  of  the  FpGModuleGF M. The
  coefficients  are  returned  in  standard  vector  form,  or  if there is no
  solution  then fail is returned. If a list of elements is given, then a list
  of  coefficients  (or  fails)  is  returned.  The  Destructive  form of this
  function  might  change  the  elements  of  of M or elm. The non-Destructive
  version makes copies to ensure that they are not changed.
  
  See also HAPPRIME_ModuleElementFromGeneratorCoefficients (11.2-4).
  
  
  11.2-4 HAPPRIME_ModuleElementFromGeneratorCoefficients
  
  > HAPPRIME_ModuleElementFromGeneratorCoefficients( M, c ) _________operation
  > HAPPRIME_ModuleElementFromGeneratorCoefficients( M, coll ) ______operation
  Returns:  Vector
  
  Returns  an  element from the module M, constructed as a linear and G-sum of
  the module generators as specified in c. If a list of coefficient vectors is
  given, a list of corresponding module elements is returned.
  
  See also HAPPRIME_ModuleGeneratorCoefficients (11.2-3)
  
  11.2-5 HAPPRIME_MinimalGeneratorsVectorSpaceGeneratingRowsDestructive
  
  > HAPPRIME_MinimalGeneratorsVectorSpaceGeneratingRowsDestructive( vgens, GA ) operation
  > HAPPRIME_MinimalGeneratorsVectorSpaceGeneratingRowsOnRightDestructive( vgens, GA ) operation
  Returns:  FpGModuleGF
  
  Returns a module with minimal generators that is equal to the FG-module with
  vector  space  basis  vgens and ModuleGroupAndAction (5.4-5) as specified in
  GA.  The solution is computed by the module radical method, which is fast at
  the expense of memory. This function will corrupt the matrix gens.
  
  This is a helper function for MinimalGeneratorsModuleRadical (5.5-9) that is
  also     used     by    ExtendResolutionPrimePowerGroupRadical    (HAPprime:
  ExtendResolutionPrimePowerGroupRadical)  (which  knows  that  its  module is
  already in vector-space form).
  
  11.2-6 HAPPRIME_IsGroupAndAction
  
  > HAPPRIME_IsGroupAndAction( obj ) ________________________________operation
  Returns:  Boolean
  
  Returns   true   if   obj   appears  to  be  a  groupAndAction  record  (see
  ModuleGroupAndAction (5.4-5)), or false otherwise.
  
  
  11.3 Resolutions
  
  For  details  of the main resolution functions in HAPprime, see Chapter 2 of
  this datatypes reference manual, and 'HAPprime: Resolutions' in the HAPprime
  user guide. This section describes the internal helper functions used by the
  higher-level functions.
  
  11.3-1 HAPPRIME_WordToVector
  
  > HAPPRIME_WordToVector( w, dim, orderG ) ____________________________method
  Returns:  HAP word (list of lists)
  
  Returns  the  boundary  map vector that corresponds to the HAP word vector w
  with  module ambient dimension dim and group order orderG (assumed to be the
  actionBlockSize).  A  HAP  word  vector  has the following format: [ [block,
  elm],  [block,  elm], ... ] where block is a block number and elm is a group
  element index (see example below).
  
  See also HAPPRIME_VectorToWord (11.3-2)
  
  ---------------------------  Example  ----------------------------
    gap> G := CyclicGroup(4);;
    gap> v := HAPPRIME_WordToVector([ [1,2],[2,3] ], 2, Order(G));
    <a GF2 vector of length 8>
    gap> HAPPRIME_DisplayGeneratingRows([v], CanonicalGroupAndAction(G));
    [.1..|..1.]
    gap> HAPPRIME_VectorToWord(v, Order(G));
    [ [ 1, 2 ], [ 2, 3 ] ]
  ------------------------------------------------------------------
  
  11.3-2 HAPPRIME_VectorToWord
  
  > HAPPRIME_VectorToWord( vec, orderG ) _____________________________function
  Returns:  Vector
  
  The  HAP word format vector that corresponds to the boundary vector vec with
  actionBlockSize assumed to be orderG.
  
  See HAPPRIME_WordToVector (11.3-1) for a few more details and an example.
  
  11.3-3 HAPPRIME_BoundaryMatrices
  
  > HAPPRIME_BoundaryMatrices( R ) __________________________________attribute
  Returns:  List of matrices
  
  If R is a resolution which stores its boundaries as a list of matrices (e.g.
  one created by HAPprime, this list is returned. Otherwise, fail is returned.
  Note  that  the  first matrix in this list corresponds to the zeroth degree:
  for  resolutions  of  modules,  this  is  the  generators of the module; for
  resolutions  of  groups,  this  is  the  empty  matrix.  The  second  matrix
  corresponds to the first degree, and so on.
  
  11.3-4 HAPPRIME_AddNextResolutionBoundaryMapMatNC
  
  > HAPPRIME_AddNextResolutionBoundaryMapMatNC( R, BndMat ) _________operation
  Returns:  HapResolution
  
  Returns  the  resolution R extended by one term, where that term is given by
  the  boundary  map  matrix  BndMat.  If  BndMat is not already in compressed
  matrix form, it will be converted into this form, and if the boundaries in R
  are not already in matrix form, they are all converted into this form.
  
  11.3-5 HAPPRIME_CreateResolutionWithBoundaryMapMatsNC
  
  > HAPPRIME_CreateResolutionWithBoundaryMapMatsNC( G, BndMats ) ____operation
  Returns:  HapResolution
  
  Returns  a  HAP resolution object for group G where the module homomorphisms
  are given by the boundary matrices in the list BndMats. This list is indexed
  with  the  boundary  matrix  for  degree  zero  as the first element. If the
  resolution  is  the  resolution of a module, the module's minimal generators
  are  this  first boundary matrix, otherwise (for the resolution of a group),
  this should be set to be the empty matrix [].
  
  
  11.4 Polynomial rings
  
  Ths  internal  functions  in  this  section  implement  isomorphisms between
  polynomial rings via maps from one set of indeterminates to another.
  
  11.4-1 HAPPRIME_SwitchPolynomialIndeterminates
  
  > HAPPRIME_SwitchPolynomialIndeterminates( R, S, poly ) ____________function
  Returns:  Polynomial or List of Polynomials
  
  Changes  the  indeterminates in poly, which should be a polynomial or a list
  of  polynomials,  substituting  the  indeterminates of the polynomial ring S
  one-for-one  for  those in R (from which all polynomials in poly must come).
  The  returned  object is either a polynomial or a list of polynomials in the
  new indeterminates, depending on the input object.
  
  See  HAPPRIME_MapPolynomialIndeterminates  (11.4-2)  for a function that can
  work with more general indeterminate maps.
  
  11.4-2 HAPPRIME_MapPolynomialIndeterminates
  
  > HAPPRIME_MapPolynomialIndeterminates( old, new, poly ) ___________function
  Returns:  Polynomial or List of Polynomials
  
  Changes  the  indeterminates in poly, which can be a polynomial or a list of
  polynomials,  substituting  the  polynomials  in  old  for those in new. The
  returned  object  is either a polynomial or a list of polynomials in the new
  indeterminates,  depending  on  the  input  object.  The  change of variable
  arguments, old and new, do not have to be simply indeterminates: they can be
  can  be  lists of polynomials which are equivalent in the two different sets
  of indeterminates. If a polynomial cannot be converted (i.e. if it cannot be
  generated  from  the  polynomials  in  old)  then  fail is returned for that
  polynomial.
  
  11.4-3 HAPPRIME_CombineIndeterminateMaps
  
  > HAPPRIME_CombineIndeterminateMaps( coeff, M, N ) _________________function
  Returns:  List
  
  Returns  the  indeterminate map that results from applying map M followed by
  map  N.  An  indeterminate  map is a list containing two lists, the first of
  which  is  a  list of polynomials in the original indeterminates, the second
  the equivalent polynomials in the new ring indeterminates.
  
  
  11.5 Gröbner Bases
  
  Ths  internal  functions  in this section provide a transparent way of using
  Singular's  Gröbner basis functions, if they are available. See the singular
  package  documentation  'singular:  singular: the GAP interface to Singular'
  for further details.
  
  11.5-1 HAPPRIME_SingularGroebnerBasis
  
  > HAPPRIME_SingularGroebnerBasis( pols, O ) ________________________function
  > HAPPRIME_SingularReducedGroebnerBasis( pols, O ) _________________function
  Returns:  List
  
  Returns  the  Gröbner  basis  (or reduced Gröbner basis) with respect to the
  ordering  O  for  the ideal generated by the polynomials pols. This function
  uses  the  Gröbner  basis  implementation  from singular, for preference, if
  available  (GroebnerBasis  (singular:  GroebnerBasis)),  and  if  so it also
  manuipulates  the  result  to  fix  a  bug  in  singular  where the returned
  polynomials   are   not   necessarily   returned   with   a  value  external
  representation   (see   'Reference:  The  Defining  Attributes  of  Rational
  Functions').
  
  If  the  option  obeyGBASIS  is  true, then this function will use whichever
  algorithm  is  specified  by  the GBASIS global variable (see SINGULARGBASIS
  (singular: SINGULARGBASIS)).
  
  
  11.6 Presentations of graded algebras
  
  For  the  main  functions dealing with presentations of graded algebras, and
  details  of  the  datatype  see Chapter 4. This section details the internal
  functions used by the higher-level functions.
  
  11.6-1 HAPPRIME_HilbertSeries
  
  > HAPPRIME_HilbertSeries( P ) _____________________________________attribute
  Returns:  List
  
  The  Hilbert-Poincaré  series for a graded ring is a polynomial H_P(t) whose
  coefficients  are  the  dimensions  of  each  degree  of the ring. It can be
  written as
  
  
       H_P(t) = Q(t) / (1-t^a)(1-t^b)...(1-t^n)
  
  
  This  function  returns  the list of coefficients for the polynomial Q(t) in
  the Hilbert Series for the graded algebra with presentation P.
  
  This  function  simply  calls  the  Singular  function hilb via the singular
  package and returns the result.
  
  11.6-2 HAPPRIME_SwitchGradedAlgebraRing
  
  > HAPPRIME_SwitchGradedAlgebraRing( A, R ) ________________________attribute
  Returns:  GradedAlgebraPresentation
  
  Returns  a  new  presentation for the graded algebra A which uses the ring R
  instead of the one in A.
  
  11.6-3 HAPPRIME_GradedAlgebraPresentationAvoidingIndeterminates
  
  > HAPPRIME_GradedAlgebraPresentationAvoidingIndeterminates( A, avoid ) attribute
  Returns:  GradedAlgebraPresentation
  
  Returns  a  new  presentation  for  the  graded  algebra  A which avoids the
  indeterminates listed in avoid.
  
  11.6-4 HAPPRIME_LastLHSBicomplexSize
  
  > HAPPRIME_LastLHSBicomplexSize______________________________global variable
  
  Stores  the  last  bicomplex  size last used by LHSSpectralSequenceLastSheet
  (4.4-10). Used for testing and generating results for paper.
  
  11.6-5 HAPPRIME_LHSSpectralSequence
  
  > HAPPRIME_LHSSpectralSequence( G, N, n ) _________________________operation
  Returns:  GradedAlgebraPresentation or list
  
  This   function   is   called   by  both  LHSSpectralSequence  (4.4-10)  and
  LHSSpectralSequenceLastSheet  (4.4-10) and does the actual work of computing
  the  Lyndon-Hoschild-Serre  spectral sequence for the group extension N -> G
  ->  G/N.  See  the  documentation  for those functions for the main details,
  including options that are passed through to this function.
  
  If  n is the string "Einf" then only the limiting sheet is returned (and the
  other  sheets  are  discarded  during  computation,  which can save time and
  memory).  Otherwise,  n  sheets are returned, or enough until convergence is
  proved, if that is smaller.
  
  11.6-6 HAPPRIME_CohomologyRingWithoutResolution
  
  > HAPPRIME_CohomologyRingWithoutResolution( G ) ____________________function
  Returns:  GradedAlgebraPresentation or fail
  
  If  the  mod-p  cohomology  ring  for  G  can be computed without building a
  resolution for G then this ring is returned, otherwise this function returns
  fail.
  
  Current cases where the resolution for G is not needed are
  
  --    if  G  is  the  group  of  order two then H^*(G, F) = F[x] where x has
        degree one
  
  --    if  G  is cyclic of order greater than two then H^*(G, F) = F[x,y]/x^2
        where x has degree one and y has degree two
  
  --    if  G  can  be  expressed  as  the direct sum of other groups then the
        cohomology  rings  for  those  groups are found (by recursive calls to
        ModPCohomologyRingPresentation                              (HAPprime:
        ModPCohomologyRingPresentation   (for   group)))  and  combined  using
        TensorProduct (4.4-1)
  
  11.6-7 HAPPRIME_Polynomial2Algebra
  
  > HAPPRIME_Polynomial2Algebra( A[, ringA], poly ) __________________function
  Returns:  Algebra element
  
  Converts  a polynomial poly in ringA (the mod-p cohomology ring presentation
  for  the cohomology algebra A) into the equivalent element in A. If ringA is
  not     provided,     it     is     recovered     using     the    attribute
  PresentationOfGradedStructureConstantAlgebra  (3.3-1). The ringA argument is
  provided  to  allow  cases  where the ring and polynomial use different (but
  isomorphic)       indeterminants       from      those      provided      by
  PresentationOfGradedStructureConstantAlgebra  (3.3-1)  (as  is  the  case in
  HAPPRIME_LHSSpectralSequence (11.6-5)).
  
  11.6-8 HAPPRIME_Algebra2Polynomial
  
  > HAPPRIME_Algebra2Polynomial( A, alg ) ____________________________function
  Returns:  Polynomial
  
  Converts  an algebra element alg in the mod-p cohomology algebra A (given by
  ModPCohomologyRing (HAP: ModPCohomologyRing)) into the equivalent polynomial
  from      the      corresponding     ring     presentation     (given     by
  PresentationOfGradedStructureConstantAlgebra (3.3-1)).
  
  
  11.7 Derivations
  
  The  kernel of a derivation is efficiently computed by writing the ring R as
  an  S-module  where  S is the subring of squares (or some larger ring in the
  kernel).  The  internal  function  in  this section is used to describe this
  S-module  and  allow  conversion  between  elements of R and elements of the
  S-module.
  
  11.7-1 HAPPRIME_SModule
  
  > HAPPRIME_SModule( R, exps ) ______________________________________function
  Returns:  Record
  
  For  a polynomial ring R, k[x_1, x_2, ..., x_n], and list of exponents exps,
  [e_1,  e_2,  ...,  e_n], returns a record which represents R as an S-module,
  where S is the subring of R given by k[x_1^e_1, x_2^e_2, ..., x_n^e_n]
  
  The record has the following components:
  
  --    Rring the original ring R
  
  --    Sring a ring isomorphic to the subring of powers S
  
  --    Spows the exponents exps
  
  --    generators the list of generators of R as an S-module
  
  --    FromPoly  a  function  which  takes  a polynomial in R and returns the
        corresponding element in the S-module (as a vector)
  
  --    ToPoly a function which takes an element in the S-module (as a vector)
        and returns the corresponding polynomial in R
  
  
  11.8 Test functions
  
  Internal helper functions for testing HAPprime.
  
  11.8-1 HAPPRIME_VersionWithSVN
  
  > HAPPRIME_VersionWithSVN(  ) ______________________________________function
  Returns:  String
  
  Returns   a  string  giving  a  current  version  number  for  the  HAPprime
  installation  assuming  that it is checked out from a subversion repository.
  This  fetches  the current version number from PackageInfo.g and appends the
  return  of the svnversion program to this, returning the resulting composite
  string.
  
  ---------------------------  Example  ----------------------------
    gap> HAPPRIME_VersionWithSVN();
    "0.2.1.302:319M"
  ------------------------------------------------------------------
  
  11.8-2 HAPPRIME_Random2Group
  
  > HAPPRIME_Random2Group( [orderG] ) _______________________________operation
  > HAPPRIME_Random2GroupAndAction( [orderG] ) ______________________operation
  Returns:  Group or groupAndAction record
  
  Returns    a    random    2-group,   or   a   groupAndAction   record   (see
  ModuleGroupAndAction  (5.4-5))  with  the canonical action. The order may be
  specified  as an argument, or if not then a group is chosen randomly (from a
  uniform  distribution)  over all of the possible groups with order from 2 to
  128.
  
  ---------------------------  Example  ----------------------------
    gap> HAPPRIME_Random2Group();
    <pc group of size 8 with 3 generators>
    gap> HAPPRIME_Random2Group();
    <pc group of size 32 with 5 generators>
  ------------------------------------------------------------------
  
  11.8-3 HAPPRIME_TestResolutionPrimePowerGroup
  
  > HAPPRIME_TestResolutionPrimePowerGroup( [ntests] ) ______________operation
  Returns:  Boolean
  
  Returns       true       if      ResolutionPrimePowerGroupGF      (HAPprime:
  ResolutionPrimePowerGroupGF            (for            group))           and
  ResolutionPrimePowerGroupRadical (HAPprime: ResolutionPrimePowerGroupRadical
  (for  group))  appear  to  be  working  correctly,  or false otherwise. This
  repeatedly  creates resolutions of length 6 for random 2-groups (up to order
  128)  using  both  of  the HAPprime resolution algorithms, and compares them
  both    with    the    original    HAP    ResolutionPrimePowerGroup    (HAP:
  ResolutionPrimePowerGroup)  and  checks  that  they  are equal. The optional
  argument ntests specifies how many resolutions to try: the default is 25.