Quelle  rws.xml   Sprache: XML

<!-- ------------------------------------------------------------------- -->
<!--                                                                     -->
<!--  rws.xml                 KBMag documentation             Derek Holt -->
<!--                                                                     -->
<!--  Copyright (C) 1997-2017, Derek Holt                                --> 
<!--                                                                     -->
<!-- ------------------------------------------------------------------- -->

<?xml version="1.0" encoding="UTF-8"?>

<Chapter Label="chap-rws">
<Heading>The Knuth-Bendix program on semigroups, monoids and groups</Heading>

<Section Label="sec-create-rws">
<Heading>Creating a rewriting system</Heading> 

<Index Key="rewriting systems" Subkey="creating"></Index> 

First the user should be aware of a technicality. 
The words in a rewriting system created in &GAP; for use by &KBMAG; 
are defined over an alphabet that consists of the generators of a free monoid, 
called the <E>word-monoid</E> of the system. 
Suppose, as before,  that the rewriting system
is defined from the semigroup, monoid or group <M>G</M> which is a quotient of
the free structure <M>F</M>. Then the generators of this alphabet will be  in
one-one correspondence with the generators (or, when <M>G</M> is a group, the
generators and their inverses) of <M>F</M>, but will not be identical to them.
This feature was necessary for technical reasons. Most of the user-level
functions take and return words in <M>F</M> rather than the alphabet, but
they do this by converting from one to the other and back.
<P/>
User-level functions have also been provided to carry out this
conversion explicitly if required. 
<P/>
The user should also be aware of a peculiarity in the way that
rewriting systems are displayed, which is really a hangover from
the &GAP;3 interface. They are displayed nicely as a record, which gives
a useful description of the system, but it does not correspond at
all to the way that they are actually stored internally!
<P/>

<ManSection>
   <Oper Name="KBMAGRewritingSystem" 
         Arg = "G" />
<Description>
This operation constructs and returns a rewriting system <M>R</M> from a
finitely presented semigroup, monoid or group <M>G</M>.
When <M>G</M> is a group, the alphabet members of <M>R</M> correspond to the generators of  <M>F</M>  together with inverses  for  those  generators 
which are not obviously involutory in <M>G</M>.
<P/>
</Description>
</ManSection>

</Section> 

<!-- ------------------------------------------------------------------- -->

<Section Label="sec-rws-fns">
<Heading>Elementary functions on rewriting systems</Heading>

<Index Key="rewriting systems" Subkey="elementary functions"></Index> 

<ManSection>
   <Filt Name="IsKBMAGRewritingSystemRep" 
         Arg = "rws"
         Type = "representation" /> 
   <Filt Name="IsRewritingSystem" 
         Arg = "rws"
         Type = "category" /> 
<Description>
<C>IsKBMAGRewritingSystemRep</C> returns <C>true</C> if &rws; 
is a rewriting system created by <Ref Func="KBMAGRewritingSystem"/>. 
The function <Ref Func="IsRewritingSystem" BookName="Reference"/> 
will also return <C>true</C> on such a system.
(The function <C>IsKnuthBendixRewritingSystem</C> has been considered 
for inclusion, but is not currently declared.) 
<P/>
</Description>
</ManSection>

<ManSection>
   <Meth Name="IsConfluent" 
         Arg = "rws" />
<Description>
This library property returns <C>true</C> if &rws; is a rewriting system 
that is known to be confluent.
<P/>
</Description>
</ManSection>

<ManSection>
   <Meth Name="SemigroupOfRewritingSytem" 
         Arg = "rws" /> 
   <Meth Name="FreeStructureOfSystem" 
         Arg = "rws" /> 
   <Oper Name="WordMonoidOfRewritingSystem" 
         Arg = "rws" /> 
<Description>
The first two library functions return, respectively, the semigroup, 
monoid or group <M>G</M>, and the free structure <M>F</M>.  
The third returns the word-monoid of the rewriting system,
as defined in section <Ref Sect="sec-create-rws"/>. 
<P/>
</Description>
</ManSection>

<ManSection>
   <Func Name="ExternalWordToInternalWordOfRewritingSystem" 
         Arg = "rws w" /> 
   <Func Name="InternalWordToExternalWordOfRewritingSystem" 
         Arg = "rws w" /> 
<Description>
These are the functions for converting between <E>external words</E>,
which are those defined over the free structure <M>F</M> of &rws;,
and the <E>internal words</E>, which are defined over the word-monoid of &rws;.
<P/>
</Description>
</ManSection>

<ManSection>
   <Attr Name="Alphabet" 
    Arg = "rws" /> 
<Description>
This is an ordered list of the generators of the word-monoid of &rws;.
It will not necessarily be in the normal order of these generators,
and it can be re-ordered by the function 
<Ref Func="ReorderAlphabetOfKBMAGRewritingSystem"/>.
<P/>
</Description>
</ManSection>

<ManSection>
   <Meth Name="Rules" 
     Arg = "rws" /> 
<Description>
This library function returns a list of the <E>reduction rules</E> of &rws;. 
Each rule is a two-element list containing the left and right hand sides 
of the rule, which are words in the alphabet of &rws;.
<P/>
</Description>
</ManSection>

<ManSection>
   <Func Name="ResetRewritingSystem" 
     Arg = "rws" /> 
<Description>
This function resets the rewriting system &rws; back to its form as it
was before the application of <Ref Func="KnuthBendix"/>  
or <Ref Func="AutomaticStructure"/>.
However, the current ordering  and values  of control  parameters  will not
be changed. The normal form and  reduction algorithms will  be unavailable
after  this call.
<P/>
</Description>
</ManSection>

</Section>

<!-- ------------------------------------------------------------------- -->

<Section Label="sec-set-order">
<Heading>Setting the ordering</Heading>

