4 General Functions
  
  Some  of  the  functions  provided by HAPprime are not specifically aimed at
  homological  algebra  or  extending  the  HAP package. The functions in this
  chapter,  which  are used internally by HAPprime extend some of the standard
  GAP functions and datatypes.
  
  
  4.1 Matrices
  
  See  'Reference:  Matrices' in the GAP reference manual for the standard GAP
  matrix functions.
  
  4.1-1 SumIntersectionMatDestructive
  
  > SumIntersectionMatDestructive( U, V ) ___________________________operation
  > SumIntersectionMatDestructiveSE( Ubasis, Uheads, Vbasis, Vheads ) operation
  
  Returns  a  list  of  length  2  with, at the first position, the sum of the
  vector  spaces  generated  by  the  rows  of  U  and  V,  and, at the second
  positionion, the intersection of the spaces.
  
  Like     the    GAP    core    function    SumIntersectionMat    (Reference:
  SumIntersectionMat),  this  performs  Zassenhaus' algorithm to compute bases
  for the sum and the intersection. However, this version operates directly on
  the  input matrices (thus corrupting them), and is rewritten to require only
  approximately  1.5  times  the space of the orginal input matrices, compared
  with  the 3 times memory requirement of the original version (in addition to
  the original input matrices in this case).
  
  The  function  SumIntersectionMatDestructiveSE takes as arguments not a pair
  of  generating  matrices,  but a pair of semi-echelon basis matrices and the
  corresponding   head   locations,   such   as  is  returned  by  a  call  to
  SemiEchelonMatDestructive   (Reference:   SemiEchelonMatDestructive)  (these
  arguments must all be mutable, so SemiEchelonMat (Reference: SemiEchelonMat)
  cannot    be    used).    This    function    is    used    internally    by
  SumIntersectionMatDestructive,  and  is  provided for the occasions when the
  user might already have the semi-echelon versions available, in which case a
  small amount of time will be saved.
  
  4.1-2 SolutionMat
  
  > SolutionMat( M, V ) _____________________________________________operation
  > SolutionMatDestructive( M, V ) __________________________________operation
  
  Calculates, for each row vector v_i in the matrix V, a solution to x_i x M =
  v_i,  and  returns these solutions in a matrix X, whose rows are the vectors
  x_i.  If  there  is not a solution for a v_i, then fail is returned for that
  row.
  
  These   functions   are   identical  to  the  kernel  functions  SolutionMat
  (Reference:     SolutionMat)    and    SolutionMatDestructive    (Reference:
  SolutionMatDestructive), but are provided for cases where multiple solutions
  using the same matrix M are required. In these cases, using this function is
  far faster, since the matrix is only decomposed once.
  
  The  Destructive  version  currupts  both  the  input  matrices,  while  the
  non-Destructive version operates on copies of these.
  
  4.1-3 IsSameSubspace
  
  > IsSameSubspace( U, V ) __________________________________________operation
  
  Returns  true  if the subspaces spanned by the rows of U and V are the same,
  false otherwise.
  
  This  function  treats the rows of the two matrices as vectors from the same
  vector  space  (with the same basis), and tests whether the subspace spanned
  by the two sets of vectors is the same.
  
  4.1-4 PrintDimensionsMat
  
  > PrintDimensionsMat( M ) _________________________________________operation
  
  Returns  a  string  containing  the  dimensions  of the matrix M in the form
  "mxn",  where  m  is  the number of rows and n the number of columns. If the
  matrix is empty, the returned string is "empty".
  
  
  4.2 Polynomials
  
  See  'Reference:  Polynomials  and  Rational Functions' in the GAP reference
  manual  for  the  functions provided by GAP for representing an manipulating
  polynomials.
  
  4.2-1 TermsOfPolynomial
  
  > TermsOfPolynomial( poly ) _______________________________________operation
  Returns:  List of pairs
  
  Returns  a list of the terms in the polynomial. This list is a list of pairs
  of  the  form  [mon,  coeff]  where  mon  is  a  monomial  and  coeff is the
  coefficient  of  that  monomial  in the polynomial. The monomials are sorted
  according  to  the  total  degree/lexicograhic  order  (the  same  as the in
  MonomialGrLexOrdering (Reference: MonomialGrlexOrdering)).
  
  4.2-2 UnivariateMonomialsOfMonomial
  
  > UnivariateMonomialsOfMonomial( mon ) ____________________________operation
  Returns:  List of univariate monomials
  
  Returns  a  list  of  the  univariate  monomials  of the largest order whose
  product  equals  mon. The univariate monomials are sorted according to their
  indeterminate number.
  
  4.2-3 IndeterminateAndCoefficientOfUnivariateMonomial
  
  > IndeterminateAndCoefficientOfUnivariateMonomial( mon ) __________operation
  Returns:  List
  
  Returns  a  list  with  in  the  first  position  the  indeterminate  of the
  univariate  monomial  mon and in the second position the coefficient of that
  indeterminate  in  the  monomial.  If  mon  is  not a monomial, then fail is
  returned.
  
  4.2-4 ReduceIdeal
  
  > ReduceIdeal( I, O ) _____________________________________________operation
  Returns:  List of polynomials
  
  Returns a reduced version of the ideal I, i.e. one in which no monomial in a
  polynomial in I is divisible by the leading term of another polynomial in I.
  The monomial ordering to be used is specified by O (see 'Reference: Monomial
  Orderings').
  
  4.2-5 ReducePolynomialRingPresentation
  
  > ReducePolynomialRingPresentation( ring, ideal ) _________________operation
  Returns:  List
  
  Reduces  a  polynomial  ring  presentation  to  an  isomorphic  presentation
  involving  the minimal number of indeterminates. Returns a list with, in the
  first  place,  the  new  polynomial  ring,  and  in the second place the new
  relations.
  
  
  4.2-6 Examples
  
  ---------------------------  Example  ----------------------------
    gap> ring := PolynomialRing(Integers, 2);;
    gap> i := IndeterminatesOfPolynomialRing(ring);;
    gap> poly := i[1] + i[1]*i[2]^2 + 3*i[2]^3;
    x_1*x_2^2+3*x_2^3+x_1
    gap> terms := TermsOfPolynomial(poly);
    [ [ x_1, 1 ], [ x_2^3, 3 ], [ x_1*x_2^2, 1 ] ]
    gap> UnivariateMonomialsOfMonomial(terms[3][1]);
    [ x_1, x_2^2 ]
    gap> IndeterminateAndCoefficientOfUnivariateMonomial(last[2]);
    [ x_2, 2 ]
          
  ------------------------------------------------------------------
  
  ---------------------------  Example  ----------------------------
    gap> ring := PolynomialRing(GF(2), 2);;
    gap> i := IndeterminatesOfPolynomialRing(ring);;
    gap> I := [i[1]^2 + i[2], i[1]^3 + i[2]^3];
    [ x_1^2+x_2, x_1^3+x_2^3 ]
    gap> ReduceIdeal(I, MonomialLexOrdering());
    [ x_1^2+x_2, x_2^3+x_1*x_2 ]
          
  ------------------------------------------------------------------
  
  ---------------------------  Example  ----------------------------
    gap> ring := PolynomialRing(GF(2), 3);;
    gap> i := IndeterminatesOfPolynomialRing(ring);;
    gap> ideal := [ i[3]^2 + i[1] + i[2] ];
    [ x_3^2+x_1+x_2 ]
    gap> ReducePolynomialRingPresentation(ring, ideal);
    [ GF(2)[x_1,x_3], [  ] ]
          
  ------------------------------------------------------------------