<Chapter Label="Funct">
<Heading>&LAGUNA; functions</Heading>

<Section Label="GenSec">
<Heading>General functions for group algebras</Heading>


<ManSection>
   <Prop Name="IsGroupAlgebra" 
         Arg="KG"  
         Comm="determines if a group ring is a group algebra" />
   <Description>
         A group ring over a field is called a group algebra.         
         For a group ring <A>KG</A>, 
	 <C>IsGroupAlgebra</C> returns <K>true</K>,
	 if the underlying ring of <A>KG</A> is a field; 
	 <K>false</K> is returned otherwise.
         This property will be set automatically for every 
	 group ring created by the function <C>GroupRing</C>. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> IsGroupAlgebra( GroupRing( GF( 2 ), DihedralGroup( 16 ) ) );
true
gap> IsGroupAlgebra( GroupRing( Integers, DihedralGroup( 16 ) ) );
false      
]]>
</Example>


<ManSection>
   <Prop Name="IsFModularGroupAlgebra" 
         Arg="KG" 
         Comm="determines if group algebra is modular" />
   <Description>
         <Index>modular group algebra</Index>
         A group algebra <M>KG</M> over a field <M>K</M> is 
	 called <E>modular</E>, if the characteristic of the field 
	 <M>K</M> divides the order of some element in <M>G</M>.
         For a group algebra <A>KG</A> of a finite group
	 <M>G</M>, <C>IsModularGroupAlgebra</C> returns 
	 <K>true</K>, if <A>KG</A> is modular 
	 according to this definition;
         <K>false</K> is returned otherwise.
         This property will be set automatically for every 
	 group algebra, created by the function 
	 <C>GroupRing</C>. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> IsFModularGroupAlgebra( GroupRing( GF( 2 ), SymmetricGroup( 6 ) ) );
true
gap> IsFModularGroupAlgebra( GroupRing( GF( 2 ), CyclicGroup( 3 ) ) );
false  
]]>
</Example>


<ManSection>
   <Prop Name="IsPModularGroupAlgebra" 
         Arg="KG"  
	 Comm="determines if group algebra is p-modular" />
   <Description>
         A group algebra <M>KG</M> is said to be <M>p</M>-modular, 
	 if <M>K</M> is a field of characteristic <M>p</M> and 
	 <M>G</M> is a finite <M>p</M>-group for the same prime 
	 <M>p</M>. 
         For a group algebra <A>KG</A> of a finite
	 group <M>G</M>, <C>IsPModularGroupAlgebra</C> 
	 returns <K>true</K>, if <A>KG</A> is 
	 <M>p</M>-modular according to this definition;
         <K>false</K> is returned otherwise.
         This property will be set automatically for every 
	group algebra, created by the function 
	 <C>GroupRing</C>. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> IsPModularGroupAlgebra( GroupRing( GF( 2 ), DihedralGroup( 16 ) ) );
true
gap> IsPModularGroupAlgebra( GroupRing( GF( 2 ), SymmetricGroup( 6 ) ) );
false        
]]>
</Example>


<ManSection>
   <Attr Name="UnderlyingGroup" 
         Label="of a group ring"
         Arg="KG" />
   <Returns>
         the underlying group of a group ring
   </Returns>
   <Description>
         This attribute stores the underlying group of a
	 group ring <A>KG</A>. In fact, it refers to
	 the attribute <C>UnderlyingMagma</C> which
	 returns the same result, and was introduced for group
	 rings for convenience, and for teaching purposes.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF ( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
gap> G := UnderlyingGroup( KG );
<pc group of size 16 with 4 generators>  
]]>
</Example>


<ManSection>
   <Attr Name="UnderlyingRing" 
         Arg="KG" />
   <Returns>
         the underlying ring of a group ring
   </Returns>
   <Description>
         This attribute stores the underlying ring of a
	 group ring <A>KG</A>. In fact, it refers to
	 the attribute <C>LeftActingDomain</C> which
	 returns the same result, and was introduced for group
	 rings for convenience, and for teaching purposes.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
gap> UnderlyingRing( KG );
GF(2)     
]]>
</Example>


<ManSection>
   <Attr Name="UnderlyingField" 
         Arg="KG" />
   <Returns>
         the underlying field of a group algebra
   </Returns>
   <Description>
         This attribute stores the underlying field of a
	 group algebra <A>KG</A>. In fact, it refers to
	 the attribute <C>LeftActingDomain</C> which
	 returns the same result, and was introduced for group
	 algebras for convenience, and for teaching purposes.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
gap> UnderlyingField( KG );
GF(2)    
]]>
</Example>
</Section>

<!-- ######################################################### -->

<Section Label="ElemFunctions">
<Heading>Operations with group algebra elements</Heading>


<ManSection>
   <Attr Name="Support" 
         Arg="x" />  
   <Returns>
         support of x as a list of elements of the underlying group
   </Returns>
   <Description>
         Returns the support of a group ring element <A>x</A>.
	 The support of a non-zero element 
	 <M> x = \alpha_1 \cdot g_1 + \alpha_2 \cdot g_2 + \cdots + \alpha_k \cdot g_k</M> 
         of a group ring is the list of elements <M>g_i \in G</M> for which 
	 the coefficient <M>\alpha_i</M> is non-zero. The support of the zero 
	 element of a group ring is defined to be the empty list.
	 This method is also applicable to elements of magma rings.
   </Description>
</ManSection>

<Example>
<![CDATA[
# First we create an element x to use in in the series of examples.
# We map the minimal generating system of the group G to its group algebra
# and denote their images as a and b
gap> G:=DihedralGroup(16);; KG:=GroupRing(GF(2),G);;
gap> l := List( MinimalGeneratingSet( G ), g -> g^Embedding( G, KG ) );
[ (Z(2)^0)*f1, (Z(2)^0)*f2 ]
gap> a := l[1]; b := l[2]; e := One( KG ); # we denote the identity by e
(Z(2)^0)*f1
(Z(2)^0)*f2
(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
gap> Support( x );
[ <identity> of ..., f1, f2, f1*f2 ]     
]]>
</Example>


<ManSection>
   <Attr Name="CoefficientsBySupport" 
         Arg="x" />
   <Returns>
  	 coefficients of support elements as list of elements 
	 of the underlying ring
   </Returns>
   <Description>
         Returns a list that contains the coefficients
	 corresponding to the elements of <C>Support( x )</C> 
	 in the same order as the elements appear in 
	 <C>Support( x )</C>.
	 This method is also applicable to elements of magma rings.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> x;
(Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2
gap> CoefficientsBySupport( x );
[ Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0 ]   
]]>
</Example>


<ManSection>
   <Attr Name="TraceOfMagmaRingElement" 
         Arg="x" 
	 Comm="returns the trace of a magma ring element" />
   <Returns>
  	 an element of the underlying ring
   </Returns>
   <Description>
         Returns the trace of a group ring element
	 <A>x</A>. 
         By definition, the trace of an element 
	 <M> x = \alpha_1 \cdot 1 + \alpha_2 \cdot g_2 + \cdots + \alpha_k \cdot g_k </M> 
	 is equal to <M>\alpha_1</M>, that is, the coefficient of the 
	 identity element in <M>G</M>. The trace of the zero 
	 element is zero. This method is also applicable to
	 elements of magma rings.  
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> x;
(Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2
gap> TraceOfMagmaRingElement( x );
Z(2)^0        
]]>
</Example>


<ManSection>
   <Attr Name="Length" 
         Arg="x"  
	 Comm="returns the length of a group ring element" />
   <Description>
         The length of an element of a group ring 
	 <A>x</A>  is defined as the number of elements in
	 its support.
	 This method is also applicable to elements of magma rings.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> x;
(Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2
gap> Length( x );
4     
]]>
</Example>


<ManSection>
   <Attr Name="Augmentation" 
         Arg="x"
	 Comm="returns the augmentation of a group ring element" />
   <Returns>
         the sum of coefficients of a group ring element
   </Returns>
   <Description>
         The augmentation of a group ring element 
	 <M> x = \alpha_1 \cdot g_1 + \alpha_2 \cdot g_2 + \cdots + \alpha_k \cdot g_k</M> 
	 is the sum of its coefficients <M> \alpha_1 + \alpha_2 + \cdots + \alpha_k </M>. 
	 The method is also applicable to elements of magma rings.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> x;
(Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2
gap> Augmentation( x );
0*Z(2)     
]]>
</Example>


<ManSection>
   <Oper Name="PartialAugmentations" 
         Arg="KG x"
	 Comm="returns partial augmentations of a group ring element" />
   <Returns>
         a list of partial augmentations and a list of conjugacy class 
         representatives
   </Returns>
   <Description>
   <Index>partial augmentation</Index>
         The partial augmentation of an element 
	 <M> x = \alpha_1 \cdot g_1 + \alpha_2 \cdot g_2 + \cdots + 
                 \alpha_k \cdot g_k</M> 
	 of the group ring <M>KG</M>,
	 corresponding to the conjugacy class of an element <M>g</M> from
         the underlying group <M>G</M> is the sum of coefficients 
         <M>\alpha_i</M> taken over all <M>g_i</M> such that <M>g_i</M>
         is conjugated to <M>g</M>.
         The function returns a list of two lists, the first one is a 
         list of partial augmentations, and the second is a list of 
         representatives of appropriate conjugacy classes of elements 
         of the group <M>G</M>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> y := x + a*b^2;
(Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2+(Z(2)^
0)*f1*f3
gap> PartialAugmentations( KG, y );
[ [ Z(2)^0, 0*Z(2), Z(2)^0, Z(2)^0 ], [ <identity> of ..., f1, f2, f1*f2 ] ]    
]]>
</Example>

<ManSection>
   <Oper Name="Involution" 
         Arg="x [, [f], s ]"
	 Comm="Involution determined by two or one mappings or the classical involution" />
   <Returns>
         an element of a group ring
   </Returns>
   <Description>
     Let <M>KG</M> be a group ring, <M>f</M> be a homomorphism from the group <M>G</M> 
     to the unit group of the ring <M>K</M>. Furthermore, let <M>s</M> be a mapping 
     <M>G \rightarrow G</M>, such that <M>s^2</M> is the identity mapping on <M>G</M>
     and for every element <M>g \in G</M> <M>f(g*s(g))</M> equals <M>f(s(g)*g)</M> and
     equals the identity element of the ring <M>K</M>. Then the involution
	 of <M>KG</M> induced by <M>f</M> and <M>s</M> is defined by
         <M> \alpha_1 \cdot g_1 + \alpha_2 \cdot g_2 + \cdots + \alpha_k \cdot g_k
	 \mapsto 
	 \alpha_1 \cdot f(g_1) \cdot s(g_1) + \alpha_2 \cdot f(g_2) \cdot s(g_2) + \cdots + 
	                                      \alpha_k \cdot f(g_k) \cdot s(g_k)</M>.
	 <P/>                                      
	 The method returns the image of <A>x</A> under the involution of <M>KG</M> 
	 induced by <M>f</M> and <M>s</M>. If the mapping <M>f</M> is omitted, <M>f</M> 
	 is assumed to map everything to the identity element of the ring <M>K</M>. 
	 If both mappings are omitted, it returns the result of so-called classical 
	 involution, induced by the mapping <M> x \mapsto x^{-1}</M>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> x;
(Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2
gap> Involution( x );
(Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(Z(2)^0)*f1*f2+(Z(2)^0)*f2*f3*f4
gap> l := List( MinimalGeneratingSet( G ), g -> g^Embedding( G, KG ) );
[ (Z(2)^0)*f1, (Z(2)^0)*f2 ]
gap> List( l, Involution ); # check how involution acts on elements of G
[ (Z(2)^0)*f1, (Z(2)^0)*f2*f3*f4 ]
gap> List( l, g -> g^-1 );
[ (Z(2)^0)*f1, (Z(2)^0)*f2*f3*f4 ]     
]]>
</Example>


<ManSection>
   <Attr Name="IsSymmetric" 
         Arg="x"
	 Comm="checks whether an element is fixed under the classical involution" />
   <Description>
   <Index>symmetric element</Index>
         An element of a group ring is called <E>symmetric</E> if it is fixed under the
         classical involution. This property is checked here. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> IsSymmetric( x );
false
gap> IsSymmetric( x * Involution( x ) );
true     
]]>
</Example>


<ManSection>
   <Attr Name="IsUnitary" 
         Arg="x"
	 Comm="checks whether an element is unitary w.r.t. classical involution" />
   <Description>
   <Index>unitary element</Index>
         A unit of a group ring is called unitary if the classical involution
         inverts it. This property is checked here. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> IsUnitary(x);
false
gap> l:=List(MinimalGeneratingSet(G),g -> g^Embedding(G,KG));
[ (Z(2)^0)*f1, (Z(2)^0)*f2 ]
gap> List(l,IsUnitary); # check that elements of G are unitary
[ true, true ]   
]]>
</Example>


<ManSection>
   <Meth Name="IsUnit" 
         Arg="[ KG, ] x"
	 Comm="for a modular group algebra and its element or for a magma ring element" />
   <Description>
     This method improves a standard &GAP; functionality for modular group algebras.
	 <P/> 
     In the two-argument version the method returns <K>true</K> if
	 <A>x</A> is an invertible element of the modular
	 group algebra <A>KG</A> and <K>false</K> 
	 otherwise. This can be done very quickly by checking 
	 whether the augmentation of the element <A>x</A>
	 is non-zero.
	 <P/>
	 If the first argument is omitted, then &LAGUNA; constructs the 
	 group <M>H</M>  generated by the
	 support of <A>x</A>, and, if this group is
	 a finite <M>p</M>-group, then checks whether 
	 the coefficients of <A>x</A> belong to a
	 field <M>F</M> of characteristic <M>p</M>. If this is the
	 case, then <C>IsUnit( FH, x )</C> is called;
	 otherwise, standard &GAP; method is used.  
   </Description>
</ManSection>


<Example>
<![CDATA[
gap> x;
(Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2
gap> IsUnit( KG, x ); # clearly, is not a unit due to augmentation zero
false
gap> y := One( KG ) + x; # this should give a unit
(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2
gap> IsUnit( KG, y );
true       
]]>
</Example>


<ManSection>
   <Meth Name="InverseOp" 
         Arg="x"  
	 Comm="for an element of the modular group algebra" />
   <Returns>
         the inverse element of an element of a group ring
   </Returns>
   <Description>
         This method improves a standard &GAP; functionality for modular group algebras.
         It calculates the inverse of a group algebra element. 
	 The user can also invoke this function by typing 
	 <C> x&circum;-1 </C>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> y;
(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2
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 ...    
]]>
</Example>


<ManSection>
   <Oper Name="BicyclicUnitOfType1" 
         Arg="[KG,] a g"
	 Comm="for elements of a group, possibly embedded into group ring" />
   <Oper Name="BicyclicUnitOfType2" 
         Arg="[KG,] a g"
	 Comm="for elements of a group, possibly embedded into group ring" />
   <Returns>
         an element of a group ring
   </Returns>
   <Description>
   <Index>bicyclic unit</Index> 
         let <M>a</M> be an element of order <M>n</M> of a group 
         <M>G</M>. We put 
         <M>\alpha = 1 + a + a^2 + ... +a^{n-1} </M>.
         Then <M>(a-1)*g*\alpha</M> and <M>\alpha*g*(a-1)</M>
         are nilpotent of index two for any element <M>g</M> of the
         group <M>G</M> not containing in the normalizer
         <M>N_G(\langle a \rangle)</M>, and the units
         <M>u_{a,g} = 1 + (a-1) * g * \alpha </M>
         and
         <M>v_{a,g} = 1 + \alpha * g * (a-1) </M> 
         are called <E>bicyclic units</E> of the 1st and 2nd type
         respectively. Note that  
         <M>u_{a,g}</M> and <M>v_{a,g}</M> may coincide for some 
         <M>a</M> and <M>g</M>, but in general this does not hold.
         In the three-argument version these methods construct 
         bicyclic units of both types when <A>a</A> and <A>g</A> are elements 
         of the underlying group <M>G</M> of a group ring <A>KG</A>.
         The two-argument version accepts images of elements <A>a</A> and <A>g</A> 
         from the underlying group in the group ring <M>KG</M> obtained using the 
         mapping <C>Embedding( G, KG )</C>. 
         Note that it is not actually 
         checked that <M>g</M> is not contained in 
         <M>N_G(\langle a \rangle)</M>, because this is
         verified in <Ref Attr="BicyclicUnitGroup" />.
    </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SmallGroup(32,6);
<pc group of size 32 with 5 generators>
gap> KG := GroupRing( GF(2), G );
<algebra-with-one over GF(2), with 5 generators>
gap> g := MinimalGeneratingSet( G );
[ f1, f2 ]
gap> g[1] in Normalizer( G, Subgroup( G, [g[2]] ) );
false
gap> g[2] in Normalizer( G, Subgroup( G, [g[1]] ) );
false
gap> g := List( g, x -> x^Embedding( G, KG ) );
[ (Z(2)^0)*f1, (Z(2)^0)*f2 ]
gap> BicyclicUnitOfType1(g[1],g[2]) = BicyclicUnitOfType2(g[1],g[2]);
false                                                                       
]]>
</Example>