<Index Key="rewriting systems" Subkey="setting the ordering"></Index> 


<ManSection>
   <Func Name="SetOrderingOfKBMAGRewritingSystem" 
    Arg = "rws ordering [, list]" />
   <Func Name="ReorderAlphabetOfKBMAGRewritingSystem" 
     Arg = "rws p" />
   <Func Name="OrderingOfKBMAGRewritingSystem" 
     Arg = "rws" />
   <Meth Name="OrderingOfRewritingSystem" 
     Arg = "rws" /> 
<Description>
<C>SetOrderingOfKBMAGRewritingSystem</C> changes the ordering on 
the  words of the rewriting system  &rws; to &ordering;.
&rws; is reset when the ordering is changed, so any previously
calculated results will be destroyed.
&ordering; must  be  one of the  strings &shortlex;,
&recursive;, &wtlex;  and  &wreathprod;.  
The default is &shortlex;, and this is the ordering of rewriting systems
returned  by  <Ref Func="KBMAGRewritingSystem"/>.   
The orderings &wtlex; and &wreathprod; require the third parameter, 
<C>list</C>,  which must be a list  of  positive integers  in   one-one correspondence  with the alphabet of &rws; in its current order.
They have  the effect of attaching weights or levels to the alphabet members, 
in the cases &wtlex; and &wreathprod;, respectively.
<P/>
Each  of these orderings depends on  the order of  the alphabet. 
The current ordering of generators is displayed under the 
<C>generatorOrder</C> field  when &rws; is  viewed.  
This ordering can   be changed  by the function  
<Ref Func="ReorderAlphabetOfKBMAGRewritingSystem"/> .
The  second  parameter <M>p</M> to  this function should be a permutation 
that moves at most <M>ng</M> points, where <M>ng</M> is  the number of generators.  
This permutation is applied to the current list of generators.
<P/>
<Ref Func="OrderingOfKBMAGRewritingSystem"/> merely prints out a description of 
the current ordering.
<P/>
In the &shortlex; ordering, shorter words come before longer ones,
and,  for words  of  equal length, the  lexicographically smaller word
comes   first, using the   ordering   of the alphabet.
The   &wtlex;  ordering is similar,   but
instead of  using the length  of the word  as the first criterion, the
total weight of the word  is used; this  is defined as  the sum of the
weights of   the generators  in  the word.   
So &shortlex; is the special case of &wtlex; in which all generators 
have the same nonzero weight.
<P/>
The &recursive; ordering is  the special case  of &wreathprod;
in which the levels of the <M>ng</M> generators are 
<M>1,2,\ldots,ng</M>, in the order of the alphabet.  
We shall not attempt
to give  a complete definition of  these orderings here, but refer the
reader instead to pages  46--50 of <Cite Key="Sims94"/>.  The &recursive;
ordering is the one appropriate  for a power-conjugate presentation of
a  polycyclic  group, but  where   the generators are  ordered  in the
reverse  order from the usual  convention  for polycyclic groups.  
The confluent  presentation will then  be the  same as the power-conjugate
presentation.  
For example,  for the  Heisenberg  group 
<M>\langle x,y,z ~|~ [x,z]=[y,z]=1,  [y,x]=z \rangle</M>, 
a good   ordering  is &recursive;  with    the  order of  generators
<M>[z^{-1},z,y^{-1},y,x^{-1},x]</M>.   
This example is included as Example 3 in 
<Ref Subsect="subsec-example3"/> below.
<P/>
Finally, a method is included for the attribute 
<Ref Func="OrderingOfRewritingSystem"/> which returns the 
appropriate &GAP; ordering on the elements of the word-monoid of &rws;. 
The standard &GAP; ordering functions, such as 
<Ref Func="IsLessThanUnder" BookName="Reference"/>  
can then be used.
<P/>
</Description>
</ManSection>

</Section> 

<!-- ------------------------------------------------------------------- -->

<Section Label="sec-ctrl-param">
<Heading>Control parameters</Heading>

<Index Key="rewriting systems" Subkey="control parameters"></Index> 

<ManSection>
   <InfoClass Name="InfoRWS"  /> 
