% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[11pt]{report}
\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}
\definecolor{FuncColor}{rgb}{1.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,1.0}

\usepackage{fancyvrb}

\usepackage{pslatex}

\usepackage[
        a4paper=true,bookmarks=false,pdftitle={Written with GAPDoc},
        pdfcreator={LaTeX with hyperref package / GAPDoc},
        colorlinks=true,backref=page,breaklinks=true,linkcolor=RoyalBlue,
        citecolor=RoyalGreen,filecolor=RoyalRed,
        urlcolor=RoyalRed,pagecolor=RoyalBlue]{hyperref}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
\newcommand{\Q}{\mathbb{Q}}
\newcommand{\R}{\mathbb{R}}
\newcommand{\C}{\mathbb{C}}
\newcommand{\Z}{\mathbb{Z}}
\newcommand{\N}{\mathbb{N}}
\newcommand{\F}{\mathbb{F}}

\newcommand{\GAP}{\textsf{GAP}}

\newsavebox{\backslashbox}
\sbox{\backslashbox}{\texttt{\symbol{92}}}
\newcommand{\bs}{\usebox{\backslashbox}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{\textsf{UnitLib}}}\\[1cm]
\hypersetup{pdftitle=\textsf{UnitLib}}
\markright{\scriptsize \mbox{}\hfill \textsf{UnitLib} \hfill\mbox{}}
{\Large \textbf{The library of normalized unit groups of modular group algebras}}\\[1cm]
{Version 2.1}\\[1cm]
{March 2007}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{Alexander Konovalov    }}\\
{\large \textbf{Elena Yakimenko   }}\\
\hypersetup{pdfauthor=Alexander Konovalov    ; Elena Yakimenko   }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{Alexander Konovalov    } --- Email: \href{mailto://konovalov@member.ams.org}{\texttt{konovalov@member.ams.org}}\\
 --- Homepage: \href{http://www.cs.st-andrews.ac.uk/~alexk/}{\texttt{http://www.cs.st-andrews.ac.uk/\~{}alexk/}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 School of Computer Science\\
 University of St Andrews\\
 Jack Cole Building, North Haugh,\\
 St Andrews, Fife, KY16 9SX, Scotland \end{minipage}
}\\
{\mbox{}\\
\small \noindent \textbf{Elena Yakimenko   } --- Email: \href{mailto://k-algebra@zsu.zp.ua}{\texttt{k-algebra@zsu.zp.ua}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 Department of Mathematics\\
 Zaporozhye National University\\
 Ul.Zhukovskogo, 66, Zaporozhye\\
 69600 Ukraine \end{minipage}
}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Abstract}
\logpage{[ 0, 0, 1 ]}
 \index{UnitLib package@\textsf{UnitLib} package} The \textsf{UnitLib} package extends the \textsf{LAGUNA} package and provides the library of normalized unit groups of modular group
algebras of all finite $p$-groups of order not greater than 243 over the field of $p$ elements. }\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
 {\copyright} 2006-2007 by Alexander Konovalov and Elena Yakimenko

 \textsf{UnitLib} is free software; you can redistribute it and/or modify it under the terms of
the GNU General Public License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later version. For
details, see the FSF's own site \href{http://www.gnu.org/licenses/gpl.html}{\texttt{http://www.gnu.org/licenses/gpl.html}}.

 If you obtained \textsf{UnitLib}, we would be grateful for a short notification sent to one of the authors.

 If you publish a result which was partially obtained with the usage of \textsf{UnitLib}, please cite it in the following form:

 A. Konovalov and E. Yakimenko. \emph{UnitLib --- The library of normalized unit groups of modular group algebras,
Version 2.1;} 2007 (\href{http://www.cs.st-andrews.ac.uk/~alexk/unitlib.htm}{\texttt{http://www.cs.st-andrews.ac.uk/\~{}alexk/unitlib.htm}}). }\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 3 ]}
 The first version of the package (as well as the subsequent version 2.1) was
released in 2006, when the first author was a postdoctoral research
collaborator at the Vrije Universiteit Brussels, Belgium. It is a pleasure of
the first author to express his gratitude to Prof. Dr. Eric Jespers for his
warm hospitality and to acknowledge the support provided by the Francqui
Stichting grant ADSI107. 

 Both authors are very grateful to the members of the \textsf{GAP} team: Thomas Breuer, Stefan Kohl and Frank Lübeck for helpful suggestions. We
would like to acknowledge Bettina Eick for communicating the package, and the
referee for testing \textsf{UnitLib} and useful commnets. Finally, we wish to thank the Centre for
Interdisciplinary Research in Computational Algebra of the University of St
Andrews and the Computational Cluster of the Kiev National Taras Shevchenko
University for offering their computer facilities for computations. }\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 4 ]}}

