2. A sample calculation with LAGUNA
  
  Before  explaining  the theory behind the LAGUNA package we present a sample
  calculation to show the reader what LAGUNA is able to compute. We will carry
  out some calculations in the group algebra of the dihedral group of order 16
  over the field of two elements. First we create this modular group algebra.
  
  ---------------------------  Example  ----------------------------
    
    gap> K := GF( 2 );
    GF(2)
    gap> G := DihedralGroup( 16 );
    <pc group of size 16 with 4 generators>
    gap> KG := GroupRing( K, G );
    <algebra-with-one over GF(2), with 4 generators>
    
  ------------------------------------------------------------------
  
  The  group  algebra  KG  has  some properties and attributes that are direct
  consequences of its definition. These can be checked very quickly.
  
  ---------------------------  Example  ----------------------------
    
    gap> IsGroupAlgebra( KG ); 
    true
    gap> IsPModularGroupAlgebra( KG );
    true
    gap> IsFModularGroupAlgebra( KG );
    true
    gap> UnderlyingGroup( KG );
    <pc group of size 16 with 4 generators>
    gap> LeftActingDomain( KG );
    GF(2)
    
  ------------------------------------------------------------------
  
  Since  KG  is  naturally  a  group  algebra,  the  information  provided  by
  LeftActingDomain can also be obtained using two other functions as follows.
  
  ---------------------------  Example  ----------------------------
    gap> UnderlyingRing( KG );
    GF(2)
    gap> UnderlyingField( KG );
    GF(2)
  ------------------------------------------------------------------
  
  Let  us  construct  a  certain element of the group algebra. For example, we
  take  a  minimal generating system of the group G and find the corresponding
  elements in KG.
  
  ---------------------------  Example  ----------------------------
    
    gap> MinimalGeneratingSet( G );
    [ f1, f2 ]
    gap> l := List( last, g -> g^Embedding( G, KG ) );
    [ (Z(2)^0)*f1, (Z(2)^0)*f2 ]
    
  ------------------------------------------------------------------
  
  Now we construct an element x as follows.
  
  ---------------------------  Example  ----------------------------
    
    gap> a :=l[1]; b:=l[2]; # a and b are images of group generators in KG
    (Z(2)^0)*f1
    (Z(2)^0)*f2
    gap> e := One( KG );    # for convenience, we denote the identity by e
    (Z(2)^0)*<identity> of ...
    gap> x := ( e + a ) * ( e + b ); 
    (Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2  
    
  ------------------------------------------------------------------
  
  We may investigate some of the basic properties of our element.
  
  ---------------------------  Example  ----------------------------
    
    gap> Support( x );
    [ <identity> of ..., f1, f2, f1*f2 ]
    gap> CoefficientsBySupport( x );
    [ Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0 ]
    gap> Length( x );
    4
    gap> TraceOfMagmaRingElement( x );
    Z(2)^0
    
  ------------------------------------------------------------------
  
  We  can also calculate the augmentation of x, which is defined as the sum of
  its coefficients.
  
  ---------------------------  Example  ----------------------------
    gap> Augmentation( x );
    0*Z(2)
    gap> IsUnit( KG, x );
    false
  ------------------------------------------------------------------
  
  Since  the  augmentation of x is zero, x is not invertible, but 1+x is. This
  is again very easy to check.
  
  ---------------------------  Example  ----------------------------
    
    gap> y := e + x;
    (Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2
    gap> IsUnit( KG, y );
    true  
    
  ------------------------------------------------------------------
  
  LAGUNA can calculate the inverse of 1+x very quickly.
  
  ---------------------------  Example  ----------------------------
    
    gap> y^-1;
    (Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f3+(Z(2)^0)*f4+(Z(2)^0)*f1*f2+(Z(2)^
    0)*f1*f3+(Z(2)^0)*f1*f4+(Z(2)^0)*f2*f4+(Z(2)^0)*f1*f2*f4+(Z(2)^0)*f2*f3*f4+(
    Z(2)^0)*f1*f2*f3*f4
    gap> y * y^-1;
    (Z(2)^0)*<identity> of ... 
    
  ------------------------------------------------------------------
  
  We  may  also  want  to check whether y is symmetric, that is, whether it is
  invariant under the classical involution; or whether it is unitary, that is,
  whether the classical involution inverts y. We find that y is neither.
  
  ---------------------------  Example  ----------------------------
    
    gap> Involution( y );
    (Z(2)^0)*f1+(Z(2)^0)*f1*f2+(Z(2)^0)*f2*f3*f4
    gap> y = Involution( y );
    false
    gap> IsSymmetric( y );
    false
    gap> y * Involution( y );
    (Z(2)^0)*<identity> of ...+(Z(2)^0)*f2+(Z(2)^0)*f2*f3*f4  
    gap> IsUnitary( y );
    false
    
  ------------------------------------------------------------------
  
  Now  we  calculate  some  important  ideals  of  KG.  First  we  obtain  the
  augmentation  ideal  which is the set of elements with augmentation zero. In
  our  case the augmentation ideal of KG coincides with the radical of KG, and
  this is taken into account in LAGUNA.
  
  ---------------------------  Example  ----------------------------
    
    gap> AugmentationIdeal( KG );
    <two-sided ideal in <algebra-with-one over GF(2), with 4 generators>,
      (dimension 15)>
    gap> RadicalOfAlgebra( KG ) = AugmentationIdeal( KG );
    true
    
  ------------------------------------------------------------------
  
  It  is  well-known  that  the augmentation ideal of KG is a nilpotent ideal.
  Using  Jennings' theory on dimension subgroups, we can obtain its nilpotency
  index  without  immediate  calculation of its powers. This is implemented in
  LAGUNA.
  
  ---------------------------  Example  ----------------------------
    gap> AugmentationIdealNilpotencyIndex( KG );
    9
  ------------------------------------------------------------------
  
  On  the  other  hand,  we  can also calculate the powers of the augmentation
  ideal.
  
  ---------------------------  Example  ----------------------------
    
    gap> AugmentationIdealPowerSeries( KG );
    [ <algebra of dimension 15 over GF(2)>, <algebra of dimension 13 over GF(2)>, 
      <algebra of dimension 11 over GF(2)>, <algebra of dimension 9 over GF(2)>, 
      <algebra of dimension 7 over GF(2)>, <algebra of dimension 5 over GF(2)>, 
      <algebra of dimension 3 over GF(2)>, <algebra of dimension 1 over GF(2)>, 
      <algebra over GF(2)> ]
    
  ------------------------------------------------------------------
  
  We  see  that the length of this list is exactly the nilpotency index of the
  augmentation ideal of KG.
  
  Now  let's work with the unit group of KG. First we calculate the normalized
  unit  group,  which  is  the  set  of  elements  with  augmentation one. The
  generators  of  the unit group are obtained as explained in Chapter 3.. This
  can  be  computed  very  quickly, but further computation with this group is
  very inefficient.
  
  ---------------------------  Example  ----------------------------
    
    gap> V := NormalizedUnitGroup( KG );
    <group of size 32768 with 15 generators>   
    
  ------------------------------------------------------------------
  
  In  order to make our computation in the normalised unit group efficient, we
  calculate a power-commutator presentation for this group.
  
  ---------------------------  Example  ----------------------------
    
    gap> W := PcNormalizedUnitGroup( KG );
    <pc group of size 32768 with 15 generators>
    
  ------------------------------------------------------------------
  
  GAP  has  many  efficient  and  practical  algorithms  for groups given by a
  power-commutator presentation. In order to use these algorithms to carry out
  computation  in  the  normalised  unit group, we need to set up isomorphisms
  between the outputs of NormalizedUnitGroup and PcNormalizedUnitGroup.
  
  The  first  isomorphism maps NormalizedUnitGroup(KG) onto the polycyclically
  presented  PcNormalizedUnitGroup(PC).  Let's find the images of the elements
  of the group G in W.
  
  ---------------------------  Example  ----------------------------
    
    gap> t := NaturalBijectionToPcNormalizedUnitGroup( KG );
    MappingByFunction( <group of size 32768 with
    15 generators>, <pc group of size 32768 with
    15 generators>, function( x ) ... end )
    gap> List( AsList( G ), x -> ( x^Embedding( G, KG ) )^t );
    [ <identity> of ..., f2, f1, f3, f7, f1*f2*f3, f2*f3, f2*f7, f1*f3, f1*f7,
      f3*f7, f1*f2*f7, f1*f2*f3*f7, f2*f3*f7, f1*f3*f7, f1*f2 ]
    
  ------------------------------------------------------------------
  
  The second isomorphism is the inverse of the first.
  
  ---------------------------  Example  ----------------------------
    gap> f := NaturalBijectionToNormalizedUnitGroup( KG );
    [ f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12, f13, f14, f15 ] ->
    [ (Z(2)^0)*f2, (Z(2)^0)*f1, (Z(2)^0)*f3,
      (Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2,
      (Z(2)^0)*f2+(Z(2)^0)*f3+(Z(2)^0)*f2*f3,
      (Z(2)^0)*f1+(Z(2)^0)*f3+(Z(2)^0)*f1*f3, (Z(2)^0)*f4,
      (Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f3+(Z(2)^0)*f1*f2+(Z(2)^0)*f1*f3+(Z(2)^
        0)*f2*f3+(Z(2)^0)*f1*f2*f3, (Z(2)^0)*f2+(Z(2)^0)*f4+(Z(2)^0)*f2*f4,
      (Z(2)^0)*f1+(Z(2)^0)*f4+(Z(2)^0)*f1*f4,
      (Z(2)^0)*f3+(Z(2)^0)*f4+(Z(2)^0)*f3*f4,
      (Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f4+(Z(2)^0)*f1*f2+(Z(2)^0)*f1*f4+(Z(2)^
        0)*f2*f4+(Z(2)^0)*f1*f2*f4, (Z(2)^0)*f2+(Z(2)^0)*f3+(Z(2)^0)*f4+(Z(2)^
        0)*f2*f3+(Z(2)^0)*f2*f4+(Z(2)^0)*f3*f4+(Z(2)^0)*f2*f3*f4,
      (Z(2)^0)*f1+(Z(2)^0)*f3+(Z(2)^0)*f4+(Z(2)^0)*f1*f3+(Z(2)^0)*f1*f4+(Z(2)^
        0)*f3*f4+(Z(2)^0)*f1*f3*f4, (Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f3+(Z(2)^
        0)*f4+(Z(2)^0)*f1*f2+(Z(2)^0)*f1*f3+(Z(2)^0)*f1*f4+(Z(2)^0)*f2*f3+(Z(2)^
        0)*f2*f4+(Z(2)^0)*f3*f4+(Z(2)^0)*f1*f2*f3+(Z(2)^0)*f1*f2*f4+(Z(2)^
        0)*f1*f3*f4+(Z(2)^0)*f2*f3*f4+(Z(2)^0)*f1*f2*f3*f4 ]
  ------------------------------------------------------------------
  
  For example, we may calculate the conjugacy classes of the group W, and then
  map their representatives back into the group algebra.
  
  ---------------------------  Example  ----------------------------
    
    gap> cc := ConjugacyClasses( W );;
    gap> Length( cc );
    848
    gap> Representative( cc[ Length( cc ) ] );
    f1*f2*f4*f6*f12*f15
    gap> last^f;
    (Z(2)^0)*<identity> of ...+(Z(2)^0)*f2+(Z(2)^0)*f4+(Z(2)^0)*f1*f2+(Z(2)^
    0)*f1*f3+(Z(2)^0)*f1*f4+(Z(2)^0)*f2*f3+(Z(2)^0)*f2*f4+(Z(2)^0)*f3*f4+(Z(2)^
    0)*f1*f2*f3+(Z(2)^0)*f1*f3*f4
    
  ------------------------------------------------------------------
  
  Having  a power-commutator presentation of the normalised unit group, we may
  use  the  full  power of the GAP functionality for such groups. For example,
  the lower central series can be calculated very quickly.
  
  ---------------------------  Example  ----------------------------
    
    gap> LowerCentralSeries( W );
    [ <pc group of size 32768 with 15 generators>,
      Group([ f3, f5*f8*f10*f12*f13*f14*f15, f6*f8*f12*f14*f15, f7, f9*f12,
          f10*f14, f11*f13, f13*f14, f14*f15 ]),
      Group([ f7, f9*f12, f10*f15, f11*f15, f13*f15, f14*f15 ]),
      Group([ f11*f15, f13*f15, f14*f15 ]), Group([ <identity> of ... ]) ]
    
  ------------------------------------------------------------------
  
  Let's  now  compute,  for  instance,  a  minimal system of generators of the
  centre  of  the normalised unit group. First we carry out the computation in
  the  group which is determined by the power-commutator presentation, then we
  map the result into our group algebra.
  
  ---------------------------  Example  ----------------------------
    
    gap> C := Centre( W );
    Group([ f3*f5*f13*f15, f7, f15, f13*f15, f14*f15, f11*f13*f14*f15 ])
    gap> m := MinimalGeneratingSet( C );
    [ f7*f13*f14*f15, f13*f14*f15, f7*f11*f14*f15, f15, f3*f5*f14 ]
    gap> List( m, g -> g^f );
    [ (Z(2)^0)*<identity> of ...+(Z(2)^0)*f3+(Z(2)^0)*f1*f2+(Z(2)^0)*f3*f4+(Z(2)^
        0)*f1*f2*f3+(Z(2)^0)*f1*f2*f4+(Z(2)^0)*f1*f2*f3*f4,
      (Z(2)^0)*f3+(Z(2)^0)*f4+(Z(2)^0)*f1*f2+(Z(2)^0)*f3*f4+(Z(2)^0)*f1*f2*f3+(
        Z(2)^0)*f1*f2*f4+(Z(2)^0)*f1*f2*f3*f4, (Z(2)^0)*<identity> of ...+(Z(2)^
        0)*f2+(Z(2)^0)*f3+(Z(2)^0)*f1*f2+(Z(2)^0)*f2*f3+(Z(2)^0)*f2*f4+(Z(2)^
        0)*f3*f4+(Z(2)^0)*f1*f2*f3+(Z(2)^0)*f1*f2*f4+(Z(2)^0)*f2*f3*f4+(Z(2)^
        0)*f1*f2*f3*f4, (Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f3+(Z(2)^0)*f4+(Z(2)^
        0)*f1*f2+(Z(2)^0)*f1*f3+(Z(2)^0)*f1*f4+(Z(2)^0)*f2*f3+(Z(2)^0)*f2*f4+(
        Z(2)^0)*f3*f4+(Z(2)^0)*f1*f2*f3+(Z(2)^0)*f1*f2*f4+(Z(2)^0)*f1*f3*f4+(Z(2)^
        0)*f2*f3*f4+(Z(2)^0)*f1*f2*f3*f4, (Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(
        Z(2)^0)*f3+(Z(2)^0)*f1*f3+(Z(2)^0)*f1*f4+(Z(2)^0)*f2*f3+(Z(2)^0)*f2*f4+(
        Z(2)^0)*f3*f4+(Z(2)^0)*f1*f3*f4 ]
    
  ------------------------------------------------------------------
  
  We  finish  our  example  by  calculating some properties of the Lie algebra
  associated with KG. This example needs no further explanation.
  
  ---------------------------  Example  ----------------------------
    
    gap> L := LieAlgebra( KG );
    #I  LAGUNA package: Constructing Lie algebra ...
    <Lie algebra over GF(2)>
    gap> D := LieDerivedSubalgebra( L );
    #I  LAGUNA package: Computing the Lie derived subalgebra ...
    <Lie algebra of dimension 9 over GF(2)>
    gap> LC := LieCentre( L );
    <Lie algebra of dimension 7 over GF(2)>
    gap> LieLowerNilpotencyIndex( KG );
    5
    gap> LieUpperNilpotencyIndex( KG );
    5
    gap> IsLieAbelian( L );
    false
    gap> IsLieSolvable( L );
    #I  LAGUNA package: Checking Lie solvability ...
    true
    gap> IsLieMetabelian( L );
    false
    gap> IsLieCentreByMetabelian( L );
    true
    
  ------------------------------------------------------------------