  
  [1X11 FR implementation details[0X
  
  [5XFR[0m creates new categories for the various objects considered in the package.
  The  first  category is [10XFRObject[0m; all objects are in this category, and have
  an [10XAlphabet[0m method.
  
  There  are  two categories below: [10XFRMachine[0m and [10XFRElement[0m. An [10XFRMachine[0m must
  have  a [10XStateSet[0m, and methods for [10XOutput[0m and a [10XTransition[0m. An [10XFRElement[0m must
  have  an  underlying [10XFRMachine[0m and [10XInitialState[0m, and [10XOutput[0m and a [10XTransition[0m
  that use the initial state.
  
  A  self-similar  group is simply a collections category of FR elements which
  is also a group.
  
  
  [1X11.1 The family of FR objects[0X
  
  All FR objects have an associated [2XAlphabetOfFRObject[0m ([14X11.1-3[0m).
  
  [1X11.1-1 FRMFamily[0m
  
  [2X> FRMFamily( [0X[3Xobj[0X[2X ) ________________________________________________[0Xoperation
  [6XReturns:[0X  the family of FR machines on alphabet [3Xobj[0m.
  
  The  family  of  an FR object is the arity of the tree on which elements cat
  act; in other words, there is one family for each alphabet.
  
  [1X11.1-2 FREFamily[0m
  
  [2X> FREFamily( [0X[3Xobj[0X[2X ) ________________________________________________[0Xoperation
  [6XReturns:[0X  the family of FR elements on alphabet [3Xobj[0m.
  
  The  family  of  an FR object is the arity of the tree on which elements cat
  act; in other words, there is one family for each alphabet.
  
  The argument may be an FR machine, an alphabet, or a family of FR machines.
  
  [1X11.1-3 AlphabetOfFRObject[0m
  
  [2X> AlphabetOfFRObject( [0X[3Xobj[0X[2X ) _______________________________________[0Xoperation
  [6XReturns:[0X  the alphabet associated with [3Xobj[0m.
  
  This  command  applies  to  the  family  of  any FR object, or to the object
  themselves. Alphabets are returned as lists, and in pratice are generally of
  the form [10X[1..n][0m.
  
  [1X11.1-4 AsPermutation[0m
  
  [2X> AsPermutation( [0X[3Xo[0X[2X ) _________________________________________________[0Xmethod
  
  This  method  takes  as argument an FR object [3Xo[0m: machine, element, or group,
  and  produces  an  equivalent  object  whose  outputs  are  permutations. In
  particular,  it  converts  Mealy  machines from domain representation to int
  representation.
  
  If this is not possible, the method returns [9Xfail[0m.
  
  [1X11.1-5 AsTransformation[0m
  
  [2X> AsTransformation( [0X[3Xo[0X[2X ) ______________________________________________[0Xmethod
  
  This  method  takes  as argument an FR object [3Xo[0m: machine, element, or group,
  and  produces  an  equivalent  object  whose outputs are transformations. In
  particular,  it  converts  Mealy  machines from domain representation to int
  representation.
  
  Since  transformations  can  never  be  inverted  by [5XGAP[0m, even when they are
  invertible, this function returns a monoid when applied to a full SC group.
  
  
  [1X11.2 Filters for [10XFRObject[1Xs[0X
  
  [1X11.2-1 IsGroupFRMachine[0m
  
  [2X> IsGroupFRMachine( [0X[3Xobj[0X[2X ) __________________________________________[0Xproperty
  [2X> IsMonoidFRMachine( [0X[3Xobj[0X[2X ) _________________________________________[0Xproperty
  [2X> IsSemigroupFRMachine( [0X[3Xobj[0X[2X ) ______________________________________[0Xproperty
  [6XReturns:[0X  [9Xtrue[0m   if   [3Xobj[0m  is  an  FR  machine  whose  stateset  is  a  free
            group/monoid/semigroup.
  
  This  function  is  the  acceptor  for those functionally recursive machines
  whose  stateset (accessible via [2XStateSet[0m ([14X3.4-1[0m)) is a free group, monoid or
  semigroup.   The   generating   set   of  its  stateset  is  accessible  via
  [2XGeneratorsOfFRMachine[0m ([14X3.4-2[0m).
  
  [1X11.2-2 IsFRMachineStrRep[0m
  
  [2X> IsFRMachineStrRep( [0X[3Xobj[0X[2X ) ___________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is a standard (group,monoid,semigroup) FR machine.
  
  There is a free object [10Xfree[0m, of rank N, a list [10Xtransitions[0m of length N, each
  entry  a  list,  indexed  by  the  alphabet, of elements of [10Xfree[0m, and a list
  [10Xoutput[0m of length [10XN[0m of transformations or permutations of the alphabet.
  
  [1X11.2-3 IsMealyMachine[0m
  
  [2X> IsMealyMachine( [0X[3Xobj[0X[2X ) ______________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is a Mealy machine.
  
  This  function  is  the  acceptor  for  the  [13XMealy machine[0m subcategory of [13XFR
  machine[0ms.
  
  [1X11.2-4 IsMealyElement[0m
  
  [2X> IsMealyElement( [0X[3Xobj[0X[2X ) ______________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is a Mealy element.
  
  This  function  is  the  acceptor  for  the  [13XMealy element[0m subcategory of [13XFR
  element[0ms.
  
  [1X11.2-5 IsMealyMachineIntRep[0m
  
  [2X> IsMealyMachineIntRep( [0X[3Xobj[0X[2X ) ________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is a Mealy machine in integer representation.
  
  A   Mealy   machine  in  [13Xinteger[0m  representation  has  components  [10Xnrstates[0m,
  [10Xtransitions[0m, [10Xoutput[0m and optionally [10Xinitial[0m.
  
  Its   stateset   is   [10X[1..nrstates][0m,   its  transitions  is  a  matrix  with
  [10Xtransitions[s][x][0m  the transition from state [10Xs[0m with input [10Xx[0m, its output is a
  list  of  transformations  or  permutations,  and  its  initial  state is an
  integer.
  
  [1X11.2-6 IsMealyMachineDomainRep[0m
  
  [2X> IsMealyMachineDomainRep( [0X[3Xobj[0X[2X ) _____________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is a Mealy machine in domain representation.
  
  A Mealy machine in [13Xdomain[0m representation has components [10Xstates[0m, [10Xtransitions[0m,
  [10Xoutput[0m and optionally [10Xinitial[0m.
  
  Its  states is a domain, its transitions is a function with [10Xtransitions(s,x)[0m
  the  transition  from  state  [10Xs[0m  with input [10Xx[0m, its output is a function with
  [10Xoutput(s,x)[0m  the output from input [10Xx[0m in state [10Xs[0m, and its initial state is an
  elemnent of [10Xstates[0m.
  
  [1X11.2-7 IsVectorFRMachineRep[0m
  
  [2X> IsVectorFRMachineRep( [0X[3Xobj[0X[2X ) ________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is a vector machine
  
  A   [13Xvector   machine[0m   is   a  representation  of  a  linear  machine  by  a
  finite-dimensional  vector  space  (implicit in the structure), a transition
  tensor  (represented  as  a  matrix  of  matrices),  and  an  output  vector
  (represented as a list).
  
  [1X11.2-8 IsAlgebraFRMachineRep[0m
  
  [2X> IsAlgebraFRMachineRep( [0X[3Xobj[0X[2X ) _______________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is an algebra machine
  
  An  [13Xalgebra  machine[0m  is  a representation of a linear machine by a finitely
  generated  free algebra, a tensor of transitions, indexed by generator index
  and  two  alphabet  indices,  and  an  output vector, indexed by a generator
  index.
  
  The  transition  tensor's  last  two entries are the 0 and 1 matrix over the
  free  algebra,  and  the  output  tensor's  last two entries are the 0 and 1
  elements of the left acting domain.
  
  [1X11.2-9 IsLinearFRMachine[0m
  
  [2X> IsLinearFRMachine( [0X[3Xobj[0X[2X ) ___________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is a linear machine.
  
  This  function  is  the  acceptor  for  the [13Xlinear machine[0m subcategory of [13XFR
  machine[0ms.
  
  [1X11.2-10 IsLinearFRElement[0m
  
  [2X> IsLinearFRElement( [0X[3Xobj[0X[2X ) ___________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is a linear element.
  
  This  function  is  the  acceptor  for  the [13Xlinear element[0m subcategory of [13XFR
  element[0ms.
  
  [1X11.2-11 IsFRElement[0m
  
  [2X> IsFRElement( [0X[3Xobj[0X[2X ) _________________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is an FR element.
  
  This  function  is  the  acceptor  for  the  [13Xfunctionally  recursive element[0m
  category.
  
  It  implies that [3Xobj[0m has an underlying FR machine, may act on sequences, and
  has a recursive [2XDecompositionOfFRElement[0m ([14X4.2-5[0m).
  
  [1X11.2-12 IsFRObject[0m
  
  [2X> IsFRObject( [0X[3Xobj[0X[2X ) __________________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is an FR machine or element.
  
  This function is the acceptor for the most general FR category (which splits
  up as [2XIsFRMachine[0m ([14X11.2-13[0m) and [2XIsFRElement[0m ([14X11.2-11[0m)).
  
  It implies that [3Xobj[0m has an attribute [2XAlphabetOfFRObject[0m ([14X11.1-3[0m).
  
  [1X11.2-13 IsFRMachine[0m
  
  [2X> IsFRMachine( [0X[3Xobj[0X[2X ) _________________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is an FR machine.
  
  This  function  is  the  acceptor  for  the  [13Xfunctionally  recursive machine[0m
  category.  It  splits  up as [2XIsGroupFRMachine[0m ([14X11.2-1[0m), [2XIsSemigroupFRMachine[0m
  ([14X11.2-1[0m), [2XIsMonoidFRMachine[0m ([14X11.2-1[0m) and [2XIsMealyMachine[0m ([14X11.2-3[0m)).
  
  It  implies  that [3Xobj[0m has attributes [2XStateSet[0m ([14X3.4-1[0m), [2XGeneratorsOfFRMachine[0m
  ([14X3.4-2[0m),  and [2XWreathRecursion[0m ([14X3.4-5[0m); the last two are usually not used for
  Mealy machines.
  
  [1X11.2-14 IsInvertible[0m
  
  [2X> IsInvertible( [0X[3Xm[0X[2X ) ________________________________________________[0Xproperty
  [6XReturns:[0X  [9Xtrue[0m if [3Xm[0m is an invertible FR machine.
  
  This  function  accepts  invertible  FR machines, i.e. machines [3Xmachine[0m such
  that  (machine,q)  is an invertible transformation of the alphabet for all q
  in the stateset of [3Xmachine[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> m := FRMachine([[[],[]]],[(1,2)]);[0X
    [4X<FR machine with alphabet [ 1 .. 2 ] on Group( [ f1 ] )>[0X
    [4Xgap> IsInvertible(m);[0X
    [4Xtrue[0X
    [4Xgap> m := FRMachine([[[],[]]],[[1,1]]);[0X
    [4X<FR machine with alphabet [ 1 .. 2 ] on Monoid( [ m1 ], ... )>[0X
    [4Xgap> IsInvertible(m);[0X
    [4Xfalse[0X
  [4X------------------------------------------------------------------[0X
  
  [1X11.2-15 IsFRGroup[0m
  
  [2X> IsFRGroup( [0X[3Xobj[0X[2X ) ___________________________________________________[0Xfilter
  [2X> IsFRMonoid( [0X[3Xobj[0X[2X ) __________________________________________________[0Xfilter
  [2X> IsFRSemigroup( [0X[3Xobj[0X[2X ) _______________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is a FR group/monoid/semigroup.
  
  These   functions   accept   [13Xself-similar   groups/monoids/semigroups[0m,  i.e.
  groups/monoids/semigroups whose elements are FR elements.
  
  [1X11.2-16 IsFRAlgebra[0m
  
  [2X> IsFRAlgebra( [0X[3Xobj[0X[2X ) _________________________________________________[0Xfilter
  [2X> IsFRAlgebraWithOne( [0X[3Xobj[0X[2X ) __________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m if [3Xobj[0m is a FR algebra [with one].
  
  These functions accept [13Xself-similar algebras [with one][0m, i.e. algebras whose
  elements are linear FR elements.
  
  
  [1X11.3 Some of the algorithms implemented[0X
  
  Few calculations with infinite groups can be guaranteed to terminate --- and
  especially  to terminate within reasonable time. This section describes some
  of the algorithms implemented in [5XFR[0m.
  
  [1X11.3-1 FRMachineRWS[0m
  
  [2X> FRMachineRWS( [0X[3Xm[0X[2X ) _______________________________________________[0Xattribute
  [6XReturns:[0X  A record containing a rewriting system for [3Xm[0m.
  
  Elements  of  an  FR  machine  are  compared using a rewriting system, which
  records all known relations among states of the machine.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> n := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);[0X
    [4X<FR machine with alphabet [ 1 .. 2 ] on Group( [ a, b ] )>[0X
    [4Xgap> FRMachineRWS(n);[0X
    [4Xrec( rws := Knuth Bendix Rewriting System for Monoid( [ a^-1, a, b^-1, b[0X
    [4X     ], ... ) with rules[0X
    [4X    [ [ a^-1*a, <identity ...> ], [ a*a^-1, <identity ...> ],[0X
    [4X      [ b^-1*b, <identity ...> ], [ b*b^-1, <identity ...> ] ],[0X
    [4X  tzrules := [ [ [ 1, 2 ], [  ] ], [ [ 2, 1 ], [  ] ], [ [ 3, 4 ], [  ] ],[0X
    [4X      [ [ 4, 3 ], [  ] ] ], letterrep := function( w ) ... end,[0X
    [4X  pi := function( w ) ... end, reduce := function( w ) ... end,[0X
    [4X  addgprule := function( w ) ... end, commit := function(  ) ... end,[0X
    [4X  restart := function(  ) ... end )[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X11.3-2 Order of FR elements[0X
  
  The  order  of an FR element [10Xe[0m is computed as follows: the tree is traversed
  recursively,  filling it as follows. For each cycle of [10Xe[0m on the first level,
  the  product  of the states on that cycle are computed. The method continues
  recursively  with  that  product, remembering the order of the cycle. Once a
  state reappears in the traversal, [5XFR[0m determines if one instance of the state
  is  in the subtree of the other, and if so whether the top one was raised to
  a  non-trivial  power  to  yield the second one as a state. If this happens,
  then  [10Xe[0m  has  infinite  order.  Otherwise,  the least common multiple of the
  powers that appeared in the traversal is returned.
  
  This  method  is guaranteed to succeed if [10Xe[0m is a bounded element. To improve
  chances   of   success,   [5XFR[0m   first  computes  whether  [10Xe[0m  acts  by  vertex
  transformations  belonging to an abelian group; and if so, if [10Xe[0m is conjugate
  to an adding machine. In that case too, [10Xe[0m has infinite order.
  
  
  [1X11.3-3 Membership in semigroups[0X
  
  The following algorithm is used to determine whether a Mealy element belongs
  to  a  self-similar  group. The corresponding problem of membership of an FR
  element in a state-closed self-similar group can be much simpler, because an
  FR  element  has an associated FR machine, all of whose states belong to the
  group.
  
  Assume  the  group  is given by generators. [5XFR[0m attempts to express the given
  Mealy  element  as  a product of generators. At the same time, it constructs
  epimorphisms  to  finite groups. It is hoped that one of these two processes
  will stop.
  
  This  amounts,  in  fact,  to  the following. Consider a group G acting on a
  tree.  It  has  a  natural, profinite closure overline G. The algorithm then
  attempts either to write an element x as a product of generators of [3XG[0m, or to
  show that x does not belong to overline G.
  
  There  are  groups  G  such  that overline G\ G contains Mealy machines. For
  these, the above algorithm will not terminate.
  
  An   additional   refinement   is   implemented   for  bounded  groups  (see
  [2XIsBoundedFRSemigroup[0m  ([14X7.2-13[0m)).  The  [2XGerms[0m  ([14X5.2-24[0m)  of  an  element  are
  computed, and compared to the germs of elements in the group.
  
  Finally,  for a group that possesses self-similar data (see Section [14X11.3-5[0m),
  very  fast methods are implemented to recognize and express an FR element as
  a product of generators.
  
  
  [1X11.3-4 Order of groups[0X
  
  The  order  of  an  FR  group  is computed as follows: if all generators are
  finitary,  then  enumeration  will  succeed  in  computing the order. If the
  action  of  the  group  is  primitive,  and  it  comes  from  a bireversible
  automaton,  then  the  Thompson-Wielandt  theorem  is  tested  against. This
  theorem states that, in our context (a group acting on a rooted tree, coming
  from  a  larger  group acting transitively), if the group is finite then the
  stabilizer  of  a  sphere  of radius 2 is a p-group; see [BM00a, Proposition
  2.1.1].  Then, [5XFR[0m attempts to find whether the group is level-transitive (in
  which  case  it  would  be  infinite). Finally, it attempts to enumerate the
  group's  elements,  testing  at  the  same  time whether these elements have
  infinite order.
  
  Needless to say, none except the first few steps are guaranteed to succeed.
  
  
  [1X11.3-5 Images and preimages of some groups in f.p. and l.p. groups[0X
  
  Contracting,  branched  groups  admit finite L-presentations (see [Bar03b]),
  that   is,   presentations   by   finitely  many  generators,  relators  and
  endomorphisms;  the  (usual)  relators  are the images of the given relators
  under iteration by all endomorphisms.
  
  Using  the  package  [5XNQL[0m,  it  is  possible  to construct infinite nilpotent
  quotients of self-similar groups, and perform fast computations in them.
  
  It  is possible to construct, algorithmically, such an L-presentation from a
  self-similar  groups;  however, this algorithm has not been implemented yet,
  mainly  because  efficiency  issues  would  make  it usable only in very few
  cases.
  
  For  groups  with  an  isomorphism  to  an L-presented group (constructed by
  [2XIsomorphismLpGroup[0m  ([14X7.2-27[0m)),  a  fast  method  expresses group elements as
  words  in the L-presented group's generators. It proceeds recursively on the
  decomposition of the element, mapping elements that are expressible by short
  words  over  the  nucleus  (usually  length  1;  length  3 is needed for the
  [2XBrunnerSidkiVieiraGroup[0m  ([14X10.1-12[0m)) to their value in the L-presented group,
  and   using   the   presentation's  endomorphism  to  construct  words  with
  appropriate decompositions.
  
  In  particular,  the  algorithm  will  stop,  returning  [9Xfail[0m, if during the
  recursion it reaches an element x such that x is a state of x but x does not
  belong to the nucleus.
  
  
  [1X11.3-6 Comparison of FR, Mealy, vector, and algebra elements[0X
  
  FR and Mealy elements can be compared quite efficiently, as long as they are
  distinct.  The  algorithm  runs as follows: let the two elements be x and y.
  Considering  both  in turn, [5XFR[0m constructs the first entries of minimal Mealy
  elements  expressing  x  and y; as soon as an output entry is distinct for x
  and  for  y,  the  status of x<y is determined; and similarly for transition
  entries.  Finally,  if either of x or y is finite-state and the entries were
  identical  up  to  that  step,  then  the  element with smallest stateset is
  considered smaller.
  
  In  this  way,  FR and Mealy elements can efficiently be compared. For Mealy
  elements,  it suffices to follow their internal data; while for FR elements,
  this  amounts  to  constructing  Mealy  elements  approximating  them  to  a
  sufficient precision so that they can be compared as such.
  
  The  algorithm  first tries to test its arguments for equality; this test is
  not guaranteed to succeed.
  
  A similar algorithm applies for linear elements. Here, one constructs vector
  element approximations; and compares, for ever-increasing values of i, first
  the  output  vectors  of basis state i; then the transitions from state i to
  state j, for all jin{1,dots,i}; then the transitions from state j to state i
  for all jin{1,dots,i-1}.
  
  
  [1X11.3-7 Inverses of linear elements[0X
  
  It  is  probably  difficult  to compute the inverse of a vector element. The
  following  approach  is  used:  to  compute the inverse of x, large (scalar)
  matrix  approximations  of  x  are  computed; they are inverted using linear
  algebra;  a  vector  element  representing  this inverse is guessed; and the
  guess  is  checked.  As  long as that check fails, larger approximations are
  computed.
  
  Needless to say, this method need not succeed; for there are vector elements
  that  are invertible, but whose inverse is not a vector element. A good test
  example  appears  in  [Bac07]:  consider the infinite matrix with 1's on the
  diagonal,  and  omega  below the diagonal. This element admits an inverse if
  and only if omega is a root of unity. The complexity of the inverse grows as
  the degree of omega grows. Here is an illustation:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> bacher := function(n)[0X
    [4X  local f;[0X
    [4X  f := CyclotomicField(n);[0X
    [4X  return VectorElement(f,One(f)*[[[[1,0],[0,0]],[0X
    [4X        [[0,0],[0,1]]],[[[0,1],[0,0]],[[1,0],[0,0]]]],[One(f),E(n)],[One(f),Zero(f)]);[0X
    [4Xend;;[0X
    [4Xgap> Inverse(bacher(3));[0X
    [4X<Linear element on alphabet CF(3)^2 with 4-dimensional stateset>[0X
    [4X6 gap> Inverse(bacher(5));[0X
    [4X<Linear element on alphabet CF(5)^2 with 6-dimensional stateset>[0X
  [4X------------------------------------------------------------------[0X
  
                n | 1    2    3    4    5    6    7    8    9    10
        dimension |      2    4    4    6    3    5    5    8    5 
      ------------------------------------------------------------
                n | 11   12   13   14   15   16   17   18   19   20
        dimension | ?    5    ?    4    6    6    ?    7    ?    7 
      ------------------------------------------------------------
                n | 22   24   26   28   30   32   34   36   38   40
        dimension | ?    6    ?    6    ?    7    ?    ?    ?    ? 
  
       [1XTable:[0X Dimension of states of inverse
  
  
