<!-- 
  HAPPRIME - rings.xml.in
  Function documentation template file for HAPprime
  Paul Smith

  Copyright (C)  2008
  Paul Smith
  National University of Ireland Galway

  $Id: functions.xml.in 200 2008-02-05 14:29:47Z pas $
-->

<!-- ********************************************************** -->
<Chapter  Label="GradedAlgebra">
  <Heading>Graded algebras</Heading>

  A graded algebra <M>A</M> is a ring that has a direct sum decomposition into 
  Abelian additive groups (called degrees)
  <Alt Only="LaTeX">
    <Display>
      A = \bigoplus_{n \in \mathbb{N}} A_n = A_0 \oplus A_1 \oplus A_2 \oplus \ldots
    </Display>
  </Alt>
  <Alt Not="LaTeX">
    <Display>
      A = A_1 + A_2 + A_3 + ...
    </Display>
  </Alt>
  and where multiplication of elements follows a grading such that 
  <Alt Only="LaTeX">
    <Display>
      A_s \times A_r \longrightarrow A_{s+r}
    </Display>
  </Alt>
  <Alt Not="LaTeX">
    <Display>
      A_s  x  A_r --> A_s+r
    </Display>
  </Alt>
  This means that for any elements <M>x \in A_s</M> and <M>y \in A_r</M>,
  the product lies in degree <M>r+s</M>, i.e. <M>xy \in A_{s+r}</M>.
  
  <Section>
    <Heading>Graded algebras in &HAP; (and &HAPprime;)</Heading>

    Small finite algebras can be represented explicitly in &GAP; using a 
    basis and a structure constant table <Ref Sect="Algebras" BookName="tut"/>,
    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, <M>n</M>. The 
    graded algebras used by &HAP; add a new component to the algebra object 
    <C>A</C>, the function <C>A!.degree(e)</C> which returns the degree of an 
    algebra element <C>e</C>.
    <P/>
    &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 
    <K>GradedAlgebraPresentation</K> datatype (see
    Section <Ref Sect="GradedAlgebraPresentationDatatype"/>).
  </Section>


  <Section>
    <Heading>Data access functions</Heading>
    <!-- GAPDocSourceSuffix="_DTmanRings_Dat" -->
  
  </Section>
    
  <Section>
    <Heading>Other functions</Heading>
    <!-- GAPDocSourceSuffix="_DTmanRings_Other" -->
  </Section>

  <Section Label="RingsExample">
    <Heading>Example: Graded algebras and mod-&p; cohomology rings</Heading>

    The mod-&p; cohomology ring of a &p;-group is a graded algebra (see
    <Ref Sect="Computing mod-p cohomology rings" BookName="HAPprime"/>).
    As an example, we use the &HAP; function
    <Ref Func="ModPCohomologyRing" BookName="HAP"/> to compute this algebra 
    for the quaternion group <M>Q_8</M> up to and including
    degree five. We can display its generators and basis (and degrees),
    and the information to construct a 'nice basis'
<!--
gap> A := ModPCohomologyRing(SmallGroup(8, 4), 5);
gap> Display(Basis(A));
gap> List(Basis(A), i->A!.degree(i));
gap> ModPRingGenerators(A);
gap> ModPRingGeneratorDegrees(A);
gap> ModPRingNiceBasis(A);
-->
<Example><![CDATA[
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 ] ] ]
]]></Example>

    A presentation for this algebra can be constructed using
    <Ref Attr="PresentationOfGradedStructureConstantAlgebra"/>, which
    (see below) returns the presentation to be
    <Alt Only="LaTeX">
      <Display>
        H^*(G, \mathbb{F}) = \frac{\mathbb{F}[x_1,x_2,x_3]}{\langle x_1^2 + x_1x_2 + x_2^2, x_2^3\rangle}
      </Display>
    </Alt>
    <Alt Not="LaTeX">
      <Display><![CDATA[
        H^*(G, F) = F[x_1, x_2, x_3] / (x_1^2 + x_1x_2 + x_2^2, x_2^3)
      ]]></Display>
    </Alt>
    where <M>x_1</M> and <M>x_2</M> have degree one and <M>x_3</M> 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 <Ref Meth="Basis" BookName="ref"/>, as demonstrated
    below.
<!--
gap> A := ModPCohomologyRing(SmallGroup(8, 4), 5);;
gap> PresentationOfGradedStructureConstantAlgebra(A);
gap> ModPRingNiceBasisAsPolynomials(A);
gap> ModPRingBasisAsPolynomials(A);
-->
<Example><![CDATA[
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 ]]]></Example>
  </Section>

</Chapter>