<Description>
This `Info' variable can be set to 0,1,2 or 3
to control the level of diagnostic output.
<P/>
The Knuth-Bendix procedure is unusually sensitive to the settings of a
number of parameters  that control its  operation. In some examples, a
small change  in   one of  these  parameters can  mean the  difference
between  obtaining a confluent  rewriting system fairly quickly on the
one hand, and  the  procedure running  on until it  uses all available
memory on the other hand.
<P/>
Unfortunately, it is   almost  impossible to  give even  very  general
guidelines   on these   settings,  although the    &wreathprod;
orderings appear to  be  more sensitive  than the &shortlex;   and
&wtlex; orderings.  The user  can  only acquire a  feeling for the
influence of these parameters by  experimentation on a large number of
examples.
<P/>
The control  parameters are defined  by the user  by setting values of
certain fields of the <E>options record</E> of a rewriting system.
<P/>
</Description>
</ManSection>

<ManSection>
   <Func Name="OptionsRecordOfKBMAGRewritingSystem" 
     Arg = "rws" /> 
<Description>
Returns the options record <C>OR</C> of the rewriting system &rws;. 
The fields of <C>OR</C> listed below can be set by the user. 
Be careful to spell them correctly, because otherwise they will 
have no effect!
<List>
<Item>
<C>OR.maxeqns</C><Br/>
    A positive integer specifying  the maximum number of rewriting
    rules allowed in &rws;.  The  default is <M>32767</M>. 
    If this number is exceeded, then <Ref Func="KnuthBendix"/>  
    or <Ref Func="AutomaticStructure"/>  will abort.
</Item>
<Item>
<C>OR.tidyint</C><Br/>
      A positive integer, <M>100</M> by default.  During the  Knuth-Bendix
      procedure, the search for overlaps is interrupted periodically
      to tidy up the existing system  by removing and/or simplifying
      rewriting rules  that have become  redundant. 
    This  tidying is done after finding <C>OR.tidyint</C> rules 
    since the last tidying.
</Item>
<Item>
<C>OR.confnum</C><Br/>
      A  positive integer, <M>500</M> by  default.  If <C>OR.confnum</C>
      overlaps are processed  in  the Knuth-Bendix procedure  but no
      new rules  are  found, then  a  fast test  for confluence   is
      carried out. This saves a lot of time  if the system really is
      confluent, but usually wastes time if it is not.
</Item>
<Item>
<C>OR.maxstoredlen</C><Br/>
      This is a list of  two   positive integers, <C>maxlhs</C>  and
      <C>maxrhs</C>; the  default is that both  are infinite.  Only those
      rewriting rules for  which the  left hand  side has  length at
      most   <C>maxlhs</C>  and the right hand    side has length at most
      <C>maxrhs</C> are stored;  longer   rules are  discarded.  In some
      examples it  is essential to   impose such limits in order  to
      obtain  a  confluent  rewriting   system. Of  course, if   the
      Knuth-Bendix procedure  halts with  such limits imposed,  then
      the    resulting system need   not be  confluent. 
      However, the confluence can  then be  tested be  re-running 
      <Ref Func="KnuthBendix"/> with the limits removed.  
      (To remove the  limits, unbind the field.)
</Item>
<Item>
<C>OR.maxoverlaplen</C><Br/>
      This  is a positive integer, which  is  infinite by default 
      (when not set). Only those overlaps of total length
      <C>OR.maxoverlaplen</C>  are processed. 
      Similar remarks apply to those for <C>OR.maxstoredlen</C>.
</Item>
<Item>
<C>OR.sorteqns</C><Br/>
      This should be <C>true</C> or <C>false</C>, 
      and <C>false</C>  is the default.  When it is  <C>true</C>, 
      the rewriting  rules  are output  in order   of
      increasing length  of left  hand  side.  (The  default is that
      they are output in the order that they were found.) 
</Item>
<Item>
<C>OR.maxoplen</C><Br/>
      This is an  integer, which is  infinite  by default (when not set).  
      When it is set, the rewriting rules are output in order
      of increasing length of left hand side (as if <C>OR.sorteqns</C>
      were <C>true</C>), and only  those  rules having  left hand sides  of
      length up to <C>OR.maxoplen</C> are output at all.  
      Again, similar remarks apply to those for <C>OR.maxstoredlen</C>.
</Item>
<Item>
<C>OR.maxreducelen</C><Br/>
      A positive integer, <M>32767</M> by default.  This is  the  maximum
      length that a word is   allowed to have during the   reduction
      process.  It is  only likely to  be   exceeded when using  the
      &wreathprod; or &recursive; ordering.
</Item>
<Item>
<C>OR.maxstates</C>, <C>OR.maxwdiffs</C><Br/>
      These are positive integers, controlling the maximum number of
      states of the word-reduction  automaton used by 
      <Ref Func="KnuthBendix"/>,   and the
      maximum  number   of  word-differences allowed   when  running
      <Ref Func="AutomaticStructure"/>,  respectively. 
      These numbers are normally increased
      automatically   when required, so it   unusual to  want to set
      these  flags. They can   be set when  either  it is desired to
      limit these parameters   (and  prevent them   being  increased
      automatically), or (as   occasionally happens), the number  of
      word-differences increases too rapidly for the program to cope
      -   when this happens, the  run  is usually  doomed to failure
      anyway.
</Item>
</List>
<P/>
</Description>
</ManSection>

</Section> 

<!-- ------------------------------------------------------------------- -->

<Section Label="sec-KB">
<Heading>The Knuth-Bendix program</Heading>

<Index Key="Knuth-Bendix program"> Knuth-Bendix program</Index> 

<ManSection>
   <Oper Name="KnuthBendix" 
     Arg = "rws" />
   <Meth Name="MakeConfluent" 
     Arg = "rws" /> 
<Description>
These two functions do the same thing, namely to
run the external Knuth-Bendix program  on the rewriting system  &rws;.
<Ref Func="KnuthBendix"/> returns  <C>true</C> if it finds a confluent rewriting 
system  and otherwise <C>false</C>. 
In either case,  if it halts  normally, then it  will update the list
of the rewriting rules of &rws;, and also store a  finite state automaton 
<C>ReductionAutomaton(rws)</C> that can be  used for  word reduction,  
and  the counting and enumeration of irreducible words.
<P/>
All control parameters (as defined in the preceding section) should be
set  before calling <Ref Func="KnuthBendix"/>.  
<Ref Func="KnuthBendix"/>   will halt either when it
finds a finite confluent system of rewriting rules, or when one of the
control parameters (such as <C>OR.maxeqns</C>) requires it to stop.  
The program can also  be made to halt and  output manually at any time 
by hitting the interrupt key (normally `ctrl-C') once.
(Hitting it twice has unpredictable consequences, since  &GAP;    
may intercept the signal.)
<P/> 
A method is installed to make the library operation <C>MakeConfluent</C> 
run the <C>KnuthBendix</C> operation. 
<P/>      
If <Ref Func="KnuthBendix"/>  halts without finding a confluent system, 
but still manages to output the current system and update &rws;, 
then it is possible to use the  resulting   rewriting system  
to  reduce  words,  and  count  and enumerate   the irreducible words; 
it  cannot   be guaranteed that the irreducible words are all in normal form, however. It is also possible to re-run <Ref Func="KnuthBendix"/>   on the current system,  usually after altering some of the control parameters. 
In fact, in some more difficult examples, this
seems to be the only means of finding a finite confluent system.
<P/>
</Description>
</ManSection>

