  
  [1X6 [33X[0;0YInternal functions[133X[101X
  
  
  [1X6.1 [33X[0;0YMatrices as [22XG[122X[101X[1X-generators of a [22XFG[122X[101X[1X-module vector space[133X[101X
  
  [33X[0;0YBoth [9XFpGModuleGF[109X (Chapter [14X3[114X) and [9XFpGModuleHomomorphismGF[109X (Chapter [14X4[114X) store a
  matrix whose rows are [22XG[122X-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.[133X
  
  [1X6.1-1 HAPPRIME_ValueOptionMaxFGExpansionSize[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_ValueOptionMaxFGExpansionSize[102X( [3Xfield[103X, [3Xgroup[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YInteger[133X
  
  [33X[0;0YReturns   the   maximum  matrix  expansion  size.  This  is  read  from  the
  [10XMaxFGExpansionSize[110X  option  from  the  [5XGAP[105X options stack [14X'Reference: Options
  Stack'[114X, computed using the [10XMaxFGExpansionMemoryLimit[110X option.[133X
  
  [1X6.1-2 HAPPRIME_KernelOfGeneratingRowsDestructive[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_KernelOfGeneratingRowsDestructive[102X( [3Xgens[103X, [3Xrowlengths[103X, [3XGA[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YList[133X
  
  [33X[0;0YReturns  a  list  of  generating  vectors  for  the  kernel of the [22XFG[122X-module
  homomorphism  defined by the generating rows [3Xgens[103X using the group and action
  [3XGA[103X.[133X
  
  [33X[0;0YThis function computes the kernel recursively by partitioning the generating
  rows into[133X
  
  
  [24X[33X[0;6Y[ B 0 ] [ C D ][133X
  
  [124X
  
  [33X[0;0Ydoing  column reduction if necessary to get the zero block at the top right.
  The matrices [22XB>[122X and [22XC[122X are small enough to be expanded, while the kernel of [22XD[122X
  is  calculated  by  recursion.  The  argument [3Xrowlengths[103X 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).[133X
  
  [33X[0;0YThe [5XGAP[105X options stack [14X'Reference: Options Stack'[114X variable [10XMaxFGExpansionSize[110X
  can  be  used  to  specify  the maximum allowable expanded matrix size. This
  governs  the size of the [22XB[122X and [22XC[122X matrices, and thus the number of recursions
  before  the kernel of [22XD[122X is also computed by recursion. A high value for will
  allow  larger  expansions  and  so  faster  computation  at the cost of more
  memory.  The  [10XMaxFGExpansionMemoryLimit[110X  option can also be used, which sets
  the  maximum  amount  of  memory  that  [5XGAP[105X  is  allowed to use (as a string
  containing  an  integer  with  the  suffix  [10Xk[110X,  [10XM[110X or [10XG[110X to indicate kilobyes,
  megabytes  or  gigabytes  respectively). In this case, the function looks at
  the  free  memory  available  to  [5XGAP[105X  and computes an appropriate value for
  [10XMaxFGExpansionSize[110X.[133X
  
  [1X6.1-3 HAPPRIME_GActMatrixColumns[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_GActMatrixColumns[102X( [3Xg[103X, [3XVt[103X, [3XGA[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_GActMatrixColumnsOnRight[102X( [3Xg[103X, [3XVt[103X, [3XGA[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YMatrix[133X
  
  [33X[0;0YReturns  the matrix that results from the applying the group action [22Xu=gv[122X (or
  [22Xu=vg[122X  in  the  case  of the [10XOnRight[110X version of this function) to each [13Xcolumn[113X
  vector  in  the  matrix  [3XVt[103X.  By  acting  on  [13Xcolumns[113X  of a matrix (i.e. the
  transpose  of  the  normal  [5XGAP[105X  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 [3XGA[103X using the [2XModuleGroupAndAction[102X ([14X3.4-5[114X) record.[133X
  
  [33X[0;0YIf  the  input  matrix [3XVt[103X is in a compressed matrix representation, then the
  returned matrix will also be in compressed matrix representation.[133X
  
  [1X6.1-4 HAPPRIME_ExpandGeneratingRow[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_ExpandGeneratingRow[102X( [3Xgen[103X, [3XGA[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_ExpandGeneratingRows[102X( [3Xgens[103X, [3XGA[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_ExpandGeneratingRowOnRight[102X( [3Xgen[103X, [3XGA[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_ExpandGeneratingRowsOnRight[102X( [3Xgens[103X, [3XGA[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YList[133X
  
  [33X[0;0YReturns  a list of [22XG[122X-generators for the vector space that corresponds to the
  of [22XG[122X-generator [3Xgen[103X (or generators [3Xgens[103X). This space is formed by multiplying
  each  generator  by  each  element  of [3XG[103X in turn, using the group and action
  specified  in  [3XGA[103X  (see  [2XModuleGroupAndAction[102X ([14X3.4-5[114X)). The returned list is
  thus [22X|G|[122X times larger than the input.[133X
  
  [33X[0;0YFor    a    list    of    generators    [3Xgens[103X    [22X[v_1,    v_2,   ...,   v_n][122X,
  [2XHAPPRIME_ExpandGeneratingRows[102X returns the list [22X[g_1v_1, g_2v_1, ..., g_1v_2,
  g_2v_2,  ...,  g_|G|v_n][122X  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 [2XHAPPRIME_ExpandGeneratingRow[102X since it
  uses  the  efficient [2XHAPPRIME_GActMatrixColumns[102X ([14X6.1-3[114X) to perform the group
  action on the whole set of generating rows at a time.[133X
  
  [33X[0;0YThe  function [2XHAPPRIME_ExpandGeneratingRowsOnRight[102X is the same as above, but
  the group action operates on the right instead.[133X
  
  [1X6.1-5 HAPPRIME_AddGeneratingRowToSemiEchelonBasisDestructive[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_AddGeneratingRowToSemiEchelonBasisDestructive[102X( [3Xbasis[103X, [3Xgen[103X, [3XGA[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YRecord with elements [10Xvectors[110X and [10Xbasis[110X[133X
  
  [33X[0;0YThis  function  augments  a  vector  space  basis with another generator. It
  returns  a record consisting of two elements: [10Xvectors[110X, a set of semi-echelon
  basis vectors for the vector space spanned by the sum of the input [3Xbasis[103X and
  all  [22XG[122X-multiples of the generating vector [3Xgen[103X; and [10Xheads[110X, a list of the head
  elements,  in  the  same  format  as  returned by [2XSemiEchelonMat[102X ([14XReference:
  SemiEchelonMat[114X).  The  generator  [3Xgen[103X is expanded according to the group and
  action specified in the [3XGA[103X record (see [2XModuleGroupAndAction[102X ([14X3.4-5[114X)).[133X
  
  [33X[0;0YIf  the input [3Xbasis[103X is not zero, it is also modified by this function, to be
  the new basis (i.e. the same as the [10Xvectors[110X element of the returned record).[133X
  
  [1X6.1-6 HAPPRIME_ReduceVectorDestructive[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_ReduceVectorDestructive[102X( [3Xv[103X, [3Xbasis[103X, [3Xheads[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YBoolean[133X
  
  [33X[0;0YReduces  the vector [3Xv[103X (in-place) using the semi-echelon set of vectors [3Xbasis[103X
  with    heads    [3Xheads[103X    (as   returned   by   [2XSemiEchelonMat[102X   ([14XReference:
  SemiEchelonMat[114X)).  Returns [9Xtrue[109X if the vector is completely reduced to zero,
  or [9Xfalse[109X otherwise.[133X
  
  
  [1X6.1-7 [33X[0;0YHAPPRIME_ReduceGeneratorsOfModuleByXX[133X[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_ReduceGeneratorsOfModuleBySemiEchelon[102X( [3Xgens[103X, [3XGA[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_ReduceGeneratorsOfModuleBySemiEchelonDestructive[102X( [3Xgens[103X, [3XGA[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_ReduceGeneratorsOfModuleByLeavingOneOut[102X( [3Xgens[103X, [3XGA[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_ReduceGeneratorsOnRightByLeavingOneOut[102X( [3Xgens[103X, [3XGA[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YList of vectors[133X
  
  [33X[0;0YReturns  a  subset  of the module generators [3Xgens[103X over the group with action
  specified  in  the  [3XGA[103X  record  (see [2XModuleGroupAndAction[102X ([14X3.4-5[114X)) that will
  still generate the module.[133X
  
  [33X[0;0YThe  [10XBySemiEchelon[110X functions gradually expand out the module generators into
  an  [22XF[122X-basis,  using  that  [22XF[122X-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
  [10XDestructive[110X  version  of this function will modify the input [3Xgens[103X parameter.
  The  non-destructive  version  makes  a  copy  first,  so  leaves  the input
  arguments unchanged, at the expense of more memory.[133X
  
  [33X[0;0YThe [10XByLeavingOneOut[110X function is tries repeatedly leaving out generators from
  the list [3Xgens[103X 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 [10XOnRight[110X version computes a minimal subset which generates
  the module under group multiplication on the right.[133X
  
  [1X6.1-8 HAPPRIME_DisplayGeneratingRows[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_DisplayGeneratingRows[102X( [3Xgens[103X, [3XGA[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Ynothing[133X
  
  [33X[0;0YDisplays  a  set of [22XG[122X-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).[133X
  
  [33X[0;0YThis    function   is   used   by   [9XDisplay[109X   for   both   [9XFpGModuleGF[109X   and
  [9XFpGModuleHomomorphismGF[109X.[133X
  
  [33X[0;0YNOTE: This is currently only implemented for GF(2)[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XHAPPRIME_DisplayGeneratingRows([127X[104X
    [4X[25X>[125X [27X ModuleGenerators(M), HAPPRIME_ModuleGroupAndAction(M));[127X[104X
    [4X[28X[...1..11|........|.......1|........|........][128X[104X
    [4X[28X[........|........|........|.1....11|........][128X[104X
    [4X[28X[........|........|........|........|..1.1.1.][128X[104X
    [4X[28X[........|.1.1..1.|........|........|........][128X[104X
    [4X[28X[........|........|......11|........|........][128X[104X
    [4X[28X[........|........|1......1|........|........][128X[104X
  [4X[32X[104X
  
  [1X6.1-9 HAPPRIME_GeneratingRowsBlockStructure[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_GeneratingRowsBlockStructure[102X( [3Xgens[103X, [3XGA[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YMatrix[133X
  
  [33X[0;0YReturns 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  [10XGA.actionBlockSize[110X:  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.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27Xb := HAPPRIME_GeneratingRowsBlockStructure([127X[104X
    [4X[25X>[125X [27X ModuleGenerators(M), ModuleActionBlockSize(M));[127X[104X
    [4X[28X[ [ 1, 0, 1, 1, 1 ], [ 1, 0, 1, 1, 1 ], [ 0, 1, 1, 1, 1 ], [ 0, 0, 1, 1, 1 ] ][128X[104X
  [4X[32X[104X
  
  [1X6.1-10 HAPPRIME_DisplayGeneratingRowsBlocks[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_DisplayGeneratingRowsBlocks[102X( [3Xgens[103X, [3XactionBlockSize[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Ynothing[133X
  
  [33X[0;0YDisplays  a  set  of  [22XG[122X-generating  rows a compact human-readable form. Each
  generating  rows  can  be divided into blocks of length [3XactionBlockSize[103X. The
  generating  rows  are  displayed in a per-block form: a [9X*[109X where the block is
  non-zero and [9X.[109X where the block is all zero.[133X
  
  [33X[0;0YThis  function  is  used  by  [2XDisplayBlocks[102X  ([14X3.4-10[114X)  (for [9XFpGModuleGF[109X) and
  [2XDisplayBlocks[102X ([14X4.5-4[114X) (for [9XFpGModuleHomomorphismGF[109X).[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XHAPPRIME_DisplayGeneratingRowsBlocks([127X[104X
    [4X[25X>[125X [27X ModuleGenerators(M), HAPPRIME_ModuleGroupAndAction(M));[127X[104X
    [4X[28X[*.*..][128X[104X
    [4X[28X[...*.][128X[104X
    [4X[28X[....*][128X[104X
    [4X[28X[.*...][128X[104X
    [4X[28X[..*..][128X[104X
    [4X[28X[..*..] [128X[104X
  [4X[32X[104X
  
  [1X6.1-11 HAPPRIME_IndependentGeneratingRows[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_IndependentGeneratingRows[102X( [3Xblocks[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YList of lists[133X
  
  [33X[0;0YGiven a block structure as returned by [2XHAPPRIME_GeneratingRowsBlockStructure[102X
  ([14X6.1-9[114X),  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.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XDisplayBlocks(M);[127X[104X
    [4X[28XModule over the group ring of Group( [ f1, f2, f3 ] )[128X[104X
    [4X[28X in characteristic 2 with 6 generators in FG^5.[128X[104X
    [4X[28X[**...][128X[104X
    [4X[28X[.*...][128X[104X
    [4X[28X[.**..][128X[104X
    [4X[28X[.**..][128X[104X
    [4X[28X[...*.][128X[104X
    [4X[28X[....*][128X[104X
    [4X[28XGenerators are in minimal echelon form.[128X[104X
    [4X[25Xgap>[125X [27Xgens := ModuleGenerators(M);;[127X[104X
    [4X[25Xgap>[125X [27XG := ModuleGroup(M);;[127X[104X
    [4X[25Xgap>[125X [27Xblocks := HAPPRIME_GeneratingRowsBlockStructure(gens, G);[127X[104X
    [4X[28X[ [ 1, 1, 0, 0, 0 ], [ 0, 1, 0, 0, 0 ], [ 0, 1, 1, 0, 0 ], [ 0, 1, 1, 0, 0 ],[128X[104X
    [4X[28X  [ 0, 0, 0, 1, 0 ], [ 0, 0, 0, 0, 1 ] ][128X[104X
    [4X[25Xgap>[125X [27XHAPPRIME_IndependentGeneratingRows(blocks);[127X[104X
    [4X[28X[ [ 1, 2, 3, 4 ], [ 5 ], [ 6 ] ][128X[104X
  [4X[32X[104X
  
  [1X6.1-12 HAPPRIME_GactFGvector[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_GactFGvector[102X( [3Xg[103X, [3Xv[103X, [3XMT[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YVector[133X
  
  [33X[0;0YReturns  the  vector  that  is  the  result  of the action [22Xu=gv[122X of the group
  element  [3Xg[103X on a module vector [3Xv[103X (according to the group multiplication table
  [3XMT[103X.  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 [2XHAPPRIME_GActMatrixColumns[102X ([14X6.1-3[114X) instead.[133X
  
  
  [1X6.1-13 [33X[0;0YHAPPRIME_CoefficientsOfGeneratingRowsXX[133X[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_CoefficientsOfGeneratingRows[102X( [3Xgens[103X, [3XGA[103X, [3Xv[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_CoefficientsOfGeneratingRows[102X( [3Xgens[103X, [3XGA[103X, [3Xcoll[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_CoefficientsOfGeneratingRowsDestructive[102X( [3Xgens[103X, [3XGA[103X, [3Xv[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_CoefficientsOfGeneratingRowsDestructive[102X( [3Xgens[103X, [3XGA[103X, [3Xcoll[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_CoefficientsOfGeneratingRowsGF[102X( [3Xgens[103X, [3XGA[103X, [3Xv[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_CoefficientsOfGeneratingRowsGF[102X( [3Xgens[103X, [3XGA[103X, [3Xcoll[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_CoefficientsOfGeneratingRowsGFDestructive[102X( [3Xgens[103X, [3XGA[103X, [3Xv[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_CoefficientsOfGeneratingRowsGFDestructive[102X( [3Xgens[103X, [3XGA[103X, [3Xcoll[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_CoefficientsOfGeneratingRowsGFDestructive2[102X( [3Xgens[103X, [3XGA[103X, [3Xv[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_CoefficientsOfGeneratingRowsGFDestructive2[102X( [3Xgens[103X, [3XGA[103X, [3Xcoll[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YVector, or list of vectors[133X
  
  [33X[0;0YFor  a  single  vector  [3Xv[103X,  this  function  returns  a  vector  [22Xx[122X giving the
  [22XG[122X-coefficients  from  [3Xgens[103X  needed  to  generate [3Xv[103X, i.e. the solution to the
  equation  [22Xx*A=v[122X,  where [22XA[122X is the expansion of [3Xgens[103X. If there is no solution,
  [9Xfail[109X is returned. If a list of vectors, [3Xcoll[103X, then a vector is returned that
  lists  the solution for each vector (any of which may be [9Xfail[109X). The standard
  forms  of  this  function  use  standard  linear  algebra  to  solve for the
  coefficients.  The  [10XDestructive[110X version will corrupt both [3Xgens[103X and [3Xv[103X. The [10XGF[110X
  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.[133X
  
  [33X[0;0YThe [10XGFDestructive2[110X 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.[133X
  
  
  [1X6.1-14 [33X[0;0YHAPPRIME_GenerateFromGeneratingRowsCoefficientsXX[133X[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_GenerateFromGeneratingRowsCoefficients[102X( [3Xgens[103X, [3XGA[103X, [3Xc[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_GenerateFromGeneratingRowsCoefficients[102X( [3Xgens[103X, [3XGA[103X, [3Xcoll[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_GenerateFromGeneratingRowsCoefficientsGF[102X( [3Xgens[103X, [3XGA[103X, [3Xc[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_GenerateFromGeneratingRowsCoefficientsGF[102X( [3Xgens[103X, [3XGA[103X, [3Xcoll[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YVector, or list of vectors[133X
  
  [33X[0;0YFor  a  vector  [3Xc[103X,  returns  (as  a vector), the module element generated by
  multiplying  [3Xc[103X  by  the  expansion  of  the  generators  [3Xgens[103X. For a list of
  coefficient vectors [3Xcoll[103X, this returns a list of generating vectors.[133X
  
  [33X[0;0YThe  standard  versions of this function use standard linear algebra. The [10XGF[110X
  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  [3Xgens[103X,  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.[133X
  
  [1X6.1-15 HAPPRIME_RemoveZeroBlocks[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_RemoveZeroBlocks[102X( [3Xgens[103X, [3XGA[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YVector[133X
  
  [33X[0;0YRemoves  from  a  set  of generating vectors [3Xgens[103X (with [2XModuleGroupAndAction[102X
  ([14X3.4-5[114X)  [3XGA[103X) any blocks that are zero in every generating vector. Removal is
  done  in-place,  i.e. the input argument [3Xgens[103X 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  [2XHAPPRIME_AddZeroBlocks[102X  ([14X6.1-16[114X) to reinstate the zero blocks
  later,  if required. See the documentation for that function for more detail
  of the block structure vector.[133X
  
  [1X6.1-16 HAPPRIME_AddZeroBlocks[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_AddZeroBlocks[102X( [3Xgens[103X, [3XblockStructure[103X, [3XGA[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YList of vectors[133X
  
  [33X[0;0YAdds  zero  blocks  to  a set of generating vectors [3Xgens[103X to make it have the
  block  structure  given  in [3XblockStructure[103X (for a given [2XModuleGroupAndAction[102X
  ([14X3.4-5[114X) [3XGA[103X). The generators [3Xgens[103X are modified in place, and also returned.[133X
  
  [33X[0;0YThe  [3XblockStructure[103X  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 [2XHAPPRIME_RemoveZeroBlocks[102X
  ([14X6.1-15[114X)  will  have  been used to remove the zero blocks, and this function
  and   such   a   [3XblockStructure[103X   vector   is  returned  by  this  function.
  [2XHAPPRIME_AddZeroBlocks[102X can be used to reinstate these zero blocks.[133X
  
  
  [1X6.2 [33X[0;0Y[22XFG[122X[101X[1X-modules[133X[101X
  
  [33X[0;0Y[22XFG[122X-modules in [5XHAPprime[105X use the datatype [9XFpGModuleGF[109X (Chapter [14X3[114X). Internally,
  this  uses many of the functions listed in Section [14X6.1[114X, and further internal
  functions are listed below.[133X
  
  [1X6.2-1 HAPPRIME_DirectSumForm[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_DirectSumForm[102X( [3Xcurrent[103X, [3Xnew[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YString[133X
  
  [33X[0;0YReturns  a  string containing the form of the generator matrix if the direct
  sum  is formed between a [9XFpGModuleGF[109X with the form [3Xcurrent[103X and a [9XFpGModuleGF[109X
  with  the  form  [3Xnew[103X.  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
  [2XModuleGeneratorsForm[102X ([14X3.5-5[114X) for information about form strings.[133X
  
  [1X6.2-2 HAPPRIME_PrintModuleDescription[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_PrintModuleDescription[102X( [3XM[103X, [3Xfunc[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Ynothing[133X
  
  [33X[0;0YUsed  by  [2XPrintObj[102X  ([14XReference:  PrintObj[114X),  [2XViewObj[102X  ([14XReference:  ViewObj[114X),
  [2XDisplay[102X   ([14XReference:  Display[114X)  and  [2XDisplayBlocks[102X  ([14X3.4-10[114X),  this  helper
  function prints a description of the module [3XM[103X. The parameter [3Xfunc[103X can be one
  of  the strings [10X"print"[110X, [10X"view"[110X, [10X"display"[110X or [10X"displayblocks"[110X, corresponding
  to the print different functions that might be called.[133X
  
  
  [1X6.2-3 [33X[0;0YHAPPRIME_ModuleGeneratorCoefficients[133X[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_ModuleGeneratorCoefficients[102X( [3XM[103X, [3Xelm[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_ModuleGeneratorCoefficientsDestructive[102X( [3XM[103X, [3Xelm[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_ModuleGeneratorCoefficients[102X( [3XM[103X, [3Xcoll[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_ModuleGeneratorCoefficientsDestructive[102X( [3XM[103X, [3Xcoll[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YVector[133X
  
  [33X[0;0YReturns  the  coefficients needed to make the module element [3Xelm[103X as a linear
  and  [22XG[122X-combination  of  the  module  generators  of  the  [9XFpGModuleGF[109X [3XM[103X. The
  coefficients  are  returned  in  standard  vector  form,  or  if there is no
  solution  then [10Xfail[110X is returned. If a list of elements is given, then a list
  of  coefficients  (or  [10Xfails[110X)  is  returned.  The  [10XDestructive[110X  form of this
  function  might  change  the  elements  of  of [3XM[103X or [3Xelm[103X. The non-[10XDestructive[110X
  version makes copies to ensure that they are not changed.[133X
  
  [33X[0;0YSee also [2XHAPPRIME_ModuleElementFromGeneratorCoefficients[102X ([14X6.2-4[114X).[133X
  
  
  [1X6.2-4 [33X[0;0YHAPPRIME_ModuleElementFromGeneratorCoefficients[133X[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_ModuleElementFromGeneratorCoefficients[102X( [3XM[103X, [3Xc[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_ModuleElementFromGeneratorCoefficients[102X( [3XM[103X, [3Xcoll[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YVector[133X
  
  [33X[0;0YReturns  an  element from the module [3XM[103X, constructed as a linear and [22XG[122X-sum of
  the module generators as specified in [3Xc[103X. If a list of coefficient vectors is
  given, a list of corresponding module elements is returned.[133X
  
  [33X[0;0YSee also [2XHAPPRIME_ModuleGeneratorCoefficients[102X ([14X6.2-3[114X)[133X
  
  [1X6.2-5 HAPPRIME_MinimalGeneratorsVectorSpaceGeneratingRowsDestructive[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_MinimalGeneratorsVectorSpaceGeneratingRowsDestructive[102X( [3Xvgens[103X, [3XGA[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_MinimalGeneratorsVectorSpaceGeneratingRowsOnRightDestructive[102X( [3Xvgens[103X, [3XGA[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YFpGModuleGF[133X
  
  [33X[0;0YReturns a module with minimal generators that is equal to the [22XFG[122X-module with
  [13Xvector  space[113X  basis  [3Xvgens[103X and [2XModuleGroupAndAction[102X ([14X3.4-5[114X) as specified in
  [3XGA[103X.  The solution is computed by the module radical method, which is fast at
  the expense of memory. This function will corrupt the matrix [3Xgens[103X.[133X
  
  [33X[0;0YThis is a helper function for [2XMinimalGeneratorsModuleRadical[102X ([14X3.5-9[114X) that is
  also     used     by    [2XExtendResolutionPrimePowerGroupRadical[102X    ([14XHAPprime:
  ExtendResolutionPrimePowerGroupRadical[114X)  (which  knows  that  its  module is
  already in vector-space form).[133X
  
  [1X6.2-6 HAPPRIME_IsGroupAndAction[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_IsGroupAndAction[102X( [3Xobj[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YBoolean[133X
  
  [33X[0;0YReturns   [10Xtrue[110X   if   [3Xobj[103X   appears  to  be  a  [10XgroupAndAction[110X  record  (see
  [2XModuleGroupAndAction[102X ([14X3.4-5[114X)), or [10Xfalse[110X otherwise.[133X
  
  
  [1X6.3 [33X[0;0YResolutions[133X[101X
  
  [33X[0;0YFor  details  of the main resolution functions in [5XHAPprime[105X, see Chapter [14X2[114X of
  this datatypes reference manual, and [14X'HAPprime: Resolutions'[114X in the [5XHAPprime[105X
  user guide. This section describes the internal helper functions used by the
  higher-level functions.[133X
  
  [1X6.3-1 HAPPRIME_WordToVector[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_WordToVector[102X( [3Xw[103X, [3Xdim[103X, [3XorderG[103X ) [32X method[133X
  [6XReturns:[106X  [33X[0;10Y[5XHAP[105X word (list of lists)[133X
  
  [33X[0;0YReturns  the  boundary  map vector that corresponds to the [5XHAP[105X word vector [3Xw[103X
  with  module ambient dimension [3Xdim[103X and group order [3XorderG[103X (assumed to be the
  [10XactionBlockSize[110X).  A  [5XHAP[105X  word  vector  has the following format: [10X[ [block,
  elm],  [block,  elm], ... ][110X where [10Xblock[110X is a block number and [10Xelm[110X is a group
  element index (see example below).[133X
  
  [33X[0;0YSee also [2XHAPPRIME_VectorToWord[102X ([14X6.3-2[114X)[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XG := CyclicGroup(4);;[127X[104X
    [4X[25Xgap>[125X [27Xv := HAPPRIME_WordToVector([ [1,2],[2,3] ], 2, Order(G));[127X[104X
    [4X[28X<a GF2 vector of length 8>[128X[104X
    [4X[25Xgap>[125X [27XHAPPRIME_DisplayGeneratingRows([v], CanonicalGroupAndAction(G));[127X[104X
    [4X[28X[.1..|..1.][128X[104X
    [4X[25Xgap>[125X [27XHAPPRIME_VectorToWord(v, Order(G));[127X[104X
    [4X[28X[ [ 1, 2 ], [ 2, 3 ] ][128X[104X
  [4X[32X[104X
  
  [1X6.3-2 HAPPRIME_VectorToWord[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_VectorToWord[102X( [3Xvec[103X, [3XorderG[103X ) [32X function[133X
  [6XReturns:[106X  [33X[0;10YVector[133X
  
  [33X[0;0YThe  [5XHAP[105X word format vector that corresponds to the boundary vector [3Xvec[103X with
  [10XactionBlockSize[110X assumed to be [3XorderG[103X.[133X
  
  [33X[0;0YSee [2XHAPPRIME_WordToVector[102X ([14X6.3-1[114X) for a few more details and an example.[133X
  
  [1X6.3-3 HAPPRIME_BoundaryMatrices[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_BoundaryMatrices[102X( [3XR[103X ) [32X attribute[133X
  [6XReturns:[106X  [33X[0;10YList of matrices[133X
  
  [33X[0;0YIf [3XR[103X is a resolution which stores its boundaries as a list of matrices (e.g.
  one created by [5XHAPprime[105X, this list is returned. Otherwise, [10Xfail[110X 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.[133X
  
  [1X6.3-4 HAPPRIME_AddNextResolutionBoundaryMapMatNC[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_AddNextResolutionBoundaryMapMatNC[102X( [3XR[103X, [3XBndMat[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Y[10XHapResolution[110X[133X
  
  [33X[0;0YReturns  the  resolution [3XR[103X extended by one term, where that term is given by
  the  boundary  map  matrix  [3XBndMat[103X.  If  [3XBndMat[103X is not already in compressed
  matrix form, it will be converted into this form, and if the boundaries in [3XR[103X
  are not already in matrix form, they are all converted into this form.[133X
  
  [1X6.3-5 HAPPRIME_CreateResolutionWithBoundaryMapMatsNC[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_CreateResolutionWithBoundaryMapMatsNC[102X( [3XG[103X, [3XBndMats[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Y[10XHapResolution[110X[133X
  
  [33X[0;0YReturns  a  [5XHAP[105X resolution object for group [3XG[103X where the module homomorphisms
  are given by the boundary matrices in the list [3XBndMats[103X. This list is indexed
  with  the  boundary  matrix  for  degree  [13Xzero[113X  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 [10X[][110X.[133X
  
  
  [1X6.4 [33X[0;0YTest functions[133X[101X
  
  [33X[0;0YInternal helper functions for testing [5XHAPprime[105X.[133X
  
  [1X6.4-1 HAPPRIME_SingularIsAvailable[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_SingularIsAvailable[102X(  ) [32X function[133X
  [6XReturns:[106X  [33X[0;10YBoolean[133X
  
  [33X[0;0YThe  [5XSingular[105X  package  can  be  succesfully  loaded  whether  the  [11Xsingular[111X
  executable  is  present  or  not, so this function attempts to check for the
  presence of this executable by searching on the system path and checking for
  global variables set by the [5XSingular[105X.[133X
  
  [33X[0;0YWhether this function returns [9Xtrue[109X or [9Xfalse[109X will not affect the rest of this
  package:  it  only  affects  which  tests  are  run  by the [11Xhapprime.txt[111X and
  [11Xtestall.g[111X test routines.[133X
  
  [1X6.4-2 HAPPRIME_Random2Group[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_Random2Group[102X( [[3XorderG[103X] ) [32X operation[133X
  [33X[1;0Y[29X[2XHAPPRIME_Random2GroupAndAction[102X( [[3XorderG[103X] ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YGroup or [10XgroupAndAction[110X record[133X
  
  [33X[0;0YReturns    a    random    2-group,   or   a   [10XgroupAndAction[110X   record   (see
  [2XModuleGroupAndAction[102X  ([14X3.4-5[114X))  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.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XHAPPRIME_Random2Group();[127X[104X
    [4X[28X<pc group of size 8 with 3 generators>[128X[104X
    [4X[25Xgap>[125X [27XHAPPRIME_Random2Group();[127X[104X
    [4X[28X<pc group of size 32 with 5 generators>[128X[104X
  [4X[32X[104X
  
  [1X6.4-3 HAPPRIME_TestResolutionPrimePowerGroup[101X
  
  [33X[1;0Y[29X[2XHAPPRIME_TestResolutionPrimePowerGroup[102X( [[3Xntests[103X] ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10YBoolean[133X
  
  [33X[0;0YReturns       [9Xtrue[109X       if      [2XResolutionPrimePowerGroupGF[102X      ([14XHAPprime:
  ResolutionPrimePowerGroupGF  for group[114X) and [2XResolutionPrimePowerGroupRadical[102X
  ([14XHAPprime:  ResolutionPrimePowerGroupRadical for group[114X) appear to be working
  correctly, or [9Xfalse[109X otherwise. This repeatedly creates resolutions of length
  6  for  random  2-groups  (up  to  order  128)  using  both  of the [5XHAPprime[105X
  resolution  algorithms,  and  compares  them  both  with  the  original  [5XHAP[105X
  [2XResolutionPrimePowerGroup[102X  ([14XHAP:  ResolutionPrimePowerGroup[114X) and checks that
  they  are equal. The optional argument [3Xntests[103X specifies how many resolutions
  to try: the default is 25.[133X
  