<ManSection>
   <Oper Name="BassCyclicUnit" 
         Arg="[ZG,] g k" />
   <Returns>
         an element of a group ring
   </Returns>
    <Description>
       <Index>Bass cyclic unit</Index> 
        Let <A>g</A> be an element of order <M>n</M> of the group <M>G</M>, 
        and 1 &lt; <A>k</A> &lt; <M>n</M> be such that <A>k</A> and <M>n</M> 
        are coprime, then  <A>k</A>^Phi(<M>n</M>) is congruent 
        to 1 modulo <M>n</M>. The unit
        <Alt Only="LaTeX">
        $$b(g,k)=\left(\sum_{j=0}^{k-1}g^j\right)^{\varphi(n)}+\frac{1-k^{\varphi (n)}}{n}\hat{g},$$
        </Alt>
        <Alt Not="LaTeX">
        b(g,k)= ( \sum_{j=0}^{k-1} g^j )^Phi(n) + ( (1-k^Phi(n))/n ) * Hat(g),
        </Alt>
        where 
        <Alt Only="LaTeX">$\hat{g} = g + g^2 + ... + g^n$,</Alt>
        <Alt Not="LaTeX">Hat(g) = g + g^2 + ... + g^n,</Alt> 
        is called a <E>Bass cyclic unit</E> of the integral group ring <A>ZG</A>.
        <P/>
        The three-argument version constructs the Bass cyclic unit <M>b(g,k)</M> for the
        element <A>g</A> from the underlying group <M>G</M> of the group ring <A>ZG</A>.
        The two-argument version accepts the image of <A>g</A> in the group ring <M>ZG</M> 
        obtained using the mapping <C>Embedding( G, KG )</C>. 
        <P/>
        Remark that when <M>G</M> is a finite nilpotent group, the group 
        generated by the Bass cyclic units contain a subgroup of finite 
        index in the centre of the unit group of <A>ZG</A> <Cite Key="JePaSe96" />.
    </Description>
</ManSection>

<Example>
<![CDATA[
gap> S := SymmetricGroup( 5 );;
gap> ZS := GroupRing( Integers, S );;
gap> f := Embedding( S, ZS );;
gap> BassCyclicUnit( ZS, (1,3,2,5,4) , 3 );
(1)*()+(-2)*(1,2,4,3,5)+(-2)*(1,3,2,5,4)+(3)*(1,4,5,2,3)+(1)*(1,5,3,4,2)
gap> BassCyclicUnit( (1,3,2,5,4)^f, 3 ); 
(1)*()+(-2)*(1,2,4,3,5)+(-2)*(1,3,2,5,4)+(3)*(1,4,5,2,3)+(1)*(1,5,3,4,2)
]]>
</Example>

</Section>


<!-- ######################################################### -->

<Section Label="Ideals">
<Heading>Important attributes of group algebras</Heading>


<ManSection>
   <Attr Name="AugmentationHomomorphism" 
         Arg="KG" 
	 Comm="returns the augmentation homomorphism" />
   <Returns>
         a homomorphism from a group ring to the underlying ring
   </Returns>
   <Description>
         The mapping which maps an element of a group ring <M>KG</M>
	 to its augmentation is a homomorphism from <M>KG</M> onto the 
	 ring <M>K</M>; see <Ref Attr="Augmentation" />.
	 This attribute stores this homomorphism for the group ring 
	 <A>KG</A>.
	 <P/>
	 Please note that for calculation of the augmentation of an element 
	 of a group ring the user is strongly recommended to use 
	 <Ref Attr="Augmentation" /> which works much faster than 
	 <C>AugmentationHomomorphism</C>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> F := GF( 2 ); G := SymmetricGroup( 3 ); FG := GroupRing( F, G );
GF(2)
Sym( [ 1 .. 3 ] )
<algebra-with-one over GF(2), with 2 generators>
gap> e := Embedding( G,FG );
<mapping: SymmetricGroup( [ 1 .. 3 ] ) -> AlgebraWithOne( GF(2), ... ) >
gap> x := (1,2)^e; y := (1,3)^e;
(Z(2)^0)*(1,2)
(Z(2)^0)*(1,3)
gap> a := AugmentationHomomorphism( FG );
[ (Z(2)^0)*(1,2,3), (Z(2)^0)*(1,2) ] -> [ Z(2)^0, Z(2)^0 ]
gap> x^a; y^a; ( x + y )^a; # this is slower
Z(2)^0
Z(2)^0
0*Z(2)   
gap> Augmentation(x); Augmentation(y); Augmentation( x + y ); # this is faster
Z(2)^0
Z(2)^0
0*Z(2)   
]]>
</Example>


<ManSection>
   <Attr Name="AugmentationIdeal" 
         Arg="KG" 
	 Comm="returns the augmentation ideal" />
   <Returns>
         an ideal of a group ring
   </Returns>
   <Description>
         If <M>KG</M> is a group ring, then its augmentation 
	 ideal <M>A</M> is generated by all elements of the form 
	 <M>g-1</M>, where <M>g \in G</M> &bslash; &obrace; <M>1</M> &cbrace;.
	 The augmentation ideal 
         consists of all elements of <M>FG</M> with augmentation 
	 <M>0</M>; see <Ref Meth="Augmentation" />. 
         This method changes a standard &GAP; functionality for modular group algebras and returns the augmentation 
	 ideal of a modular group algebra <A>KG</A>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
gap> AugmentationIdeal( KG );
<two-sided ideal in <algebra-with-one over GF(2), with 4 generators>,
  (dimension 15)>
]]>
</Example>


<ManSection>
   <Attr Name="RadicalOfAlgebra" 
         Arg="KG"  
	 Comm="for modular group algebra of finite p-group" />
   <Returns>
         an ideal of a group algebra
   </Returns>
   <Description>
         This method improves a standard &GAP; functionality for modular group algebras of finite <M>p</M>-groups.
	 Since in this case the radical of the group algebra coincides with 
	 its augmentation ideal, this method simply checks if 
	 the algebra <A>KG</A> is a <M>p</M>-modular group algebra, 
	 and, if yes, it returns the augmentation ideal;
	 otherwise, the standard &GAP; method will be used.  
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
gap> RadicalOfAlgebra( KG );
<two-sided ideal in <algebra-with-one over GF(2), with 4 generators>,
  (dimension 15)>
gap> RadicalOfAlgebra( KG ) = AugmentationIdeal( KG );
true     
]]>
</Example>


<ManSection>
   <Attr Name="WeightedBasis" 
         Arg="KG"  
	 Comm="for modular group algebra of finite p-group" />
   <Returns>
         a record of two components: weighted basis elements and
	 their weights
   </Returns>
   <Description>
         The argument <A>KG</A> must be a <M>p</M>-modular 
	 group algebra. 
         <P/>
	 For a group algebra <M>KG</M>, let <M>A</M> denote the 
	 augmentation ideal, and assume that <M>c</M> is the 
	 smallest number such that <M>A^c=0</M>. Then a weighted 
	 basis of <M>KG</M> is some basis <M> b_1, \ldots, b_n </M> 
	 for the augmentation ideal <M>A</M>, for which there are
	 indices <M> i_1=1, \ldots, i_{c-1} </M> such that 
	 <M> b_{i_k}, \ldots, b_n </M> is a basis for <M>A^k</M>. 
	 The weight of an element <M>b_i</M> of a weighted basis 
	 is the unique integer <M>w</M> such that 
	 <M>b_i</M> belongs to <M>w</M>-th power of <M>A</M> but 
	 does not belong to its <M>(w+1)</M>-th power. 
	 <P/>
         Note that this function actually constructs a basis for 
	 the <E>augmentation ideal</E> of <A>KG</A> and not for 
	 <A>KG</A> itself. Since the augmentation ideal has 
	 co-dimension 1 in <C>KG</C>, a basis for <C>KG</C> can
	 be easily obtained by adjoining the identity element of 
	 the group.
	 <P/>
         The method returns a record whose basis entry is the basis
	 and the weights entry is a list of the corresponding weights 
	 the of basis elements. See Section <Ref Sect="TheoryThird" /> 
	 for more details.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), ElementaryAbelianGroup( 4 ) );
<algebra-with-one over GF(2), with 2 generators>
gap> WeightedBasis( KG );
rec( 
  weightedBasis := [ (Z(2)^0)*<identity> of ...+(Z(2)^0)*f1, 
      (Z(2)^0)*<identity> of ...+(Z(2)^0)*f2, 
      (Z(2)^0)*<identity> of ...+(Z(2)^0)*f1+(Z(2)^0)*f2+(Z(2)^0)*f1*f2 ], 
  weights := [ 1, 1, 2 ] )
]]>
</Example>


<ManSection>
   <Attr Name="AugmentationIdealPowerSeries" 
         Arg="KG" 
	 Comm="for p-modular group algebra" />
   <Returns>
         a list of ideals of a group algebra
   </Returns>
   <Description>
         The argument <A>KG</A> is a <M>p</M>-modular group
	 algebra. The method returns a list whose elements are 
	 the terms of the augmentation ideal filtration of 
	 <A>KG</A>, that is 
	 <C>AugmentationIdealPowerSeries(A)[i]</C> is the
	 <M>i</M>-th power of the augmentation ideal of <A>KG</A>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
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
]]>
</Example>


<ManSection>
   <Attr Name="AugmentationIdealNilpotencyIndex" 
         Arg="KG"
         Comm="for p-modular group algebra" />
   <Description>
         For the <M>p</M>-modular group algebra <A>KG</A>
	 the method returns the smallest number <M>n</M> such 
	 that <M>A^n=0</M>, where <M>A</M> is the 
	 augmentation ideal of <A>KG</A>. This can be 
	 done using Jenning's theory without the explicit
	 calculations of the powers of the augmentation ideal.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
