<!-- $Id: functions.xml,v 1.7 2004/06/18 13:41:38 gap Exp $ -->
<Chapter Label="Funct">
<Heading>&Sophus; functions</Heading>

<Section Label="LieNB">
<Heading>Some general functions to compute with Lie algebras</Heading>

<ManSection>
   <Func Name="SophusTest" 
         Arg="" />
   <Description>
Tests &Sophus; functions, returns true if it finds no mistakes, and returns
false otherwise. May take a couple of minutes to complete. 
   </Description>
</ManSection>


<ManSection>
   <Prop Name="IsLieNilpotentOverFp" 
         Arg="L" />
   <Description>
Returns true if <A>L</A> is a nilpotent Lie algebra and its underlying
field is a finite prime field.
   </Description>
</ManSection>


<ManSection>
   <Attr Name="MinimalGeneratorNumber" 
         Arg="L" />
   <Description>
Computes the minimal number of generators for <Math>L</Math>, which is the 
dimension of <Math>L/L'</Math>.
   </Description>
</ManSection>

<ManSection>
   <Func Name="AbelianLieAlgebra" 
         Arg="F,d"/>
   <Description>
Returns the Abelian Lie algebra with dimension <Math>d</Math> over
 the field <A>F</A>.
   </Description>
</ManSection>




</Section>

<Section>
<Heading>Functions to compute with nilpotent bases</Heading>
<ManSection>
   <Attr Name="NilpotentBasis" 
         Arg="L" />
      <Description>
Computes a nilpotent basis for <Math>L</Math>. Nilpotent bases are defined
in Section <Ref Sect="Intro"/>.
   </Description>
</ManSection>


<ManSection>
   <Attr Name="LieNBWeights" 
         Arg="B" />
      <Description>
Every element of the nilpotent basis <Math>B</Math> has a weight; 
See Section <Ref Sect="Intro"/>. This
function returns the list of these weights.
   </Description>
</ManSection>


<ManSection>
   <Attr Name="LieNBDefinitions" 
         Arg="B" />
   <Description>
  This function returns a list. The <A>i</A>-th element of this list 
is 0 if <A>B[i]</A> has weight 1. Otherwise the <A>i</A>-th element is 
<A>[k,l]</A> if the definition of <A>B[i]</A> is <A>[B[k],B[l]]</A>. 
See Section <Ref Sect="Intro"/>.
   </Description>
</ManSection>

<ManSection>
   <Prop Name="IsNilpotentBasis" 
         Arg="B"/>
   <Description>
Returns <K>true</K> if the basis <A>B</A> of a Lie algebra was computed
with the function <C>NilpotentBasis</C>; <K>false</K> otherwise.
   </Description>
</ManSection>

<ManSection>
   <Prop Name="IsLieAlgebraWithNB" 
         Arg="L"/>
   <Description>
Returns <K>true</K> if a nilpotent basis for <A>L</A> has already been computed
using the function
<C>NilpotentBasis</C>; <K>false</K> otherwise.
   </Description>
</ManSection>


</Section>

<Section>
<Heading>The cover</Heading>
<ManSection>
   <Attr Name="LieCover" 
         Arg="L" />
      <Description>
Computes the cover for the nilpotent Lie algebra <Math>L</Math> as
defined in Section <Ref Sect="Intro"/>.
   </Description>
</ManSection>

<ManSection>
   <Attr Name="CoverHomomorphism" 
         Arg="C" />
      <Description>
The nilpotent Lie algebra <A>C</A> was obtained from a nilpotent Lie 
algebra <A>L</A> using the <A>LieCover( L )</A> function call. This 
function returns the natural homomorphism from <A>C</A> onto <A>L</A>.
   </Description>
</ManSection>

<ManSection>
   <Attr Name="CoverOf" 
         Arg="C" />
      <Description>
The nilpotent Lie algebra <A>C</A> was obtained from a nilpotent Lie 
algebra <A>L</A> using the <A>LieCover( L )</A> function call. This 
function returns <A>L</A>.
</Description>
</ManSection>


<ManSection>
   <Prop Name="IsLieCover" 
         Arg="C"/>
   <Description>
Returns <K>true</K> if the Lie algebra <A>C</A> was obtained as the 
Lie cover of another Lie algebra <A>L</A> using the <A>LieCover( L )</A>
function call.
   </Description>
</ManSection>

<ManSection>
   <Attr Name="LieMultiplicator" 
         Arg="C" />
      <Description>
The nilpotent Lie algebra <A>C</A> was obtained from a nilpotent Lie 
algebra <A>L</A> using the <A>LieCover( L )</A> function call. This function
returns the central ideal of <A>C</A> which is the multiplicator of <A>L</A>;
see Section <Ref Sect="Intro"/>.
</Description>
</ManSection>

<ManSection>
   <Attr Name="LieNucleus" 
         Arg="C" />
      <Description>
The nilpotent Lie algebra <A>C</A> was obtained from a nilpotent Lie 
algebra <A>L</A> using the <A>LieCover( L )</A> function call. This function
returns the central ideal of <A>C</A> which is the nucleus of <A>L</A>;
see Section <Ref Sect="Intro"/>.
</Description>
</ManSection>


</Section>

<Section>
<Heading>Automorphisms of nilpotent Lie algebras</Heading>

We define a special class of automorphisms for our work.


<ManSection>
<Meth Name="NilpotentLieAutomorphism" 
         Arg="L, gens, imgs" />
   <Description>
   <A>L</A> is a nilpotent Lie algebra, <A>gens</A> is a generating set, and
