5 Internal Function Reference
  
  These are functions that are used internally in HAPprime. They should not be
  needed  by  users  of  the  package, but may be useful to developers and are
  provided for completeness
  
  
  5.1 Matrices as g-generators of a row space
  
  Both  FpGModuleGF  and FpGModuleHomomorphismGF 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.
  
  5.1-1 HAPPRIME_GActMatrixColumns
  
  > HAPPRIME_GActMatrixColumns( g, Vt, groupAndAction ) _____________operation
  Returns:  The matrix that results from the applying the group action u=gv to
            each column vector in the matrix Bt. The action is provided by the
            function action, and operates on blocks of size actionBlockSize.
  
  A  set  of  vectors are passed as columns of a matrix (i.e. the transpose of
  the  normal  GAP  representation).  In  this  way the group action is just a
  permutation of the rows of the matrix, which is a fast operation.
  
  If  the  input  matrix Vt is in a compressed matrix representation, then the
  returned matrix will also be in compressed matrix representation.
  
  5.1-2 HAPPRIME_ExpandGeneratingRow
  
  > HAPPRIME_ExpandGeneratingRow( gen, groupAndAction ) _____________operation
  Returns:  A list of the F-generators for the vector space that correspond to
            the  single  g-generator  gen. This space is formed by multiplying
            the  generator  by  each  element  of the group in turn, using the
            group    and    action    specified    in    groupAndAction   (see
            HAPPRIME_ModuleGroupAndAction).
  
  5.1-3 HAPPRIME_ExpandGeneratingRows
  
  > HAPPRIME_ExpandGeneratingRows( gens, groupAndAction ) ___________operation
  Returns:  A  list  of  F-generators for the vector space that corresponds to
            the  set of g-generators gens. This space is formed by multiplying
            each  generator  by  each  element  of G in turn, using the action
            specified by action with blocksize actionBlockSize.
  
  If  the  input generators are [v_1, v_2, ..., v_n] then the returned list is
  [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. The returned matrix is |G| times larger than the input gens
  
  This    function    is    more    efficient    than    repeated    use    of
  HAPPRIME_ExpandGeneratingRow     since     it     uses     the     efficient
  HAPPRIME_GActMatrixColumns  to  perform the group action on the whole set of
  generating rows at a time.
  
  5.1-4 HAPPRIME_AddGeneratingRowToSemiEchelonBasisDestructive
  
  > HAPPRIME_AddGeneratingRowToSemiEchelonBasisDestructive( basis, gen, groupAndAction ) operation
  
  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. The generator
  gen  is  expanded  according  to  the  group  and  action  specified  in the
  groupAndAction record (see HAPPRIME_ModuleGroupAndAction).
  
  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).
  
  5.1-5 HAPPRIME_ReduceVectorDestructive
  
  > HAPPRIME_ReduceVectorDestructive( v, basis, heads ) _____________operation
  Returns:  Reduces  the  vector  v  (in-place)  using the semi-echelon set of
            vectors  basis  with  heads heads (as returned by SemiEchelonMat).
            Returns true if the vector is completely reduced to zero, or false
            otherwise.
  
  5.1-6 HAPPRIME_ReduceGeneratorsOfModuleBySemiEchelon
  
  > HAPPRIME_ReduceGeneratorsOfModuleBySemiEchelon( gens, G, action ) operation
  > HAPPRIME_ReduceGeneratorsOfModuleBySemiEchelonDestructive( gens, groupAndAction ) operation
  Returns:  A  subset of the module generators gens over the group with action
            specified      in      the      groupAndAction     record     (see
            HAPPRIME_ModuleGroupAndAction)   that   will  still  generate  the
            module.
  
  This gradually expands 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.
  
  5.1-7 HAPPRIME_ReduceGeneratorsOfModuleByLeavingOneOut
  
  > HAPPRIME_ReduceGeneratorsOfModuleByLeavingOneOut( gens, GA ) ____operation
  Returns:  A  subset of the module generators gens over the group with action
            specifed      in      the      groupAndAction      record     (see
            HAPPRIME_ModuleGroupAndAction)   that   will  still  generate  the
            module.
  
  This  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.
  
  5.1-8 HAPPRIME_DisplayGeneratingRows
  
  > HAPPRIME_DisplayGeneratingRows( gens, groupAndAction ) __________operation
  
  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|........|........]
  ------------------------------------------------------------------
  
  5.1-9 HAPPRIME_GeneratingRowsBlockStructure
  
  > HAPPRIME_GeneratingRowsBlockStructure( gens, groupAndAction ) ___operation
  Returns:  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
  groupAndActionA.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 ] ]
  ------------------------------------------------------------------
  
  5.1-10 HAPPRIME_DisplayGeneratingRowsBlocks
  
  > HAPPRIME_DisplayGeneratingRowsBlocks( gens, actionBlockSize ) ___operation
  
  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  for  both  FpGModuleGF  and
  FpGModuleHomomorphismGF.
  
  ---------------------------  Example  ----------------------------
    gap> HAPPRIME_DisplayGeneratingRowsBlocks(
    >  ModuleGenerators(M), HAPPRIME_ModuleGroupAndAction(M));
    [*.*..]
    [...*.]
    [....*]
    [.*...]
    [..*..]
    [..*..] 
  ------------------------------------------------------------------
  
  5.1-11 HAPPRIME_IndependentGeneratingRows
  
  > HAPPRIME_IndependentGeneratingRows( blocks ) ____________________operation
  Returns:  A  list  of  list  of  row  indices,  where  each  list of indices
            represent  a  set  of  generating  rows that are indepndent of the
            others  (i.e.  share  no  blocks).  The  input  is  not the set of
            generating rows, but the block structure of the generating rows as
            returned by HAPPRIME_GeneratingRowsBlockStructure.
  
  ---------------------------  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 ] ]
  ------------------------------------------------------------------
  
  5.1-12 HAPPRIME_GactFGvector
  
  > HAPPRIME_GactFGvector( g, v, MT ) _______________________________operation
  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 to use 5.1-1
  instead.
  
  5.1-13 HAPPRIME_CoefficientsOfGeneratingRows
  
  > HAPPRIME_CoefficientsOfGeneratingRows( gens, groupAndAction, v ) operation
  > HAPPRIME_CoefficientsOfGeneratingRows( gens, groupAndAction, coll ) operation
  > HAPPRIME_CoefficientsOfGeneratingRowsDestructive( gens, groupAndAction, v ) operation
  > HAPPRIME_CoefficientsOfGeneratingRowsDestructive( gens, groupAndAction, coll ) operation
  > HAPPRIME_CoefficientsOfGeneratingRowsGF( gens, groupAndAction, v ) operation
  > HAPPRIME_CoefficientsOfGeneratingRowsGF( gens, groupAndAction, coll ) operation
  > HAPPRIME_CoefficientsOfGeneratingRowsGFDestructive( gens, groupAndAction, v ) operation
  > HAPPRIME_CoefficientsOfGeneratingRowsGFDestructive( gens, groupAndAction, coll ) operation
  Returns:  For  a  single  vector  v,  it  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. If the generators are in
  echelon form, this can save memory, but is slower.
  
  5.1-14 HAPPRIME_GenerateFromGeneratingRowsCoefficients
  
  > HAPPRIME_GenerateFromGeneratingRowsCoefficients( gens, groupAndAction, c ) operation
  > HAPPRIME_GenerateFromGeneratingRowsCoefficients( gens, groupAndAction, coll ) operation
  > HAPPRIME_GenerateFromGeneratingRowsCoefficientsGF( gens, groupAndAction, c ) operation
  > HAPPRIME_GenerateFromGeneratingRowsCoefficientsGF( gens, groupAndAction, coll ) operation
  Returns:  Generate a vector of collection of vectors as a combination of the
            generators  gens  given  by  the  coefficients c, or collection of
            vectors.  This is simply the result of multiplying the vector c or
            matrix coll by the expansion of the generators gens.
  
  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.
  
  5.1-15 HAPPRIME_RemoveZeroBlocks
  
  > HAPPRIME_RemoveZeroBlocks( gens, groupAndAction ) _______________operation
  
  Removes  from  a  set  of  generating  vectors  gens  (with group and action
  groupAndAction  any  blocks  that are zero in every generating vector. These
  will  be unaffected by any row or expansion operation, and can be removed to
  save  time  or  memory.  The function HAPPRIME_AddZeroBlocks (5.1-16) can be
  used  to replace the missing zeroes. This function requires the summed block
  structure of gens, which is returned by HAPPRIME_RemoveZeroBlocks.
  
  5.1-16 HAPPRIME_AddZeroBlocks
  
  > HAPPRIME_AddZeroBlocks( gens, blockStructure, groupAndAction ) __operation
  
  Adds  zero  blocks  to  a set of generating vectors gens to make it have the
  block  structure  given  in  blockStructure  (for  a  given group and action
  groupAndAction).  The  generators  gens  are  modified  in  place,  and also
  returned.
  
  The  blockStructure  parameter is identical to that returned by a prior call
  to HAPPRIME_RemoveZeroBlocks (5.1-15), which was most likely used earlier to
  remove zero blocks from the generators.
  
  
  5.2 FG-modules
  
  Internal helper functions for FpGModuleGFss.
  
  5.2-1 HAPPRIME_DirectSumForm
  
  > HAPPRIME_DirectSumForm( current, new ) __________________________operation
  
  Returns  a  string containing the form of the generator matrix if the direct
  sum  is  formed between a module with the form current and a module 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 (4.2-16) for information about form strings.
  
  5.2-2 HAPPRIME_PrintModuleDescription
  
  > HAPPRIME_PrintModuleDescription( M ) ____________________________operation
  
  Prints  the  standard  description  of a module M. This is used by PrintObj,
  ViewObj and Display, with the use specified
  
  5.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  the  coefficients needed to make the module element elm as a linear
  and  g-  combination  of  the  module  generators  of  the  module  M.  They
  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.
  
  ---------------------------  Example  ----------------------------
  ------------------------------------------------------------------
  
  5.2-4 HAPPRIME_ModuleElementFromGeneratorCoefficients
  
  > HAPPRIME_ModuleElementFromGeneratorCoefficients( M, c ) _________operation
  > HAPPRIME_ModuleElementFromGeneratorCoefficients( M, coll ) ______operation
  
  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.
  
  ---------------------------  Example  ----------------------------
  ------------------------------------------------------------------
  
  5.2-5 HAPPRIME_MinimalGeneratorsVectorSpaceGeneratingRowsDestructive
  
  > HAPPRIME_MinimalGeneratorsVectorSpaceGeneratingRowsDestructive( vgens, groupAndAction ) operation
  
  Returns a module with minimal generators that is equal to the FG-module with
  vector space basis vgens and group and action as specified in groupAndAction
  (see  ModuleGroupAndAction).  The solution is computed by the module radical
  method, which is fast at the expense of memory.
  
  This  is  a helper function for MinimalGeneratorsModuleRadical (4.2-30) that
  is  also used by ExtendResolutionPrimePowerGroupRadical (4.4-2) (which knows
  that its module is already in vector-space form).
  
  This function will corrupt the matrix gens.
  
  5.2-6 HAPPRIME_IsGroupAndAction
  
  > HAPPRIME_IsGroupAndAction( R ) __________________________________operation
  
  Returns true if R appears to be a groupAndAction record, or false otherwise.
  
  
  5.3 Resolutions
  
  Internal helper functions for building resolutions.
  
  5.3-1 HAPPRIME_WordToVector
  
  > HAPPRIME_WordToVector( w, dim, orderG ) ____________________________method
  
  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). For example, [ [1,2],[2,3] ] = [ 0100|0010 ].
  
  5.3-2 HAPPRIME_VectorToWord
  
  > HAPPRIME_VectorToWord( vec, orderG ) _____________________________function
  
  The  HAP word format vector that corresponds to the boundary vector vec with
  actionBlockSize  assumed  to  be  orderG.  For  example,  [  0100|0010 ] = [
  [1,2],[2,3] ].
  
  5.3-3 HAPPRIME_BoundaryMatrices
  
  > HAPPRIME_BoundaryMatrices( R ) _____________________________________method
  
  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.
  
  5.3-4 HAPPRIME_AddNextResolutionBoundaryMapMatNC
  
  > HAPPRIME_AddNextResolutionBoundaryMapMatNC( R, BndMat ) _________operation
  
  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.
  
  5.3-5 HAPPRIMECreateResolutionWithBoundaryMapMatsNC
  
  > HAPPRIMECreateResolutionWithBoundaryMapMatsNC( R, BndMat ) ______operation
  
  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 [].
  
  
  5.4 Miscellaneous
  
  Miscellaneous internal helper functions.
  
  5.4-1 VersionWithSVN
  
  > VersionWithSVN(  ) _______________________________________________function
  
  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.5.168M"
  ------------------------------------------------------------------