  
  [1m[4m[31m2. [1mUnitLib[1m[4m[31m functions[0m
  
  Since the main purpose of [1mUnitLib[0m 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
  [1mGAP[0m  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 [1mLAGUNA[0m package [BK+], see
  their description in the [1mLAGUNA[0m manual.
  
  To use the [1mUnitLib[0m package first you need to load it as follows:
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> LoadPackage("unitlib");[0m
    [22m[35m----------------------------------------------------------------------------[0m
    [22m[35mLoading  UnitLib 2.1 (Library of normalized unit groups of modular group algebras)[0m
    [22m[35mby Alexander Konovalov (http://www.cs.st-andrews.ac.uk/~alexk/) and[0m
    [22m[35m   Elena Yakimenko (k-algebra@zsu.zp.ua).[0m
    [22m[35m----------------------------------------------------------------------------[0m
    [22m[35mtrue[0m
    [22m[35mgap>[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  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.
  
  
  [1m[4m[31m2.1 MainFunctions[0m
  
  [1m[4m[31m2.1-1 PcNormalizedUnitGroupSmallGroup[0m
  
  [1m[34m> PcNormalizedUnitGroupSmallGroup( [0m[22m[34ms, n[0m[1m[34m ) __________________________[0mfunction
  [1mReturns:[0m  PcGroup
  
  Let [22m[34ms[0m be a power of prime p and [22m[34mn[0m is an integer from [22m[32m[ 1 .. NrSmallGroups(s)
  ][0m.  Then  [22m[32mPcNormalizedUnitGroupSmallGroup([22m[34ms[0m,[22m[34mn[0m)[0m  returns  the normalized unit
  group  V(KG) of the modular group algebra KG, where G is [22m[32mSmallGroup([22m[34ms[0m,[22m[34mn[0m)[0m and
  K is a field of p elements.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> PcNormalizedUnitGroupSmallGroup(128,161);[0m
    [22m[35m<pc group of size 170141183460469231731687303715884105728 with 127 generators>[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  The result returned by [22m[32mPcNormalizedUnitGroupSmallGroup[0m will be equivalent to
  the following sequence of commands:
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35m                                                                         [0m
    [22m[35mgap> G := SmallGroup( s, n );[0m
    [22m[35mgap> p := PrimePGroup( G );[0m
    [22m[35mgap> K := GF( p );[0m
    [22m[35mgap> KG := GroupRing( K, G );[0m
    [22m[35mgap> PcNormalizedUnitGroup( KG );[0m
    [22m[35m                                                                               [0m
  [22m[35m------------------------------------------------------------------[0m
  
  Nevertheless,  [22m[32mPcNormalizedUnitGroupSmallGroup[0m  is  not  just a shortcut for
  such computation. It reads the description of the normalized unit group from
  the  [1mUnitLib[0m  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.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> V:=PcNormalizedUnitGroup(GroupRing(GF(2),SmallGroup(8,3)));[0m
    [22m[35m<pc group of size 128 with 7 generators>[0m
    [22m[35mgap> V1:=PcNormalizedUnitGroupSmallGroup(8,3);                   [0m
    [22m[35m<pc group of size 128 with 7 generators>[0m
    [22m[35mgap> V1=V;     # two isomorphic groups but not identical objects[0m
    [22m[35mfalse[0m
    [22m[35mgap> IdGroup(V)=IdGroup(V1);[0m
    [22m[35mtrue[0m
    [22m[35mgap> IsomorphismGroups(V,V1);[0m
    [22m[35m[ f1, f2, f3, f4, f5, f6, f7 ] -> [ f1, f2, f3, f4, f5, f6, f7 ][0m
    [22m[35mgap> KG:=UnderlyingGroupRing(V1);  # now the correct way[0m
    [22m[35m<algebra-with-one over GF(2), with 3 generators>[0m
    [22m[35mgap> V1=PcNormalizedUnitGroup(KG); # V1 is an attribite of KG[0m
    [22m[35mtrue[0m
    [22m[35mgap> K:=UnderlyingField(KG);[0m
    [22m[35mGF(2)[0m
    [22m[35mgap> G:=UnderlyingGroup(KG);     [0m
    [22m[35m<pc group of size 8 with 3 generators>[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Moreover,  the  original  group  G  can  be  embedded into the output of the
  [22m[32mPcNormalizedUnitGroupSmallGroup[0m,  as  it is shown in the continuation of the
  previous example:
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> f:=Embedding(G,V1); [0m
    [22m[35m[ f1, f2, f3 ] -> [ f2, f1, f3 ][0m
    [22m[35mgap> g:=List(GeneratorsOfGroup(G), x -> x^f ); [0m
    [22m[35m[ f2, f1, f3 ][0m
    [22m[35mgap> G1:=Subgroup(V1,g);[0m
    [22m[35mGroup([ f2, f1, f3 ])[0m
    [22m[35mgap> IdGroup(G1);[0m
    [22m[35m[ 8, 3 ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  If  the  first argument [22m[34ms[0m (the order of a group) is not a power of prime, an
  error  message  will appear. If [22m[34ms[0m 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 [1munitlib/userdata[0m directory
  with the help of the function [1m[34mSavePcNormalizedUnitGroup[0m ([1m2.1-2[0m).
  
  It  is  worth to mention that for some groups of order 243, the construction
  of  the  normalized  unit  group  using  [22m[32mPcNormalizedUnitGroupSmallGroup[0m may
  already  require  some noticeable amount of time. For example, it took about
  166  seconds  of CPU time to compute [22m[32mPcNormalizedUnitGroupSmallGroup(243,30)[0m
  on Intel Xeon 3.4 GHz with 2048 KB cache.
  
  [1m[4m[31m2.1-2 SavePcNormalizedUnitGroup[0m
  
  [1m[34m> SavePcNormalizedUnitGroup( [0m[22m[34mG[0m[1m[34m ) ___________________________________[0mproperty
  [1mReturns:[0m  true
  
  Let  [22m[34mG[0m  be  a finite p-group of order s from the Small Groups Library of the
  [1mGAP[0m   system,   constructed   with   the   help   of  [22m[32mSmallGroup(s,n)[0m.  Then
  [22m[32mSavePcNormalizedUnitGroup([22m[34mG[0m)[0m  creates  the  file  with  the name of the form
  [1mus_n.g[0m  in the directory [1munitlib/userdata[0m, and returns [22m[32mtrue[0m 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 [22m[34mG[0m over the field of p
  elements.
  
  If  the  order  of  [22m[34mG[0m  is greater than 243, after this you can construct the
  group  V(KG)  using [1m[34mPcNormalizedUnitGroupSmallGroup[0m ([1m2.1-1[0m) 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 [1munitlib/userdata[0m directory. If there will be no
  such  file  there,  you will get an error message, otherwise the computation
  will begin.
  
  If  the order of [22m[34mG[0m is less or equal to 243, then the file will be created in
  the  [1munitlib/userdata[0m  directory,  but [1mUnitLib[0m will continue to use the file
  with  the  same name from the appropriate directory in [1munitlib/data[0m. You can
  compare these two files to make it sure that they are the same.
  
  [1m[46mWARNINGS:[0m
  
  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  [1mGAP[0m  system, constructed with the help of [22m[32mSmallGroup(s,n)[0m,
  otherwise the consistency of data may be lost.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> SavePcNormalizedUnitGroup( SmallGroup( 256, 56092 ) );[0m
    [22m[35mtrue[0m
    [22m[35mgap> PcNormalizedUnitGroupSmallGroup( 256, 56092 );[0m
    [22m[35mWARNING : the library of V(KG) for groups of order[0m
    [22m[35m256 is not available yet !!![0m
    [22m[35mYou can use only groups from the unitlib/userdata directory[0m
    [22m[35min case if you already computed their descriptions[0m
    [22m[35m(See the manual for SavePcNormalizedUnitGroup)[0m
    [22m[35m[0m
    [22m[35mDescription of V(KG) for G=SmallGroup(256,[0m
    [22m[35m56092) accepted, started its generation[0m
    [22m[35m<pc group of size[0m
    [22m[35m57896044618658097711785492504343953926634992332820282019728792003956564819968[0m
    [22m[35m  with 255 generators>[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m2.2 Service tools[0m
  
  [1m[4m[31m2.2-1 UNITLIBBuildManual[0m
  
  [1m[34m> UNITLIBBuildManual( [0m[22m[34m[0m[1m[34m ) ___________________________________________[0mfunction
  
  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 [1mUnitLib[0m 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  [1mUnitLib[0m  which requires UNIX/Linux
  environment.
  
  [1m[4m[31m2.2-2 UNITLIBBuildManualHTML[0m
  
  [1m[34m> UNITLIBBuildManualHTML( [0m[22m[34m[0m[1m[34m ) _______________________________________[0mfunction
  
  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 [1mUnitLib[0m 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.
  