<ManSection>
   <Func Name="ReductionAutomaton" 
     Arg = "rws"  /> 
<Description>
Returns the reduction automaton of &rws;. 
Only expert users will wish to see this explicitly.  
See the section on finite state automata below for general
information on functions for manipulating automata.
<P/>
</Description>
</ManSection>

</Section>

<!-- ------------------------------------------------------------------- -->

<Section Label="sec-auto-gps">
<Heading>The automatic groups program</Heading>

<Index Key="automatic groups program"> automatic groups program</Index> 

<ManSection>
   <Func Name="AutomaticStructure" 
     Arg = "rws [,large filestore diff1]"  /> 
<Description>
This function runs the  external automatic groups  program  
on  the rewriting system &rws;.  
It returns <C>true</C> if successful and <C>false</C> otherwise. 
If  successful, it stores three finite state automata
<C>FirstWordDifferenceAutomaton(rws)</C>, 
<C>SecondWordDifferenceAutomaton(rws)</C> 
and <C>WordAcceptor(rws)</C>: see <Ref Func="WordAcceptor"/> below. 
The  first two  of  these  are used for word-reduction, 
and the third for counting and enumeration of irreducible words 
(i.e. words in normal form).
<P/>
The three optional parameters to <Ref Func="AutomaticStructure"/>  
are all boolean, and <C>false</C> by  default.  
Setting  <C>large</C> to be <C>true</C> results in   some of  the control
parameters (such as  <C>maxeqns</C>  and <C>tidyint</C>) being   set
larger than they would be   otherwise. 
This is necessary for  examples that require a large amount of space. 
Setting <C>filestore</C> to be <C>true</C> results
in more  use being made  of temporary files  than would  be otherwise.
This makes the program run slower, but it may be  necessary if you are
short of  core memory. 
Setting <C>diff1</C> to  be <C>true</C> is a more technical
option, which is  explained more fully   in the documentation for  the
stand-alone &KBMAG; package. It is not  usually necessary or helpful,
but it enables  one or two  examples to complete  that would otherwise
run out of space.
<P/>
The &ordering; field of &rws; will usually be set to &shortlex;
for <Ref Func="AutomaticStructure"/>  to be applicable.
However, it is now possible to use some procedures written by Sarah Rees
that work when the ordering is &wtlex; or &wreathprod;. In the latter
case, each generator must have the same level as its inverse.
<P/>
The only control parameters for &rws; that
are likely to be relevant are <C>maxeqns</C> and <C>maxwdiffs</C>.
<P/>
</Description>
</ManSection>

<ManSection>
   <Func Name="WordAcceptor" 
     Arg = "rws" /> 
   <Func Name="FirstWordDifferenceAutomaton" 
     Arg = "rws" /> 
   <Func Name="SecondWordDifferenceAutomaton" 
     Arg = "rws" /> 
   <Func Name="GeneralMultiplier" 
     Arg = "rws" /> 
<Description>
These functions return, respectively, the word acceptor, the first and
second word-difference automata, and the general multiplier automaton of &rws;. 
They can only be called after a successful call of
<C>AutomaticStructure(rws)</C>. 
All except the word acceptor are <M>2</M>-variable
automata that read pairs of words in the alphabet of &rws;.
Note that the general multiplier has
its states labeled, where the different labels represent the accepting
states for the different letters in the alphabet of &rws;.
<P/>
</Description>
</ManSection>

</Section> 

<!-- ------------------------------------------------------------------- -->

<Section Label="sec-word-red">
<Heading>Word reduction</Heading>

<ManSection>
   <Oper Name="IsReducedWord" 
     Arg = "rws w"  /> 
   <Meth Name="IsReducedForm" 
     Arg = "rws w"  /> 
<Description>
These two functions do the same thing, namely to
test  whether the word <M>w</M> in  the generators of  the freestructure
<C>FreeStructure(rws)</C>  of the rewriting system system
&rws; is reduced or not, and return <C>true</C> or <C>false</C>.
<P/>
<Ref Func="IsReducedWord"/>  can only be used after <Ref Func="KnuthBendix"/> 
or <Ref Func="AutomaticStructure"/>  has been run successfully on &rws;. 
In the former case, if <C>KnuthBendix</C>  halted without
a  confluent set of rules, then  irreducible words are not necessarily
in  normal form (but  reducible  words are  definitely  not in  normal form).    
If  <C>KnuthBendix</C>  completes with a  confluent rewriting system or 
<C>AutomaticStructure</C>  completes  successfully, then  it   is guaranteed that all irreducible words are in normal form.
<P/>
</Description>
</ManSection>

<ManSection>
   <Oper Name="ReducedWord" 
     Arg = "rws w"  /> 
   <Meth Name="ReducedForm" 
     Arg = "rws w"  /> 
<Description>
Reduce the word  <M>w</M> in the generators of the freestructure
<C>FreeStructure(rws)</C>  of the rewriting system  &rws;
(or, equivalently, in the    generators  of the underlying   group  of &rws;), 
and return the result.
<P/>
<Ref Func="ReducedForm"/>  can only be used after <Ref Func="KnuthBendix"/>  or <Ref Func="AutomaticStructure"/> 
has been run successfully on &rws;.  
In the former case, if  <C>KnuthBendix</C>  halted without  a
confluent  set of  rules, then the   irreducible word returned is  not
necessarily in  normal   form.  
If <C>KnuthBendix</C>   completes   with  a confluent
rewriting  system or  <C>AutomaticStructure</C> completes successfully, 
then it  is guaranteed that all irreducible words are in normal form.
<P/>
</Description>
</ManSection>

</Section> 

<!-- ------------------------------------------------------------------- -->

<Section Label="sec-enum-irre">
<Heading>Counting and enumerating irreducible words</Heading>