gap> AugmentationIdealNilpotencyIndex( KG );
9      
]]>
</Example>


<ManSection>
   <Attr Name="AugmentationIdealOfDerivedSubgroupNilpotencyIndex"
         Arg="KG"
         Comm="for p-modular group algebra" />
   <Description>
         For the <M>p</M>-modular group algebra <A>KG</A>
	 this attribute stores the nilpotency index of the 
	 augmentation ideal of <M>KG'</M> where <M>G'</M> denotes the
	 derived subgroup of <M>G</M>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
gap> AugmentationIdealOfDerivedSubgroupNilpotencyIndex( KG );
4
gap> D := DerivedSubgroup( UnderlyingGroup( KG ) );
Group([ f3, f4 ])
gap> KD := GroupRing( GF( 2 ), D );
<algebra-with-one over GF(2), with 2 generators>
gap> AugmentationIdealNilpotencyIndex( KD );
4       
]]>
</Example>


<ManSection>
   <Oper Name="LeftIdealBySubgroup" 
         Arg="KG H" 
	 Comm="returns the left or twosided ideal of a group ring" />
   <Oper Name="RightIdealBySubgroup" 
         Arg="KG H" 
	 Comm="returns the right or twosided ideal of a group ring" />
   <Oper Name="TwoSidedIdalBySubgroup" 
         Arg="KG H" 
	 Comm="returns the twosided ideal of a group ring" />
   <Returns>
         an ideal of a group ring
   </Returns>
   <Description>
         Let <A>KG</A> be a group ring of a group <M>G</M> over the
         ring <M>K</M>, and <A>H</A> be a subgroup of <M>G</M>.
         Then the set <M>J_l(H)</M> of all elements of <A>KG</A>
         of the form 
         <Display>
         \sum_{h \in H} x_h(h-1)
         </Display>
         is the left ideal in <A>KG</A> generated by all elements
         <M>h-1</M> with <M>h</M> in <M>H</M>. The right ideal
         <M>J_r(H)</M> is defined analogously.
         These operations are used to consrtuct such ideals,
         taking into account the fact, that the ideal <M>J_l(H)</M> 
         is two-sided if and only if <A>H</A> is normal in <M>G</M>.
         An attempt of constructing two-sided ideal for a non-normal 
         subgroup <A>H</A> will lead to an error message. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF(2), DihedralGroup(16) );
<algebra-with-one over GF(2), with 4 generators>
gap> G := DihedralGroup(16);
<pc group of size 16 with 4 generators>
gap> KG := GroupRing( GF(2), G );
<algebra-with-one over GF(2), with 4 generators>
gap> D := DerivedSubgroup( G );
Group([ f3, f4 ])
gap> LeftIdealBySubgroup( KG, D );
<two-sided ideal in <algebra-with-one over GF(2), with 4 generators>,
  (dimension 12)>                              
gap> H := Subgroup( G, [ GeneratorsOfGroup(G)[1] ]);
Group([ f1 ])
gap> IsNormal( G, H );
false
gap> LeftIdealBySubgroup( KG, H );
<left ideal in <algebra-with-one over GF(2), with 4 generators>, (dimension 8
 )>
]]>
</Example>


</Section>

<!-- ######################################################### -->

<Section Label="UnitGroup">
<Heading>Computations with the unit group</Heading>


<ManSection>
   <Attr Name="NormalizedUnitGroup" 
         Arg="KG" />
   <Returns>
         a group generated by group algebra elements
   </Returns>
   <Description>
         Determines the normalized unit group of a <M>p</M>-modular 
	 group algebra <A>KG</A> over the field of <M>p</M> elements. 
	 Returns the normalized unit group
	 as the group generated by certain elements of <A>KG</A>; 
	 see Section <Ref Sect="TheoryThird" /> for more details.
	 <P/> 
	 For efficient computations the user is recommended to use
         <Ref Attr="PcNormalizedUnitGroup" />.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
gap> V := NormalizedUnitGroup( KG );
<group of size 32768 with 15 generators>
gap> u := GeneratorsOfGroup( V )[4];
(Z(2)^0)*f3  
]]>
</Example>


<ManSection>
   <Attr Name="PcNormalizedUnitGroup" 
         Arg="KG" />
   <Returns>
         a group given by power-commutator presentation
   </Returns>
   <Description>
         The argument <A>KG</A> is a <M>p</M>-modular group 
	 algebra over the field of <M>p</M> elements. 
	 <C>PcNormalizedUnitGroup</C> returns 
	 the normalized unit group of <A>KG</A> given by a power-commutator
	 presentation. The generators in this polycyclic presentation 
	 correspond to the weighted basis elements of <A>KG</A>. 
	 For more details, see Section <Ref Sect="TheoryThird" />.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> W := PcNormalizedUnitGroup( KG );
<pc group of size 32768 with 15 generators>
gap> w := GeneratorsOfGroup( W )[4];
f4       
]]>
</Example>


<ManSection>
   <Attr Name="NaturalBijectionToPcNormalizedUnitGroup" 
         Arg="KG" />
   <Returns>
         a homomorphism of groups
   </Returns>
   <Description>
         The normalised unit group of a <M>p</M>-modular group 
	 algebra <M>KG</M> over the field of <M>p</M> elements
	 can be computed using two methods, 
	 namely <Ref Attr="NormalizedUnitGroup" /> and
         <Ref Attr="PcNormalizedUnitGroup" />. 
	 These two methods return two different objects, and they
	 can be used for different types of computations. The 
	 elements of <C>NormalizedUnitGroup(KG)</C> are 
	 represented in their natural group algebra representation,
	 and hence they can easily be identified in the group
         algebra. However, the more quickly constructed 
	 <C>NormalizedUnitGroup(KG)</C> is often not suitable 
	 for further fast calculations. Hence one will have to use
         <C>PcNormalizedUnitGroup(KG)</C> if one wants to 
	 find some group theoretic properties of the normalized 
	 unit group. This method returns the bijection from 
	 <C>NormalizedUnitGroup(<A>KG</A>)</C> onto 
         <C>PcNormalizedUnitGroup(<A>KG</A>)</C>. This bijection can
	 be used to map the result of a computation in
	 <C>PcNormalizedUnitGroup(<A>KG</A>)</C> into <C>NormalizedUnitGroup(<A>KG</A>)</C>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> f := NaturalBijectionToPcNormalizedUnitGroup( KG );
MappingByFunction( <group of size 32768 with 15 generators>, <pc group of size\
 32768 with 15 generators>, function( x ) ... end )
gap> u := GeneratorsOfGroup( V )[4];;
gap> u^f;
f4   
gap> GeneratorsOfGroup( V )[4]^f = GeneratorsOfGroup( W )[4];
true      
]]>
</Example>


<ManSection>
   <Attr Name="NaturalBijectionToNormalizedUnitGroup" 
         Arg="KG" />
   <Returns>
         a homomorphism of groups
   </Returns>
   <Description>
         For a <M>p</M>-modular group algebra <A>KG</A>
	 over the field of <M>p</M> elements 
         this function returns the inverse of the mapping
	 <Ref Attr="NaturalBijectionToPcNormalizedUnitGroup" />
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> t := NaturalBijectionToNormalizedUnitGroup(KG);;
gap> w := GeneratorsOfGroup(W)[4];;
gap> w^t;
(Z(2)^0)*f3    
gap> GeneratorsOfGroup( W )[4]^t = GeneratorsOfGroup( V )[4];
true     
]]>
</Example>


<ManSection>
   <Oper Name="Embedding"
         Label="from group to unit group"
         Arg="H V" />
   <Returns>
         a homomorphism from an underlying group to a normalized unit group in pc-presentation
   </Returns>
   <Description>
         Let <A>H</A> be a subgroup of a group <M>G</M> and 
         <A>V</A> be the normalized unit group of the group algebra 
         <M>KG</M> given by the power-commutator presentation
         (see <Ref Attr="PcNormalizedUnitGroup"/>. 
         Then <C>Embedding( H, V )</C> returns the homomorphism from 
         <A>H</A> to <A>V</A>, which is the composition of 
         <C>Embedding( H, KG )</C> and 
         <C>NaturalBijectionToPcNormalizedUnitGroup( KG )</C>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := DihedralGroup( 16 );
<pc group of size 16 with 4 generators>
gap> KG := GroupRing( GF( 2 ), G );
<algebra-with-one over GF(2), with 4 generators>
gap> V:=PcNormalizedUnitGroup( KG );
<pc group of size 32768 with 15 generators>
gap> ucs := UpperCentralSeries( V );;
gap> f := Embedding( G, V );
[ f1, f2, f3, f4 ] -> [ f1, f2, f4, f8 ]
gap> G1 := Image( f, G ); 
Group([ f1, f2, f4, f8 ])
gap> H := Intersection( ucs[2], G1 ); # compute intersection in V(KG)
Group([ f4, f8, f4*f8 ])
gap> T:=PreImage( f, H );             # find its preimage in G
Group([ f3, f4, f3*f4 ])
gap> IdGroup( T ); 
[ 4, 1 ]
]]>
</Example>

