2. UnitLib functions
  
  Since the main purpose of 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
  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 LAGUNA package [BK+], see
  their description in the LAGUNA manual.
  
  To use the UnitLib package first you need to load it as follows:
  
  ---------------------------  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>
    
  ------------------------------------------------------------------
  
  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.
  
  
  2.1 MainFunctions
  
  2.1-1 PcNormalizedUnitGroupSmallGroup
  
  > PcNormalizedUnitGroupSmallGroup( s, n ) __________________________function
  Returns:  PcGroup
  
  Let s be a power of prime p and n is an integer from [ 1 .. NrSmallGroups(s)
  ].  Then  PcNormalizedUnitGroupSmallGroup(s,n)  returns  the normalized unit
  group  V(KG) of the modular group algebra KG, where G is SmallGroup(s,n) and
  K is a field of p elements.
  
  ---------------------------  Example  ----------------------------
    
    gap> PcNormalizedUnitGroupSmallGroup(128,161);
    <pc group of size 170141183460469231731687303715884105728 with 127 generators>
    
  ------------------------------------------------------------------
  
  The result returned by PcNormalizedUnitGroupSmallGroup will be equivalent to
  the following sequence of commands:
  
  -----------------------------  Log  ------------------------------
                                                                             
    gap> G := SmallGroup( s, n );
    gap> p := PrimePGroup( G );
    gap> K := GF( p );
    gap> KG := GroupRing( K, G );
    gap> PcNormalizedUnitGroup( KG );
                                                                                   
  ------------------------------------------------------------------
  
  Nevertheless,  PcNormalizedUnitGroupSmallGroup  is  not  just a shortcut for
  such computation. It reads the description of the normalized unit group from
  the  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.
  
  ---------------------------  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>
    
  ------------------------------------------------------------------
  
  Moreover,  the  original  group  G  can  be  embedded into the output of the
  PcNormalizedUnitGroupSmallGroup,  as  it is shown in the continuation of the
  previous example:
  
  ---------------------------  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 ]
    
  ------------------------------------------------------------------
  
  If  the  first argument s (the order of a group) is not a power of prime, an
  error  message  will appear. If 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 unitlib/userdata directory
  with the help of the function SavePcNormalizedUnitGroup (2.1-2).
  
  It  is  worth to mention that for some groups of order 243, the construction
  of  the  normalized  unit  group  using  PcNormalizedUnitGroupSmallGroup may
  already  require  some noticeable amount of time. For example, it took about
  166  seconds  of CPU time to compute PcNormalizedUnitGroupSmallGroup(243,30)
  on Intel Xeon 3.4 GHz with 2048 KB cache.
  
  2.1-2 SavePcNormalizedUnitGroup
  
  > SavePcNormalizedUnitGroup( G ) ___________________________________property
  Returns:  true
  
  Let  G  be  a finite p-group of order s from the Small Groups Library of the
  GAP   system,   constructed   with   the   help   of  SmallGroup(s,n).  Then
  SavePcNormalizedUnitGroup(G)  creates  the  file  with  the name of the form
  us_n.g  in the directory unitlib/userdata, and returns 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 G over the field of p
  elements.
  
  If  the  order  of  G  is greater than 243, after this you can construct the
  group  V(KG)  using PcNormalizedUnitGroupSmallGroup (2.1-1) 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 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 G is less or equal to 243, then the file will be created in
  the  unitlib/userdata  directory,  but UnitLib will continue to use the file
  with  the  same name from the appropriate directory in unitlib/data. You can
  compare these two files to make it sure that they are the same.
  
  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  GAP  system, constructed with the help of SmallGroup(s,n),
  otherwise the consistency of data may be lost.
  
  ---------------------------  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>
    
  ------------------------------------------------------------------
  
  
  2.2 Service tools
  
  2.2-1 UNITLIBBuildManual
  
  > UNITLIBBuildManual(  ) ___________________________________________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 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  UnitLib  which requires UNIX/Linux
  environment.
  
  2.2-2 UNITLIBBuildManualHTML
  
  > UNITLIBBuildManualHTML(  ) _______________________________________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 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.