<ManSection>
   <Meth Name="Size" 
     Arg = "rws" /> 
<Description>
Returns the number of irreducible words in the rewriting system &rws;.
<P/>
<Ref Func="Size"/> can only be  used  after <Ref Func="KnuthBendix"/> or 
<Ref Func="AutomaticStructure"/>  has been run successfully  on &rws;. 
In  the former case, if  <C>KnuthBendix</C>  halted without a
confluent  set of rules, then the  number of  irreducible words may be
greater than the number of words in normal form (which is equal to the
order  of the underlying group, monoid or semigroup <M>G</M>  of  &rws;).  
If <C>KnuthBendix</C>   completes with a confluent rewriting system  
or <C>AutomaticStructure</C>  completes successfully, 
then it is  guaranteed that
<Ref Func="Size"/>  will  return the correct order of <M>G</M>.
<P/>
</Description>
</ManSection>

<ManSection>
   <Meth Name="Order" 
     Arg = "rws w" /> 
<Description>
The order  of the element <M>w</M> of the free structure 
<C>FreeStructure(rws)</C>  of &rws; 
as an element of the group or monoid from which &rws; was defined.
<P/>
<Ref Func="Order"/> can only be  used  after <Ref Func="KnuthBendix"/> or
<Ref Func="AutomaticStructure"/>  has been run successfully  on &rws;.
It is not guaranteed to terminate in the case of infinite order, but it
usually seems to do so in practice!
<P/>
</Description>
</ManSection>

<ManSection>
   <Oper Name="EnumerateReducedWords" 
     Arg = "rws min max"  /> 
<Description>
Enumerate  all  irreducible words in  the  rewriting system &rws; that
have   lengths between <C>min</C> and <C>max</C> (inclusive), 
which should be non-negative integers.    
The result is returned  as  a list of words.
The enumeration is by depth-first search  of a finite state automaton,
and so the words in the  list returned  are ordered lexicographically
(not by &shortlex;).
<P/>
<Ref Func="EnumerateReducedWords"/>  can only be used after 
<Ref Func="KnuthBendix"/> 
or <Ref Func="AutomaticStructure"/>  has been run successfully on &rws;. 
In  the former case,  if <C>KnuthBendix</C>  halted  without a
confluent set of  rules, then not all irreducible   words in the  list
returned will necessarily be in normal form.  
If <C>KnuthBendix</C>  completes with a
confluent rewriting  system or <C>AutomaticStructure</C>  
completes successfully, then
it is guaranteed that all words in the list will be in normal form.
<P/>
</Description>
</ManSection>

<ManSection>
   <Func Name="GrowthFunction" 
     Arg = "rws"  /> 
<Description>
Returns the growth function of the set of irreducible words in the
rewriting system &rws;. This is a rational function, of which
the coefficient of <M>x^n</M> in its Taylor expansion is equal to the number of
irreducible words of length <M>n</M>.
<P/>
If the coefficients in this rational function are larger than about <M>16000</M> 
then strange error messages will appear and <C>fail</C> will be returned.
<P/>
<Ref Func="GrowthFunction"/>  can only be used after <Ref Func="KnuthBendix"/> 
or <Ref Func="AutomaticStructure"/>  has been run successfully on &rws;. 
In  the former case,  if <C>KnuthBendix</C>  halted  without a
confluent set of  rules, then not all irreducible   words in the  list
returned will necessarily be in normal form.  
If <C>KnuthBendix</C>  completes with a
confluent rewriting  system or <C>AutomaticStructure</C>  
completes successfully, then it is guaranteed that all words in the list 
will be in normal form.
<P/>
</Description>
</ManSection>

</Section> 

<!-- ------------------------------------------------------------------- -->

<Section Label="sec-examples">
<Heading>Rewriting System Examples</Heading>

<Index Key="rewriting systems" Subkey="examples"></Index> 
<Index Key="examples of rewriting systems"></Index>

Here are five examples to illustrate the operations described above. 

<Subsection Label="subsec-example1">
<Heading>Example 1</Heading>

<Index Key="alternating group A4 example"></Index> 
We start with a easy example - the alternating group <M>A_4</M>.
<P/>
<Example>
<![CDATA[
gap> F := FreeGroup( "a", "b" );;
gap> a := F.1;;  b := F.2;;
gap> G := F/[a^2, b^3, (a*b)^3];;
gap> R := KBMAGRewritingSystem( G );
rec(
       isRWS := true,
  generatorOrder := [_g1,_g2,_g3],
    inverses := [_g1,_g3,_g2],
    ordering := "shortlex",
   equations := [
     [_g2^2,_g3],
     [_g1*_g2*_g1,_g3*_g1*_g3]
   ]
)
]]>
</Example>
Notice that monoid generators, printed as <C>_g1, _g2, _g3</C>, are used
internally. These correspond to the group generators <M>a, b, b^{-1}</M>.
<P/>
<Example>
<![CDATA[
gap> KnuthBendix( R );
true
gap> R;
rec(
       isRWS := true,
 isConfluent := true,
  generatorOrder := [_g1,_g2,_g3],
    inverses := [_g1,_g3,_g2],
    ordering := "shortlex",
   equations := [
     [_g1^2,IdWord],
     [_g2*_g3,IdWord],
     [_g3*_g2,IdWord],
     [_g2^2,_g3],
     [_g3*_g1*_g3,_g1*_g2*_g1],
     [_g3^2,_g2],
     [_g2*_g1*_g2,_g1*_g3*_g1],
     [_g3*_g1*_g2*_g1,_g2*_g1*_g3],
     [_g1*_g2*_g1*_g3,_g3*_g1*_g2],
     [_g2*_g1*_g3*_g1,_g3*_g1*_g2],
     [_g1*_g3*_g1*_g2,_g2*_g1*_g3]
   ]
)
]]>
</Example>
The <E>equations</E> field of <M>R</M> is now a complete system 
of rewriting rules. 
<P/>
<Example>
<![CDATA[
gap> Size( R );
12
gap> EnumerateReducedWords( R, 0, 12 );
[ <identity ...>, a, a*b, a*b*a, a*b^-1, a*b^-1*a, b, b*a, b*a*b^-1, b^-1, 
  b^-1*a, b^-1*a*b ]
]]>
</Example>
We have enumerated all of the elements of the group - note that they
are returned as words in the free group <M>F</M>.
</Subsection>