<ManSection>
   <Attr Name="Units" 
         Arg="KG" />
   <Returns>
         the unit group of a group ring
   </Returns>
   <Description>
         This improves a standard &GAP; functionality for modular group 
	 algebras of finite <M>p</M>-groups over the field of <M>p</M> elements.
         It returns the unit group of <A>KG</A> as a direct product of
	 <C>Units(K)</C> and <C>NormalizedUnitGroup(KG)</C>, where the latter is
	 generated by certain elements of <A>KG</A>;
	 see Chapter <Ref Chap="Theory" /> for more details.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> U := Units( KG );
#I  LAGUNA package: Computing the unit group ...
<group of size 32768 with 15 generators>
gap> GeneratorsOfGroup( U )[5]; # now elements of U are already in KG
(Z(2)^0)*f1+(Z(2)^0)*f3+(Z(2)^0)*f1*f3
gap> FH := GroupRing( GF(3), SmallGroup(27,3) );
<algebra-with-one over GF(3), with 3 generators>
gap> T := Units( FH );
#I  LAGUNA package: Computing the unit group ...
<group of size 5083731656658 with 27 generators>
gap> x := GeneratorsOfGroup( T )[1];
DirectProductElement( [ Z(3), (Z(3)^0)*<identity> of ... ] )
gap> x in FH;
false
gap> x[1] * x[2] in FH; # how to get the corresponding element of FH
true 
]]>
</Example>


<ManSection>
   <Attr Name="PcUnits" 
         Arg="KG" />
   <Returns>
         a group given by power-commutator presentation
   </Returns>
   <Description>
         Returns the unit group of <A>KG</A> as a direct product of
	 <C>Units(K)</C> and <C>PcNormalizedUnitGroup(KG)</C>, where the latter 
	 is a group given by a polycyclic presentation. 
	 See Section <Ref Sect="TheoryFourth" /> for more details.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> W := PcUnits( KG );
<pc group of size 32768 with 15 generators>
gap> GeneratorsOfGroup( W )[5];
f5   
gap> FH := GroupRing( GF(3), SmallGroup(27,3) );
<algebra-with-one over GF(3), with 3 generators>
gap> T := PcUnits(FH);
<group of size 5083731656658 with 27 generators>
gap> x := GeneratorsOfGroup( T )[2];
DirectProductElement( [ Z(3)^0, f1 ] )                      
]]>
</Example>


<ManSection>
   <Prop Name="IsGroupOfUnitsOfMagmaRing"
         Arg="U" />
   <Description>
         This property will be automatically set 
	 <K>true</K>, if <A>U</A> is a group generated by
	 some units of a magma ring, including 
	 <C>Units(KG)</C> and <C>NormalizedUnitgroup(KG)</C>. 
	 Otherwise this property will not be bound.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> IsGroupOfUnitsOfMagmaRing( NormalizedUnitGroup( KG ) );
true
gap> IsGroupOfUnitsOfMagmaRing( Units( KG ) );
true     
]]>
</Example>


<ManSection>
   <Prop Name="IsUnitGroupOfGroupRing"
         Arg="U"/>
   <Description>
         This property will be automatically set  <K>true</K>,
	 if <A>U</A> is the unit group of a <M>p</M>-modular group
	 algebra, obtained either by <C>Units(KG)</C> or by 
	 <C>PcUnits(KG)</C>. Otherwise this property will not be 
	 bound.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> IsUnitGroupOfGroupRing( Units( KG ) );
true
gap> IsUnitGroupOfGroupRing( PcUnits( KG ) );
true     
]]>
</Example>


<ManSection>
   <Prop Name="IsNormalizedUnitGroupOfGroupRing"
         Arg="U" />
   <Description>
         This property will be automatically set  <K>true</K>,
	 if <A>U</A> is the normalized unit group of a 
	 <M>p</M>-modular group algebra, obtained either by 
	 <C>NormalizedUnitGroup(KG)</C> or by 
	 <C>PcNormalizedUnitGroup(KG)</C>. 
	 Otherwise this property will not be bound.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> IsNormalizedUnitGroupOfGroupRing( NormalizedUnitGroup( KG ) );
true
gap> IsNormalizedUnitGroupOfGroupRing( PcNormalizedUnitGroup( KG ) );
true     
]]>
</Example>


<ManSection>
   <Attr Name="UnderlyingGroupRing"
         Arg="U" />
   <Returns>
         a group ring
   </Returns>
   <Description>
         If <A>U</A> is the (normalized) unit group of a 
	 <M>p</M>-modular group algebra <M>KG</M> 
	 obtained using one of the
	 functions <C>Units(KG)</C>, <C>PcUnits(KG)</C>,
	 <C>NormalizedUnitGroup(KG)</C> or 
	 <C>PcNormalizedUnitGroup(KG)</C>,
	 then the attribute <C>UnderlyingGroupRing</C> stores
	 <M>KG</M>. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> UnderlyingGroupRing( Units( KG ) );
<algebra-with-one of dimension 16 over GF(2)>
gap> UnderlyingGroupRing( PcUnits( KG ) );
<algebra-with-one of dimension 16 over GF(2)>
gap> UnderlyingGroupRing( NormalizedUnitGroup( KG ) );
<algebra-with-one of dimension 16 over GF(2)>
gap> UnderlyingGroupRing( PcNormalizedUnitGroup( KG ) );
<algebra-with-one of dimension 16 over GF(2)>
]]>
</Example>


<ManSection>
   <Attr Name="UnitarySubgroup"
         Arg="U" />
   <Returns>
         the subgroup of the unit group
   </Returns>
   <Description>
         Let <A>U</A> be the normalized unit group of a group ring
         in either natural (see <Ref Attr="NormalizedUnitGroup"/>) 
         or power-commutator (see <Ref Attr="PcNormalizedUnitGroup"/>) 
         presentation.
         The attribute stores the unitary subgroup of <A>U</A>,
         generated by all unitary units of <A>U</A> 
         (see <Ref Attr="IsUnitary"/>).
         The method is straightforward, so it is not recommended
         to run it for large groups.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 8 ) );
<algebra-with-one over GF(2), with 3 generators>
gap> U := NormalizedUnitGroup( KG );
<group of size 128 with 7 generators>
gap> HU := UnitarySubgroup( U );
<group with 5 generators>
gap> IdGroup( HU );
[ 64, 261 ]
gap> V := PcNormalizedUnitGroup( KG );
<pc group of size 128 with 7 generators>
gap> HV := UnitarySubgroup( V );
Group([ f1, f2, f5, f6, f7 ])
gap> IdGroup( HV );
[ 64, 261 ]
gap> Image(NaturalBijectionToPcNormalizedUnitGroup( KG ), HU ) = HV;
true
]]>
</Example>


<ManSection>
   <Attr Name="BicyclicUnitGroup"
         Arg="U" />
   <Returns>
         the subgroup of the unit group, generated by bicyclic units
   </Returns>
   <Description>
         Let <A>U</A> be the normalized unit group of a group ring
         in either natural (see <Ref Attr="NormalizedUnitGroup"/>) 
         or power-commutator (see <Ref Attr="PcNormalizedUnitGroup"/>) 
         presentation.
         The attribute stores the subgroup of <A>U</A>,
         generated by all bicyclic units <M>u_{g,h}</M> and 
         <M>v_{g,h}</M> (see <Ref Oper="BicyclicUnitOfType1"/> and
         <Ref Oper="BicyclicUnitOfType2"/>), 
         where <M>g</M> and <M>h</M> run over the elements of the 
         underlying group, and <M>h</M> do not belongs to the 
         normalizer of <M> \langle g \rangle </M> in <M>G</M>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 8 ) );
<algebra-with-one over GF(2), with 3 generators>
gap> U := NormalizedUnitGroup( KG );
<group of size 128 with 7 generators>
gap> BU := BicyclicUnitGroup( U );
<group with 2 generators>
gap> IdGroup( BU );
[ 4, 2 ]
gap> V := PcNormalizedUnitGroup( KG );
<pc group of size 128 with 7 generators>
gap> BV := BicyclicUnitGroup( V );
Group([ f5*f6, f5*f7 ])
gap> IdGroup( BV );
[ 4, 2 ]
gap> Image( NaturalBijectionToPcNormalizedUnitGroup( KG ), BU ) = BV;
true
]]>
</Example>

<!--
<ManSection>
   <Oper Name="AugmentationIdealPowerFactorGroup"
         Arg="KG n" />
   <Returns>
         PcGroup
   </Returns>
   <Description>
         ????????????????????????????????????????
   </Description>
</ManSection>

<Example>
<![CDATA[
]]>
</Example>
-->


