  
  [1X4 Functionally recursive elements[0X
  
  A  [13Xfunctionally  recursive  element[0m  is  given  by  a functionally recursive
  machine and an initial state q. Many functions for FR machines, which accept
  a  state  as  an  argument,  apply to FR elements. In that case, no state is
  passed to the function.
  
  The  main  function  of  FR  elements  is to serve as group/monoid/semigroup
  elements:  they  can  be  multiplied  and divided, and they act naturally on
  sequences. They can also be tested for equality, and can be sorted.
  
  FR  elements  are  stored  as  free  group/monoid/semigroup  words. They are
  printed as [10X<n|w>[0m, where [10Xn[0m is the degree of their alphabet.
  
  Equality  of  FR  elements is tested as follows. Given FR elements (m,q) and
  (m,r),  we  set up a "rewriting system" for m, which records a purported set
  of  relations  among states of m. We start by an empty rewriting system, and
  we always ensure that the rewriting system is reduced and shortlex-reducing.
  Then, to compare q and r, we first compare their activities. If they differ,
  the  elements are distinct. Otherwise, we reduce q and r using the rewriting
  system.  If  the resulting words are graphically equal, then they are equal.
  Otherwise,  we  add  the  rule  q->  r or r-> q to the rewriting system, and
  proceed  recursively  to  compare coordinatewise the states of these reduced
  words.  As  a  bonus,  we  keep  the  rewriting  system  to  speed up future
  comparisons.
  
  Efficient  comparison requires lookup in sorted lists, aka "Sets". Given two
  FR elements x and y, we declare that x<y if, for the shortlex-first sequence
  l  such that [10XOutput(Transition(x,l))[0m and [10XOutput(Transition(y,l))[0m differ, the
  former  is  less  than  the  latter  (compared  as lists). In fact, a single
  internal  function  compares x and y and returns -1,0,1 depending on whether
  x<y  or  x=y  or  x>y.  It traverses, in breadth first fashion, the alphabet
  sequences,  and  stops  either  when  provably  x=y  or if different outputs
  appear.
  
  
  [1X4.1 Creators for [10XFRElement[1Xs[0X
  
  [1X4.1-1 FRElementNC[0m
  
  [2X> FRElementNC( [0X[3Xfam, free, transitions, outputs, init[0X[2X ) ____________[0Xoperation
  [6XReturns:[0X  A new FR element.
  
  This  function  constructs a new FR element, belonging to family [3Xfam[0m. It has
  stateset  the free group/semigroup/monoid [3Xfree[0m, and transitions described by
  [3Xstates[0m and [3Xoutputs[0m, and initial states [3Xinit[0m.
  
  [3Xtransitions[0m  is  a list of lists; [3Xtransitions[0m[[3Xs[0m][[3Xx[0m] is a word in [3Xfree[0m, which
  is the state reached by the machine when started in state [3Xs[0m and fed input [3Xx[0m.
  
  [3Xoutputs[0m  is a list of lists; [3Xoutputs[0m[[3Xs[0m][[3Xx[0m] is a output letter of the machine
  when it receives input [3Xx[0m in state [3Xs[0m.
  
  [3Xinit[0m is a word in [3Xfree[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> f := FreeGroup(2);[0X
    [4X<free group on the generators [ f1, f2 ]>[0X
    [4Xgap> e := FRElementNC(FREFamily([1,2]),f,[[One(f),f.1],[One(f),f.2^-1]],[0X
    [4X                      [[2,1],[2,1]],f.1);[0X
    [4X<2|f1>[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.1-2 FRElement[0m
  
  [2X> FRElement( [0X[3X[names, ]transitions, outputs, init[0X[2X ) ________________[0Xoperation
  [2X> FRElement( [0X[3Xfree, transitions, outputs, init[0X[2X ) ___________________[0Xoperation
  [6XReturns:[0X  A new FR element.
  
  This  function  constructs  a  new  FR  element.  It  has  stateset  a  free
  group/semigroup/monoid,  structure described by [3Xtransitions[0m and [3Xoutputs[0m, and
  initial  state [3Xinit[0m. If the stateset is not passed as argument [3Xfree[0m, then it
  is  determined  by [3Xtransitions[0m and [3Xoutputs[0m; it is a free group if all states
  are  invertible,  and  a  free  monoid  otherwise. In that case, [3Xnames[0m is an
  optional list; at position [3Xs[0m it contains a string describing generator [3Xs[0m.
  
  [3Xtransitions[0m  is  a list of lists; [10Xtransitions[s][x][0m is either an associative
  word,  or  a list of integers or FR elements describing the state reached by
  the  machine  when  started  in  state  [3Xs[0m and fed input [3Xx[0m. Positive integers
  indicate  a  generator, negative integers its inverse, the empty list in the
  identity  state,  and lists of length greater than one indicate a product of
  states.  If an entry is an FR element, then its machine is incorporated into
  the newly constructed element.
  
  [3Xoutputs[0m   is   a   list;   at  position  [3Xs[0m  it  contains  a  permutation,  a
  transformation, or a list of images, describing the activity of state [3Xs[0m.
  
  [3Xinit[0m  is  either  an  associative  word,  an  integer, or a list of integers
  describing the inital state of the machine.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);[0X
    [4X<2|tau>[0X
    [4Xgap> tau1 := FRElement(["tau1","tau"],[[[],[2]],[[],[2]]],[(),(1,2)],1);[0X
    [4X<2|tau1>[0X
    [4Xgap> (tau/tau1)^2;[0X
    [4X<2|tau1*tau2^-1*tau1*tau2^-1>[0X
    [4Xgap> IsOne(last);[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> f := FreeGroup("tau","tau1");[0X
    [4X<free group on the generators [ tau, tau1 ]>[0X
    [4Xgap> tau := FRElement(f,[[One(f),f.1],[One(f),f.1]],[(1,2),()],f.1);[0X
    [4X<2|tau>[0X
    [4Xgap> tau1 := FRElement(f,[[One(f),f.1],[One(f),f.1]],[(1,2),()],f.2);[0X
    [4X<2|tau1>[0X
    [4Xgap> (tau/tau1)^2;[0X
    [4X<2|tau1*tau2^-1*tau1*tau2^-1>[0X
    [4Xgap> IsOne(last);[0X
    [4Xtrue[0X
    [4Xgap> tauX := FRElement(f,[[One(f),f.1],[One(f),f.1]],[(1,2),()],1);;[0X
    [4Xgap> tauY := FRElement(f,[[One(f),f.1],[One(f),f.1]],[(1,2),()],f.1);;[0X
    [4Xgap> Size(Set([tau,tauX,tauY]));[0X
    [4X1[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.1-3 FRElement[0m
  
  [2X> FRElement( [0X[3Xm, q[0X[2X ) _______________________________________________[0Xoperation
  [6XReturns:[0X  A new FR element.
  
  This function constructs a new FR element. If [3Xm[0m is an FR machine, it creates
  the element (m,q) whose [10XFRMachine[0m is [3Xm[0m and whose initial state is [3Xq[0m.
  
  If  [3Xm[0m  is an FR element, this command creates an FR element with the same FR
  machine as [3Xm[0m, and with initial state [3Xq[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);[0X
    [4X<FR machine with alphabet [ 1 .. 2 ] on Group( [ a, b ] )>[0X
    [4Xgap> a := FRElement(m,1); b := FRElement(m,2);[0X
    [4X<2|a>[0X
    [4X<2|b>[0X
    [4Xgap> Comm(b,b^a);[0X
    [4X<2|b^-1*a^-1*b^-1*a*b*a^-1*b*a>[0X
    [4Xgap> IsOne(last);[0X
    [4Xtrue[0X
    [4Xgap> last2=FRElement(m,[-2,-1,-2,1,2,-1,2,1]);[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.1-4 ComposeElement[0m
  
  [2X> ComposeElement( [0X[3Xl, p[0X[2X ) __________________________________________[0Xoperation
  [6XReturns:[0X  A new FR element.
  
  This function constructs a new FR element. [3Xl[0m is a list of FR elements, and [3Xp[0m
  is  a  permutation, transformation or list. In that last case, the resulting
  element [10Xg[0m satisfies [10XDecompositionOfFRElement(g)=[l,p][0m.
  
  If  all  arguments  are  Mealy  elements,  the  result  is  a Mealy element.
  Otherwise, it is a MonoidFRElement.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);;[0X
    [4Xgap> a := FRElement(m,1); b := FRElement(m,2);[0X
    [4X<2|a>[0X
    [4X<2|b>[0X
    [4Xgap> ComposeElement([b^0,b],(1,2));[0X
    [4X<2|f1>[0X
    [4Xgap> last=a;[0X
    [4Xtrue[0X
    [4Xgap> DecompositionOfFRElement(last2);[0X
    [4X[ [ <2|identity ...>, <2|f5> ], [ 2, 1 ] ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.1-5 VertexElement[0m
  
  [2X> VertexElement( [0X[3Xv, e[0X[2X ) ___________________________________________[0Xoperation
  [6XReturns:[0X  A new FR element.
  
  This  function constructs a new FR element. [3Xv[0m is either an integer or a list
  of  integers,  and  represents  a  vertex. [3Xe[0m is an FR element. The resulting
  element  acts on the subtree below vertex [3Xv[0m as [3Xe[0m acts on the whole tree, and
  fixes all other subtrees.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> e := FRElement([[[],[]]],[(1,2)],[1]);[0X
    [4X<2|f1>[0X
    [4Xgap> f := VertexElement(1,e);;[0X
    [4Xgap> g := VertexElement(2,f);;[0X
    [4Xgap> g = VertexElement([2,1],e);[0X
    [4Xtrue[0X
    [4Xgap> 1^e;[0X
    [4X2[0X
    [4Xgap> [1,1]^f;[0X
    [4X[ 1, 2 ][0X
    [4Xgap> [2,1,1]^g;[0X
    [4X[ 2, 1, 2 ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.1-6 DiagonalElement[0m
  
  [2X> DiagonalElement( [0X[3Xn, e[0X[2X ) _________________________________________[0Xoperation
  [6XReturns:[0X  A new FR element.
  
  This  function constructs a new FR element. [3Xn[0m is either an integer or a list
  of  integers,  representing  a  sequence  of operations to be performed on [3Xe[0m
  starting from the last.
  
  [10XDiagonalElement(n,e)[0m  is  an  element with trivial output, and with e^(-1)^i
  binomial(n,i)  in  coordinate i+1 of the alphabet, assumed to be of the form
  [10X[1..d][0m.
  
  In  particular,  [10XDiagonalElement(0,e)[0m  is  the  same  as [10XVertexElement(1,e)[0m;
  [10XDiagonalElement(1,e)[0m  is the commutator of [10XVertexElement(1,e)[0m with any cycle
  mapping  1  to  2;  and  [10XDiagonalElement(-1,e)[0m  has a transition to [3Xe[0m at all
  inputs.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> e := FRElement([[[],[],[1]]],[(1,2,3)],[1]);[0X
    [4X<3|f1>[0X
    [4Xgap> Display(e);[0X
    [4X    |     1        2      3[0X
    [4X----+--------+--------+------+[0X
    [4X f1 | <id>,2   <id>,3   f1,1[0X
    [4X----+--------+--------+------+[0X
    [4XInitial state: f1[0X
    [4Xgap> Display(DiagonalElement(0,e));[0X
    [4X    |     1        2        3[0X
    [4X----+--------+--------+--------+[0X
    [4X f1 |   f2,1   <id>,2   <id>,3[0X
    [4X f2 | <id>,2   <id>,3     f2,1[0X
    [4X----+--------+--------+--------+[0X
    [4XInitial state: f1[0X
    [4Xgap> Display(DiagonalElement(1,e));[0X
    [4X    |     1         2        3[0X
    [4X----+--------+---------+--------+[0X
    [4X f1 |   f2,1   f2^-1,2   <id>,3[0X
    [4X f2 | <id>,2    <id>,3     f2,1[0X
    [4X----+--------+---------+--------+[0X
    [4XInitial state: f1[0X
    [4Xgap> Display(DiagonalElement(2,e));[0X
    [4X    |     1         2      3[0X
    [4X----+--------+---------+------+[0X
    [4X f1 |   f2,1   f2^-2,2   f2,3[0X
    [4X f2 | <id>,2    <id>,3   f2,1[0X
    [4X----+--------+---------+------+[0X
    [4XInitial state: f1[0X
    [4Xgap> Display(DiagonalElement(-1,e));[0X
    [4X    |     1        2      3[0X
    [4X----+--------+--------+------+[0X
    [4X f1 |   f2,1     f2,2   f2,3[0X
    [4X f2 | <id>,2   <id>,3   f2,1[0X
    [4X----+--------+--------+------+[0X
    [4XInitial state: f1[0X
    [4Xgap> DiagonalElement(-1,e)=DiagonalElement(2,e);[0X
    [4Xtrue[0X
    [4Xgap> Display(DiagonalElement([0,-1],e));[0X
    [4X G  |     1        2        3[0X
    [4X----+--------+--------+--------+[0X
    [4X f1 |   f2,1   <id>,2   <id>,3[0X
    [4X f2 |   f3,1     f3,2     f3,3[0X
    [4X f3 | <id>,2   <id>,3     f3,1[0X
    [4X----+--------+--------+--------+[0X
    [4XInitial state: f1[0X
    [4Xgap> Display(DiagonalElement([-1,0],e));[0X
    [4X G  |     1        2        3[0X
    [4X----+--------+--------+--------+[0X
    [4X f1 |   f2,1     f2,2     f2,3[0X
    [4X f2 |   f3,1   <id>,2   <id>,3[0X
    [4X f3 | <id>,2   <id>,3     f3,1[0X
    [4X----+--------+--------+--------+[0X
    [4XInitial state: f1[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.1-7 AsGroupFRElement[0m
  
  [2X> AsGroupFRElement( [0X[3Xe[0X[2X ) ___________________________________________[0Xoperation
  [2X> AsMonoidFRElement( [0X[3Xe[0X[2X ) __________________________________________[0Xoperation
  [2X> AsSemigroupFRElement( [0X[3Xe[0X[2X ) _______________________________________[0Xoperation
  [6XReturns:[0X  An  FR element isomorphic to [3Xm[0m, with a free group/monoid/semigroup
            as stateset.
  
  This  function constructs, from the FR element [3Xe[0m, an isomorphic FR element [10Xf[0m
  with  a  free  group/monoid/semigroup  as stateset. [3Xe[0m may be a Mealy, group,
  monoid or semigroup FR element.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> e := AsGroupFRElement(FRElement(GuptaSidkiMachines(3),4));[0X
    [4X<3|f1>[0X
    [4Xgap> Display(e);[0X
    [4X G  |     1         2        3[0X
    [4X----+--------+---------+--------+[0X
    [4X f1 |   f2,1   f2^-1,2     f1,3[0X
    [4X f2 | <id>,2    <id>,3   <id>,1[0X
    [4X----+--------+---------+--------+[0X
    [4XInitial state: f1[0X
    [4Xgap> e=FRElement(GuptaSidkiMachines(3),4);[0X
    [4X#I  \=: converting second argument to FR element[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> e := AsMonoidFRElement(FRElement(GuptaSidkiMachines(3),4));[0X
    [4X<3|m1>[0X
    [4Xgap> Display(e);[0X
    [4X M  |     1        2        3[0X
    [4X----+--------+--------+--------+[0X
    [4X m1 |   m2,1     m3,2     m1,3[0X
    [4X m2 | <id>,2   <id>,3   <id>,1[0X
    [4X m3 | <id>,3   <id>,1   <id>,2[0X
    [4X----+--------+--------+--------+[0X
    [4XInitial state: m1[0X
    [4Xgap> e=FRElement(GuptaSidkiMachines(3),4);[0X
    [4X#I  \=: converting second argument to FR element[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> e := AsSemigroupFRElement(FRElement(GuptaSidkiMachines(3),4));[0X
    [4X<3|s1>[0X
    [4Xgap> Display(e);[0X
    [4X S  |   1      2      3[0X
    [4X----+------+------+------+[0X
    [4X s1 | s2,1   s3,2   s1,3[0X
    [4X s2 | s4,2   s4,3   s4,1[0X
    [4X s3 | s4,3   s4,1   s4,2[0X
    [4X s4 | s4,1   s4,2   s4,3[0X
    [4X----+------+------+------+[0X
    [4XInitial state: s1[0X
    [4Xgap> e=FRElement(GuptaSidkiMachines(3),4);[0X
    [4X#I  \=: converting second argument to FR element[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X4.2 Operations and Attributes for [10XFRElement[1Xs[0X
  
  [1X4.2-1 Output[0m
  
  [2X> Output( [0X[3Xe[0X[2X ) _____________________________________________________[0Xoperation
  [6XReturns:[0X  A transformation of [3Xe[0m's alphabet.
  
  This function returns the transformation of [3Xe[0m's alphabet, i.e. the action on
  strings  of length 1 over the alphabet. This transformation is a permutation
  if [3Xmachine[0m is a group machine, and a transformation otherwise.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;[0X
    [4Xgap> Output(tau);[0X
    [4X(1,2)[0X
    [4Xzap := FRElement(["zap"],[[[],[1]]],[[1,1]],[1]);;[0X
    [4Xgap> Output(zap);[0X
    [4X<1,1>[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-2 Activity[0m
  
  [2X> Activity( [0X[3Xe[, l][0X[2X ) ______________________________________________[0Xoperation
  [2X> ActivityInt( [0X[3Xe[, l][0X[2X ) ___________________________________________[0Xoperation
  [2X> ActivityTransformation( [0X[3Xe[, l][0X[2X ) ________________________________[0Xoperation
  [2X> ActivityPerm( [0X[3Xe[, l][0X[2X ) __________________________________________[0Xoperation
  [6XReturns:[0X  The transformation induced by [3Xe[0m on the [3Xl[0mth level of the tree.
  
  This  function  returns  the transformation induced by [3Xe[0m on the [3Xl[0mth level of
  the tree, i.e. on the strings of length [3Xl[0m over [3Xe[0m's alphabet.
  
  This  set  of  strings is identified with the set L={1,...,d^l} of integers,
  where  the  alphabet  of  [3Xe[0m  has d letters. Changes of the first letter of a
  string  induce  changes  of  a multiple of d^l-1 on the position in L, while
  changes  of  the last letter of a string induce changes of 1 on the position
  in L.
  
  In  its  first form, this command returns a permutation (for group elements)
  or  a  [2XTrans[0m  ([14X12.1-23[0m) (for other elements). In the second form, it returns
  the   unique   integer   [10Xi[0m   such   that   the   transformation  [3Xe[0m  acts  on
  [10X[1..Length(AlphabetOfFRObject(e))^n][0m     as     adding     [10Xi[0m     in     base
  [10XLength(alphabet(e))[0m,  or  [9Xfail[0m  if  no  such [10Xi[0m exists. In the third form, it
  returns  a [5XGAP[0m transformation. In the fourth form, it returns a permutation,
  or [9Xfail[0m if [3Xe[0m is not invertible.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;[0X
    [4Xgap> Output(tau); PermList(last)=Activity(tau);[0X
    [4X[ 2, 1 ][0X
    [4Xtrue[0X
    [4Xgap> Activity(tau,2); ActivityInt(tau,2);[0X
    [4X(1,3,2,4)[0X
    [4X1[0X
    [4Xgap> Activity(tau,3); ActivityInt(tau,3);[0X
    [4X(1,5,3,7,2,6,4,8)[0X
    [4X1[0X
    [4Xgap> zap := FRElement(["zap"],[[[1],[]]],[[1,1]],[1]);[0X
    [4X<2|zap>[0X
    [4Xgap> Output(zap);[0X
    [4X[ 1, 1 ][0X
    [4Xgap> Activity(zap,3);[0X
    [4X<1,1,1,2,1,2,3,4>[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-3 Transition[0m
  
  [2X> Transition( [0X[3Xe, i[0X[2X ) ______________________________________________[0Xoperation
  [6XReturns:[0X  An element of [3Xmachine[0m's stateset.
  
  This  function  returns  the state reached by [3Xe[0m when fed input [3Xi[0m. This input
  may be an alphabet letter or a sequence of alphabet letters.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;[0X
    [4Xgap> Transition(tau,2);[0X
    [4Xtau[0X
    [4Xgap> Transition(tau,[2,2]);[0X
    [4Xtau[0X
    [4Xgap> Transition(tau^2,[2,2]);[0X
    [4Xtau[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-4 Transitions[0m
  
  [2X> Transitions( [0X[3Xe[0X[2X ) ________________________________________________[0Xoperation
  [6XReturns:[0X  A list of elements of [3Xmachine[0m's stateset.
  
  This  function  returns  the  states  reached  by [3Xe[0m when fed the alphabet as
  input.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;[0X
    [4Xgap> Transitions(tau);[0X
    [4X[ <identity ...>, tau ][0X
    [4Xgap> Transition(tau^2);[0X
    [4X[ tau, tau ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-5 Portrait[0m
  
  [2X> Portrait( [0X[3Xe, l[0X[2X ) ________________________________________________[0Xoperation
  [2X> PortraitPerm( [0X[3Xe, l[0X[2X ) ____________________________________________[0Xoperation
  [2X> PortraitInt( [0X[3Xe, l[0X[2X ) _____________________________________________[0Xoperation
  [6XReturns:[0X  A nested list describing the action of [3Xe[0m.
  
  This  function returns a sequence of l+1 lists; the ith list in the sequence
  is  an  [3Xi-1[0m-fold  nested  list.  The  entry at position (x_1,...,x_i) is the
  transformation of the alphabet induced by [3Xe[0m under vertex x_1... x_i.
  
  The  difference  between  the  commands  is  the following: [10XPortrait[0m returns
  transformations,  [10XPortraitPerm[0m  returns  permutations,  and  and [10XPortraitInt[0m
  returns  integers,  the  power  of  the  cycle  x->  x+1 that represents the
  transformation, as for the function [2XActivityInt[0m ([14X4.2-2[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;[0X
    [4Xgap> Portrait(tau,0);[0X
    [4X[ <2,1> ][0X
    [4Xgap> Portrait(tau,3);[0X
    [4X[ <2,1>, [ <>, <2,1> ], [ [ <>, <> ], [ <>, <2,1> ] ],[0X
    [4X  [ [ [ <>, <> ], [ <>, <> ] ], [ [ <>, <> ], [ <>, <2,1> ] ] ] ][0X
    [4Xgap> PortraitPerm(tau,0);[0X
    [4X[ (1,2) ][0X
    [4Xgap> PortraitInt(tau,0);[0X
    [4X[ 1 ][0X
    [4Xgap> PortraitInt(tau,3);[0X
    [4X[ 1 , [ 0 , 1 ],[0X
    [4X  [ [ 0 , 0 ], [ 0 , 1 ] ],[0X
    [4X  [ [ [ 0 , 0 ], [ 0 , 0 ] ], [ [ 0 , 0 ], [ 0 , 1 ] ] ] ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-6 DecompositionOfFRElement[0m
  
  [2X> DecompositionOfFRElement( [0X[3Xe[, n][0X[2X ) ______________________________[0Xoperation
  [6XReturns:[0X  A list describing the action and transitions of [3Xe[0m.
  
  This  function  returns  a list. The second coordinate is the action of [3Xe[0m on
  its alphabet, see [2XOutput[0m ([14X4.2-1[0m). The first coordinate is a list, containing
  in  position  i  the FR element inducing the action of [3Xe[0m on strings starting
  with i.
  
  If a second argument [3Xn[0m is supplied, the decomposition is iterated [3Xn[0m times.
  
  This FR element has same underlying machine as [3Xe[0m, and initial state given by
  [2XTransition[0m ([14X4.2-3[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;[0X
    [4Xgap> DecompositionOfFRElement(tau);[0X
    [4X[ [ <2|identity ...>, <2|tau> ], [ 2, 1 ] ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-7 StateSet[0m
  
  [2X> StateSet( [0X[3Xe[0X[2X ) ___________________________________________________[0Xoperation
  [6XReturns:[0X  The set of states associated with [3Xe[0m.
  
  This  function returns the stateset of [3Xe[0m. If [3Xe[0m is of Mealy type, this is the
  list of all states reached by [3Xe[0m.
  
  If  [3Xe[0m  is  of  group/semigroup/monoid type, then this is the stateset of the
  underlying  FR  machine,  and  not  the minimal set of states of [3Xe[0m, which is
  computed with [2XStates[0m ([14X4.2-9[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;[0X
    [4Xgap> StateSet(tau);[0X
    [4X<free group on the generators [ tau ]>[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-8 State[0m
  
  [2X> State( [0X[3Xe, v[0X[2X ) ___________________________________________________[0Xoperation
  [6XReturns:[0X  An FR element describing the action of [3Xe[0m at vertex [3Xv[0m.
  
  This  function  returns  the  FR  element with same underlying machine as [3Xe[0m,
  acting on the binary tree as [3Xe[0m acts on the subtree below [3Xv[0m.
  
  [3Xv[0m  is  either an integer or a list. This function returns an FR element, but
  otherwise is essentially a call to [2XTransition[0m ([14X4.2-3[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;[0X
    [4Xgap> State(tau,2);[0X
    [4X<2|tau>[0X
    [4Xgap> State(tau,[2,2]);[0X
    [4X<2|tau>[0X
    [4Xgap> State(tau^2,[2,2]);[0X
    [4X<2|tau>[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-9 States[0m
  
  [2X> States( [0X[3Xe[0X[2X ) _____________________________________________________[0Xoperation
  [6XReturns:[0X  A list of FR elements describing the action of [3Xe[0m on all subtrees.
  
  This function calls repeatedly [2XState[0m ([14X4.2-8[0m) to compute all the states of [3Xe[0m;
  it returns the smallest list of [10XFRElement[0ms that is closed under the function
  [2XState[0m ([14X4.2-8[0m).
  
  [3Xe[0m may be either an FR element, or a list of FR elements. In the latter case,
  it  amounts  to computing the list of all states of all elements of the list
  [3Xe[0m.
  
  The  ordering of the list is as follows. First come [3Xe[0m, or all elements of [3Xe[0m.
  Then come the states reached by [3Xe[0m in one transition, ordered by the alphabet
  letter  leading to them; then come those reached in two transitions, ordered
  lexicographically by the transition; etc.
  
  Note  that  this function is not guaranteed to terminate. There is currently
  no  mechanism that detects whether an FR element is finite state, so in fact
  this function terminates if and only if [3Xe[0m is finite-state.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);;[0X
    [4Xgap> a := FRElement(m,1);; b := FRElement(m,2);;[0X
    [4Xgap> States(a);[0X
    [4X[ <2|a>, <2|identity ...>, <2|b> ][0X
    [4Xgap> States(b);[0X
    [4X[ <2|b>, <2|identity ...>, <2|a> ][0X
    [4Xgap> States(a^2);[0X
    [4X[ <2|a^2>, <2|b>, <2|identity ...>, <2|a> ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-10 FixedStates[0m
  
  [2X> FixedStates( [0X[3Xe[0X[2X ) ________________________________________________[0Xoperation
  [6XReturns:[0X  A  list  of  FR  elements  describing  the  action  of  [3Xe[0m at fixed
            vertices.
  
  This  function calls repeatedly [2XState[0m ([14X4.2-8[0m) to compute all the states of [3Xe[0m
  at non-trivial fixed vertices.
  
  [3Xe[0m may be either an FR element, or a list of FR elements. In the latter case,
  it  amounts  to computing the list of all states of all elements of the list
  [3Xe[0m.
  
  The  ordering of the list is as follows. First come [3Xe[0m, or all elements of [3Xe[0m.
  Then come the states reached by [3Xe[0m in one transition, ordered by the alphabet
  letter  leading to them; then come those reached in two transitions, ordered
  lexicographically by the transition; etc.
  
  Note  that  this  function  is  not  guaranteed  to  terminate,  if [3Xe[0m is not
  finite-state.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);;[0X
    [4Xgap> a := FRElement(m,1);; b := FRElement(m,2);;[0X
    [4Xgap> FixedStates(a);[0X
    [4X[ ][0X
    [4Xgap> FixedStates(b);[0X
    [4X[ <2|identity ...>, <2|a> ][0X
    [4Xgap> FixedStates(a^2);[0X
    [4X[ <2|b>, <2|identity ...>, <2|a> ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-11 LimitStates[0m
  
  [2X> LimitStates( [0X[3Xe[0X[2X ) ________________________________________________[0Xoperation
  [6XReturns:[0X  A  set  of FR element describing the recurring actions of [3Xe[0m on all
            subtrees.
  
  This  function  computes  the  [2XStates[0m  ([14X4.2-9[0m)  S  of [3Xe[0m, and then repeatedly
  removes  elements  that are not [13Xrecurrent[0m, i.e. that do not appear as states
  of  elements  of  S  on  subtrees  distinct  from  the entire tree; and then
  converts the result to a set.
  
  As  for  [2XStates[0m  ([14X4.2-9[0m),  [3Xe[0m  may  be  either an FR element, or a list of FR
  elements.
  
  Note  that  this  function  is  not  guaranteed  to  terminate. It currently
  terminates if and only if [2XStates[0m ([14X4.2-9[0m) terminates.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);;[0X
    [4Xgap> a := FRElement(m,1);; b := FRElement(m,2);;[0X
    [4Xgap> LimitStates(a);[0X
    [4X[ <2|identity ...>, <2|b>, <2|a> ][0X
    [4Xgap> LimitStates(a^2);[0X
    [4X[ <2|identity ...>, <2|b>, <2|a> ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-12 IsFiniteStateFRElement[0m
  
  [2X> IsFiniteStateFRElement( [0X[3Xe[0X[2X ) ______________________________________[0Xproperty
  [2X> IsFiniteStateFRMachine( [0X[3Xe[0X[2X ) ______________________________________[0Xproperty
  [6XReturns:[0X  [9Xtrue[0m if [3Xe[0m is a finite-state element.
  
  This function tests whether [3Xe[0m is a finite-state element.
  
  When applied to a Mealy element, it returns [9Xtrue[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> m := GuptaSidkiMachines(3);; Display(m);[0X
    [4X   |  1     2     3[0X
    [4X---+-----+-----+-----+[0X
    [4X a | a,1   a,2   a,3[0X
    [4X b | a,2   a,3   a,1[0X
    [4X c | a,3   a,1   a,2[0X
    [4X d | b,1   c,2   d,3[0X
    [4X---+-----+-----+-----+[0X
    [4Xgap> Filtered(StateSet(m),i->IsFiniteStateFRElement(FRElement(m,i)));[0X
    [4X[ 1, 2, 3, 4 ][0X
    [4Xgap> IsFiniteStateFRMachine(m);[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-13 NucleusOfFRMachine[0m
  
  [2X> NucleusOfFRMachine( [0X[3Xm[0X[2X ) _________________________________________[0Xoperation
  [6XReturns:[0X  The nucleus of the machine [3Xm[0m.
  
  This function computes the [13Xnucleus[0m of the machine [3Xm[0m. It is the minimal set [10XN[0m
  of states such that, for every word [3Xs[0m in the states of [3Xm[0m, all states of [3Xs[0m of
  at large enough depth belong to [10X[0m.
  
  It  may  also  be characterized as the minimal set [10XN[0m of states that contains
  the limit states of [3Xm[0m and is such that the limit states of [10XN*m[0m belong to [10XN[0m.
  
  The  elements  of  the  nucleus  form  the stateset of a Mealy machine; this
  machine is created by [2XNucleusMachine[0m ([14X5.2-27[0m).
  
  This  command  is  not  guaranteed  to  terminate;  though  it  will, if the
  semigroup  generated by [3Xm[0m is contracting. If the minimal such [10XN[0m is infinite,
  this command either returns [3XK[0m or runs forever.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);;[0X
    [4Xgap> NucleusOfFRMachine(m);[0X
    [4X[ <2|identity ...>, <2|b>, <2|a> ][0X
    [4Xgap> m := FRMachine(["a","b"],[[[],[1]],[[1],[2]]],[(1,2),()]);;[0X
    [4Xgap> NucleusOfFRMachine(m);[0X
    [4Xfail[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-14 InitialState[0m
  
  [2X> InitialState( [0X[3Xe[0X[2X ) _______________________________________________[0Xoperation
  [6XReturns:[0X  The initial state of an FR element.
  
  This  function  returns the initial state of an FR element. It is an element
  of the stateset of the underlying FR machine of [3Xe[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> n := FRElement(["tau","mu"],[[[],[1]],[[],[-2]]],[(1,2),(1,2)],[1,2]);[0X
    [4X<2|tau*mu>[0X
    [4Xgap> InitialState(n);[0X
    [4Xtau*mu[0X
    [4Xgap> last in StateSet(n);[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-15 \^[0m
  
  [2X> \^( [0X[3Xe, v[0X[2X ) _________________________________________________________[0Xmethod
  [6XReturns:[0X  The image of a vertex [3Xv[0m under [3Xe[0m.
  
  This  function  accepts  an  FR  element  and a vertex [3Xv[0m, which is either an
  integer  or a list. It returns the image of [3Xv[0m under the transformation [3Xe[0m, in
  the same format (integer/list) as [3Xv[0m.
  
  The list [3Xv[0m can be a periodic list (see [2XPeriodicList[0m ([14X12.1-4[0m)). In that case,
  the  result  is  again a periodic list. The computation will succeed only if
  the states along the period are again periodic.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;[0X
    [4Xgap> 1^tau;[0X
    [4X2[0X
    [4Xgap> [1,1]^tau;[0X
    [4X[ 2, 1 ][0X
    [4Xgap> [2,2,2]^tau;[0X
    [4X[ 1, 1, 1 ][0X
    [4Xgap List([0..5],i->PeriodicList([],[2])^(tau^i));[0X
    [4X[ [/ 2 ], [/ 1 ], [ 2, / 1 ], [ 1, 2, / 1 ], [ 2, 2, / 1 ],[0X
    [4X  [ 1, 1, 2, / 1 ] ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-16 \*[0m
  
  [2X> \*( [0X[3Xm, n[0X[2X ) _________________________________________________________[0Xmethod
  [6XReturns:[0X  The product of the two FR elements [3Xm[0m and [3Xn[0m.
  
  This  function  returns  a  new  FR  element, which is the product of the FR
  elements [3Xm[0m and [3Xn[0m.
  
  In case [3Xm[0m and [3Xn[0m have the same underlying machine, this is the machine of the
  result.  In  case  the  machine  of  [3Xn[0m  embeds  in  the  machine  of  [3Xm[0m (see
  [2XSubFRMachine[0m  ([14X3.5-9[0m)),  the  machine of the product is the machine of [3Xm[0m. In
  case the machine of [3Xm[0m embeds in the machine of [3Xn[0m, the machine of the product
  is  the machine of [3Xn[0m. Otherwise the machine of the product is the product of
  the machines of [3Xm[0m and [3Xn[0m (See [2X\*[0m ([14X3.5-3[0m)).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;[0X
    [4Xgap> tau*tau; tau^2;[0X
    [4X<2|tau^2>[0X
    [4X<2|tau^2>[0X
    [4Xgap> [2,2,2]^(tau^2);[0X
    [4X[ 2, 1, 1 ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X4.2-17 \[\][0m
  
  [2X> \[\]( [0X[3Xm, i[0X[2X ) _______________________________________________________[0Xmethod
  [2X> \{\}( [0X[3Xm, l[0X[2X ) _______________________________________________________[0Xmethod
  [6XReturns:[0X  A [list of] FR element[s] with initial state [3Xi[0m.
  
  These     are     respectively     synonyms     for    [10XFRElement(m,i)[0m    and
  [10XList(l,s->FRElement(m,s))[0m. The argument [3Xm[0m must be an FR machine, [3Xi[0m must be a
  positive integer, and [3Xl[0m must be a list.
  
