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> s := AugmentationIdealPowerSeries( KG );;
    gap> s[2];
    <algebra of dimension 13 over GF(2)>
    gap> List(s,Dimension);
    [ 15, 13, 11, 9, 7, 5, 3, 1, 0 ]
    gap> Length(s);
    9
    
  
  
  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> Image(t) = W;
    true
    gap> List( AsList( G ), x -> ( x^Embedding( G, KG ) )^t );
    [ <identity> of ..., f1, f2, f4, f8, f1*f2, f1*f4, f1*f8, f2*f4, f2*f8, 
      f4*f8, f1*f2*f4, f1*f2*f8, f1*f4*f8, f2*f4*f8, f1*f2*f4*f8 ]
    
  
  
  The second isomorphism is the inverse of the first.
  
    Example  
    
    gap> f := NaturalBijectionToNormalizedUnitGroup( KG );;
    gap> Image(f) = V;
    true
    
  
  
  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*f3*f6*f10*f13
    gap> last^f;
    (Z(2)^0)*<identity> of ...+(Z(2)^0)*f1*f2+(Z(2)^0)*f1*f3+(Z(2)^0)*f1*f4+(Z(2)^
    0)*f2*f3+(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([ f4*f8, f5*f7*f11*f13*f15, f6*f7*f9*f11*f13*f14*f15, f8, f9*f13, 
          f10*f11, f12*f13, f13*f15, f14*f15 ]), 
      Group([ f8, f9*f15, f10*f11, f12*f15, f13*f15, f14*f15 ]), 
      Group([ f12*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 );;
    gap> m := MinimalGeneratingSet( C );
    [ f8*f13*f14*f15, f13*f14*f15, f8*f12*f14*f15, f15, f4*f6*f8*f13 ]
    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)*f1+(Z(2)^0)*f3+(Z(2)^0)*f1*f2+(Z(2)^0)*f1*f3+(Z(2)^0)*f1*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)*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)*f1+(Z(2)^0)*f2+(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)*f2*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 of dimension 16 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