<ManSection>
   <Attr Name="GroupBases" 
         Arg="KG"  
	 Comm="for a p-modular group algebra" />
   <Returns>
         a list of lists of group rings elements 
   </Returns>
   <Description>
         The subgroup <M>B</M> of the normalized unit group of the
	 group algebra <M>KG</M> is called a <E>group basis</E>, if
	 the elements of <M>B</M> are linearly independent over the 
	 field <M>K</M> and <M> KB=KG </M>.
	 If <A>KG</A> is a <M>p</M>-modular group algebra, then
	 <C>GroupBases</C> returns a list of representatives of 
	 the conjugacy classes of the group bases of the group
	 algebra <A>KG</A> in its normalised unit group. 
   </Description>
</ManSection>


<Example>
<![CDATA[
gap> D8 := DihedralGroup( 8 );
<pc group of size 8 with 3 generators>
gap> K := GF(2);
GF(2)
gap> KD8 := GroupRing( GF( 2 ), D8 );
<algebra-with-one over GF(2), with 3 generators>
gap> gb := GroupBases( KD8 );;
gap> Length( gb );
32
gap> Length( gb[1] );
8    
gap> gb[1][1];
(Z(2)^0)*<identity> of ...
gap> ForAll(gb, b -> IdGroup(Group(b))=[8,3]);
true
]]>
</Example>
</Section>

<!-- ######################################################### -->


<Section Label="LieAlgebra">
<Heading>The Lie algebra of a group algebra</Heading>

<ManSection>
   <Meth Name="LieAlgebraByDomain" 
         Arg="A" />
   <Description>
         This method takes a group algebra as its argument, 
	       and constructs its associated Lie algebra in which the product 
	       is the bracket operation: <M>[a,b]=ab-ba</M>.
         It is recommended that the user never calls this method. 
	       The Lie algebra for an associative algebra should normally 
	       be created using <C>LieAlgebra( A )</C>. 
	       When <C>LieAlgebra</C> is first invoked, it constructs the 
	       Lie algebra for <A>A</A> using <C>LieAlgebraByDomain</C>. 
         After that it stores this Lie algebra and simply returns it
	       if <C>LieAlgebra</C> is called again.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SymmetricGroup(3);; FG := GroupRing( GF( 2 ), G );
<algebra-with-one over GF(2), with 2 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
]]>
</Example>


<ManSection>
   <Filt Name="IsLieAlgebraByAssociativeAlgebra" 
         Arg="L"  
	 Type="Category" />
   <Description>
         This category signifies that the Lie algebra <A>L</A> was
	 constructed as the Lie algebra associated with an associative
	 algebra (this piece of information cannot be obtained later).
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF(3), DihedralGroup(16) );
<algebra-with-one over GF(3), with 4 generators>
gap> L := LieAlgebra ( KG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(3)>
gap> IsLieAlgebraByAssociativeAlgebra( L );
true
]]>
</Example>


<ManSection>
   <Attr Name="UnderlyingAssociativeAlgebra" 
         Arg="L" />
   <Returns>
         the underlying associative algebra of a Lie algebra  
   </Returns>	 
   <Description>
         If a Lie algebra <A>L</A> is constructed from an associative
	 algebra, then it remembers this underlying associative algebra as 
	 one of its attributes.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF(2), DihedralGroup(16) ); 
<algebra-with-one over GF(2), with 4 generators>
gap> L := LieAlgebra ( KG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> UnderlyingAssociativeAlgebra( L );
<algebra-with-one over GF(2), with 4 generators>
gap> last = KG;
true  
]]>
</Example>


<ManSection>
   <Attr Name="NaturalBijectionToLieAlgebra" 
         Arg="A" />
   <Returns>
         a mapping
   </Returns>
   <Description>
         The natural linear bijection between the (isomorphic, but not
	 equal) underlying vector spaces of an associative algebra
	 <A>A</A> and its associated Lie algebra is stored as an 
	 attribute of <A>A</A>. Note that this is a vector space
	 isomorphism between two algebras, but not an algebra
	 isomorphism.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> F := GF( 2 ); G := SymmetricGroup( 3 ); FG := GroupRing( F, G );
GF(2)
Sym( [ 1 .. 3 ] )
<algebra-with-one over GF(2), with 2 generators>
gap> t := NaturalBijectionToLieAlgebra( FG );; 
#I  LAGUNA package: Constructing Lie algebra ...
gap> a := Random( FG );
(Z(2)^0)*()+(Z(2)^0)*(2,3)+(Z(2)^0)*(1,2)+(Z(2)^0)*(1,2,3)
gap> a * a;                     # product in the associative algebra
(Z(2)^0)*()+(Z(2)^0)*(2,3)+(Z(2)^0)*(1,2)+(Z(2)^0)*(1,2,3)
gap> b := a^t;
LieObject( (Z(2)^0)*()+(Z(2)^0)*(2,3)+(Z(2)^0)*(1,2)+(Z(2)^0)*(1,2,3) )
gap> b * b; # product in the Lie algebra (commutator) - must be zero!
LieObject( <zero> of ... )
]]>
</Example>


<ManSection>
   <Attr Name="NaturalBijectionToAssociativeAlgebra" 
         Arg="L" />
   <Description>
         This is the inverse of the previous linear bijection,
	 stored as an attribute of the Lie algebra <A>L</A>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SymmetricGroup(3); FG := GroupRing( GF( 2 ), G );
Sym( [ 1 .. 3 ] )
<algebra-with-one over GF(2), with 2 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> s := NaturalBijectionToAssociativeAlgebra( L );;
gap> InverseGeneralMapping( s ) = NaturalBijectionToLieAlgebra( FG );
true   
]]>
</Example>


<ManSection>
   <Prop Name="IsLieAlgebraOfGroupRing" 
         Arg="L" />
   <Description>
         If a Lie algebra <A>L</A> is constructed from an associative
	 algebra which happens to be in fact a group ring, it has
	 many nice properties that can be used for fast algorithms,
	 so this information is stored as a property.
   </Description>
</ManSection>


<Example>
<![CDATA[
gap> F := GF( 2 ); G := SymmetricGroup( 3 ); FG := GroupRing( F, G );
GF(2)
Sym( [ 1 .. 3 ] )
<algebra-with-one over GF(2), with 2 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> IsLieAlgebraOfGroupRing( L );
true   
]]>
</Example>


<ManSection>
   <Attr Name="UnderlyingGroup"
         Label="of Lie algebra of a group ring" 
         Arg="L" />
   <Returns>
         the underlying group
   </Returns>
   <Description>
         The underlying group of a Lie algebra <A>L</A> that is
	 constructed from a group ring is defined as the underlying
	 group of this group ring; see <Ref Attr="UnderlyingGroup" 
	 Label="of a group ring" />.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> F := GF( 2 ); G := SymmetricGroup( 3 ); FG := GroupRing( F, G );
GF(2)
Sym( [ 1 .. 3 ] )
<algebra-with-one over GF(2), with 2 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> UnderlyingGroup( L );
Sym( [ 1 .. 3 ] )
gap> LeftActingDomain( L );
GF(2)   
]]>
</Example>


<ManSection>
   <Oper Name="Embedding" 
         Label="from group to Lie algebra"
         Arg="U L" />
   <Returns>
         a mapping, which is a composition of two mappings 
   </Returns>
   <Description>
         Let <M>FG</M> be a group ring, let <A>U</A> be a submagma 
	 of <M>G</M>, and let <A>L</A> be the Lie algebra 
	 associated with <M>FG</M>. Then <C>Embedding(<A>U</A>, <A>L</A> )</C> 
	 returns the obvious mapping from <A>U</A> to <A>L</A>
         (as the composition of the mappings 
	 <C>Embedding( <A>U</A>, FG )</C> and
	 <C>NaturalBijectionToLieAlgebra( FG )</C>).
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> F := GF( 2 ); G := SymmetricGroup( 3 ); FG := GroupRing( F, G );
GF(2)
Sym( [ 1 .. 3 ] )
<algebra-with-one over GF(2), with 2 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> f := Embedding( G, L );;
gap> (1,2)^f + (1,3)^f;
LieObject( (Z(2)^0)*(1,2)+(Z(2)^0)*(1,3) )   
]]>
</Example>


<ManSection>
   <Meth Name="LieCentre" 
         Arg="L" />
   <Returns>
         a Lie algebra
   </Returns>
   <Description>
         The centre of the Lie algebra associated with a group ring 
	 corresponds to the centre of the underlying group ring, 
	 and it can be calculated very fast by considering the 
	 conjugacy classes of the group. This method returns the 
	 centre of <A>L</A> using this idea.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SmallGroup( 256, 400 ); FG := GroupRing( GF( 2 ), G ); 
<pc group of size 256 with 8 generators>
<algebra-with-one over GF(2), with 8 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> C := LieCentre( L );
<Lie algebra of dimension 28 over GF(2)>
gap> D := LieDerivedSubalgebra( L );
#I  LAGUNA package: Computing the Lie derived subalgebra ...
<Lie algebra of dimension 228 over GF(2)>
gap> c := Dimension( C ); d := Dimension( D ); l := Dimension( L );
28
228
256
gap> c + d = l; # This is always the case for Lie algebras of group algebras! 
true
]]>
</Example>