<Subsection Label="subsec-example2">
<Heading>Example 2</Heading>

<Index Key="Fibonacci group F(2,5) example"></Index>
We construct the Fibonacci group <M>F(2,5)</M>, 
defined by a semigroup rather than a group presentation. 
Interestingly these define the same structure (although
they would not do so for <M>F(2,r)</M> with <M>r</M> even).
<P/>
<Example>
<![CDATA[
gap> S := FreeSemigroup( 5 );; 
gap> a := S.1;;  b := S.2;;  c := S.3;;  d := S.4;;  e := S.5;;
gap> Q := S/[ [a*b,c], [b*c,d], [c*d,e], [d*e,a], [e*a,b] ];
<fp semigroup on the generators [ s1, s2, s3, s4, s5 ]>
gap> R := KBMAGRewritingSystem( Q ); 
rec(
       isRWS := true,
      silent := true,
  generatorOrder := [_s1,_s2,_s3,_s4,_s5],
    inverses := [,,,,],
    ordering := "shortlex",
   equations := [
     [_s1*_s2,_s3],
     [_s2*_s3,_s4],
     [_s3*_s4,_s5],
     [_s4*_s5,_s1],
     [_s5*_s1,_s2]
   ]
)
gap> KnuthBendix( R );
true
gap> Size( R );
11
gap> EnumerateReducedWords( R, 0, 4 );
[ s1, s1^2, s1^2*s4, s1*s3, s1*s4, s2, s2^2, s2*s5, s3, s4, s5 ]
]]>
</Example>
Let's do the same thing using the &recursive; ordering.
<P/>
<Example>
<![CDATA[
gap> SetOrderingOfKBMAGRewritingSystem( R, "recursive" );
gap> KnuthBendix( R );
true
gap> Size( R ); 
11
gap> EnumerateReducedWords( R, 0, 11 );
[ s1, s1^2, s1^3, s1^4, s1^5, s1^6, s1^7, s1^8, s1^9, s1^10, s1^11 ]
]]>
</Example>

</Subsection>


<Subsection Label="subsec-example3">
<Heading>Example 3</Heading>

<Index Key="Heisenberg group example"></Index>
The Heisenberg group is the free <M>2</M>-generator nilpotent 
group of class <M>2</M>.   
For <C>KnuthBendix</C> to complete, we need to use the &recursive;
ordering, and reverse our initial order of generators. (Alternatively,
we  could avoid this reversal, by using a &wreathprod; ordering, and
setting the levels of the generators to be <M>6,5,4,3,2,1</M>.)
<P/>
<Example>
<![CDATA[
gap> F := FreeGroup("x","y","z");;
gap> x := F.1;;  y := F.2;;  z := F.3;;
gap> G := F/[Comm(y,x)*z^-1, Comm(z,x), Comm(z,y)];;
gap> R := KBMAGRewritingSystem( G );
rec(
       isRWS := true,
  generatorOrder := [_g1,_g2,_g3,_g4,_g5,_g6],
    inverses := [_g2,_g1,_g4,_g3,_g6,_g5],
    ordering := "shortlex",
   equations := [
     [_g4*_g2*_g3,_g5*_g2],
     [_g6*_g2,_g2*_g6],
     [_g6*_g4,_g4*_g6]
   ]
)
gap> SetOrderingOfKBMAGRewritingSystem( R, "recursive" );
gap> ReorderAlphabetOfKBMAGRewritingSystem( R, (1,6)(2,5)(3,4) );
gap> R;
rec(
       isRWS := true,
  generatorOrder := [_g6,_g5,_g4,_g3,_g2,_g1],
    inverses := [_g5,_g6,_g3,_g4,_g1,_g2],
    ordering := "recursive",
   equations := [
     [_g4*_g2*_g3,_g5*_g2],
     [_g6*_g2,_g2*_g6],
     [_g6*_g4,_g4*_g6]
   ]
)
gap> SetInfoLevel( InfoRWS, 1 );
gap> KnuthBendix( R );
#I  Calling external Knuth-Bendix program.
#System is confluent.
#Halting with 18 equations.
#I  External Knuth-Bendix program complete.
#I  System computed is confluent.
true
gap> R;
rec(
       isRWS := true,
 isConfluent := true,
  generatorOrder := [_g6,_g5,_g4,_g3,_g2,_g1],
    inverses := [_g5,_g6,_g3,_g4,_g1,_g2],
    ordering := "recursive",
   equations := [
     [_g6*_g5,IdWord],
     [_g5*_g6,IdWord],
     [_g4*_g3,IdWord],
     [_g3*_g4,IdWord],
     [_g2*_g1,IdWord],
     [_g1*_g2,IdWord],
     [_g6*_g2,_g2*_g6],
     [_g6*_g4,_g4*_g6],
     [_g4*_g2,_g2*_g4*_g5],
     [_g5*_g2,_g2*_g5],
     [_g6*_g1,_g1*_g6],
     [_g5*_g4,_g4*_g5],
     [_g6*_g3,_g3*_g6],
     [_g3*_g1,_g1*_g3*_g5],
     [_g4*_g1,_g1*_g4*_g6],
     [_g3*_g2,_g2*_g3*_g6],
     [_g5*_g1,_g1*_g5],
     [_g5*_g3,_g3*_g5]
   ]
)
gap> Size( R );
infinity
gap> IsReducedWord( R, z*y*x );
false
gap> ReducedForm( R, z*y*x );
x*y*z^2
gap> IsReducedForm( R, x*y*z^2 );
true
]]>
</Example>

