% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}

\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\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{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}

%%  for a long time these were red and blue by default,
%%  now black, but keep variables to overwrite
\definecolor{FuncColor}{rgb}{0.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,0.0}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}


\usepackage{fancyvrb}

\usepackage{mathptmx,helvet}
\usepackage[T1]{fontenc}
\usepackage{textcomp}


\usepackage[
            pdftex=true,
            bookmarks=true,        
            a4paper=true,
            pdftitle={Written with GAPDoc},
            pdfcreator={LaTeX with hyperref package / GAPDoc},
            colorlinks=true,
            backref=page,
            breaklinks=true,
            linkcolor=linkColor,
            citecolor=citeColor,
            filecolor=fileColor,
            urlcolor=urlColor,
            pdfpagemode={UseNone}, 
           ]{hyperref}

\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont}

% 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,}}
%% were never documented, give conflicts with some additional packages

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

%% nicer description environments, allows long labels
\usepackage{enumitem}
\setdescription{style=nextline}

%% depth of toc
\setcounter{tocdepth}{1}





%% command for ColorPrompt style examples
\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}}
\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}}
\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}}


\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\mbox{}\vfill

\begin{center}{\maintitlesize \textbf{\textsf{UnitLib}\mbox{}}}\\
\vfill

\hypersetup{pdftitle=\textsf{UnitLib}}
\markright{\scriptsize \mbox{}\hfill \textsf{UnitLib} \hfill\mbox{}}
{\Huge \textbf{The library of normalized unit groups of modular group algebras\mbox{}}}\\
\vfill

{\Huge Version 3.2.0\mbox{}}\\[1cm]
{11 November 2014\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{Alexander Konovalov    \mbox{}}}\\
{\Large \textbf{Elena Yakimenko  \mbox{}}}\\
\hypersetup{pdfauthor=Alexander Konovalov    ; Elena Yakimenko  }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{Alexander Konovalov    }  Email: \href{mailto://alexk@mcs.st-andrews.ac.uk} {\texttt{alexk@mcs.st-andrews.ac.uk}}\\
  Homepage: \href{http://www.cs.st-andrews.ac.uk/~alexk/} {\texttt{http://www.cs.st-andrews.ac.uk/\texttt{\symbol{126}}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  }\\
  Address: \begin{minipage}[t]{8cm}\noindent
 Department of Mathematics\\
 Zaporozhye National University\\
 Zaporozhye, 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. 

 It also contains a parallel implementation of the computation of the
normalized unit group of a modular group algebra of a finite $p$-group (which should be retrieved from the \textsf{GAP} Small Groups Library) over the field of $p$ elements. \mbox{}}\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
 {\copyright} 2006-2012 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 3.2.0}, 2012 (\href{http://www.cs.st-andrews.ac.uk/~alexk/unitlib/} {\texttt{http://www.cs.st-andrews.ac.uk/\texttt{\symbol{126}}alexk/unitlib/}}). \mbox{}}\\[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{\"u}beck for helpful suggestions.
We would like to acknowledge Bettina Eick for communicating the package, and
the referee for testing \textsf{UnitLib} and useful comments. 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. \mbox{}}\\[1cm]
\newpage

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

\tableofcontents
\newpage

 
\chapter{\textcolor{Chapter }{Introduction}}\label{Intro}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7DFB63A97E67C0A1}{}
{
  
\section{\textcolor{Chapter }{General aims}}\label{Aims}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X8557083378F2A3B2}{}
{
  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/} {\texttt{http://www.cs.st-andrews.ac.uk/\texttt{\symbol{126}}alexk/laguna/}}), 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 time-consuming computation. The group created with \textsf{UnitLib} will have the same properties and attributes as the one computed with \textsf{LAGUNA}. 

 The version \textsf{UnitLib} 3.0.0 released in May 2009 also contained a parallel implementation of the
computation of the normalized unit group of a modular group algebra of a
finite $p$-group over the field of $p$ elements, which works for groups from the \textsf{GAP} small groups library. It is developed on the base of the sequential version of
this algorithm (which works for any $p$-group with no limitations) from the \textsf{LAGUNA} package. Parallelisation is implemented using the \textsf{SCSCP} package that is capable of connecting several local or remote \textsf{GAP} instances using the \textsf{SCSCP} protocol. 

 In April 2012, \textsf{UnitLib} 3.1.0 was updated to comply with \textsf{GAP} 4.5. 

 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
maintainers, because they may be already computed or we can compute them for
you. 

 }

 
\section{\textcolor{Chapter }{Theoretical background}}\label{TheoryUnitlib}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X7B6AEBDF7B857E2E}{}
{
  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 ]}