<ManSection>
   <Meth Name="LieDerivedSubalgebra" 
         Arg="L" />
   <Returns>
         a Lie algebra
   </Returns>
   <Description>
         If <A>L</A> is the Lie algebra associated with a group ring,
	 then this method returns the Lie derived subalgebra of 
	 <A>L</A>. This can be done very fast using the conjugacy classes
	 of the underlying group.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SmallGroup( 256, 400 ); FG := GroupRing( GF( 2 ), G ); 
<pc group of size 256 with 8 generators>
<algebra-with-one over GF(2), with 8 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> C := LieCentre( L );
<Lie algebra of dimension 28 over GF(2)>
gap> D := LieDerivedSubalgebra( L );
#I  LAGUNA package: Computing the Lie derived subalgebra ...    
<Lie algebra of dimension 228 over GF(2)>
gap> l := Dimension( L ); c := Dimension( C ); d := Dimension( D );
256
28
228
gap> c + d = l; # This is always the case for Lie algebras of group algebras!
true
]]>
</Example>


<ManSection>
   <Meth Name="IsLieAbelian" 
         Arg="L" />
   <Description>
         The Lie algebra <A>L</A> of an associative algebra <M>A</M> 
	 is Lie abelian, if and only if <M>A</M> is abelian, so this
	 method refers to <C>IsAbelian( A )</C>. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SymmetricGroup( 3 ); FG := GroupRing( GF( 2 ), G); 
Sym( [ 1 .. 3 ] )
<algebra-with-one over GF(2), with 2 generators>
gap> L := LieAlgebra( FG );          
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> IsAbelian( G );
false
gap> IsAbelian( L );    # This command should not be used for Lie algebras!
true                    
gap> IsLieAbelian( L ); # Instead, IsLieAbelian is the correct command.
false   
]]>
</Example>


<ManSection>
   <Meth Name="IsLieSolvable" 
         Arg="L" />
   <Description>
         In <Cite Key="PPS73" /> Passi, Passman, and Sehgal have 
 	 classified all groups <M>G</M> such that the Lie algebra associated 
         with the group ring is solvable. 
	 This method uses their classification, making it 
	 considerably faster than the more elementary method 
	 which just calculates Lie commutators. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SmallGroup( 256, 400 ); FG := GroupRing( GF( 2 ), G ); 
<pc group of size 256 with 8 generators>
<algebra-with-one over GF(2), with 8 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> IsLieSolvable( L );                       # This is very fast.
#I  LAGUNA package: Checking Lie solvability ...
true
gap> List( LieDerivedSeries( L ), Dimension ); # This is very slow.
#I  LAGUNA package: Computing the Lie derived subalgebra ...
[ 256, 228, 189, 71, 0 ]   
]]>
</Example>


<ManSection>
   <Meth Name="IsLieNilpotent" 
         Arg="L" />
   <Description>
         In <Cite Key="PPS73" /> Passi, Passman, and Sehgal have classified
	 all groups <M>G</M> such that the Lie algebra associated 
	 with the group ring is Lie nilpotent. This method 
	 uses their classification, making it considerably faster 
	 than the more elementary method which just calculates 
	 Lie commutators. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SmallGroup( 256, 400 ); FG := GroupRing( GF( 2 ), G ); 
<pc group of size 256 with 8 generators>
<algebra-with-one over GF(2), with 8 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> IsLieNilpotent( L );                           # This is very fast.
#I  LAGUNA package: Checking Lie nilpotency ...
true
gap> List( LieLowerCentralSeries( L ), Dimension ); # This is very slow.
#I  LAGUNA package: Computing the Lie derived subalgebra ...
[ 256, 228, 222, 210, 191, 167, 138, 107, 76, 54, 29, 15, 6, 0 ]   
]]>
</Example>


<ManSection>
   <Prop Name="IsLieMetabelian" 
         Arg="L" />
   <Description>
         In <Cite Key="LR86" /> Levin and Rosenberger have classified 
	 all groups <M>G</M> such that the Lie algebra associated with
	 the group ring is Lie metabelian. This method uses 
         their classification, making it considerably faster than 
         the more elementary method which just calculates Lie 
	 commutators. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SmallGroup( 256, 400 ); FG := GroupRing( GF( 2 ), G ); 
<pc group of size 256 with 8 generators>
<algebra-with-one over GF(2), with 8 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> IsLieMetabelian( L );
false   
]]>
</Example>


<ManSection>
   <Prop Name="IsLieCentreByMetabelian" 
         Arg="L" />
   <Description>
         In <Cite Key="Ross" /> the third author of this package 
	 classified all groups <M>G</M> such that the Lie algebra associated 
         with the group ring is Lie 
	 centre-by-metabelian. 
         This method uses the classification, making it 
	 considerably faster than the more elementary method 
	 which just calculates Lie commutators. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SymmetricGroup( 3 ); FG := GroupRing( GF( 2 ), G ); 
Sym( [ 1 .. 3 ] )
<algebra-with-one over GF(2), with 2 generators>
gap> L := LieAlgebra( FG );       
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> IsLieMetabelian( L );                                             
false
gap> IsLieCentreByMetabelian( L );
true   
]]>
</Example>


<ManSection>
   <Meth Name="CanonicalBasis" 
         Arg="L" />
   <Returns>
         basis of a Lie algebra
   </Returns>
   <Description>
         The canonical basis of a group algebra <M>FG</M> is formed
	 by the elements of <M>G</M>. Here <A>L</A> is the
	 Lie algebra associated with <M>FG</M>, and 
	 the method returns the images of the elements of <M>G</M> in 
	 <A>L</A>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SymmetricGroup( 3 ); FG := GroupRing( GF( 2 ), G ); 
Sym( [ 1 .. 3 ] )
<algebra-with-one over GF(2), with 2 generators>
gap> L := LieAlgebra( FG );       
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> B := CanonicalBasis( L );
CanonicalBasis( <Lie algebra of dimension 6 over GF(2)> )
gap> Elements( B );
[ LieObject( (Z(2)^0)*() ), LieObject( (Z(2)^0)*(2,3) ),
  LieObject( (Z(2)^0)*(1,2) ), LieObject( (Z(2)^0)*(1,2,3) ),
  LieObject( (Z(2)^0)*(1,3,2) ), LieObject( (Z(2)^0)*(1,3) ) ]
]]>
</Example>


<ManSection>
   <Prop Name="IsBasisOfLieAlgebraOfGroupRing" 
         Arg="B" />
   <Description>
         A basis <A>B</A> has this property if the preimages of the basis
         vectors in the group algebra form a group. It can be verified if a  
	 basis has this property. This is 
	 important for the speed of the calculation of the structure 
	 constants table; see <Ref Meth="StructureConstantsTable" />.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := SymmetricGroup( 3 ); FG := GroupRing( GF( 2 ), G ); 
Sym( [ 1 .. 3 ] )
<algebra-with-one over GF(2), with 2 generators>
gap> L := LieAlgebra( FG );    
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> B := CanonicalBasis( L );
CanonicalBasis( <Lie algebra of dimension 6 over GF(2)> )
gap> IsBasisOfLieAlgebraOfGroupRing( B );
true   
]]>
</Example>


<ManSection>
   <Meth Name="StructureConstantsTable" 
         Arg="B" />
   <Description>
         A very fast implementation for calculating the structure 
	 constants table for the Lie algebra <C>L</C> associated 
	 with a group ring with respect to its canonical basis
	 <A>B</A> using its special structure; 
	 see <Ref Meth="CanonicalBasis" />.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := CyclicGroup( 2 ); FG := GroupRing( GF( 2 ), G ); 
<pc group of size 2 with 1 generators>
<algebra-with-one over GF(2), with 1 generators>
gap> L := LieAlgebra( FG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> B := CanonicalBasis( L );
CanonicalBasis( <Lie algebra of dimension 2 over GF(2)> )
gap> StructureConstantsTable( B );    
#I  LAGUNA package: Computing the structure constants table ...   
[ [ [ [  ], [  ] ], [ [  ], [  ] ] ], [ [ [  ], [  ] ], [ [  ], [  ] ] ], -1, 
  0*Z(2) ]  
]]>
</Example>


<ManSection>
   <Attr Name="LieUpperNilpotencyIndex" 
         Arg="KG" />
   <Description>
         <Index>upper Lie power series</Index>
         In a modular group algebra <M>KG</M> the <E>upper
	 Lie power series</E> is defined as follows:
	 <M>KG^{(1)}=KG</M>, <M>KG^{(n+1)}</M> is the associative
	 ideal, generated by <M>[KG^{(n)},KG]</M>.
         The upper Lie nilpotency index <M>t^L(G)</M> of the group
	 algebra <M>KG</M> is defined to be the 
	 smallest number <M>n</M> such that <M>KG^{(n)}=0</M>.
         It can be calculated very fast using Lie dimension
	 subgroups <Cite Key="Shalev91" />, that is, using only 
	 information about the underlying group; see 
	 <Ref Attr="LieDimensionSubgroups" />. This is why it is
	 stored as an attribute of the group algebra <A>KG</A> 
	 rather than that of its associated Lie algebra.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
gap> LieUpperNilpotencyIndex( KG );
5      
]]>
</Example>