\tableofcontents
\newpage

  
\chapter{\textcolor{Chapter }{Introduction}}\label{Intro}
\logpage{[ 1, 0, 0 ]}
{
  
\section{\textcolor{Chapter }{General aims}}\label{Aims}
\logpage{[ 1, 1, 0 ]}
{
  Let $KG$ be a group algebra of a finite $p$-group $G$ over the field $K$ of characteristic $p$, and let $V(KG)$ be the normalized unit group of $KG$. The pc-presentation of the group $V(KG)$ can be computed using the \textsf{GAP} package \textsf{LAGUNA} (\href{http://www.cs.st-andrews.ac.uk/~alexk/laguna.htm}{\texttt{http://www.cs.st-andrews.ac.uk/\~{}alexk/laguna.htm}}), but for groups of orders 64 and more such computation will already take a
lot of time. 

 The \textsf{UnitLib} package is an extension of the \textsf{LAGUNA} package that is focused on this problem. It contains the library of normalized
unit groups of modular group algebras of finite $p$-groups over the field of $p$ elements. This allows the user to retrieve the pre-computed group from the
library instead of the long-time computation. The group created with \textsf{UnitLib} will have the same properties and attributes as the one computed with \textsf{LAGUNA}. 

 The current version of \textsf{UnitLib} provides the library of normalized unit groups $V(KG)$ for all $p$-groups of order not greater than 243. If you need to work with groups of
bigger orders, please write to the authors, because we may already have them
computed or can compute them for you. 

 }

 
\section{\textcolor{Chapter }{Theoretical background}}\label{TheoryUnitlib}
\logpage{[ 1, 2, 0 ]}
{
  Since the \textsf{UnitLib} package is an extension of the \textsf{LAGUNA} package \cite{Laguna}, we refer to the  \textbf{LAGUNA: LAGUNA package} manual for the theoretical backround. In particular, Chapter 3 (The basic
theory behind \textsf{LAGUNA}) of that manual contains definitions of the modular group algebra and its
normalized unit group, the power-commutator presentation of the group, and
also more details about the algorithm for the computation of the
pc-presentation of the normalized unit group of a modular group algebra of a
finite $p$-group. }

 
\section{\textcolor{Chapter }{Installation and system requirements}}\label{Install}
\logpage{[ 1, 3, 0 ]}
{
  \textsf{UnitLib} is designed for \textsf{GAP}4.4 and no compatibility with previous releases of \textsf{GAP}4 is guaranteed. 

 Libraries of normalized unit groups of groups of orders less than 243, except
for the order 128, will be available in any operating system. 

 The library for groups of order 128 was compressed using the \texttt{gzip} program and, therefore, will be available only in UNIX-type systems (including
UNIX-installation in Mac OS X and Cygwin installation in Windows). 

 To work with the library for groups of order 243 you will also need the \texttt{Curl} program (\href{http://curl.haxx.se}{\texttt{http://curl.haxx.se}}) to retrieve the data from the UnitLib homepage, and the \textsf{GAP} package \textsf{Qaos} (\href{http://www.gap-system.org/Packages/qaos.html}{\texttt{http://www.gap-system.org/Packages/qaos.html}}) which provides the \textsf{GAP} function \texttt{Curl} to work with \texttt{cURL}. 

 If you need to work with groups of order 128 or 243 in Windows environment or
you can not use \texttt{Curl}, please write to the authors. We will be able to give you a version of \textsf{UnitLib} with locally stored non-compressed data. 

 Because the \textsf{UnitLib} is an extension of the \textsf{LAGUNA} package, you must have the \textsf{LAGUNA} package installed. You can obtain it from the \textsf{GAP} homepage or from its homepage \href{http://www.cs.st-andrews.ac.uk/~alexk/laguna.htm}{\texttt{http://www.cs.st-andrews.ac.uk/\~{}alexk/laguna.htm}}. 

 To use the \textsf{UnitLib} online help it is necessary to install the \textsf{GAP}4 package \textsf{GAPDoc} by Frank L\"ubeck and Max Neunh\"offer, which is available from the \textsf{GAP} homepage or from \href{http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc/}{\texttt{http://www.math.rwth-aachen.de/\~{}Frank.Luebeck/GAPDoc/}}. 

 \textsf{UnitLib} is distributed in standard formats (\texttt{zoo}, \texttt{tar.gz}, \texttt{tar.bz2}, \texttt{-win.zip}) and can be obtained from the \textsf{GAP} homepage or from \href{http://www.cs.st-andrews.ac.uk/~alexk/unitlib.htm}{\texttt{http://www.cs.st-andrews.ac.uk/\~{}alexk/unitlib.htm}}. To unpack the archive \texttt{unitlib-2.1.zoo} you need the program \texttt{unzoo}, which can be obtained from the \textsf{GAP} homepage \href{http://www.gap-system.org/}{\texttt{http://www.gap-system.org/}} (see section `Distribution'). To install \textsf{UnitLib}, copy this archive into the \texttt{pkg} subdirectory of your \textsf{GAP}4.4 installation. Then the subdirectory \texttt{unitlib} containing the package will be created in the \texttt{pkg} directory after the command

 \texttt{unzoo -x unitlib-2.1.zoo} }

 }

  
\chapter{\textcolor{Chapter }{\textsf{UnitLib} functions}}\label{Funct}
\logpage{[ 2, 0, 0 ]}
{
  Since the main purpose of \textsf{UnitLib} is the storage of large amount of data, it has only two main user functions,
which allow to read the description of $V(KG)$ for the given catalogue number of $G$ in the Small Groups Libary of the \textsf{GAP} system, and to save the description of $V(KG)$ if the user would like to store it for further usage for the group that is not
contained in the library. 

 Examples below contain some functions from the \textsf{LAGUNA} package \cite{Laguna}, see their description in the \textsf{LAGUNA} manual. 

 To use the \textsf{UnitLib} package first you need to load it as follows: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> LoadPackage("unitlib");
  ----------------------------------------------------------------------------
  Loading  UnitLib 2.1 (Library of normalized unit groups of modular group algebras)
  by Alexander Konovalov (http://www.cs.st-andrews.ac.uk/~alexk/) and
     Elena Yakimenko (k-algebra@zsu.zp.ua).
  ----------------------------------------------------------------------------
  true
  gap>
  
\end{Verbatim}
 In case of a non-UNIX system, a warning will be displayed about
non-availability of the library of normalized unit groups for groups of orders
128 and 243. 
\section{\textcolor{Chapter }{MainFunctions}}\label{MainFunctions}
\logpage{[ 2, 1, 0 ]}
{
  

\subsection{\textcolor{Chapter }{PcNormalizedUnitGroupSmallGroup}}
\logpage{[ 2, 1, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PcNormalizedUnitGroupSmallGroup( s, n )\index{PcNormalizedUnitGroupSmallGroup@\texttt{PcNormalizedUnitGroupSmallGroup}}
\label{PcNormalizedUnitGroupSmallGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 PcGroup 



 Let \mbox{\texttt{s}} be a power of prime $p$ and \mbox{\texttt{n}} is an integer from \texttt{[ 1 .. NrSmallGroups(s) ]}. Then \texttt{PcNormalizedUnitGroupSmallGroup(\mbox{\texttt{s}},\mbox{\texttt{n}})} returns the normalized unit group $V(KG)$ of the modular group algebra $KG$, where $G$ is \texttt{SmallGroup(\mbox{\texttt{s}},\mbox{\texttt{n}})} and $K$ is a field of $p$ elements. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> PcNormalizedUnitGroupSmallGroup(128,161);
  <pc group of size 170141183460469231731687303715884105728 with 127 generators>
  
\end{Verbatim}
 The result returned by \texttt{PcNormalizedUnitGroupSmallGroup} will be equivalent to the following sequence of commands: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
                                                                           
  gap> G := SmallGroup( s, n );
  gap> p := PrimePGroup( G );
  gap> K := GF( p );
  gap> KG := GroupRing( K, G );
  gap> PcNormalizedUnitGroup( KG );
                                                                                 
\end{Verbatim}
 Nevertheless, \texttt{PcNormalizedUnitGroupSmallGroup} is not just a shortcut for such computation. It reads the description of the
normalized unit group from the \textsf{UnitLib} library and then reconstructs all its necessary attributes and properties.
Thus, if you would like to obtain the group algebra $KG$ or the field $K$ and the group $G$, you should extract them from $V(KG)$, which should be constructed first. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> V:=PcNormalizedUnitGroup(GroupRing(GF(2),SmallGroup(8,3)));
  <pc group of size 128 with 7 generators>
  gap> V1:=PcNormalizedUnitGroupSmallGroup(8,3);                   
  <pc group of size 128 with 7 generators>
  gap> V1=V;     # two isomorphic groups but not identical objects
  false
  gap> IdGroup(V)=IdGroup(V1);
  true
  gap> IsomorphismGroups(V,V1);
  [ f1, f2, f3, f4, f5, f6, f7 ] -> [ f1, f2, f3, f4, f5, f6, f7 ]
  gap> KG:=UnderlyingGroupRing(V1);  # now the correct way
  <algebra-with-one over GF(2), with 3 generators>
  gap> V1=PcNormalizedUnitGroup(KG); # V1 is an attribite of KG
  true
  gap> K:=UnderlyingField(KG);
  GF(2)
  gap> G:=UnderlyingGroup(KG);     
  <pc group of size 8 with 3 generators>
  
\end{Verbatim}
 Moreover, the original group $G$ can be embedded into the output of the \texttt{PcNormalizedUnitGroupSmallGroup}, as it is shown in the continuation of the previous example: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> f:=Embedding(G,V1); 
  [ f1, f2, f3 ] -> [ f2, f1, f3 ]
  gap> g:=List(GeneratorsOfGroup(G), x -> x^f ); 
  [ f2, f1, f3 ]
  gap> G1:=Subgroup(V1,g);
  Group([ f2, f1, f3 ])
  gap> IdGroup(G1);
  [ 8, 3 ]
  
\end{Verbatim}
 If the first argument \mbox{\texttt{s}} (the order of a group) is not a power of prime, an error message will appear.
If \mbox{\texttt{s}} is bigger than 243, you will get a warning telling that the library does not
contain $V(KG)$ for $G$ of such order, and you can use only data that you already stored in your \texttt{unitlib/userdata} directory with the help of the function \texttt{SavePcNormalizedUnitGroup} (\ref{SavePcNormalizedUnitGroup}). 

 It is worth to mention that for some groups of order 243, the construction of
the normalized unit group using \texttt{PcNormalizedUnitGroupSmallGroup} may already require some noticeable amount of time. For example, it took about
166 seconds of CPU time to compute \texttt{PcNormalizedUnitGroupSmallGroup(243,30)} on Intel Xeon 3.4 GHz with 2048 KB cache. 

\subsection{\textcolor{Chapter }{SavePcNormalizedUnitGroup}}
\logpage{[ 2, 1, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SavePcNormalizedUnitGroup( G )\index{SavePcNormalizedUnitGroup@\texttt{SavePcNormalizedUnitGroup}}
\label{SavePcNormalizedUnitGroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
 true 



 Let \mbox{\texttt{G}} be a finite $p$-group of order $s$ from the Small Groups Library of the \textsf{GAP} system, constructed with the help of \texttt{SmallGroup(s,n)}. Then \texttt{SavePcNormalizedUnitGroup(\mbox{\texttt{G}})} creates the file with the name of the form \texttt{us{\textunderscore}n.g} in the directory \texttt{unitlib/userdata}, and returns \texttt{true} if this file was successfully generated. This file contains the description of
the normalized unit group $V(KG)$ of the group algebra of the group \mbox{\texttt{G}} over the field of $p$ elements. 

 If the order of \mbox{\texttt{G}} is greater than 243, after this you can construct the group $V(KG)$ using \texttt{PcNormalizedUnitGroupSmallGroup} (\ref{PcNormalizedUnitGroupSmallGroup}) similarly to the previous section. The preliminary warning will be displayed,
telling that for such orders you can use only those groups that were already
computed by the user and saved to the \texttt{unitlib/userdata} directory. If there will be no such file there, you will get an error message,
otherwise the computation will begin. 

 If the order of \mbox{\texttt{G}} is less or equal to 243, then the file will be created in the \texttt{unitlib/userdata} directory, but \textsf{UnitLib} will continue to use the file with the same name from the appropriate
directory in \texttt{unitlib/data}. You can compare these two files to make it sure that they are the same. 

 \textsc{WARNINGS:} 

 1. It is important to apply this function to the underlying group $G$ and not to the normalized unit group $V(KG)$. 

 2. The user should use as an argument only groups from the Small Groups
Library of the \textsf{GAP} system, constructed with the help of \texttt{SmallGroup(s,n)}, otherwise the consistency of data may be lost. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> SavePcNormalizedUnitGroup( SmallGroup( 256, 56092 ) );
  true
  gap> PcNormalizedUnitGroupSmallGroup( 256, 56092 );
  WARNING : the library of V(KG) for groups of order
  256 is not available yet !!!
  You can use only groups from the unitlib/userdata directory
  in case if you already computed their descriptions
  (See the manual for SavePcNormalizedUnitGroup)
  
  Description of V(KG) for G=SmallGroup(256,
  56092) accepted, started its generation
  <pc group of size
  57896044618658097711785492504343953926634992332820282019728792003956564819968
    with 255 generators>
  
\end{Verbatim}
 }

 \newpage 
\section{\textcolor{Chapter }{Service tools}}\label{Service}
\logpage{[ 2, 2, 0 ]}
{
  

\subsection{\textcolor{Chapter }{UNITLIBBuildManual}}
\logpage{[ 2, 2, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{UNITLIBBuildManual(  )\index{UNITLIBBuildManual@\texttt{UNITLIBBuildManual}}
\label{UNITLIBBuildManual}
}\hfill{\scriptsize (function)}}\\


 This function is used to build the manual in the following formats: DVI, PDF,
PS, HTML and text for online help. We recommend that the user should have a
recent and fairly complete {\TeX} distribution. Since \textsf{UnitLib} is distributed together with its manual, it is not necessary for the user to
use this function. Normally it is intended to be used by the developers only.
This is the only function of \textsf{UnitLib} which requires UNIX/Linux environment. }

 

\subsection{\textcolor{Chapter }{UNITLIBBuildManualHTML}}
\logpage{[ 2, 2, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{UNITLIBBuildManualHTML(  )\index{UNITLIBBuildManualHTML@\texttt{UNITLIBBuildManualHTML}}
\label{UNITLIBBuildManualHTML}
}\hfill{\scriptsize (function)}}\\


 This fuction is used to build the manual only in HTML format. This does not
depend on the availability of the {\TeX} installation and works under Windows and MacOS as well. Since \textsf{UnitLib} is distributed together with its manual, it is not necessary for the user to
use this function. Normally it is intended to be used by the developers only. }

 }

 }

  
\chapter{\textcolor{Chapter }{Details of implementation}}\label{Theory}
\logpage{[ 3, 0, 0 ]}
{
  In this chapter we describe the approach used to store the normalized unit
group of the group algebra in the library, and to reconstruct the group $V(KG)$ from the stored information. 
\section{\textcolor{Chapter }{Saving the data}}\label{Writing}
\logpage{[ 3, 1, 0 ]}
{
  To compute the pc-presentation of the normalized unit group of the modular
group algebra of a finite $p$-group we used the function \texttt{PcNormalizedUnitGroup} from the \textsf{LAGUNA} package. It uses the algorithm descibed in \cite{Bovdi}. See the \textsf{LAGUNA} manual \cite{Laguna} for more details. 

 When this group is computed, the main idea is to use \textsf{GAP} function \texttt{CodePcGroup} that returns the code for the polycyclic generating sequence of the group, and
then to create the group from this code using the \textsf{GAP} function \texttt{PcGroupCode}. 

 The resulting code could be very long, and to compress it we used the \textsf{GAP} function \texttt{HexStringInt} than returns a string that represents the code with hexa-decimal digits (using
A-F as digits 10-15). The inverse translation then can be performed with the \textsf{GAP} function \texttt{IntHexString}. This allowed to save almost 20 MB of space on groups of order 128 and reduce
the total size of their database to 90 MB. 

 For groups of order 128 we decided to compress the library with the \texttt{gzip} program, and then uncompress each file "on fly" when it is requested. This
allowed us to reduce the size of their part in the library from 90 to 12 MB,
which is already quite reasonable. Of course, there is some little overhead
arising from the uncompression and subsequent translation from hexa-decimal
notation, but it is neglectible comparatively with the total time of the
computation of $V(KG)$ from scratch. 

 There is one more thing that needs to be stored together with this code to
make it sure that we will correctly indentify the underlying group $G$ of the group algebra $KG$ with its image in the pc-presentation of the normalized unit group $V(KG)$. 

 The group $G$ is extracted from the \textsf{GAP} Small Groups Library, so it is always the same, unless its description in the
library will be changed (and it will be an important task of \textsf{UnitLib} maintaner to update the package in this case!), and here we are safe from
inconsistencies. 

 But the next stage is the computation of generators of the normalized unit
group $V(KG)$, and the first step is the dimension basis of the group $G$, that can be computed using the \textsf{LAGUNA} function \texttt{DimensionBasis}. To avoid the influence of possible changes in \textsf{GAP} or usage of random methods, we store (in compacted form) the information about
the dimension basis of $G$ in the \textsf{UnitLib}. 

 All further procedures are implemented inside the \textsf{LAGUNA} package, and their result is uniquely determined and predictable. 

 For most groups all information is stored in a single file. However, this is
not the case for groups of order 243, where we have about 30 MB of data for 67
groups. For these groups we provide a solution on the base of Web-services.
The information about the dimension basis is stored locally, while the codes
for polycyclic generating sequences are available from the \textsf{UnitLib} homepage, and the package will access them using the \texttt{Curl} function from the \textsf{Qaos} package \cite{QaoS}. 

 For the reader interested in more details, the package contains the file \texttt{unitlib/lib/genlib.g} with the function \texttt{CreatePcNormalizedUnitGroupsLibrary}, that creates library files for groups of a given prime power order, and the
file \texttt{unitlib/lib/genpar.g} with the function \texttt{ParCreatePcNormalizedUnitGroupsLibrary}, which is the parallel version of the previous function and must be used with
the \textsf{ParGAP} package \cite{ParGAP}. }

 
\section{\textcolor{Chapter }{Reading the data}}\label{Reading}
\logpage{[ 3, 2, 0 ]}
{
  To reconstruct the normalized unit group $V(KG)$ from the library, we need only to know the catalogue number of the underlying
group $G$ in the \textsf{GAP} Small Groups Library. 

 We use the same numbering as in the \textsf{GAP} Small Group Library, so \textsf{UnitLib} finds the appropriate library file(s) and reads from it the code for the
polycyclic generating sequence of $V(KG)$ and the information about the dimension basis of $G$ used for the computation of this code. 

 Then $V(KG)$ is created from the code using the \textsf{GAP} function \texttt{PcGroupCode}. We also create $G$ using the \textsf{GAP} Small Groups Library. 

 Now to "glue" $V(KG)$ with the underlying group $G$ properly, the value of the attribute \texttt{DimensionBasis} of $G$ is setted in accordance with the data retrieved from the library. This will
guarantee the correct construction of \texttt{NaturalBijectionToPcNormalizedUnitGroup} and \texttt{NaturalBijectionToNormalizedUnitGroup} by the \textsf{LAGUNA} package. 

 It remains now to make only several technical steps, such as constructing the
group algebra $KG$ over the appropriate field $K$, and storing $KG$ in the attribute \texttt{UnderlyingGroupRing} of $V(KG)$ and $V(KG)$ in the attribute \texttt{PcNormalizedUnitGroup} of $KG$. }

 }

  
\chapter{\textcolor{Chapter }{An example of \textsf{UnitLib} usage}}\label{Example}
\logpage{[ 4, 0, 0 ]}
{
  We will finish with several examples of \textsf{UnitLib} usage to give an idea how to work with the package. 

 In the first example we retrieve from the library the normalized unit group of
the group algebra of the dihedral group of order 128 over the field of two
elements, compute its center and express one of its generators in terms of
group algebra elements: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IdGroup(DihedralGroup(128));
  [ 128, 161 ]
  gap> V := PcNormalizedUnitGroupSmallGroup( 128, 161 );
  <pc group of size 170141183460469231731687303715884105728 
    with 127 generators>
  gap> C := Center( V );           
  <pc group with 34 generators>  
  gap> gens := MinimalGeneratingSet( C );;
  gap> KG := UnderlyingGroupRing( V );
  <algebra-with-one over GF(2), with 7 generators>
  gap> f := NaturalBijectionToNormalizedUnitGroup( KG );;
  gap> gens[8]^f;
  (Z(2)^0)*f3+(Z(2)^0)*f4+(Z(2)^0)*f7+(Z(2)^0)*f3*f4+(Z(2)^
  0)*f3*f5+(Z(2)^0)*f3*f6+(Z(2)^0)*f3*f7+(Z(2)^0)*f4*f5+(Z(2)^
  0)*f4*f6+(Z(2)^0)*f4*f7+(Z(2)^0)*f3*f4*f5+(Z(2)^0)*f3*f4*f6+(
  Z(2)^0)*f3*f4*f7+(Z(2)^0)*f3*f5*f6+(Z(2)^0)*f3*f5*f7+(Z(2)^
  0)*f3*f6*f7+(Z(2)^0)*f4*f5*f6+(Z(2)^0)*f4*f5*f7+(Z(2)^
  0)*f4*f6*f7+(Z(2)^0)*f3*f4*f5*f6+(Z(2)^0)*f3*f4*f5*f7+(Z(2)^
  0)*f3*f4*f6*f7+(Z(2)^0)*f3*f5*f6*f7+(Z(2)^0)*f4*f5*f6*f7+(Z(2)^
  0)*f3*f4*f5*f6*f7
  
\end{Verbatim}
 In the second example we will check the conjecture about the coincidence of
the lower and upper Lie nilpotency indices of the modular group algebras for
all non-abelian groups of order 64. 

 It is known that these indices coincide for $p$-groups with $ p>3 $ \cite{Bhandari-Passi}, but in the general case the problem remains open. 

 The indices $t_L(G)$ and $t^L(G)$ can be computed using the \textsf{LAGUNA} package. While the upper Lie nilpotency index can be expressed only in terms
of the underlying group $G$, the lower Lie nilpotency index is determined by the formula $t_L(G) =$ cl $V(KG) + 1$ \cite{Du}, and can be computed immediately whenever $V(KG)$ is known. 

 In the program below we enumerate all groups of size 64 and check the
conjecture (we do not exclude from consideration some particular cases when
the conjecture is known to be true for $p=2$, because this is beyond the task of this manual). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> for n in [ 1 .. NrSmallGroups( 64 ) ] do
  > if not IsAbelian( SmallGroup( 64, n ) ) then
  >   Print( n, "\r" );
  >   V := PcNormalizedUnitGroupSmallGroup( 64, n );
  >   KG := UnderlyingGroupRing( V );
  >   if LieLowerNilpotencyIndex( KG ) <>
  >      LieUpperNilpotencyIndex( KG ) then
  >     Print( n," - counterexample !!! \n" );
  >     break;
  >   fi;
  > fi;
  > od;
  gap>
  
\end{Verbatim}
 Thus, the test was finished without finding a counterexample. 

 In the next example we will answer the question about possible nilpotency
classes of normalized unit groups of modular group algebras of nonabelian
groups of order 128: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> cl := [];
  gap> for n in [ 1 .. NrSmallGroups( 128 ) ] do
  > if not IsAbelian( SmallGroup( 128, n ) ) then
  >   Print( n, "\r" );
  >   V := PcNormalizedUnitGroupSmallGroup( 128, n );  
  >   AddSet( cl, NilpotencyClassOfGroup( V ) );
  > fi;
  > od;
  gap> cl;
  [ 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 16, 32 ]
  
\end{Verbatim}
 With \textsf{UnitLib} you can perform the computation from the last example in several hours on a
modern computer. Without \textsf{UnitLib} you will spend the same time to compute only several normalized unit groups $V(KG)$ for groups of order 128 with the help of the \textsf{LAGUNA} package. Note that without \textsf{LAGUNA} such computation would not be feasible at all. }

 \def\bibname{References\logpage{[ "Bib", 0, 0 ]}}

\bibliographystyle{alpha}
\bibliography{manual}

\def\indexname{Index\logpage{[ "Ind", 0, 0 ]}}


\printindex

\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}