\hyperdef{L}{X7DB566D5785B7DBC}{}
{
  \textsf{UnitLib} 3.2.0 is designed for \textsf{GAP} 4.5 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). If you need
to work with groups of order 128 in Windows, please write to the maintainer to
request a version of \textsf{UnitLib} with locally stored non-compressed data. 

 To work with the library for groups of order 243 you will also need the \textsf{IO} package by Max Neunh{\"o}ffer (\href{http://www-groups.mcs.st-and.ac.uk/~neunhoef/Computer/Software/Gap/io.html} {\texttt{http://www-groups.mcs.st-and.ac.uk/\texttt{\symbol{126}}neunhoef/Computer/Software/Gap/io.html}}) to retrieve the data from the \textsf{UnitLib} homepage. 

 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/\texttt{\symbol{126}}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{\"u}beck and Max Neunh{\"o}ffer, 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/\texttt{\symbol{126}}Frank.Luebeck/GAPDoc/}}. 

 \textsf{UnitLib} is distributed in standard formats (\texttt{tar.gz}, \texttt{tar.bz2}, \texttt{.zip}, \texttt{-win.zip}) and can be obtained from the \textsf{GAP} homepage or from \href{http://www.cs.st-andrews.ac.uk/~alexk/unitlib/} {\texttt{http://www.cs.st-andrews.ac.uk/\texttt{\symbol{126}}alexk/unitlib/}}. To install \textsf{UnitLib}, unpack its archive into the \texttt{pkg} subdirectory of your \textsf{GAP}4.5 installation. When you don't have access to the directory of your main \textsf{GAP} installation, you can also install the package \emph{outside the \textsf{GAP} main directory} by unpacking it inside a directory \texttt{MYGAPDIR/pkg}. Then to be able to load \textsf{UnitLib} you need to call \textsf{GAP} with the \texttt{-l ";MYGAPDIR"} option. 

 }

 }

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

 To use the \textsf{UnitLib} package first you need to load it as follows: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LoadPackage("unitlib");|
  ----------------------------------------------------------------------------
  Loading  UnitLib 3.1.0 (The library of normalized unit groups of modular group algebras)
  by Alexander Konovalov (http://www.cs.st-andrews.ac.uk/~alexk/) and
     Elena Yakimenko.
  Homepage: http://www.cs.st-andrews.ac.uk/~alexk/unitlib/
  ----------------------------------------------------------------------------
  true
  
\end{Verbatim}
 Under Windows, a warning will be displayed about non-availability of the
library of normalized unit groups for groups of orders 128. 

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

 
\section{\textcolor{Chapter }{MainFunctions}}\label{MainFunctions}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X8336306D816FFF06}{}
{
  

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



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

 \newpage 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@PcNormalizedUnitGroupSmallGroup(128,161);|
  <pc group of size 170141183460469231731687303715884105728 with 127 generators>
  
\end{Verbatim}
 The result returned by \texttt{PcNormalizedUnitGroupSmallGroup} is equivalent to the following: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
                                                                           
  !gapprompt@gap>| !gapinput@G := SmallGroup( s, n );|
  !gapprompt@gap>| !gapinput@p := PrimePGroup( G );|
  !gapprompt@gap>| !gapinput@K := GF( p );|
  !gapprompt@gap>| !gapinput@KG := GroupRing( K, G );|
  !gapprompt@gap>| !gapinput@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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@V:=PcNormalizedUnitGroup(GroupRing(GF(2),SmallGroup(8,3)));|
  <pc group of size 128 with 7 generators>
  !gapprompt@gap>| !gapinput@V1:=PcNormalizedUnitGroupSmallGroup(8,3);                   |
  <pc group of size 128 with 7 generators>
  !gapprompt@gap>| !gapinput@V1=V;     # two isomorphic groups but not identical objects|
  false
  !gapprompt@gap>| !gapinput@IdGroup(V)=IdGroup(V1);|
  true
  !gapprompt@gap>| !gapinput@IsomorphismGroups(V,V1);|
  [ f1, f2, f3, f4, f5, f6, f7 ] -> [ f1, f2, f3, f4, f5, f6, f7 ]
  !gapprompt@gap>| !gapinput@KG:=UnderlyingGroupRing(V1);  # now the correct way|
  <algebra-with-one over GF(2), with 3 generators>
  !gapprompt@gap>| !gapinput@V1=PcNormalizedUnitGroup(KG); # V1 is an attribute of KG|
  true
  !gapprompt@gap>| !gapinput@K:=UnderlyingField(KG);|
  GF(2)
  !gapprompt@gap>| !gapinput@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 next example: \newpage 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@f:=Embedding(G,V1); |
  [ f1, f2, f3 ] -> [ f2, f1, f3 ]
  !gapprompt@gap>| !gapinput@g:=List(GeneratorsOfGroup(G), x -> x^f ); |
  [ f2, f1, f3 ]
  !gapprompt@gap>| !gapinput@G1:=Subgroup(V1,g);|
  Group([ f2, f1, f3 ])
  !gapprompt@gap>| !gapinput@IdGroup(G1);|
  [ 8, 3 ]
  
\end{Verbatim}
 If the first argument \mbox{\texttt{\mdseries\slshape s}} (the order of a group) is not a power of prime, an error message will appear.
If \mbox{\texttt{\mdseries\slshape 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
\hyperdef{L}{X7B0154C97CD03CF9}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SavePcNormalizedUnitGroup({\mdseries\slshape G})\index{SavePcNormalizedUnitGroup@\texttt{SavePcNormalizedUnitGroup}}
\label{SavePcNormalizedUnitGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{ParSavePcNormalizedUnitGroup({\mdseries\slshape G})\index{ParSavePcNormalizedUnitGroup@\texttt{ParSavePcNormalizedUnitGroup}}
\label{ParSavePcNormalizedUnitGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 true 



 Let \mbox{\texttt{\mdseries\slshape 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)} (see \texttt{SmallGroup} (\textbf{Reference: SmallGroup (for group order and index)})). Then \texttt{SavePcNormalizedUnitGroup(\mbox{\texttt{\mdseries\slshape 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{\mdseries\slshape G}} over the field of $p$ elements. 

 If the order of \mbox{\texttt{\mdseries\slshape 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{\mdseries\slshape 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{NOTE THAT:} 

 1. The argument should be the underlying group $G$ and not the normalized unit group $V(KG)$. 

 2. The argument should be a group from the \textsf{GAP} Small Groups Library constructed with the help of \texttt{SmallGroup(s,n)}, otherwise the date consistency may be lost. 

 \texttt{ParSavePcNormalizedUnitGroup} works in the same way, but uses the function \texttt{ParPcNormalizedUnitGroup} to parallelise the computation using the \textsf{GAP} package \textsf{SCSCP}. }

 \newpage 
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>B @gapinput|SavePcNormalizedUnitGroup( SmallGroup( 256, 56092 ) );B
  true
  @gapprompt|gap>B @gapinput|PcNormalizedUnitGroupSmallGroup( 256, 56092 );B
  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).
  #I  Description of V(KG) for G=SmallGroup(256,
  56092) accepted, started its generation...
  <pc group of size 
  57896044618658097711785492504343953926634992332820282019728792003956564819968
    with 255 generators>
  
\end{Verbatim}
 }

 }

 
\chapter{\textcolor{Chapter }{Implementation Details}}\label{Theory}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X7AB84A0B83B2C1F1}{}
{
  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 ]}
\hyperdef{L}{X7AE826977E0CD714}{}
{
  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 identify 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 function \texttt{SingleHTTPRequest} (\textbf{IO: SingleHTTPRequest}) from the \textsf{IO} package. 

 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 ]}
\hyperdef{L}{X8134F0157BE00ABA}{}
{
  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} (\textbf{Reference: PcGroupCode}). We also create $G$ using the \textsf{GAP} Small Groups Library. 

 Now to ``glue'' the group $V(KG)$ with the underlying group $G$ properly, the value of the attribute \texttt{DimensionBasis} (\textbf{LAGUNA: DimensionBasis}) of $G$ is set in accordance with the data retrieved from the library. This will
guarantee the correct construction of \texttt{NaturalBijectionToPcNormalizedUnitGroup} (\textbf{LAGUNA: NaturalBijectionToPcNormalizedUnitGroup}) and \texttt{NaturalBijectionToNormalizedUnitGroup} (\textbf{LAGUNA: 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} (\textbf{LAGUNA: UnderlyingGroupRing}) of $V(KG)$ and $V(KG)$ in the attribute \texttt{PcNormalizedUnitGroup} (\textbf{LAGUNA: PcNormalizedUnitGroup}) of $KG$. }

 }

 
\chapter{\textcolor{Chapter }{An example of \textsf{UnitLib} usage}}\label{Example}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X784567E178B5E912}{}
{
  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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@IdGroup(DihedralGroup(128));|
  [ 128, 161 ]
  !gapprompt@gap>| !gapinput@V := PcNormalizedUnitGroupSmallGroup( 128, 161 );|
  <pc group of size 170141183460469231731687303715884105728 with 127 generators>
  !gapprompt@gap>| !gapinput@C := Center( V );           |
  <pc group with 34 generators>  
  !gapprompt@gap>| !gapinput@gens := MinimalGeneratingSet( C );;|
  !gapprompt@gap>| !gapinput@KG := UnderlyingGroupRing( V );|
  <algebra-with-one over GF(2), with 7 generators>
  !gapprompt@gap>| !gapinput@f := NaturalBijectionToNormalizedUnitGroup( KG );;|
  !gapprompt@gap>| !gapinput@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}[commandchars=@|B,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>B @gapinput|for n in [ 1 .. NrSmallGroups( 64 ) ] doB
  @gapprompt|>B @gapinput|if not IsAbelian( SmallGroup( 64, n ) ) thenB
  @gapprompt|>B @gapinput|  V := PcNormalizedUnitGroupSmallGroup( 64, n );B
  @gapprompt|>B @gapinput|  KG := UnderlyingGroupRing( V );B
  @gapprompt|>B @gapinput|  if LieLowerNilpotencyIndex( KG ) <>B
  @gapprompt|>B @gapinput|     LieUpperNilpotencyIndex( KG ) thenB
  @gapprompt|>B @gapinput|    Print( n," - counterexample !!! \n" );B
  @gapprompt|>B @gapinput|    break;B
  @gapprompt|>B @gapinput|  fi;B
  @gapprompt|>B @gapinput|fi;B
  @gapprompt|>B @gapinput|od;B
  
\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 64: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@cl := [];;|
  !gapprompt@gap>| !gapinput@for n in [ 1 .. NrSmallGroups( 64 ) ] do|
  !gapprompt@>| !gapinput@if not IsAbelian( SmallGroup( 64, n ) ) then|
  !gapprompt@>| !gapinput@  V := PcNormalizedUnitGroupSmallGroup( 64, n );  |
  !gapprompt@>| !gapinput@  AddSet( cl, NilpotencyClassOfGroup( V ) );|
  !gapprompt@>| !gapinput@fi;|
  !gapprompt@>| !gapinput@od;|
  !gapprompt@gap>| !gapinput@cl;|
  [ 2, 3, 4, 5, 6, 7, 8, 16 ]
  
\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 ]}
\hyperdef{L}{X7A6F98FD85F02BFE}{}
}

\bibliographystyle{alpha}
\bibliography{manual}

\addcontentsline{toc}{chapter}{References}

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

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Index}


\printindex

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