<ManSection>
   <Attr Name="LieLowerNilpotencyIndex" 
         Arg="KG" />
   <Description>
         <Index>lower Lie power series</Index>
         In a modular group algebra <M>KG</M> the <E>lower
	 Lie power series</E> is defined as follows:
	 <M>KG^{[n]}</M> is the associative
	 ideal, generated by all (left-normed) Lie-products
	 <M>[x_1, x_2, \dots, x_n]</M>, <M> x_i \in KG </M>.
         The lower Lie nilpotency index <M>t_L(G)</M> of the group
	 algebra <M>KG</M> is defined to be the 
	 minimal smallest <M>n</M> such that <M>KG^{[n]}=0</M>.
         In <Cite Key="Du" /> the Jennings' conjecture was proved,
	 which means that the nilpotency class of the normalized
	 unit group of the modular group algebra <M>KG</M> is 
	 equal to <M>t_L(G)-1</M>. 
	 <P/>
	 This allows to express lower Lie nilpotency index via the
	 nilpotency class of the normalized unit group, and with its
	 polycyclic presentation, provided by &LAGUNA;, this will be
	 faster than elementary calculations with Lie commutators.
	 As the previous attribute, this index is also stored as an 
	 attribute of the group algebra <A>KG</A>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF( 2 ), DihedralGroup( 16 ) );
<algebra-with-one over GF(2), with 4 generators>
gap> LieLowerNilpotencyIndex( KG );
5     
]]>
</Example>


<ManSection>
   <Attr Name="LieDerivedLength" 
         Arg="L" />
   <Description>
         <Index>Lie derived series</Index>
         <Index>Lie derived length</Index>
         Let <M>L</M> be a Lie algebra. The <E>Lie derived series</E> 
         of <M>L</M> is defined as follows: 
         <M>\delta^{[0]}(L) = L</M> and
         <M>\delta^{[n]}(L) = [\delta^{[n-1]}(L), 
                               \delta^{[n-1]}(L)]</M>.
         <M>L</M> is called Lie solvable if there exists an integer 
         <M>m</M> such that <M> \delta^{[m]}(L) = 0 </M>. In this 
         case the integer <M>m</M> is called the <E>Lie derived length</E> 
         of <M>L</M>, and it is returned by this function. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KG := GroupRing( GF ( 2 ), DihedralGroup( 16 ) );;
gap> L := LieAlgebra( KG );
#I  LAGUNA package: Constructing Lie algebra ...
<Lie algebra over GF(2)>
gap> LieDerivedLength( L );
#I  LAGUNA package: Computing the Lie derived subalgebra ...
3                                                            
]]>
</Example>

</Section>

<!-- ######################################################### -->

<Section Label="Other">
<Heading>Other commands</Heading>


<ManSection>
   <Attr Name="SubgroupsOfIndexTwo" 
         Arg="G"
	 Comm="for a group" />
   <Description>
         Returns a list of subgroups of <M>G</M> with index two. 
         Such subgroups are important for the investigation of
	 the Lie structure of the group algebra <M>KG</M> in the case
	 of characteristic 2.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> SubgroupsOfIndexTwo( DihedralGroup( 16 ) );
[ Group([ f3, f4, f1 ]), Group([ f3, f4, f2 ]), Group([ f3, f4, f1*f2 ]) ]
]]>
</Example>


<ManSection>
   <Meth Name="DihedralDepth" 
         Arg="U" 
	 Comm="for a finite 2-group" />
   <Description>
         For a finite 2-group <A>U</A>, the function returns its 
	 <E>dihedral depth</E>, which is defined to be the maximal
	 number <M>d</M> such that <A>U</A> contains a subgroup
	 isomorphic to the dihedral
	 group of order <M>2^{d+1}</M>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> KD8 := GroupRing( GF(2), DihedralGroup( 8 ) );
<algebra-with-one over GF(2), with 3 generators>
gap> UD8 := PcNormalizedUnitGroup( KD8 );
<pc group of size 128 with 7 generators>
gap> DihedralDepth( UD8 );
2      
]]>
</Example>


<ManSection>
   <Meth Name="DimensionBasis" 
         Arg="G"  
	 Comm="for a finite p-group" />
   <Returns>
         record with two components: `dimensionBasis' 
         (list of group elements) and `weights' (list of weights)
   </Returns>
   <Description>
         For a finite <M>p</M>-group <A>G</A>, returns its
	 Jennings basis as it was described in Section 
	 <Ref Label="TheoryThird" />.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := DihedralGroup( 16 );
<pc group of size 16 with 4 generators>  
gap> DimensionBasis( G );
rec( dimensionBasis := [ f1, f2, f3, f4 ], weights := [ 1, 1, 2, 4 ] )    
]]>
</Example>


<ManSection>
   <Attr Name="LieDimensionSubgroups" 
         Arg="G"  
	 Comm="for a finite p-group" />
   <Returns>
         list of subgroups
   </Returns>
   <Description>
         For a finite <M>p</M>-group <A>G</A>, returns the series
	 of its Lie dimension subgroups. The <M>m</M>-th Lie dimension
	 subgroup <M> D_{(m)} </M> is the intersection of the group
	 <M>G</M> and <M> 1+KG^{(m)} </M>, where 
         <M>KG^{(m)}</M> is the <M>m</M>-th term of the
         upper Lie power series of <M>KG</M>; 
	 see <Ref Attr="LieUpperNilpotencyIndex" />
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := DihedralGroup( 16 );
<pc group of size 16 with 4 generators>  
gap> LieDimensionSubgroups( G );
[ <pc group of size 16 with 4 generators>, Group([ f3, f4 ]), Group([ f4 ]),
  Group([ <identity> of ... ]) ]     
]]>
</Example>


<ManSection>
   <Attr Name="LieUpperCodimensionSeries" 
         Label="for group ring"
         Arg="KG"  
	 Comm="for a modular group algebra of a finite p-group" />
   <Attr Name="LieUpperCodimensionSeries" 
         Label="for group"
         Arg="G"  
	 Comm="for a finite p-group" />
   <Returns>
         list of subgroups
   </Returns>
   <Description>
         A notion of upper Lie codimension subgroups was introduced in
         <Cite Key="CS"/>. For a finite <M>p</M>-group <A>G</A>, 
         <M>C_i</M> is the set of all elements <M>g</M> in <A>G</A>,
         such that the Lie commutator <M>[ g, g_1, ..., g_i ]</M> of the
         length <M>i+1</M> is equal to zero for all <M>g_1, ..., g_i</M>
         from <A>G</A>, and <M> C_0 = {1} </M>.
         By Du's theorem (see <Cite Key="Du"/>), <M>C_i</M> coincides
         with the intersection of <M>G</M> and the i-th term of the upper
         central series 
         <M>{1}=Z_0 &lt; Z_1 &lt; Z_2 &lt; ... &lt; Z_n = V(KG)</M>
         of the normalized unit group <M>V(KG)</M>.
         This fact is used in &LAGUNA; to speed up computation of this
         series. Since <M>V(KG)</M> is involved in computation, for the 
         first time the argiment should be the group ring <A>KG</A>, but
         later you can also apply it to the group <A>G</A> itself.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> G := DihedralGroup(16);
<pc group of size 16 with 4 generators>
gap> KG := GroupRing( GF(2), G );
<algebra-with-one over GF(2), with 4 generators>
gap> LieUpperCodimensionSeries( KG );
[ Group([ f1, f2, f3, f4 ]), Group([ f3, f4, f3*f4 ]), Group([ f4 ]), 
  Group([ f4 ]), Group([  ]) ]
gap> LieUpperCodimensionSeries( G );
[ Group([ f1, f2, f3, f4 ]), Group([ f3, f4, f3*f4 ]), Group([ f4 ]), 
  Group([ f4 ]), Group([  ]) ]
]]>
</Example>


<ManSection>
   <InfoClass Name="LAGInfo"
              Comm="Info class for LAGUNA algorithms" />
   <Description>
      <C>LAGInfo</C> is a special Info class for &LAGUNA; algorithms.
      It has 5 levels: 0, 1 (default), 2, 3 and 4. To change info 
      level to <C>k</C>, use command <C>SetInfoLevel(LAGInfo, k)</C>. 
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> SetInfoLevel( LAGInfo, 2 );
gap> KD8 := GroupRing( GF( 2 ), DihedralGroup( 8 ) );
<algebra-with-one over GF(2), with 3 generators>
gap> UD8 := PcNormalizedUnitGroup( KD8 );
#I  LAGInfo: Computing the pc normalized unit group ...
#I  LAGInfo: Calculating weighted basis ...
#I  LAGInfo: Calculating dimension basis ...
#I  LAGInfo: dimension basis finished !
#I  LAGInfo: Weighted basis finished !
#I  LAGInfo: Computing the augmentation ideal filtration...
#I  LAGInfo: Filtration finished !
#I  LAGInfo: finished, converting to PcGroup
<pc group of size 128 with 7 generators>     
]]>
</Example>

</Section>


</Chapter>