  
  [1X12 Miscellanea[0X
  
  
  [1X12.1 Helpers[0X
  
  [1X12.1-1 TensorSum[0m
  
  [2X> TensorSum( [0X[3Xobjects, ...[0X[2X ) ________________________________________[0Xfunction
  
  This   function   is   similar   in   syntax  to  [2XDirectProduct[0m  ([14XReference:
  DirectProduct[0m),  and  delegates  to  [10XTensorSumOp[0m;  its  meaning  depends  on
  context, see e.g. [2XTensorSumOp[0m ([14X3.5-4[0m).
  
  [1X12.1-2 TensorProduct[0m
  
  [2X> TensorProduct( [0X[3Xobjects, ...[0X[2X ) ____________________________________[0Xfunction
  
  This   function   is   similar   in   syntax  to  [2XDirectProduct[0m  ([14XReference:
  DirectProduct[0m),  and  delegates  to  [10XTensorProductOp[0m; its meaning depends on
  context, see e.g. [2XTensorProductOp[0m ([14X3.5-5[0m).
  
  [1X12.1-3 DirectSum[0m
  
  [2X> DirectSum( [0X[3Xobjects, ...[0X[2X ) ________________________________________[0Xfunction
  
  This   function   is   similar   in   syntax  to  [2XDirectProduct[0m  ([14XReference:
  DirectProduct[0m),  and  delegates  to  [10XDirectSumOp[0m;  its  meaning  depends  on
  context, see e.g. [2XDirectSumOp[0m ([14X3.5-6[0m).
  
  [1X12.1-4 PeriodicList[0m
  
  [2X> PeriodicList( [0X[3Xpreperiod[, period][0X[2X ) _____________________________[0Xoperation
  [2X> PeriodicList( [0X[3Xlist, i[0X[2X ) _________________________________________[0Xoperation
  [2X> PeriodicList( [0X[3Xlist, f[0X[2X ) _________________________________________[0Xoperation
  [2X> CompressedPeriodicList( [0X[3Xpreperiod[, period][0X[2X ) ___________________[0Xoperation
  [2X> CompressedPeriodicList( [0X[3Xlist, i[0X[2X ) _______________________________[0Xoperation
  [2X> PrePeriod( [0X[3Xlist[0X[2X ) _______________________________________________[0Xoperation
  [2X> Period( [0X[3Xlist[0X[2X ) __________________________________________________[0Xoperation
  
  These  functions  manipulate  [13Xperiodic  lists[0m, i.e. lists of infinite length
  such that elements follow a periodic order after some point.
  
  The  first  command  creates a periodic list, specified by its preperiod and
  period,  which must both be lists. If the period is absent, this is actually
  a finite list.
  
  The  second  command  creates  a periodic list by decreeing that the entries
  after the end of the list start again at position [3Xi[0m.
  
  The  third  command creates a list by applying function [3Xf[0m to all elements of
  [3Xl[0m.
  
  The  fourth  and fifth command compress the newly created periodic list, see
  [2XCompressPeriodicList[0m ([14X12.1-5[0m).
  
  The  sixth and seventh commands return respectively the preperiod and period
  of a periodic list.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> l := PeriodicList([1],[2,3,4]);[0X
    [4X[ 1, / 2, 3, 4 ][0X
    [4Xgap> l[5];[0X
    [4X2[0X
    [4Xgap> Add(l,100,3); l;[0X
    [4X[ 1, 2, 100, / 3, 4, 2 ][0X
    [4Xgap> Remove(l,5);[0X
    [4X4[0X
    [4Xgap> l;[0X
    [4X[ 1, 2, 100, 3, / 2, 3, 4 ][0X
    [4Xgap> PrePeriod(l);[0X
    [4X[ 1, 2, 100, 3 ][0X
    [4Xgap> Period(l);[0X
    [4X[ 2, 3, 4 ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X12.1-5 CompressPeriodicList[0m
  
  [2X> CompressPeriodicList( [0X[3Xl[0X[2X ) _______________________________________[0Xoperation
  
  This  function  compresses  a  periodic  list,  in replacing the period by a
  minimal  period, and shortening the preperiod. No value is returned, but the
  list [3Xl[0m is modified. It remains equal (under [10X=[0m) to the original list.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> l := PeriodicList([1],[2,3,4,2,3,4]);[0X
    [4X[ 1, / 2, 3, 4, 2, 3, 4 ][0X
    [4Xgap> Add(l,4,5); l;[0X
    [4X[ 1, 2, 3, 4, 4, / 2, 3, 4, 2, 3, 4 ][0X
    [4Xgap> CompressPeriodicList(l);[0X
    [4Xgap> l;[0X
    [4X[ 1, 2, 3, 4, / 4, 2, 3 ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X12.1-6 IsConfinal[0m
  
  [2X> IsConfinal( [0X[3Xl, m[0X[2X ) ______________________________________________[0Xoperation
  [6XReturns:[0X  [9Xtrue[0m if [3Xl[0m and [3Xm[0m are eventually equal.
  
  This  function  tests  whether  two  lists are [13Xconfinal[0m, i.e. whether, after
  removal of the same suitable number of elements from both lists, they become
  equal.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> l := PeriodicList([1],[2,3,2,3]);[0X
    [4X[ 1, / 2, 3, 2, 3 ][0X
    [4Xgap> m := PeriodicList([0,1],[3,2]);[0X
    [4X[ 0, 1, / 3, 2 ][0X
    [4Xgap> IsConfinal(l,m);[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  [1X12.1-7 ConfinalityClass[0m
  
  [2X> ConfinalityClass( [0X[3Xl[0X[2X ) ___________________________________________[0Xoperation
  [6XReturns:[0X  The strictly periodic list with same tail as [3Xl[0m.
  
  There  exists  a  unique periodic list, with no preperiod, which is confinal
  (see  [2XIsConfinal[0m  ([14X12.1-6[0m)) to [3Xl[0m. This strictly periodic list is returned by
  this command.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> l := PeriodicList([1],[2,3,2,3]);[0X
    [4X[ 1, / 2, 3, 2, 3 ][0X
    [4Xgap> ConfinalityClass(l);[0X
    [4X[/ 3, 2 ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X12.1-8 LargestCommonPrefix[0m
  
  [2X> LargestCommonPrefix( [0X[3Xc[0X[2X ) ________________________________________[0Xoperation
  [6XReturns:[0X  The longest list that is a prefix of all elements of [3Xc[0m.
  
  This  command  computes  the  longest  (finite  or periodic) list which is a
  prefix  of  all  elements of [3Xc[0m. The argument [3Xc[0m is a collection of finite and
  periodic lists.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> LargestCommonPrefix([PeriodicList([1],[2,3,2,3]),[1,2,3,4]]);[0X
    [4X[ 1, 2, 3 ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X12.1-9 WordGrowth[0m
  
  [2X> WordGrowth( [0X[3Xg, rec(options...)[0X[2X ) _________________________________[0Xfunction
  [2X> WordGrowth( [0X[3Xg:options...[0X[2X ) _______________________________________[0Xfunction
  [2X> OrbitGrowth( [0X[3Xg, point[, limit][0X[2X ) _________________________________[0Xfunction
  [2X> Ball( [0X[3Xg, radius[0X[2X ) ________________________________________________[0Xfunction
  [2X> Sphere( [0X[3Xg, radius[0X[2X ) ______________________________________________[0Xfunction
  [6XReturns:[0X  The word growth of the semigroup [3Xg[0m.
  
  This  function computes the first terms of growth series associated with the
  semigroup  [3Xg[0m.  The argument [3Xg[0m can actually be a group/monoid/semigroup, or a
  list representing that semigroup's generating set.
  
  The  behaviour  of [10XWordGrowth[0m is controlled via options passed in the second
  argument, which is a record. They can be combined when reasonable, and are:
  
  [8X[10Xlimit:=n[0m[8X[0m
        to specify a limit radius;
  
  [8X[10Xsphere:=radius[0m[8X[0m
        to  return  the  sphere  of  the specified radius, unless a radius was
        specified in [10Xlimit[0m, in which case the value is ignored;
  
  [8X[10Xspheres:=maxradius[0m[8X[0m
        to  return  the  list of spheres of radius between 0 and the specified
        limit;
  
  [8X[10Xspheresizes:=maxradius[0m[8X[0m
        to  return  the  list  sizes  of  spheres  of radius between 0 and the
        specified limit;
  
  [8X[10Xball:=radius[0m[8X[0m
        to return the ball of the specified radius;
  
  [8X[10Xballs:=maxradius[0m[8X[0m
        to  return  the  list  of  balls of radius between 0 and the specified
        limit;
  
  [8X[10Xballsizes:=maxradius[0m[8X[0m
        to  return  the  list  sizes  of  balls  of  radius  between 0 and the
        specified limit;
  
  [8X[10Xindet:=z[0m[8X[0m
        to  return  the  [10Xspheresizes[0m,  as  a  polynomial  in  [10Xz[0m  (or the first
        indeterminate if [10Xz[0m is not a polynomial;
  
  [8X[10Xdraw:=filename[0m[8X[0m
        to  create  a  rendering  of  the  Cayley  graph of [3Xg[0m. Edges are given
        colours  according  to  the  cyclic  ordering  "red", "blue", "green",
        "gray", "yellow", "cyan", "orange", "purple". If [10Xfilename[0m is a string,
        the  graph  is  appended,  in [9Xdot[0m format, to that file. Otherwise, the
        output  is  converted  to  Postscript using the program [9Xneato[0m from the
        [5Xgraphviz[0m  package,  and  displayed  in  a  separate X window using the
        program [5Xdisplay[0m. This works on UNIX systems.
  
        It is assumed, but not checked, that [5Xgraphviz[0m and [5Xdisplay[0m are properly
        installed on the system.
  
  [8X[10Xpoint:=p[0m[8X[0m
        to  compute  the  growth  of  the  orbit of [10Xp[0m under [3Xg[0m, rather than the
        growth of [3Xg[0m.
  
  [8X[10Xtrack:=true[0m[8X[0m
        to keep track of a word in the generators that gives the element. This
        affects  the  "ball",  "balls", "sphere" and "spheres" commands, where
        the  result  returned  is  a  3-element  list:  the first entry is the
        original  results;  the  second  entry  is  a homomorphism from a free
        group/monoid/semigroup;   and  the  third  entry  contains  the  words
        corresponding to the first entry via the homomorphism.
  
  If  the  first  argument  is  an  integer [10Xn[0m and not a record, the command is
  interpreted as [10XWordGrowth(...,rec(spheresizes:=n))[0m.
  
  [10XWordGrowth(...,rec(draw:=true))[0m    may    be   abbreviated   as   [10XDraw(...)[0m;
  [10XWordGrowth(...,rec(ball:=n))[0m    may    be    abbreviated   as   [10XBall(...,n)[0m;
  [10XWordGrowth(...,rec(sphere:=n))[0m may be abbreviated as [10XSphere(...,n)[0m;
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> WordGrowth(GrigorchukGroup,4);[0X
    [4X[ 1, 4, 6, 12, 17 ][0X
    [4Xgap> WordGrowth(GrigorchukGroup,rec(limit:=4,indet:=true));[0X
    [4X17*x_1^4+12*x_1^3+6*x_1^2+4*x_1+1[0X
    [4Xgap> WordGrowth(GrigorchukGroup,rec(limit:=1,spheres:=true));[0X
    [4X[ [ <Mealy element on alphabet [ 1, 2 ] with 1 state, initial state 1> ],[0X
    [4X  [ d, b, c, a ] ][0X
    [4Xgap> WordGrowth(GrigorchukGroup,rec(point:=[2,2,2]));[0X
    [4X[ 1, 1, 1, 1, 1, 1, 1, 1 ][0X
    [4Xgap> OrbitGrowth(GrigorchukGroup,[1,1,1]);[0X
    [4X[ 1, 2, 2, 1, 1, 1 ][0X
    [4Xgap> WordGrowth(GrigorchukGroup,rec(spheres:=4,point:=PeriodicList([],[2])));[0X
    [4X[ [ [/ 2 ] ], [ [ 1, / 2 ] ], [ [ 1, 1, / 2 ] ], [ [ 2, 1, / 2 ] ],[0X
    [4X  [ [ 2, 1, 1, / 2 ] ] ][0X
    [4Xgap> WordGrowth([(1,2),(2,3)],rec(spheres:=infinity,track:=true));[0X
    [4X[ [ [  ], [ (2,3), (1,2) ], [ (), (1,2,3), (1,3,2) ], [ (1,3) ] ],[0X
    [4X  MappingByFunction( <free semigroup on the generators [ s1, s2 ]>, <group>, function( w ) ... end ),[0X
    [4X  [ [  ], [ s2, s1 ], [ s2^2, s2*s1, s1*s2 ], [ s2*s1*s2 ] ] ][0X
  [4X------------------------------------------------------------------[0X
  
  Note  that  the  orbit  growth  of [10X[/2][0m is constant 1, while that of [10X[/1][0m is
  constant  2.  The  following  code  would  find the point with maximal orbit
  growth  of a semigroup acting on the integers (for example, constructed with
  [2XPermGroup[0m ([14X7.2-1[0m)):
  
  [4X------------------------------------------------------------------[0X
    [4XMaximalOrbitGrowth := function(g)[0X
    [4X    local maxpt, growth, max;[0X
    [4X    maxpt := LargestMovedPoint(g);[0X
    [4X    growth := List([1..maxpt],n->WordGrowth(g:point:=n));[0X
    [4X    max := Maximum(growth);[0X
    [4X    return [max,Filtered([1..maxpt],n->growth[n]=max)];[0X
    [4Xend;[0X
  [4X------------------------------------------------------------------[0X
  
  For                   example,                  the                  command
  [10XDraw(BasilicaGroup,rec(point:=PeriodicList([],[2,1]),limit:=3));[0m    produces
  (in a new window) the following picture:
  
  [1X12.1-10 ShortGroupRelations[0m
  
  [2X> ShortGroupRelations( [0X[3Xg, n[0X[2X ) _____________________________________[0Xoperation
  [2X> ShortMonoidRelations( [0X[3Xg, n[0X[2X ) ____________________________________[0Xoperation
  [6XReturns:[0X  A list of relations between words over [3Xg[0m, of length at most [3Xn[0m.
  
  This  function  assumes that [3Xg[0m is a list of monoid elements. it searches for
  products of at most [3Xn[0m elements over [3Xg[0m that are equal.
  
  In  its first form, it returns a list of words in a free group [10Xf[0m of rank the
  length  of  [3Xg[0m,  that are trivial in [3Xg[0m. The first argument may be a group, in
  which case its symmetric generating set is considered.
  
  In  its  second  form,  it  returns a list of pairs [10X[l,r][0m, where [10Xl[0m and [10Xr[0m are
  words  in  a free monoid [10Xf[0m of rank the length of [3Xg[0m, that are equal in [3Xg[0m. The
  first  argument  may be a monoid, in which case its monoid generating set is
  considered.
  
  This  command  does not construct all such pairs; rather, it returns a small
  set,  in  the  hope  that  it  may  serve  as  a presentation for the monoid
  generated by [3Xg[0m.
  
  The  first  element of the list returned is actually not a relation: it is a
  homomorphism from [10Xf[0m to [the group/monoid generated by] [3Xg[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> ShortGroupRelations(GrigorchukGroup,10);[0X
    [4X[ [ x1, x2, x3, x4 ] -> [ a, b, c, d ],[0X
    [4X  x1^2, x2^2, x3^2, x4^2, x2*x3*x4, x4*x1*x4*x1*x4*x1*x4*x1,[0X
    [4X  x3*x1*x3*x1*x3*x1*x3*x1*x3*x1*x3*x1*x3*x1*x3*x1 ][0X
    [4Xgap> ShortGroupRelations(GuptaSidkiGroup,9);[0X
    [4X[ [ x1, x2 ] -> [ x, gamma ],[0X
    [4X  x1^3, x2^3, x2*x1^-1*x2*x1^-1*x2*x1^-1*x2*x1^-1*x2*x1^-1*x2*x1^-1*[0X
    [4X     x2*x1^-1*x2*x1^-1*x2*x1^-1,    x1^-1*x2^-1*x1^-1*x2^-1*x1^-1*x2^-1*[0X
    [4Xx1^-1*x2^-1*x1^-1*x2^-1*x1^-1*x2^-1*x1^-1*x2^-1*x1^-1*x2^-1*x1^-1*x2^-1 ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X12.1-11 ShortGroupWordInSet[0m
  
  [2X> ShortGroupWordInSet( [0X[3Xg, s, n[0X[2X ) __________________________________[0Xoperation
  [2X> ShortMonoidWordInSet( [0X[3Xg, s, n[0X[2X ) _________________________________[0Xoperation
  [2X> ShortSemigroupWordInSet( [0X[3Xg, s, n[0X[2X ) ______________________________[0Xoperation
  [6XReturns:[0X  Words over [3Xg[0m that express elements of [3Xs[0m.
  
  This  command produces words in the free group/monoid/semigroup generated by
  [3Xg[0m's  generators  that  express  elements of the set [3Xs[0m. Elements of length at
  most  [3XAbsoluteValue(n)[0m  are  searched; if [3Xn[0m is non-negative then at most one
  element is returned. The value [10X[3Xn[0m[10X=infinity[0m is allowed.
  
  The  second  argument  may  be  either  a list, a predicate (i.e. a function
  returning [9Xtrue[0m or [9Xfalse[0m) or an element.
  
  The function returns a list of words in the free group/monoid/semigroup; the
  first    entry   of   the   list   is   a   homomorphism   from   the   free
  group/monoid/semigroup to [3Xg[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> l := ShortMonoidWordInSet(Group((1,2),(2,3),(3,4)),[0X
    [4X            [(1,2,3,4),(4,3,2,1)],-3);[0X
    [4X[ MappingByFunction( <free monoid on the generators [ m1, m2, m3 ]>, Group([0X
    [4X    [ (1,2), (2,3), (3,4) ]), function( w ) ... end ), m3*m2*m1, m1*m2*m3 ][0X
    [4Xgap> f := Remove(l,1);;[0X
    [4Xgap> List(l,x->x^f);[0X
    [4X[ (1,2,3,4), (1,4,3,2) ][0X
    [4Xgap> ShortMonoidWordInSet(GrigorchukGroup,[0X
    [4X       [Comm(GrigorchukGroup.1,GrigorchukGroup.2)],4);[0X
    [4X[ MappingByFunction( <free monoid on the generators [ m1, m2, m3, m4[0X
    [4X     ]>, <self-similar monoid over [ 1 .. 2 ] with[0X
    [4X    4 generators>, function( w ) ... end ), m1*m2*m1*m2 ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X12.1-12 SurfaceBraidFpGroup[0m
  
  [2X> SurfaceBraidFpGroup( [0X[3Xn, g, p[0X[2X ) ___________________________________[0Xfunction
  [2X> PureSurfaceBraidFpGroup( [0X[3Xn, g, p[0X[2X ) _______________________________[0Xfunction
  [6XReturns:[0X  The [pure] surface braid group on [3Xn[0m strands.
  
  This  function  creates a finitely presented group, isomorphic to the [pure]
  braid  group  on  [3Xn[0m  strands of the surface of genus [3Xg[0m, with [3Xp[0m punctures. In
  particular,  [10XSurfaceBraidFpGroup(n,0,1)[0m  is  the  usual  braid group (on the
  disc).
  
  The  presentation  comes  from  [Bel04].  The  first  2g  generators are the
  standard a_i,b_i surface generators; the next n-1 are the standard s_i braid
  generators; and the last are the extra z generators.
  
  The  pure  surface  braid  group  is  the kernel of the natural map from the
  surface  braid  group to the symmetric group on [3Xn[0m points, defined by sending
  a_i,b_i,z to the identity and s_i to the transposition [10X(i,i+1)[0m.
  
  [1X12.1-13 CharneyBraidFpGroup[0m
  
  [2X> CharneyBraidFpGroup( [0X[3Xn[0X[2X ) _________________________________________[0Xfunction
  [6XReturns:[0X  The braid group on [3Xn[0m strands.
  
  This  function  creates  a finitely presented group, isomorphic to the braid
  group    on    [3Xn[0m    strands   (on   the   disc).   It   is   isomorphic   to
  [10XSurfaceBraidFpGroup(n,0,1)[0m, but has a different presentation, due to Charney
  ([Cha95]), with one generator per non-trivial permutation of [3Xn[0m points.
  
  [1X12.1-14 ArtinRepresentation[0m
  
  [2X> ArtinRepresentation( [0X[3Xn[0X[2X ) _________________________________________[0Xfunction
  [6XReturns:[0X  The braid group's representation on [10XFreeGroup(n)[0m.
  
  This function creates a Artin's representatin, a homomorphism from the braid
  group on [3Xn[0m strands (on the disc) into the automorphism group of a free group
  of rank [3Xn[0m.
  
  [1X12.1-15 StringByInt[0m
  
  [2X> StringByInt( [0X[3Xn[, b][0X[2X ) ____________________________________________[0Xfunction
  [6XReturns:[0X  A string representing [3Xn[0m in base [3Xb[0m.
  
  This  function converts a positive integer to string. It accepts an optional
  second argument, which is a base in which to print [3Xn[0m. By default, [3Xb[0m is 2.
  
  [1X12.1-16 PositionInTower[0m
  
  [2X> PositionInTower( [0X[3Xt, x[0X[2X ) __________________________________________[0Xfunction
  [6XReturns:[0X  The largest index such that [10Xt[i][0m contains [3Xx[0m.
  
  This  function  assumes  [3Xt[0m  is  a  descending tower of domains, such as that
  constructed  by  [10XLowerCentralSeries[0m.  It  returns the largest integer [10Xi[0m such
  that  [10Xt[i][0m  contains  [3Xx[0m;  in case the tower ends precisely with [3Xx[0m, the value
  [9Xinfinity[0m is returned.
  
  [3Xx[0m can be an element or a subdomain of [10Xt[1][0m.
  
  [1X12.1-17 RenameSubobjects[0m
  
  [2X> RenameSubobjects( [0X[3Xobj, refobj[0X[2X ) __________________________________[0Xfunction
  
  This  function traverses [3Xobj[0m if it is a list or a record, and, when it finds
  an element which has no name, but is equal (in the sense of [10X=[0m) to an element
  of [3Xrefobj[0m, assigns it the name of that element.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> trivial := Group(());; SetName(trivial,"trivial");[0X
    [4Xgap> a := List([1..10],i->Group(Random(SymmetricGroup(3))));[0X
    [4X[ Group([ (2,3) ]), Group([ (2,3) ]), Group([ (1,3) ]), Group([ (1,3) ]),[0X
    [4X  Group([ (1,3,2) ]), Group([ (1,3,2) ]), Group([ (1,2) ]), Group(()),[0X
    [4X  Group([ (2,3) ]), Group([ (1,3,2) ]) ][0X
    [4Xgap> RenameSubobjects(a,[trivial]); a;[0X
    [4X[ Group([ (2,3) ]), Group([ (2,3) ]), Group([ (1,3) ]), Group([ (1,3) ]),[0X
    [4X  Group([ (1,3,2) ]), Group([ (1,3,2) ]), Group([ (1,2) ]), trivial,[0X
    [4X  Group([ (2,3) ]), Group([ (1,3,2) ]) ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X12.1-18 CoefficientsInAbelianExtension[0m
  
  [2X> CoefficientsInAbelianExtension( [0X[3Xx, b, G[0X[2X ) ________________________[0Xfunction
  [6XReturns:[0X  The coefficients in [3Xb[0m of the element [3Xx[0m, modulo [3XG[0m.
  
  If  [3Xb[0m  is  a  list  of  group  elements  b_1,...,b_k, and H=< G,b_1,...,b_k>
  contains  [3XG[0m  as  a  normal subgroup, and H/G is abelian and xin H, then this
  function computes exponents e_1,...,e_k such that prod b_i^e_iG=xG.
  
  [1X12.1-19 MagmaEndomorphismByImagesNC[0m
  
  [2X> MagmaEndomorphismByImagesNC( [0X[3Xf, im[0X[2X ) _____________________________[0Xfunction
  [6XReturns:[0X  An endomorphism of [3Xf[0m.
  
  This  function constructs an endomorphism of the group,monoid or semigroup [3Xf[0m
  specified  by  sending  generator  number  i to the ith entry in [3Xim[0m. It is a
  shortcut     for     a     call     to     [10XGroupHomomorphismByImagesNC[0m    or
  [10XMagmaHomomorphismByFunctionNC(...,MappedWord(...))[0m.
  
  [1X12.1-20 MagmaHomomorphismByImagesNC[0m
  
  [2X> MagmaHomomorphismByImagesNC( [0X[3Xf, g, im[0X[2X ) __________________________[0Xfunction
  [6XReturns:[0X  An homomorphism from [3Xf[0m to [3Xg[0m.
  
  This  function  constructs a homomorphism of the group,monoid or semigroup [3Xf[0m
  specified  by  sending  generator  number  i to the ith entry in [3Xim[0m. It is a
  shortcut     for     a     call     to     [10XGroupHomomorphismByImagesNC[0m    or
  [10XMagmaHomomorphismByFunctionNC(...,MappedWord(...))[0m.
  
  [1X12.1-21 NewFIFO[0m
  
  [2X> NewFIFO( [0X[3X[l][0X[2X ) __________________________________________________[0Xoperation
  [2X> Add( [0X[3Xf, i[0X[2X ) _____________________________________________________[0Xoperation
  [2X> Append( [0X[3Xf, l[0X[2X ) __________________________________________________[0Xoperation
  
  These  functions  create  and  extend  FIFOs,  i.e.  first-in first-out data
  structures.
  
  The first command creates a FIFO, with an optional list initializing it.
  
  The second and third commands add an element, or append a list, to the FIFO.
  
  Elements  are  removed  via  [10XNextIterator(f)[0m,  and  the  FIFO  is tested for
  emptyness  via [10XIsDoneIterator(f)[0m. Thus, a typical use is the following code,
  which  tests  in  breadth-first  manner that all numbers in [10X[1..1000][0m have a
  successor which is prime:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> f := NewFIFO([1..10000]);[0X
    [4X<iterator>[0X
    [4Xgap> for i in f do if not IsPrime(i) then Add(f,i+1); fi; od;[0X
  [4X------------------------------------------------------------------[0X
  
  [1X12.1-22 ProductIdeal[0m
  
  [2X> ProductIdeal( [0X[3Xa, b[0X[2X ) _____________________________________________[0Xfunction
  [2X> ProductBOIIdeal( [0X[3Xa, b[0X[2X ) __________________________________________[0Xfunction
  [6XReturns:[0X  the product of the ideals [3Xa[0m and [3Xb[0m.
  
  The  first  command  computes  the product of the left ideal [3Xa[0m and the right
  ideal  [3Xb[0m.  If  they  are  not  appropriately-sided ideals, the command first
  attempts to convert them.
  
  The second command assumes that the ring of these ideals has a basis made of
  invertible elements. It is then much easier to compute the product.
  
  [1X12.1-23 DimensionSeries[0m
  
  [2X> DimensionSeries( [0X[3Xa[, n][0X[2X ) ________________________________________[0Xfunction
  [6XReturns:[0X  A nested list of ideals in the algebra-with-one [3Xa[0m.
  
  This command computes the powers of the augmentation ideal of [3Xa[0m, and returns
  their list. The list stops when the list becomes stationary.
  
  The  optional second argument gives a limit to the number of terms to put in
  the series.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> a := ThinnedAlgebraWithOne(GF(2),GrigorchukGroup);[0X
    [4X<self-similar algebra-with-one on alphabet GF(2)^2 with 4 generators>[0X
    [4Xgap> q := MatrixQuotient(a,3);[0X
    [4X<algebra-with-one of dimension 22 over GF(2)>[0X
    [4Xgap> l := DimensionSeries(q);[0X
    [4X[ <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (5 generators)>,[0X
    [4X  <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 21)>,[0X
    [4X  <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 18)>,[0X
    [4X  <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 14)>,[0X
    [4X  <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 10)>,[0X
    [4X  <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 6)>,[0X
    [4X  <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 3)>,[0X
    [4X  <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 1)>,[0X
    [4X  <algebra of dimension 0 over GF(2)> ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X12.1-24 Trans[0m
  
  [2X> Trans( [0X[3Xlist, ...[0X[2X ) _______________________________________________[0Xfunction
  
  This  function  creates  a  new  transformation, in the family [10XTRANS_FAMILY[0m.
  These  objects  behave  quite  as  usual transformations (see [2XTransformation[0m
  ([14XReference: Transformation[0m)); the differences are that these transformations
  do  not  have  a bounded set on which they operate; they are all part of one
  family,  and  act  on  [10XPosInt[0m.  The  other difference is that, when they are
  invertible, these transformations are simply permutations.
  
  If  one  argument  is  passed,  it  is  a  list  of  images,  as in [2XPermList[0m
  ([14XReference:  PermList[0m). If two arguments are passed and both are lists, they
  are  the  source  and  range,  as in [2XPermListList[0m ([14XReference: PermListList[0m).
  Finally, if two arguments are passed and the second is a function, the first
  argument  is  treated  as  the  source  and  the range is computed with this
  function.
  
  Transformations are printed, and converted to strings, as [10X"<x,y,...>"[0m, where
  the  [10Xx,y,...[0m  denote  the  images  of  [10X1,2,...[0m under the transformation; the
  shortest possible list is printed.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> Trans();[0X
    [4X<>[0X
    [4Xgap> Trans([1,,2]);[0X
    [4X<1,2,2>[0X
    [4Xgap> 3^last;[0X
    [4X2[0X
    [4Xgap> Trans([1,3,3]);[0X
    [4X<1,3>[0X
    [4Xgap> Trans([10,11],[11,12]);[0X
    [4X<1,2,3,4,5,6,7,8,9,11,12>[0X
    [4Xgap> Trans([10,11],x->x^2);[0X
    [4X<1,2,3,4,5,6,7,8,9,100,121>[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X12.2 User settings[0X
  
  [1X12.2-1 InfoFR[0m
  
  [2X> InfoFR__________________________________________________________[0Xinfo class
  
  This    is    an    [9XInfo[0m   class   for   the   package   [5XFR[0m.   The   command
  [10XSetInfoLevel(InfoFR,1);[0m  switches on the printing of some information during
  the  computations  of  certain  [5XFR[0m  functions;  in  particular all automatic
  conversions between FR machines and Mealy machines.
  
  The  command [10XSetInfoLevel(InfoFR,2);[0m requests a little more information, and
  in  particular  prints intermediate results in potentially long calculations
  such as [2XNucleusOfFRSemigroup[0m ([14X7.2-17[0m).
  
  The  command  [10XSetInfoLevel(InfoFR,3);[0m ensures that [5XFR[0m will print information
  every  few seconds or so. This is useful to gain confidence that the program
  is not stuck due to a programming bug by the author of [5XFR[0m.
  
  [1X12.2-2 SEARCH@[0m
  
  [2X> SEARCH@____________________________________________________[0Xglobal variable
  
  This  variable  controls  the  search mechanism in FR groups. It is a record
  with in particular entries [10Xradius[0m and [10Xdepth[0m.
  
  [10Xradius[0m  limits  the  search  in  FR  groups  to  balls of that radius in the
  generating  set. For example, the command [10Xx in G[0m will initiate a search in [10XG[0m
  to attempt to express [10Xx[0m as a reasonably short word in the generators of [10XG[0m.
  
  [10Xdepth[0m limits the level of the tree on which quotients of FR groups should be
  considered.  Again  for the command [10Xx in G[0m, deeper and deeper quotients will
  be  considered,  in  the hope of finding a quotient of [10XG[0m to which [10Xx[0m does not
  belong.
  
  A  primitive mechanism is implemented to search alternatively for a quotient
  disproving [10Xx in G[0m and a word proving [10Xx in G[0m.
  
  When  the limits are reached and the search was unsuccessful, an interactive
  [10XError()[0m is raised, to let the user increase their values.
  
  Specific  limits  can  be  passed to any command via the options [10XFRdepth[0m and
  [10XFRradius[0m, as for example in [10XSize(G:FRdepth:=3,FRradius:=5)[0m.
  
