3 Graded algebras
  
  A  graded  algebra  A  is  a  ring  that has a direct sum decomposition into
  Abelian additive groups (called degrees)
  
  
       A = A_1 + A_2 + A_3 + ...
  
  
  and where multiplication of elements follows a grading such that
  
  
       A_s x A_r --> A_s+r
  
  
  This  means that for any elements x in A_s and y in A_r, the product lies in
  degree r+s, i.e. xy in A_s+r.
  
  
  3.1 Graded algebras in HAP (and HAPprime)
  
  Small finite algebras can be represented explicitly in GAP using a basis and
  a  structure  constant  table  'Tutorial:  Algebras',  which  specifies  all
  products  of basis elements. HAP extends this definition to provide a finite
  approximation  to  a graded algebra, storing all basis elements and products
  up to a given degree, n. The graded algebras used by HAP add a new component
  to  the algebra object A, the function A!.degree(e) which returns the degree
  of an algebra element e.
  
  HAPprime  uses  this  HAP algebra object and adds some attributes, providing
  information  on the basis and generators of the algebra. A ring presentation
  for   this   algebra   can  also  be  computed  and  represented  using  the
  GradedAlgebraPresentation datatype (see Section 4).
  
  
  3.2 Data access functions
  
  3.2-1 ModPRingGeneratorDegrees
  
  > ModPRingGeneratorDegrees( A ) ___________________________________attribute
  Returns:  List
  
  Returns  a  list  containing  the  degree  of  each  generator  in a minimal
  generating  set  for the mod-p cohomology ring A. The ith degree in the list
  corresponds  to  the  ith  generator  returned  by  ModPRingGenerators (HAP:
  ModPRingGenerators)
  
  3.2-2 ModPRingNiceBasis
  
  > ModPRingNiceBasis( A ) __________________________________________attribute
  Returns:  List
  
  Returns  the  information  needed  to  convert  the  basis  for A (see Basis
  (Reference:  Basis))  into a nicer basis consisting of only products of ring
  generators.  The  function  returns  a  pair of lists [Coeff, Bas]. The list
  Coeff  is  a  change-of-basis  matrix,  where the ith row gives the standard
  basis element i in terms of the nice basis. The list Bas can be used to form
  the  new  basis and is a list of integers where the ith 'nice basis' element
  is given by Product(List(Bas[i], x->Basis(A)[x])).
  
  This  attribute  returns  exactly  the same list as is provided by component
  A!.niceBasis   (see   ModPCohomologyRing   (HAP:   ModPCohomologyRing),  but
  automatically constructs this list if it is not available.
  
  3.2-3 ModPRingNiceBasisAsPolynomials
  
  > ModPRingNiceBasisAsPolynomials( A ) _____________________________attribute
  Returns:  List
  
  A  list  which  gives  the 'nice basis' of the algebra A (as returned by the
  second  element  of  ModPRingNiceBasis  (3.2-2)) in terms of products of the
  indeterminates     in     the     ring    presentation    (as    given    by
  PresentationOfGradedStructureConstantAlgebra  (3.3-1)). The ith entry in the
  list  corresponds  to  the  ith  basis element returned by ModPRingNiceBasis
  (3.2-2).
  
  3.2-4 ModPRingBasisAsPolynomials
  
  > ModPRingBasisAsPolynomials( A ) _________________________________attribute
  Returns:  List
  
  A  list  which gives the basis of the algebra A (as returned by Basis(A)) in
  terms of sums of products of the indeterminates in the ring presentation (as
  given  by  PresentationOfGradedStructureConstantAlgebra  (3.3-1)).  The  ith
  entry  in  the  list  corresponds to the ith basis element returned by Basis
  (Reference: Basis).
  
  
  3.3 Other functions
  
  3.3-1 PresentationOfGradedStructureConstantAlgebra
  
  > PresentationOfGradedStructureConstantAlgebra( A ) _______________attribute
  Returns:  GradedAlgebraPresentation
  
  Returns  a  ring presentation for the graded algebra A. The ring A must be a
  structure  constant  algebra  with  embedded degrees, such as is returned by
  ModPCohomologyRing   (HAP:   ModPCohomologyRing).   The  generators  of  the
  GradedAlgebraPresentation             (as             returned            by
  IndeterminatesOfGradedAlgebraPresentation    (4.3-3)   are   in   one-to-one
  correspondance  with  the  generators of A as returned by ModPRingGenerators
  (HAP:  ModPRingGenerators) (ignoring the first generator, which is in degree
  zero).
  
  
  3.4 Example: Graded algebras and mod-p cohomology rings
  
  The  mod-p  cohomology ring of a p-group is a graded algebra (see 'HAPprime:
  Computing mod-p cohomology rings and their Poincaré series'). As an example,
  we  use  the  HAP  function  ModPCohomologyRing (HAP: ModPCohomologyRing) to
  compute this algebra for the quaternion group Q_8 up to and including degree
  five.  We  can  display  its  generators  and  basis  (and degrees), and the
  information to construct a 'nice basis'
  
  ---------------------------  Example  ----------------------------
    gap> A := ModPCohomologyRing(SmallGroup(8, 4), 5);
    <algebra of dimension 9 over GF(2)>
    gap> Display(Basis(A));
    CanonicalBasis( Algebra( GF(2), [ v.1, v.2, v.3, v.4, v.5, v.6, v.7, v.8, v.9
     ] ) )
    gap> List(Basis(A), i->A!.degree(i));
    [ 0, 1, 1, 2, 2, 3, 4, 5, 5 ]
    gap> ModPRingGenerators(A);
    [ v.1, v.2, v.3, v.7 ]
    gap> ModPRingGeneratorDegrees(A);
    [ 0, 1, 1, 4 ]
    gap> ModPRingNiceBasis(A);
    [ [ [ 1, 0, 0, 0, 0, 0, 0, 0, 0 ], [ 0, 1, 0, 0, 0, 0, 0, 0, 0 ],
          [ 0, 0, 1, 0, 0, 0, 0, 0, 0 ], [ 0, 0, 0, 0, 0, 1, 0, 0, 0 ],
          [ 0, 0, 0, 0, 1, 1, 0, 0, 0 ], [ 0, 0, 0, 0, 0, 0, 0, 0, 1 ],
          [ 0, 0, 0, 1, 0, 0, 0, 0, 0 ], [ 0, 0, 0, 0, 0, 0, 0, 1, 0 ],
          [ 0, 0, 0, 0, 0, 0, 1, 1, 0 ] ],
      [ [ 1, 1, 1 ], [ 1, 1, 2 ], [ 1, 1, 3 ], [ 1, 1, 7 ], [ 1, 2, 2 ],
          [ 1, 2, 3 ], [ 1, 2, 7 ], [ 1, 3, 7 ], [ 2, 2, 3 ] ] ]
  ------------------------------------------------------------------
  
  A    presentation    for    this    algebra   can   be   constructed   using
  PresentationOfGradedStructureConstantAlgebra   (3.3-1),  which  (see  below)
  returns the presentation to be
  
  
       H^*(G, F) = F[x_1, x_2, x_3] / (x_1^2 + x_1x_2 + x_2^2, x_2^3)
  
  
  where  x_1  and x_2 have degree one and x_3 is degree four. The 'nice basis'
  referred to above is monomials of degree up to five in this polynomial ring,
  and  is  not necessarily the same as the basis of the algebra given by Basis
  (Reference: Basis), as demonstrated below.
  
  ---------------------------  Example  ----------------------------
    gap> A := ModPCohomologyRing(SmallGroup(8, 4), 5);;
    gap> PresentationOfGradedStructureConstantAlgebra(A);
    Graded algebra GF(2)[ x_1, x_2, x_3 ] / [ x_1^2+x_1*x_2+x_2^2, x_2^3
     ] with indeterminate degrees [ 1, 1, 4 ]
    
    gap> ModPRingNiceBasisAsPolynomials(A);
    [ Z(2)^0, x_1, x_2, x_3, x_1^2, x_1*x_2, x_1*x_3, x_2*x_3, x_1^2*x_2 ]
    gap> ModPRingBasisAsPolynomials(A);
    [ Z(2)^0, x_1, x_2, x_1*x_2, x_1^2+x_1*x_2, x_1^2*x_2, x_3, x_2*x_3,
      x_1*x_3+x_2*x_3 ]
  ------------------------------------------------------------------