<A>imgs</A> is a subset of <A>L</A> with the same length as <A>gens</A>.
Returns the automorphism of <A>L</A> which maps the element of <A>gens</A>
to the elements of <A>imgs</A>. It is the responsibility 
of the user to make sure that the arguments are given so that the 
automorphism exists. These automorphisms can be compared, 
multiplied using the <A>*</A>
sign, and the inverse of such an automorphism can also be computed 
in the usual manner.
   </Description>
</ManSection>

<ManSection>
<Meth Name="IdentityNilpotentLieAutomorphism" 
         Arg="L" />
   <Description>
   <A>L</A> is a nilpotent Lie algebra; returns the identity automorphism of <Math>L</Math>. 
   </Description>
</ManSection>

<ManSection>
   <Prop Name="IsNilpotentLieAutomorphism" 
         Arg="A"/>
   <Description>
Returns <K>true</K> if <A>A</A> was obtained 
using a <A>NilpotentLieAutomorphism</A> or an <A>IdentityNilpotentLieAutomorphism</A>
function call.
   </Description>
</ManSection>
</Section>

<Section>
<Heading>Automorphism group and isomorphism testing</Heading>

<ManSection>
<Meth Name="AutomorphismGroup" 
         Arg="L" />
   <Description>
   <A>L</A> is a nilpotent Lie algebra;
returns the automorphism group of <A>L</A> as a group
generated by &GAP; algebra automorphisms. The automorphism group
is computed as explained in <Cite Key="Sch"/>.
   </Description>
</ManSection>

<ManSection>
<Meth Name="AutomorphismGroupNilpotentLieAlgebra" 
         Arg="L"/>
   <Description>
   <A>L</A> is a nilpotent Lie algebra;
returns the automorphism group of <A>L</A> in the internally used
hybrid format. The automorphism group
is computed as explained in <Cite Key="Sch"/>. The hybrid format, which is
very similar to the one used in <Cite Key="autpgrp"/>, is a 
record that contains the following fields.
<List>
<Item> <C>glAutos</C>: a set of automorphisms which together with 
<C>agAutos</C>
            generate the automorphism group;
</Item>

<Item><C>glOrder</C>: an integer whose product with the numbers in 
<C>agOrder</C> gives
            the size of the automorphism group;</Item>

<Item><C>agAutos</C>: a polycyclic generating sequence for a soluble normal
            subgroup of the automorphism group;</Item>

<Item><C>agOrder</C>: the relative orders corresponding to <C>agAutos</C>;
</Item>

<Item><C>liealg</C>: The Lie algebra acted upon by the automorphisms.</Item>
<Item><C>size</C>: the size of the automorphism group.</Item>
<Item><C>field</C>: the underlying field of the Lie algebra.</Item>
<Item><C>prime</C>: the characteristic of the underlying field.</Item>
</List>
We do not return an automorphism group in the standard form 
because we wish to distinguish between <C>agAutos</C> and <C>glAutos</C>;
the latter act non-trivially on the derived quotient of <M>L</M>. This
hybrid-group description of the automorphism group permits more 
efficient computations with it. 
</Description>
</ManSection>


<ManSection>
<Meth Name="AreIsomorphicNilpotentLieAlgebras" 
         Arg="L, K"/>
   <Description>
Returns <K>true</K> if <A>L</A> and <A>K</A> are isomorphic; <K>false</K> otherwise.
   </Description>
</ManSection>
</Section>

<Section>
<Heading>Descendants</Heading>
<ManSection>
<Meth Name="Descendants" 
         Arg="L, step"/>
   <Description>
Returns the <K>step</K>-step 
descendants of a nilpotent Lie algebra <A>L</A>.
   </Description>
</ManSection>


<ManSection>
<Meth Name="DescendantsOfStep1OfAbelianLieAlgebra" 
         Arg="L, step"/>
   <Description>
Returns the <K>1</K>-step 
descendants of the abelian Lie algebra with dimension <A>d</A> defined over
the field of <A>p</A> elements.
   </Description>
</ManSection>
</Section>

<Section>
<Heading>Input and output</Heading>

The package provides with a number of functions that can be used to store
lists of Lie algebras.
Here we document only the most important ones,  see the source code <C>io.gi</C> for the rest. 



<ManSection>
   <Func Name="WriteLieAlgebraToString" 
         Arg="L"/>
   <Description>
Returns a string that encodes the nilpotent Lie algebra <A>L</A>
   </Description>
</ManSection>

<ManSection>
   <Func Name="ReadStringToNilpotentLieAlgebra" 
         Arg="string, p, d"/>
   <Description>
Decodes <A>string</A> into a <A>d</A>-dimensional nilpotent Lie algebra
defined over the field of <A>p</A> elements.
   </Description>
</ManSection>

<ManSection>
   <Func Name="WriteLieAlgebraListToFile" 
         Arg="list, name, file"/>
   <Description>
<A>list</A> is a list of nilpotent Lie algebras. Encodes each Lie algebra
in <A>list</A> to a string. 
The list so obtained is written into <A>file</A>. The name of this list will be <A>name</A>.
   </Description>
</ManSection>

<ManSection>
   <Func Name="SophusBuildManual" 
         Arg=""/>
   <Description>
Builds Sophus manual.
</Description>
</ManSection>

<ManSection>
   <Func Name="SophusBuildManualHTML" 
         Arg=""/>
   <Description>
Builds Sophus manual in html format.
   </Description>
</ManSection>

</Section>


</Chapter>



