%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  example.tex            GAP documentation              Bjoern Assmann
%W                                                            
%%
%H  $Id: malcor.tex,v 1.3 2007/05/24 16:48:37 bjoern Exp $
%%
%Y  Copyright (C) 1997, School of Math & Comp. Sci., St Andrews, Scotland
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Computing the Mal'cev correspondence}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The main functions}

Let $G$ be a $T$-group
and $\hat{G}$ its $\Q$-powered hull.
In this chapter we describe functionality 
for setting up the 
Mal'cev correspondence
between $\hat{G}$ and the Lie algebra $L(G)$.

The data structures needed for computations with $\hat{G}$ and 
$L(G)$ are 
stored in a so-called Mal'cev object.
Computational representations of 
elements of $\hat{G}$, respectively $L(G)$, 
will be called Mal'cev group elements, respectively 
Mal'cev Lie elements.

\> MalcevObjectByTGroup( <N> )

If <N> is a a T-group 
(i.e. a finitely generated torsion-free nilpotent group),
given by a polycyclic presentation with respect to a Mal'cev basis,
then this function computes the Mal'cev correspondence for <N> 
and stores the result in a so-called Mal'cev object. 
Otherwise this function returns `fail'.
In the moment this function is restricted to groups $N$
of nilpotency class at most 9.

\> UnderlyingGroup( <mo> )

For a Mal'cev object <mo> this function returns the T-group,
which was used to build <mo>.

\> UnderlyingLieAlgebra( <mo> )

For a Mal'cev object <mo> this function returns the Lie algebra,
which underlies the correspondence described by <mo>.

\> Dimension( <mo> )

returns the dimension of the Lie algebra that underlies the Mal'cev object <mo>.

\> MalcevGrpElementByExponents( <mo>, <exps> )

For a Mal'cev object <mo> and an exponent vector <exps> with rational 
entries, this functions returns the Mal'cev group element, which 
has exponents <exps> with respect to the Mal'cev basis of the underlying
group of <mo>.

\> MalcevLieElementByCoefficients( <mo>, <coeffs> )

For a Mal'cev object <mo> and a coefficient vector <coeffs> with rational 
entries, this functions returns the Mal'cev Lie element, which 
has coefficients  <coeffs> with respect to the basis of the underlying
Lie algebra of <mo>.

\> RandomGrpElm( <mo>, <range> )

For a Mal'cev object <mo> this function returns the output of 
MalcevGrpElementByExponents( <mo>, <exps> ), where <exps> is an
exponent vector whose entries are randomly chosen integers between 
-<range> and <range>.

\> RandomLieElm( <mo>, <range> )

For a Mal'cev object <mo> this function returns the output of 
MalcevLieElementByExponents( <mo>, <coeffs> ), where <coeffs> is 
a coefficient vector whose entries are randomly chosen integers between 
-<range> and <range>.

\> Log( <g> )

For Mal'cev group element <g> this function returns the corresponding
Mal'cev Lie element.

\> Exp( <x> )

For Mal'cev Lie element <x> this function returns the corresponding
Mal'cev group element.

\> `<g> * <h>'{multiplication} 

returns the product of Mal'cev group elements.

\> Comm( <x>, <y> )

If <x>,<y> are Mal'cev group elements, then this function returns
the group theoretic commutator of <x> and <y>.
If <x>,<y> are Mal'cev Lie elements, then this functions returns
the Lie commutator of <x> and <y>.

\> MalcevSymbolicGrpElementByExponents( <mo>, <exps> )

For a Mal'cev object <mo> and an exponent vector <exps> with rational 
indeterminates as entries, 
this functions returns the Mal'cev group element, which 
has exponents <exps> with respect to the Mal'cev basis of the underlying
group of <mo>.

\> MalcevLieElementByCoefficients( <mo>, <coeffs> )

For a Mal'cev object <mo> and a coefficient vector <coeffs> with rational 
indeterminates as entries, 
this functions returns the Mal'cev Lie element, which 
has coefficients  <coeffs> with respect to the basis of the underlying
Lie algebra of <mo>.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{An example application}

\beginexample
gap> n := 2;
2
gap> F := FreeGroup( n );
<free group on the generators [ f1, f2 ]>
gap> c := 3;
3
gap> N := NilpotentQuotient( F, c );
Pcp-group with orders [ 0, 0, 0, 0, 0 ]

gap> mo := MalcevObjectByTGroup( N );
<<Malcev object of dimension 5>>
gap> dim := Dimension( mo );
5
gap> UnderlyingGroup( mo );
Pcp-group with orders [ 0, 0, 0, 0, 0 ]
gap> UnderlyingLieAlgebra( mo );
<Lie algebra of dimension 5 over Rationals>

gap> g := MalcevGrpElementByExponents( mo, [1,1,0,2,-1/2] );
[ 1, 1, 0, 2, -1/2 ]
gap> x := MalcevLieElementByCoefficients( mo, [1/2, 2, -1, 3, 5 ] );
[ 1/2, 2, -1, 3, 5 ]

gap> h := RandomGrpElm( mo );
[ 5, -3, 0, -2, 8 ]
gap> y := RandomLieElm( mo );
[ 3, 9, 5, 5, 2 ]

gap> z := Log( g );
[ 1, 1, -1/2, 7/3, -1/3 ]
gap> Exp( z ) = g;
true
gap> k := Exp( y );
[ 3, 9, 37/2, 77/4, 395/4 ]
gap> Log( k ) = y;
true

gap> g*h;
[ 6, -2, 5, 10, -15/2 ]
gap> Comm(g,h);
[ 0, 0, 8, 10, -18 ]
gap> Comm(x,y);
[ 0, 0, 3/2, -25/4, -79/4 ]

gap> indets := List( List( [1..dim], i->Concatenation( "a_", String(i) ) ),
>                   x->Indeterminate( Rationals, x : new ) );
[ a_1, a_2, a_3, a_4, a_5 ]
gap> g_sym := MalcevSymbolicGrpElementByExponents( mo, indets );
[ a_1, a_2, a_3, a_4, a_5 ]
gap> x_sym := Log( g_sym );
[ a_1, a_2, -1/2*a_1*a_2+a_3, 1/12*a_1^2*a_2+1/4*a_1*a_2-1/2*a_1*a_3+a_4,
  -1/12*a_1*a_2^2+1/4*a_1*a_2-1/2*a_2*a_3+a_5 ]
gap> g_sym * g;
[ a_1+1, a_2+1, a_2+a_3, a_3+a_4+2, 1/2*a_2^2+1/2*a_2+a_3+a_5-1/2 ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%