</Subsection>


<Subsection Label="subsec-example4">
<Heading>Example 4</Heading>

This is an  example of the use  of the Knuth-Bendix algorithm to prove
the nilpotence of a  finitely presented group.  
(The method is due  to Sims, and is described in Chapter 11.8 of 
<Cite Key="Sims94"/>.) 
This example is of intermediate difficulty, and demonstrates the necessity 
of using the <C>maxstoredlen</C> control parameter.
<P/>
The group  is   
<Display>  
\langle a,b ~|~ [b,a,b], [b,a,a,a,a],  [b,a,a,a,b,a,a] \rangle 
</Display> 
with left-normed commutators.
The first step  in the  method is to   check that there is  a  maximal
nilpotent quotient of the group, for which we  could use, for example,
the &GAP; <Ref Func="NilpotentQuotient" BookName="nq"/> command, 
from   the  package <Package>nq</Package>.  
We find that  there is a  maximal  such quotient, and it  has
class <M>7</M>, and the  layers going down  the lower central series have the
abelian structures <M>[0,0], [0], [0], [0], [0], [2], [2]</M>.
<P/>
By  using the  stand-alone  `C' nilpotent quotient program, it is
possible to  find  a  power-commutator  presentation of  this  maximal
quotient.  We now construct  a new presentation of  the same group, by
introducing  the  generators  in  this  power-commutator presentation,
together with  their definitions as powers  or commutators  of earlier
generators.  It is this new presentation that  we use as input for the
Knuth-Bendix program.  Again we  use the &recursive; ordering, but  this
time we will  be careful to  introduce the  generators  in the correct
order in the first place!
<P/>
<Example>
<![CDATA[
gap> F := FreeGroup( "h", "g", "f", "e", "d", "c", "b", "a" );;
gap> h := F.1;;  g := F.2;;  f := F.3;;  e := F.4;; 
gap> d := F.5;;  c := F.6;;  b := F.7;;  a := F.8;;
gap> G := F/[Comm(b,a)*c^-1, Comm(c,a)*d^-1, Comm(d,a)*e^-1, Comm(e,b)*f^-1, 
>            Comm(f,a)*g^-1, Comm(g,b)*h^-1, Comm(g,a), Comm(c,b), Comm(e,a)];;
gap> R:=KBMAGRewritingSystem(G);
rec(
       isRWS := true,
  generatorOrder := [_g1,_g2,_g3,_g4,_g5,_g6,_g7,_g8,_g9,_g10,
               _g11,_g12,_g13,_g14,_g15,_g16],
    inverses := [_g2,_g1,_g4,_g3,_g6,_g5,_g8,_g7,_g10,_g9,
               _g12,_g11,_g14,_g13,_g16,_g15],
    ordering := "shortlex",
   equations := [
     [_g14*_g16*_g13,_g11*_g16],
     [_g12*_g16*_g11,_g9*_g16],
     [_g10*_g16*_g9,_g7*_g16],
     [_g8*_g14*_g7,_g5*_g14],
     [_g6*_g16*_g5,_g3*_g16],
     [_g4*_g14*_g3,_g1*_g14],
     [_g4*_g16,_g16*_g4],
     [_g12*_g14,_g14*_g12],
     [_g8*_g16,_g16*_g8]
   ]
)
]]>
</Example>
A little experimentation reveals that this example works  best  when
only those equations with left and right hand sides of lengths at most
<M>10</M> are kept.
<P/>
<Example>
<![CDATA[
gap> SetOrderingOfKBMAGRewritingSystem( R, "recursive" );
gap> O := OptionsRecordOfKBMAGRewritingSystem( R );
gap> O.maxstoredlen := [10,10];;
gap> SetInfoLevel( InfoRWS, 2 );
gap> KnuthBendix( R );
  # 60 eqns; total len: lhs, rhs = 129, 143; 25 states; 0 secs.
  # 68 eqns; total len: lhs, rhs = 364, 326; 28 states; 0 secs.
  # 77 eqns; total len: lhs, rhs = 918, 486; 45 states; 0 secs.
  # 91 eqns; total len: lhs, rhs = 728, 683; 58 states; 0 secs.
  # 102 eqns; total len: lhs, rhs = 1385, 1479; 89 states; 0 secs.
  . . . .
  # 310 eqns; total len: lhs, rhs = 4095, 4313; 489 states; 1 secs.
  # 200 eqns; total len: lhs, rhs = 2214, 2433; 292 states; 1 secs.
  # 194 eqns; total len: lhs, rhs = 835, 922; 204 states; 1 secs.
  # 157 eqns; total len: lhs, rhs = 702, 723; 126 states; 1 secs.
  # 151 eqns; total len: lhs, rhs = 553, 444; 107 states; 1 secs.
  # 101 eqns; total len: lhs, rhs = 204, 236; 19 states; 1 secs.
  #No new eqns for some time - testing for confluence
  #System is not confluent.
  # 172 eqns; total len: lhs, rhs = 616, 473; 156 states; 1 secs.
  # 171 eqns; total len: lhs, rhs = 606, 472; 156 states; 1 secs.
  #No new eqns for some time - testing for confluence
  #System is not confluent.
  # 151 eqns; total len: lhs, rhs = 452, 453; 92 states; 1 secs.
  # 151 eqns; total len: lhs, rhs = 452, 453; 92 states; 1 secs.
  #No new eqns for some time - testing for confluence
  #System is not confluent.
  # 101 eqns; total len: lhs, rhs = 200, 239; 15 states; 1 secs.
  # 101 eqns; total len: lhs, rhs = 200, 239; 15 states; 1 secs.
  #No new eqns for some time - testing for confluence
#System is confluent.
#Halting with 101 equations.
WARNING: The monoid defined by the presentation may have changed,
     since equations have been discarded.
     If you re-run, include the original equations.
  #Exit status is 0
#I  External Knuth-Bendix program complete.
#WARNING: Because of the control parameters you set, the system may
# not be confluent. Unbind the parameters and re-run KnuthBendix
# to check!
#I  System computed is NOT confluent.
false
]]>
</Example>
Now it is essential to re-run with the <C>maxstoredlen</C> limit removed
to check that the system really is confluent.
<P/>
<Example>
<![CDATA[
gap> Unbind( O.maxstoredlen );
gap> KnuthBendix( R );
  # 101 eqns; total len: lhs, rhs = 200, 239; 15 states; 0 secs.
  #No new eqns for some time - testing for confluence
#System is confluent.
#Halting with 101 equations.
#Exit status is 0
#I  External Knuth-Bendix program complete.
#I  System computed is confluent.
true
]]>
</Example>
In fact, in this case, we did have a confluent set already.
<P/>
Inspection  of the confluent  set now  reveals it   to be  precisely a
power-commutator presentation  of  a nilpotent  group,  and so we have
proved that the group we started with really is nilpotent.  Of course,
this means also that it is equal to its largest nilpotent quotient, of
which we already know the structure.
</Subsection>


<Subsection Label="subsec-example5">
<Heading>Example 5</Heading>

Our final example illustrates the use of the <C>AutomaticStructure</C> 
command, which runs  the   automatic groups  programs. 
The  group  has  a balanced symmetrical presentation with <M>3</M> generators 
and <M>3</M> relators,  and  was originally proposed  by  Heineken as a  
possible  example of a  finite group with such a presentation. 
In fact, the <Ref Func="AutomaticStructure"/>  command proves
it to be infinite.
<P/>
This  example is of intermediate difficulty,  but there is  no need to
use any special options.  It takes  a few minutes to  run on a
WorkStation. It works better with the optional <E>large</E> parameter of
<C>AutomaticStructure</C>  set to <C>true</C>. 
<P/>
We will not attempt to explain  all of the  output in detail here; the
interested user should  consult the documentation  for the stand-alone
&KBMAG;  package. Roughly speaking,  it  first runs the  Knuth-Bendix
program, which does not halt with a confluent rewriting system, but is
used instead to construct a   word-difference finite state  automaton.
This  in  turn is used  to construct  the word-acceptor and multiplier
automata for the  group.    Sometimes the initial   constructions  are
incorrect, and  part of the  procedure consists in checking  for this,
and making corrections. In fact, in this example, the correct automata
are considerably  smaller than the  ones first constructed.  The final
stage is to run   an axiom-checking program, which  essentially checks
that the  automata  satisfy  the  group relations.  If this  completes
successfully,  then the correctness of   the automata has been proved,
and they can be used for correct word-reduction and enumeration in the
group.
<P/>
<Example>
<![CDATA[
gap> F := FreeGroup( "a", "b", "c" );;
gap> a := F.1;;  b := F.2;;  c := F.3;;
gap> G := F/[Comm(a,Comm(a,b))*c^-1, Comm(b,Comm(b,c))*a^-1,
>            Comm(c,Comm(c,a))*b^-1];;
gap> R := KBMAGRewritingSystem( G );
rec(
       isRWS := true,
     verbose := true,
  generatorOrder := [_g1,_g2,_g3,_g4,_g5,_g6],
    inverses := [_g2,_g1,_g4,_g3,_g6,_g5],
    ordering := "shortlex",
   equations := [
     [_g2*_g4*_g2*_g3*_g1,_g5*_g4*_g2*_g3],
     [_g4*_g6*_g4*_g5*_g3,_g1*_g6*_g4*_g5],
     [_g6*_g2*_g6*_g1*_g5,_g3*_g2*_g6*_g1]
   ]
)
gap> SetInfoLevel( InfoRWS, 1 );
gap> AutomaticStructure( R, true );
#I  Calling external automatic groups program.
#Running Knuth-Bendix Program
 (pathname)/kbprog -mt 20 -hf 100 -cn 0 -wd -me 262144 -t 500 (filename)
#Halting with 42317 equations.
#First word-difference machine with 271 states computed.
#Second word-difference machine with 271 states computed.
#System is confluent, or halting factor condition holds.

#Running program to construct word-acceptor and multiplier automata
 (pathname)/gpmakefsa -l (filename)
#Word-acceptor with 1106 states computed.
#General multiplier with 2428 states computed.
#Validity test on general multiplier succeeded.
#Running program to verify axioms on the automatic structure
 (pathname)/gpaxioms -l (filename)
#General length-2 multiplier with 2820 states computed.
#Checking inverse and short relations.
#Checking relation:  _g2*_g4*_g2*_g3*_g1 = _g5*_g4*_g2*_g3
#Checking relation:  _g4*_g6*_g4*_g5*_g3 = _g1*_g6*_g4*_g5
#Checking relation:  _g6*_g2*_g6*_g1*_g5 = _g3*_g2*_g6*_g1
#Axiom checking succeeded.
#I  Computation was successful - automatic structure computed.
#Minimal reducible word acceptor with 1058 states computed.
#Minimal Knuth-Bendix equation fsa with 1891 states computed.
#Correct diff1 fsa with 271 states computed.
#Correct diff2 fsa with 271 states computed.
true

gap> Size( R );
infinity
gap> Order( R, a );
infinity
gap> Order( R, Comm(a,b) );
infinity
]]>
</Example>
</Subsection>

</Section> 

</Chapter>