  
  [1X4 Presentations of graded algebras[0X
  
  A  graded  algebra A is a an algebra that has additional structure, called a
  grading  (see Section [14X3[0m). Graded algebras of the type found in [5XHAPprime[0m have
  a presentation as a quotient of a polynomial ring
  
  
       H^*(G, F) = F[x_1, x_2, ..., x_n] / <I_1, I_2, ..., I_m>
  
  
  where  the polynomial ring indeterminates x_i each have an associated degree
  d_i and the I_j are relations which together generate an ideal in the ring.
  
  
  [1X4.1 The [9XGradedAlgebraPresentation[1X datatype[0X
  
  For  algebras  that  have a presentation as a quotient of a polynomial ring,
  the [9XGradedAlgebraPresentation[0m datatype stores a quotient R/I where:
  
  --    R is a polynomial ring
  
  --    I is a set of relations in R that generate an ideal
  
  and it also stores a grading in the form of
  
  --    the degree of each indeterminate of R
  
  
  [1X4.2 Construction function[0X
  
  
  [1X4.2-1 GradedAlgebraPresentation construction functions[0X
  
  [2X> GradedAlgebraPresentation( [0X[3XR, I, degs[0X[2X ) _________________________[0Xoperation
  [2X> GradedAlgebraPresentationNC( [0X[3XR, I, degs[0X[2X ) _______________________[0Xoperation
  [6XReturns:[0X  [9XGradedAlgebraPresentation[0m
  
  Construct  a [9XGradedAlgebraPresentation[0m object representing a presentation of
  a graded algebra as the quotient of a polynomial ring [3XR[0m by the ideal [3XI[0m (as a
  list  of  relations  in  [3XR[0m)  where  the  indeterminates of [3XR[0m (as returned by
  [2XIndeterminatesOfGradedAlgebraPresentation[0m    ([14X4.3-3[0m)   have   degrees   [3Xdegs[0m
  respectively.
  
  The   function  [9XGradedAlgebraPresentation[0m  checks  that  the  arguments  are
  compatible, while the [10XNC[0m method performs no checks.
  
  
  [1X4.3 Data access functions[0X
  
  [1X4.3-1 BaseRing[0m
  
  [2X> BaseRing( [0X[3XA[0X[2X ) ___________________________________________________[0Xattribute
  [6XReturns:[0X  Polynomial ring
  
  Returns the base ring of the graded algebra presentation [3XA[0m.
  
  [1X4.3-2 CoefficientsRing[0m
  
  [2X> CoefficientsRing( [0X[3XA[0X[2X ) ___________________________________________[0Xattribute
  [6XReturns:[0X  Ring
  
  Returns the ring of coefficients of the graded algebra presentation [3XA[0m.
  
  [1X4.3-3 IndeterminatesOfGradedAlgebraPresentation[0m
  
  [2X> IndeterminatesOfGradedAlgebraPresentation( [0X[3XA[0X[2X ) __________________[0Xattribute
  [6XReturns:[0X  List
  
  Returns the indeterminates used in the graded algebra presentation [3XA[0m.
  
  [1X4.3-4 GeneratorsOfPresentationIdeal[0m
  
  [2X> GeneratorsOfPresentationIdeal( [0X[3XA[0X[2X ) ______________________________[0Xattribute
  [6XReturns:[0X  List
  
  Returns the relations in the ring presentation for the graded algebra [3XA[0m. The
  relations  are  returned  sorted  in  order  of  increasing  degree,  and by
  indeterminate within each degree.
  
  [1X4.3-5 PresentationIdeal[0m
  
  [2X> PresentationIdeal( [0X[3XA[0X[2X ) __________________________________________[0Xattribute
  [6XReturns:[0X  Ideal
  
  Returns  the  ideal  in  the  graded  algebra  presentation [3XA[0m as a [5XGAP[0m ideal
  [14X'Reference: Ideal'[0m.
  
  [1X4.3-6 IndeterminateDegrees[0m
  
  [2X> IndeterminateDegrees( [0X[3XA[0X[2X ) _______________________________________[0Xattribute
  [6XReturns:[0X  List
  
  Returns  the  degrees  of  the  polynomial ring indeterminates in the graded
  algebra  presentation  [3XA[0m.  The ordering corresponds to the order of the ring
  indeterminates    returned    by   [2XIndeterminatesOfGradedAlgebraPresentation[0m
  ([14X4.3-3[0m).
  
  
  [1X4.3-7     Example:     Constructing     and     accessing    data    of    a[0X
  [1X[9XGradedAlgebraPresentation[1X[0X
  
  We  demonstrate creating a [9XGradedAlgebraPresentation[0m object and reading back
  its  data  by  creating the graded algebra A with presentation F_2[x_1, x_2,
  x_3]  /  (x_1x_2,  x_1^3+x_2^3)  where x_1 and x_2 have degree 1 and x_3 has
  degree 4
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> R := PolynomialRing(GF(2), 3);;[0X
    [4Xgap> A := GradedAlgebraPresentation(R, [R.1*R.2, R.1^3+R.2^3], [1,1,4]);[0X
    [4XGraded algebra GF(2)[ x_1, x_2, x_3 ] / [ x_1*x_2, x_1^3+x_2^3[0X
    [4X ] with indeterminate degrees [ 1, 1, 4 ][0X
    [4Xgap> BaseRing(A);[0X
    [4XGF(2)[x_1,x_2,x_3][0X
    [4Xgap> CoefficientsRing(A);[0X
    [4XGF(2)[0X
    [4Xgap> IndeterminatesOfGradedAlgebraPresentation(A);[0X
    [4X[ x_1, x_2, x_3 ][0X
    [4Xgap> PresentationIdeal(A);[0X
    [4X<two-sided ideal in GF(2)[x_1,x_2,x_3], (2 generators)>[0X
    [4Xgap> GeneratorsOfPresentationIdeal(A);[0X
    [4X[ x_1*x_2, x_1^3+x_2^3 ][0X
    [4Xgap> IndeterminateDegrees(A);[0X
    [4X[ 1, 1, 4 ][0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X4.4 Other functions[0X
  
  
  [1X4.4-1 TensorProduct[0X
  
  [2X> TensorProduct( [0X[3XA, B[0X[2X ) ___________________________________________[0Xoperation
  [2X> TensorProduct( [0X[3Xcoll[0X[2X ) ___________________________________________[0Xoperation
  [6XReturns:[0X  GradedAlgebraPresentation
  
  Returns  a presentation for the graded algebra that is the tensor product of
  two graded algebras presented by [3XA[0m and [3XB[0m, or of a list of graded algebras.
  
  [1X4.4-2 IsIsomorphicGradedAlgebra[0m
  
  [2X> IsIsomorphicGradedAlgebra( [0X[3XA, B[0X[2X ) _______________________________[0Xoperation
  
  Returns  [9Xtrue[0m  if  the  graded  algebras  [3XA[0m  and  [3XB[0m are isomorphic, or [9Xfalse[0m
  otherwise. This function tries all possible ring isomorphisms, so may take a
  considerable  length  of  time  for  graded  algebras with a large number of
  dimensions in each degree.
  
  [1X4.4-3 IsAssociatedGradedRing[0m
  
  [2X> IsAssociatedGradedRing( [0X[3XA, B[0X[2X ) __________________________________[0Xoperation
  
  Returns [9Xtrue[0m if the algebra [3XA[0m is an associated graded ring of the algebra [3XB[0m.
  This  is  the  case  if  the  additive  structure  is  the  same  (i.e.  the
  Hilbert-Poincaré  series  is  the same), and the generators for [3XA[0m (and their
  degrees) are included in the generators for [3XB[0m.
  
  [1X4.4-4 DegreeOfRepresentative[0m
  
  [2X> DegreeOfRepresentative( [0X[3XA, p[0X[2X ) __________________________________[0Xoperation
  [6XReturns:[0X  Integer
  
  Returns  the  degree  of  a polynomial representative [3Xp[0m from the graded ring
  presentation [3XA[0m.
  
  [1X4.4-5 MaximumDegreeForPresentation[0m
  
  [2X> MaximumDegreeForPresentation( [0X[3XA[0X[2X ) _______________________________[0Xattribute
  [6XReturns:[0X  Integer
  
  Returns  the  maximum  degree  in  generators or relations that is needed to
  generate the graded algebra presentation [3XA[0m. This is not necessarily the same
  as  the  largest  degree  in  any  of  the  relations  and generators - some
  relations  may  be redundant (for example due to being a Groebner basis), so
  this  routine  checks  for  the  largest degree of a required generator, and
  returns the maximum of this and the generator degrees.
  
  
  [1X4.4-6 SubspaceDimensionDegree[0X
  
  [2X> SubspaceDimensionDegree( [0X[3XA, d[0X[2X ) _________________________________[0Xoperation
  [2X> SubspaceDimensionDegree( [0X[3XA, degs[0X[2X ) ______________________________[0Xoperation
  [6XReturns:[0X  Integer or list
  
  Returns  the  dimension  of  degree  [3Xd[0m of the graded algebra [3XA[0m, or a list of
  dimensions corresponding to the list of degrees [3Xdegs[0m.
  
  
  [1X4.4-7 SubspaceBasisRepsByDegree[0X
  
  [2X> SubspaceBasisRepsByDegree( [0X[3XA, d[0X[2X ) _______________________________[0Xoperation
  [2X> SubspaceBasisRepsByDegree( [0X[3XA, degs[0X[2X ) ____________________________[0Xoperation
  [6XReturns:[0X  List or list of lists
  
  Returns a basis for degree [3Xd[0m of the graded algebra [3XA[0m, or a list of bases for
  the   list   of   degrees  [3Xdegs[0m.  Each  basis  is  returned  as  a  list  of
  representatives.
  
  [1X4.4-8 CoefficientsOfPoincareSeries[0m
  
  [2X> CoefficientsOfPoincareSeries( [0X[3XA, n[0X[2X ) ____________________________[0Xoperation
  [6XReturns:[0X  List
  
  Returns  the  first  [3Xn[0m  coefficients  of  the Poincaré series for the graded
  algebra with [3XA[0m. These are equal to the dimensions of degrees 0 to n-1 of the
  algebra  (a  fact  that  is  used  in  the  function [2XSubspaceDimensionDegree[0m
  ([14X4.4-6[0m)).
  
  [13XThis function uses the [5Xsingular[0m[13X package.[0m
  
  [1X4.4-9 HilbertPoincareSeries[0m
  
  [2X> HilbertPoincareSeries( [0X[3XA[0X[2X ) ______________________________________[0Xattribute
  [6XReturns:[0X  Rational function
  
  Returns  the  Poincaré  series  for the graded algebra [3XA[0m. This is a rational
  function  P(t)/Q(t)  which  is  a is a polynomial whose coefficients are the
  dimensions of each degree of the algebra.
  
  [13XThis function uses the [5Xsingular[0m[13X package.[0m
  
  [1X4.4-10 LHSSpectralSequence[0m
  
  [2X> LHSSpectralSequence( [0X[3XG[, N], n[0X[2X ) ________________________________[0Xoperation
  [2X> LHSSpectralSequenceLastSheet( [0X[3XG[, N][0X[2X ) __________________________[0Xoperation
  [6XReturns:[0X  [9XGradedAlgebraPresentation[0m or list
  
  Computes the Lyndon-Hoschild-Serre spectral sequence for the group extension
  N  ->  G  ->  G/N.  If a normal suggroup [3XN[0m is not provided, then the largest
  central subgroup of G is used, or (if the order of the centre is larger than
  sqrt|G|)  then the central subgroup that leads to the smallest initial sheet
  size is chosen.
  
  The  function [2XLHSSpectralSequence[0m returns the first [3Xn[0m sheets of the spectral
  sequence,  or  all  of the sequence up to convergence, if that occurs before
  the (n+1)th sheet. The Lyndon-Hoschild-Serre spectral sequence starts at the
  E_2  sheet, so the first element in returned list will always be empty. If [3Xn[0m
  is set to [9Xinfinity[0m then the length of the returned list equals the number of
  sheets  for  convergence,  and  the  last  sheet in the list is the limiting
  sheet.
  
  The function [2XLHSSpectralSequenceLastSheet[0m returns only the limiting sheet of
  the  spectral  sequence.  This  ring  is an associated graded algebra of the
  mod-p  cohomology  ring  of  G,  with  the same additive structure while not
  necessarily being isomorphic to it.
  
  There are four options [14X'Reference: Options Stack'[0m which can be used to guide
  this algorithm:
  
  --    [10XInitialLHSBicomplexSize[0m can be used to specify the initial size of the
        bicomplex  (the  default  is  5).  If, in the process of computing the
        spectral  sequence,  this  is found to be too small then the algorithm
        restarts  with  a  larger  value. Specifying a larger initial value in
        these cases can save time.
  
  --    [10XLargerLHSBicomplexBreak[0m  if  set to [9Xtrue[0m will force the calculation to
        enter  a  break loop before restarting with a larger bicomplex, should
        the  bicomplex  be found to be too small. The user user is prompted to
        type  [10Xreturn;[0m  before continuing. The default behaviour is [9Xfalse[0m, i.e.
        no prompt.
  
  --    [10XLargerLHSBicomplexFail[0m  if  set  to  [9Xtrue[0m  will return [9Xfail[0m should the
        bicomplex  be  found  to be too small. The default behaviour is [9Xfalse[0m,
        i.e.  to  either  restart  or  prompt, depending on the setting of the
        previous option.
  
  --    [10XNoInductiveProof[0m  if  set  to  [9Xtrue[0m will not check that the cohomology
        rings  for  N  and  G/N  are  correct.  Instead,  it  will compute the
        cohomology  rings  only up to the degree needed for the bicomplex size
        (5 by default, or specified by the [10XInitialLHSBicomplexSize[0m option).
  
  
  [1X4.5 Example: Computing the Lyndon-Hoschild-Serre spectral sequence and mod-p[0X
  [1Xcohomology ring for a small p-group[0X
  
  The Lyndon-Hoschild-Serre spectral sequence is relates the cohomologies of a
  normal  subgroup  N  and a quotient group G/N to the cohomology of the total
  group  G: the limiting sheet of the sequence is an associated graded ring of
  the cohomology of G.
  
  In this example we calculate the Lyndon-Hoschild-Serre spectral sequence for
  a  group of order 16 using the centre of G as our normal subgroup. By asking
  for an infinite number of terms, this function calculates enough terms to be
  sure that the sequence has converged. We compare the dimensions in the first
  (E_2)  and last (E_infty) sheet, we demonstrate that the limiting sheet (the
  last  in  the list) is a graded algebra by multiplying some elements, and we
  calculate the Poincaré series of the last sheet.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> G := SmallGroup(16, 4);;[0X
    [4Xgap> SS := LHSSpectralSequence(G, Centre(G), infinity);[0X
    [4X[ , Graded algebra GF(2)[ x_1, x_2, x_3, x_4 ] /[0X
    [4X    [  ] with indeterminate degrees [ 1, 1, 1, 1 ],[0X
    [4X  Graded algebra GF(2)[ x_1, x_2, x_3, x_4 ] / [ x_2^2, x_1^2+x_1*x_2[0X
    [4X     ] with indeterminate degrees [ 1, 1, 2, 2 ],[0X
    [4X  Graded algebra GF(2)[ x_1, x_2, x_3, x_4 ] / [ x_2^2, x_1^2+x_1*x_2[0X
    [4X     ] with indeterminate degrees [ 1, 1, 2, 2 ] ][0X
    [4Xgap> # i.e. we identify convergence after 3 terms[0X
    [4Xgap> #[0X
    [4Xgap> # Compare the dimensions of the first and last sheet[0X
    [4Xgap> SubspaceDimensionDegree(SS[2], [1..10]);[0X
    [4X[ 4, 10, 20, 35, 56, 84, 120, 165, 220, 286 ][0X
    [4Xgap> SubspaceDimensionDegree(SS[3], [1..10]);[0X
    [4X[ 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ][0X
    [4Xgap> #[0X
    [4Xgap> # Take the two basis elements from degree 1 and check that the[0X
    [4Xgap> # product is in degree two[0X
    [4Xgap> B := SubspaceBasisRepsByDegree(SS[3], 1);[0X
    [4X[ x_1, x_2 ][0X
    [4Xgap> DegreeOfRepresentative(SS[3], B[1]*B[2]);[0X
    [4X2[0X
    [4Xgap> #[0X
    [4Xgap> # And find the Poincare series[0X
    [4Xgap> HilbertPoincareSeries(SS[3]);[0X
    [4X(1)/(x_1^2-2*x_1+1)[0X
  [4X------------------------------------------------------------------[0X
  
  The  largest  degree  in  the  presentation  for  the  limiting sheet in the
  Lyndon-Hoschild-Serre  spectral  sequence  for  G is the same as the largest
  degree  in  the presentation for the mod-p cohomology ring of G. We continue
  this example by calculating this maximum degree, n, for our group G and then
  computing  the mod-p cohomology ring. We confirm that the cohomology ring is
  an  associated  graded  ring of the limiting sheet of the spectral sequence,
  and check whether in this case it is in fact also isomorphic.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> G := SmallGroup(16, 4);;[0X
    [4Xgap> Einf := LHSSpectralSequenceLastSheet(G, Centre(G));[0X
    [4XGraded algebra GF(2)[ x_1, x_2, x_3, x_4 ] / [ x_2^2, x_1^2+x_1*x_2[0X
    [4X ] with indeterminate degrees [ 1, 1, 2, 2 ][0X
    [4Xgap> #[0X
    [4Xgap> # Find the maximum degree[0X
    [4Xgap> n := MaximumDegreeForPresentation(Einf);[0X
    [4X2[0X
    [4Xgap> #[0X
    [4Xgap> # And calculate the cohomology ring[0X
    [4Xgap> H := ModPCohomologyRingPresentation(G, n);[0X
    [4XGraded algebra GF(2)[ x_1, x_2, x_3, x_4 ] / [ x_1*x_2+x_2^2, x_1^2[0X
    [4X ] with indeterminate degrees [ 1, 1, 2, 2 ][0X
    [4Xgap> #[0X
    [4Xgap> # Check for an associated graded ring, and isomorphism[0X
    [4Xgap> IsAssociatedGradedRing(H, Einf);[0X
    [4Xtrue[0X
    [4Xgap> IsIsomorphicGradedAlgebra(H, Einf);[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
