  
  [1X3 Basic orbit enumeration[0X
  
  This package contains a new implementation of the standard orbit enumeration
  algorithm. The design principles for this implementation have been:
  
  --    Allow partial orbit enumeration and later continuation.
  
  --    Consequently use hashing techniques.
  
  --    Implement stabiliser calculation and Schreier transversals on demand.
  
  --    Allow for searching in orbits during orbit enumeration.
  
  Some  of  these  design  principles  made  it  necessary  to change the user
  interface in comparison to the standard [5XGAP[0m one.
  
  
  [1X3.1 Enumerating orbits[0X
  
  The  enumeration  of  an  orbit works in at least two stages: First an orbit
  object  is created with all the necessary information to describe the orbit.
  Then  the actual enumeration is started. The latter stage can be repeated as
  many times as needed in the case that the orbit enumeration stopped for some
  reason  before the orbit was enumerated completely. See below for conditions
  under which this happens.
  
  For orbit object creation there is the following function:
  
  [1X3.1-1 Orb[0m
  
  [2X> Orb( [0X[3Xgens, point, op[, opt][0X[2X ) ____________________________________[0Xfunction
  [6XReturns:[0X  An orbit object
  
  The  argument  [3Xgens[0m  is either a [5XGAP[0m group object or a list of generators of
  the  group  acting,  [3Xpoint[0m is a point in the orbit to be enumerated, [3Xop[0m is a
  [5XGAP[0m  function describing the action of the generators on points in the usual
  way,  that  is, [10X[3Xop[0m[10X(p,g)[0m returns the result of the action of the element [10Xg[0m on
  the point [10Xp[0m.
  
  The  optional  argument  [3Xopt[0m  is  a [5XGAP[0m record which can contain quite a few
  options  changing  the orbit enumeration. For a list of possible options see
  Subsection [14X3.1-4[0m at the end of this section.
  
  The  function  returns an "orbit" object that can later be used to enumerate
  (a  part  of)  the orbit of [3Xpoint[0m under the action of the group generated by
  [3Xgens[0m.
  
  If  [3Xgens[0m  is  a  group  object, then its generators are taken as the list of
  generators  acting.  If  the  group object knows its size, then this size is
  used to speed up orbit and in particular stabiliser computations.
  
  The following operation actually starts the orbit enumeration:
  
  [1X3.1-2 Enumerate[0m
  
  [2X> Enumerate( [0X[3Xorb[, limit][0X[2X ) _______________________________________[0Xoperation
  [6XReturns:[0X  The orbit object [3Xorb[0m
  
  [3Xorb[0m  must  be  an orbit object created by [2XOrb[0m ([14X3.1-1[0m). The optional argument
  [3Xlimit[0m  must  be a positive integer meaning that the orbit enumeration should
  stop  if  [3Xlimit[0m  points  have  been  found,  regardless whether the orbit is
  complete  or  not. Note that the orbit enumeration can be continued by again
  calling the [2XEnumerate[0m operation. If the argument [3Xlimit[0m is omitted, the whole
  orbit is enumerated, unless other options lead to prior termination.
  
  To see whether an orbit is closed you can use the following filter:
  
  [1X3.1-3 IsClosed[0m
  
  [2X> IsClosed( [0X[3Xorb[0X[2X ) ____________________________________________________[0Xfilter
  [6XReturns:[0X  [9Xtrue[0m or [9Xfalse[0m
  
  The result indicates, whether the orbit [3Xorb[0m is already complete or not.
  
  Here is an example of an orbit enumeration:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> g := GeneratorsOfGroup(MathieuGroup(24)); [0X
    [4X[ (1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23), [0X
    [4X  (3,17,10,7,9)(4,13,14,19,5)(8,18,11,12,23)(15,20,22,21,16), [0X
    [4X  (1,24)(2,23)(3,12)(4,16)(5,18)(6,10)(7,20)(8,14)(9,21)(11,17)[0X
    [4X  (13,22)(15,19) [0X
    [4X ][0X
    [4Xgap> o := Orb(g,2,OnPoints);[0X
    [4X<open Int-orbit, 1 points>[0X
    [4Xgap> Enumerate(o,20);[0X
    [4X<open Int-orbit, 21 points>[0X
    [4Xgap> IsClosed(o);[0X
    [4Xfalse[0X
    [4Xgap> Enumerate(o);   [0X
    [4X<closed Int-orbit, 24 points>[0X
    [4Xgap> IsClosed(o);    [0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  The  orbit object [10Xo[0m now behaves like an immutable dense list, the entries of
  which are the points in the orbit in the order as they were found during the
  orbit  enumeration  (note  that  this  is  not always true when one uses the
  function  [2XAddGeneratorsToOrbit[0m  ([14X3.1-15[0m)).  So you can ask the orbit for its
  length,  access entries, and ask, whether a given point lies in the orbit or
  not.  Due  to  the hashing techniques used such lookups are quite fast, they
  usually only use a constant time regardless of the length of the orbit!
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> Length(o);[0X
    [4X24[0X
    [4Xgap> o[1];[0X
    [4X2[0X
    [4Xgap> o[2];[0X
    [4X3[0X
    [4Xgap> o{[3..5]};[0X
    [4X[ 23, 4, 17 ][0X
    [4Xgap> 17 in o;[0X
    [4Xtrue[0X
    [4Xgap> Position(o,17);[0X
    [4X5[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X3.1-4 Options for orbits[0X
  
  The optional fourth argument [3Xopt[0m of the function [2XOrb[0m ([14X3.1-1[0m) is a [5XGAP[0m record
  and  its  components  change the behaviour of the orbit enumeration. In this
  subsection  we explain the use of the components of this options record. All
  components are themselves optional. For every component we also describe the
  possible values in the following list:
  
  [8X[10Xeqfunc[0m[8X[0m
        This  component  always  has  to  be given together with the component
        [10Xhashfunc[0m.  If  both are given, they are used to set up a hash table to
        store  the  points in the orbit. You have to use this if the automatic
        mechanism  to  find  a  suitable  hash function does not work for your
        starting point in the orbit.
  
        Note  that  if  you  use  this  feature,  the  hash  table cannot grow
        automatically  any  more, unless you also use the components [10Xhfbig[0m and
        [10Xhfdbig[0m  as  well.  See  the  description  of  [2XGrowHT[0m  ([14X4.3-5[0m)  for  an
        explanation how to use this feature.
  
  [8X[10Xgenstoapply[0m[8X[0m
        This is only used internally and is intentionally not documented.
  
  [8X[10Xgrpsizebound[0m[8X[0m
        Possible  values  for this component are positive integers. By setting
        this value one can help the orbit enumeration to complete earlier. The
        given number must be an upper bound for the order of the group. If the
        exact group order is given and the stabiliser is calculated during the
        orbit enumeration (see component [10Xpermgens[0m), then the orbit enumeration
        can  stop  as soon as the orbit is found completely and the stabiliser
        is  complete,  which  is usually much earlier than after all generator
        are applied to all points in the orbit.
  
  [8X[10Xhashfunc[0m[8X[0m
        See component [10Xeqfunc[0m.
  
  [8X[10Xhashlen[0m[8X[0m
        Possible  values  are positive integers. This component determines the
        initial  size  of the hash used for the orbit enumeration. The default
        value is 10000. If the hash table turns out not to be large enough, it
        is  automatically increased by a factor of two during the calculation.
        Although  this  process is quite fast it still improves performance to
        give a sensible hash size in advance.
  
  [8X[10Xhfbig[0m[8X and [10Xhfdbig[0m[8X[0m
        These  components  can  only  be  used  in  connection with [10Xeqfunc[0m and
        [10Xhashfunc[0m  and are otherwise ignored. There values are simply passed on
        to  the  hash  table created. The idea is to still be able to grow the
        hash table if need be. See Section [14X4.4[0m for more details.
  
  [8X[10Xlog[0m[8X[0m
        If  this component is set to [9Xtrue[0m then a log of the enumeration of the
        orbit  is  written  into  the components [10Xlog[0m, [10Xlogind[0m and [10Xlogpos[0m. Every
        time  a  new  point is found in the orbit enumeration, two numbers are
        appended  to  the log, first the number of the generator applied, then
        the  index, under which the new point is stored in the orbit. For each
        point  in the orbit, the start of the entries for that point in [10Xlog[0m is
        stored in [10Xlogind[0m and the end of those entries is marked by storing the
        number of the last generator producing a new point negated.
  
        The  purpose  of  a log is the following: With a log one can later add
        group  generators to the orbit and thus get a different Schreier tree,
        such  that  the  resulting  orbit enumeration is still a breadth first
        enumeration  using  the  new  generating  set!  This  is  desirable to
        decrease  the  depth  of the Schreier tree. The log helps to implement
        this  in  a  way, such that the old generators do not again have to be
        applied  to  all  the  points  in  the orbit. See [2XAddGeneratorsToOrbit[0m
        ([14X3.1-15[0m) for details.
  
        A log needs roughly 3 machine words per point in the orbit as memory.
  
  [8X[10Xlookingfor[0m[8X[0m
        This  component is used to search for something in the orbit. The idea
        is  that  the orbit enumeration is stopped when some condition is met.
        This  condition  can  be specified with a great flexibility. The first
        way is to store a list of points into [10Xorb.lookingfor[0m. In that case the
        orbit enumeration stops, when a point is found that is in that list. A
        second possiblity is to store a hash table object into [10Xorb.lookingfor[0m.
        Then  every  newly  found point in the orbit is looked up in that hash
        table and the orbit enumeration stops as soon as a point is found that
        is  also  in  the hash table. The third possibility is functional: You
        can store a [5XGAP[0m function into [10Xopt.lookingfor[0m which is called for every
        newly  found point in the orbit. It gets both the orbit object and the
        point  as its two arguments. This function has to return [9Xfalse[0m or [9Xtrue[0m
        and in the latter case the orbit enumeration is stopped.
  
        Whenever  the  orbit enumeration is stopped the component [10Xfound[0m is set
        to the number of the found point in the orbit. Access this information
        using [10XPositionOfFound(orb)[0m.
  
  [8X[10Xmatgens[0m[8X[0m
        This is not yet implemented. It will allow for stabiliser computations
        in matrix groups.
  
  [8X[10Xonlystab[0m[8X[0m
        If  this  boolean flag is set to [9Xtrue[0m then the orbit enumeration stops
        once  the stabiliser is completely determined. Note that this can only
        be   known,   if   a  bound  for  the  group  size  is  given  in  the
        [10Xopt.grpsizebound[0m  option  and  when  more  than  half  of the orbit is
        already found, or when [10Xopt.stabsizebound[0m is given.
  
  [8X[10Xorbsizebound[0m[8X[0m
        Possible  values  for  this component are positive integers. The given
        number must be an upper bound for the orbit length. Giving this number
        helps  the  orbit enumeration to stop earlier, when the orbit is found
        completely.
  
  [8X[10Xpermbase[0m[8X[0m
        This  component  is  used  to tell the orbit enumerator that a certain
        list  of  points  is a base of the permutation representation given in
        the  [10Xopt.permgens[0m  component.  This  information  is  often  available
        beforehand  and  can  drastically speed up the calculation of Schreier
        generators,  especially for the common case that they are trivial. The
        value is just a list of integers.
  
  [8X[10Xpermgens[0m[8X[0m
        If  this  component  is set, it must be set to a list of permutations,
        that  represent  the  same  group as the generators used to define the
        orbit.  This  permutation representation is then used to calculate the
        stabiliser  of  the  starting  point.  After  the orbit enumeration is
        complete, you can call [10XStabilizer([3Xorb[0m[10X)[0m with [3Xorb[0m being the orbit object
        and  get the stabiliser as a permutation group. The stabiliser is also
        stored  in  the  [10Xstab[0m  component of the orbit object. Furthermore, the
        size  of  the  stabiliser  is  stored in the [10Xstabsize[0m component of the
        orbit  object  and  the  component  [10Xstabwords[0m  contains the stabiliser
        generators  as  words  in  the original group generators. Access these
        words  with  [10XStabWords(orb)[0m. Here, a word is a list of integers, where
        positive  integers  are numbers of generators and a negative integer i
        indicates  the  inverse  of the generator with number -i. In this way,
        complete  information  about  the  stabiliser  can be derived from the
        orbit object.
  
  [8X[10Xreport[0m[8X[0m
        Possible  values  are  non-negative  integers.  This  value asks for a
        status   report   whenever  the  orbit  enumeration  has  applied  all
        generators  to  [10Xopt.report[0m points. A value of 0, which is the default,
        switches  off  this report. In each report, the total number of points
        already found are given.
  
  [8X[10Xschreier[0m[8X[0m
        This  boolean flag decides, whether a Schreier tree is stored together
        with  the  orbit.  A  Schreier  tree just stores for each point, which
        generator  was  applied  to  which other point in the orbit to get it.
        Thus,  having  the  Schreier  tree enables the usage of the operations
        [2XTraceSchreierTreeForward[0m  ([14X3.1-11[0m) and [2XTraceSchreierTreeBack[0m ([14X3.1-12[0m).
        A Schreier tree needs two additional machine words of memory per point
        in  the  orbit.  The  [10Xopt.schreier[0m  flag  is  automatically set when a
        stabiliser  is  computed  during  orbit  enumeration  (see  components
        [10Xopt.permgens[0m and [10Xopt.matgens[0m).
  
  [8X[10Xschreiergenaction[0m[8X[0m
        The  value  of this component must be a function with 4 arguments: the
        orbit  object,  an  index  [3Xi[0m,  an  integer  [3Xj[0m, and an index [3Xpos[0m. It is
        called,  whenever  during the orbit enumeration generator number [3Xj[0m was
        applied  to  point  number [3Xi[0m and the result was an already known point
        with   number  [3Xpos[0m.  This  is  no  longer  done,  once  the  component
        [10Xstabcomplete[0m is set to [9Xtrue[0m, which happens when there is evidence that
        the stabiliser is already completely determined.
  
        This  component is used internally when the [10Xpermgens[0m component was set
        and the stabiliser is calculated.
  
  [8X[10Xstab[0m[8X[0m
        This component is used to tell the orbit enumerator that a subgroup of
        the  stabiliser  of  the  starting  point  is  already  known. Store a
        subgroup  of  the  group generated by the permutations in [10Xopt.permgens[0m
        stabilising the starting point into this component.
  
  [8X[10Xstabchainrandom[0m[8X[0m
        This  value  can  be  a  positive  integer  between  1  and  1000.  If
        [10Xopt.permgens[0m  is  given,  an  integer  value is used to set the [10Xrandom[0m
        option  when calculating a stabiliser chain to compute the size of the
        group  generated  by  the  Schreier  generators.  Although  this  size
        computation  can  be speeded up considerably, the user should be aware
        that  for  values  smaller  than  1000  this  triggers  a  Monte Carlo
        algorithm  that  can  produce  wrong  results  with  a  certain  error
        probability. A verification of the obtained results is advisable. Note
        however,  that such computations can only err in one direction, namely
        underestimating the size of the group.
  
  [8X[10Xstabsizebound[0m[8X[0m
        Possible  values  for  this component are positive integers. The given
        number  must  be an upper bound for the size of the stabiliser. Giving
        this  number  helps  the  orbit enumeration to stop earlier, when also
        [10Xopt.orbsizebound[0m or [10Xopt.grpsizebound[0m are given or when [10Xopt.onlystab[0m is
        set.
  
  [8X[10Xstorenumbers[0m[8X[0m
        This  boolean  flag  decides,  whether  the positions of points in the
        orbit  are  stored in the hash. The memory requirement for this is one
        machine word (4 or 8 bytes depending on the architecture) per point in
        the orbit. If you just need the orbit itself this is not necessary. If
        you  however  want  to  find  the  position  of  a  point in the orbit
        efficiently  after  enumeration,  then you should switch this on. That
        is, the operation [10X\in[0m is always fast, but [10XPosition([3Xorb[0m[10X, [3Xpoint[0m[10X)[0m is only
        fast if [10Xopt.storenumbers[0m was set to [9Xtrue[0m or the orbit is "permutations
        acting on positive integers". In the latter case this flag is ignored.
  
  For some examples using these options see Chapter [14X10[0m.
  
  
  [1X3.1-5 Output components of orbits[0X
  
  The  following  components are bound in an orbit object. There might be some
  more,  but  those are implementation specific and not guaranteed to be there
  in  future versions. Note that you have to access these components using the
  "[10X.~[0m"  dot  exclamation  mark notation and you should avoid using these if at
  all possible.
  
  [8X[10Xdepth[0m[8X and [10Xdepthmarks[0m[8X[0m
        If  the  orbit has either a Schreier tree or a log, then the component
        [10Xdepth[0m  holds  its  depth,  that  is  the  maximal  number of generator
        applications needed to reach any point in the orbit. The corresponding
        component  [10Xdepthmarks[0m is a list of indices, at position i it holds the
        index of the first point in the orbit in depth i in the Schreier tree.
  
  [8X[10Xgens[0m[8X[0m
        The list of group generators.
  
  [8X[10Xht[0m[8X[0m
        If the orbit uses a hash table it is stored in this component.
  
  [8X[10Xop[0m[8X[0m
        The operation function.
  
  [8X[10Xorbind[0m[8X[0m
        If  generators  have  been  added to the orbit later then the order in
        which the points are actually stored in the orbit might not correspond
        to  a  breadth  first search. To cover this case, the component [10Xorbind[0m
        contains  in  position  i  the index under which the i-th point in the
        breadth-first  search  using the new generating set is actually stored
        in the orbit.
  
  [8X[10Xschreiergen[0m[8X and [10Xschreierpos[0m[8X[0m
        If  a  Schreier  tree of the orbit was kept then both these components
        are lists containing integers. If point number i was found by applying
        generator number j to point number p then position i of [10Xschreiergen[0m is
        j  and  position  i  of  [10Xschreierpos[0m  is p. You can use the operations
        [2XTraceSchreierTreeForward[0m  ([14X3.1-11[0m)  and [2XTraceSchreierTreeBack[0m ([14X3.1-12[0m)
        to compute words in the generators using these two components.
  
  [8X[10Xtab[0m[8X[0m
        For  an  orbit  in  which  permutations  act on positive integers this
        component is bound to a list containing in position i the index in the
        orbit, where the number i is stored.
  
  The  following  operations  help  to  ask additional information about orbit
  objects:
  
  [1X3.1-6 StabWords[0m
  
  [2X> StabWords( [0X[3Xorb[0X[2X ) ________________________________________________[0Xoperation
  [6XReturns:[0X  A list of words
  
  If  the  stabiliser  was  computed  during  the orbit enumeration, then this
  function returns the stabiliser generators found as words in the generators.
  A  word  is  a  sequence  of  integers,  where  positive  integers stand for
  generators and negative numbers for their inverses.
  
  [1X3.1-7 PositionOfFound[0m
  
  [2X> PositionOfFound( [0X[3Xorb[0X[2X ) __________________________________________[0Xoperation
  [6XReturns:[0X  An integer
  
  If during the orbit enumeration the option [10Xlookingfor[0m was used and the orbit
  enumerator  looked  for  something, then this operation returns the index in
  the orbit, where the something was found most recently.
  
  [1X3.1-8 DepthOfSchreierTree[0m
  
  [2X> DepthOfSchreierTree( [0X[3Xorb[0X[2X ) ______________________________________[0Xoperation
  [6XReturns:[0X  An integer
  
  If  a  Schreier tree or a log was stored during orbit enumeration, then this
  operation returns the depth of the Schreier tree.
  
  We  present  a  few  more  operations one can do with orbit objects. One can
  express  the  action  of a given group element in the group generated by the
  generators given in the [10XOrb[0m command on this orbit as a permutation:
  
  [1X3.1-9 ActionOnOrbit[0m
  
  [2X> ActionOnOrbit( [0X[3Xorb, grpels[0X[2X ) ____________________________________[0Xoperation
  [6XReturns:[0X  A permutation or [9Xfail[0m
  
  [3Xorb[0m  must  be  an orbit object and [3Xgrpels[0m a list of group elements acting on
  the  orbit.  This  operation  calculates  the action of [3Xgrpels[0m on [3Xorb[0m as [5XGAP[0m
  permutations,  where the numbering of the points is in the same order as the
  points   have  been  found  in  the  orbit.  Note  that  this  operation  is
  particularly  fast if the orbit is an orbit of a permutation group acting on
  positive  integers  or  if  you  used  the  option [10Xstorenumbers[0m described in
  Subsection [14X3.1-4[0m.
  
  [1X3.1-10 OrbActionHomomorphism[0m
  
  [2X> OrbActionHomomorphism( [0X[3Xg, orb[0X[2X ) _________________________________[0Xoperation
  [6XReturns:[0X  An action homomorphism
  
  The  argument  [3Xg[0m  must  be  a  group and [3Xorb[0m an orbit on which [3Xg[0m acts in the
  action  of  the  orbit  object. This operation returns a homomorphism into a
  permutation group acquired by taking the action of [3Xg[0m on the orbit.
  
  [1X3.1-11 TraceSchreierTreeForward[0m
  
  [2X> TraceSchreierTreeForward( [0X[3Xorb, nr[0X[2X ) _____________________________[0Xoperation
  [6XReturns:[0X  A word in the generators
  
  [3Xorb[0m  must  be  an  orbit  object  with  a Schreier tree, that is, the option
  [10Xschreier[0m  must have been set during creation, and [3Xnr[0m must be the number of a
  point  in  the  orbit. This operation traces the Schreier tree and returns a
  word in the generators that maps the starting point to the point with number
  [3Xnr[0m.  Here, a word is a list of integers, where positive integers are numbers
  of  generators  and  a  negative  integer  i  indicates  the  inverse of the
  generator with number -i.
  
  [1X3.1-12 TraceSchreierTreeBack[0m
  
  [2X> TraceSchreierTreeBack( [0X[3Xorb, nr[0X[2X ) ________________________________[0Xoperation
  [6XReturns:[0X  A word in the generators
  
  [3Xorb[0m  must  be  an  orbit  object  with  a Schreier tree, that is, the option
  [10Xschreier[0m  must have been set during creation, and [3Xnr[0m must be the number of a
  point  in  the  orbit. This operation traces the Schreier tree and returns a
  word  in  the  generators that maps the point with number [3Xnr[0m to the starting
  point.  As above, a word is here a list of integers, where positive integers
  are  numbers of generators and a negative integer i indicates the inverse of
  the generator with number -i.
  
  [1X3.1-13 ActWithWord[0m
  
  [2X> ActWithWord( [0X[3Xgens, w, op, p[0X[2X ) ___________________________________[0Xoperation
  [6XReturns:[0X  A point
  
  [3Xgens[0m  must be a list of group generators, [3Xw[0m a list of positive integers less
  than  or  equal  to the length of [3Xgens[0m, [3Xop[0m an action function and [3Xp[0m a point.
  This  operation  computes the action of the word [3Xw[0m in the generators [3Xgens[0m on
  the point [3Xp[0m and returns the result.
  
  [1X3.1-14 EvaluateWord[0m
  
  [2X> EvaluateWord( [0X[3Xgens, w[0X[2X ) _________________________________________[0Xoperation
  [6XReturns:[0X  A group element
  
  [3Xgens[0m  must be a list of group generators, [3Xw[0m a list of positive integers less
  than  or equal to the length of [3Xgens[0m. This operation evaluates the word [3Xw[0m in
  the generators [3Xgens[0m and returns the result.
  
  [1X3.1-15 AddGeneratorsToOrbit[0m
  
  [2X> AddGeneratorsToOrbit( [0X[3Xorb, l[, p][0X[2X ) _____________________________[0Xoperation
  [6XReturns:[0X  The orbit object [3Xorb[0m
  
  [3Xorb[0m  must  be  an  orbit object, [3Xl[0m a list of new generators and, if given, [3Xp[0m
  must  be a list of permutations of equal length. [3Xp[0m must be given if and only
  if  the  component [10Xpermgens[0m was specified upon creation of the orbit object.
  The  new  generators  are  appended to the old list of generators. The orbit
  object  is  changed  such  that it then shows the outcome of a breadth-first
  orbit  enumeration  with  the [13Xnew[0m list of generators. Note that the order of
  the  points  already  enumerated  will [13Xnot[0m be changed. However, the Schreier
  tree changes, the component [10Xorbind[0m is changed to indicate the order in which
  the  points  were  found in the breadth-first search with the new generators
  and the components [10Xdepth[0m and [10Xdepthmarks[0m are changed.
  
  Note  that all this is particularly efficient if the orbit has a log. If you
  add  generators  to  an orbit with log, the old generators do not have to be
  applied again to all points!
  
  Note  that  new  generators can actually enlarge an orbit if they generate a
  larger group than the old ones alone. Note also that when adding generators,
  the orbit is automatically enumerated completely
  
  [1X3.1-16 MakeSchreierTreeShallow[0m
  
  [2X> MakeSchreierTreeShallow( [0X[3Xorb[, d][0X[2X ) _____________________________[0Xoperation
  [6XReturns:[0X  The orbit object [3Xorb[0m
  
  Uses  [2XAddGeneratorsToOrbit[0m  ([14X3.1-15[0m)  to add more generators to the orbit in
  order  to make the Schreier tree shallower. If [3Xd[0m it is given, generators are
  added  until  the  depth  is  less  than  or  equal to [3Xd[0m or until three more
  generators  did  not  reduce the depth any more. If [3Xd[0m is not given, then the
  logarithm to base 2 of the orbit length is taken as a default value.
  
  [1X3.1-17 FindSuborbits[0m
  
  [2X> FindSuborbits( [0X[3Xorb, subgens[, nrsuborbits][0X[2X ) ____________________[0Xoperation
  [6XReturns:[0X  A record
  
  The  argument  [3Xorb[0m  must  be  a  closed orbit object with a Schreier vector,
  [3Xsubgens[0m  a list of generators for a subgroup of the originally acting group.
  If given, [3Xnrsuborbits[0m must be a lower limit for the number of suborbits.
  
  The  returned record describes the suborbit structure of [3Xorb[0m with respect to
  the   group   generated   by   [3Xsubgens[0m   using   the  following  components:
  [10Xissuborbitrecord[0m  is  bound to [9Xtrue[0m, [10Xo[0m is bound to [3Xorb[0m, [10Xnrsuborbits[0m is bound
  to  the  number  of  suborbits  and  [10Xreps[0m  is  a  list of length [10Xnrsuborbits[0m
  containing  the  index  in  the orbit of a representative for each suborbit.
  Likewise, [10Xwords[0m contains words in the original group generators of the orbit
  that map the starting point of the orbit to those representatives. [10Xlens[0m is a
  list containing the lengths of the suborbits. The component [10Xsuborbs[0m is bound
  to  a  list  of  lists,  one for each suborbit containing the indices of the
  points  in  the orbit. The component [10Xsuborbnr[0m is a list with the same length
  as  the  orbit, containing in position i the number of the suborbit in which
  point i in the orbit is contained.
  
  Finally,   the   component  [10Xconjsuborbit[0m  is  bound  to  a  list  of  length
  [10Xnrsuborbits[0m,  containing  for  each suborbit the number the suborbit reached
  from  the  starting point by the inverse of the word used to reach the orbit
  representative.  This  latter information probably only makes sense when the
  subgroup  generated  by  [3Xsubgens[0m is contained in the point stabiliser of the
  starting  point  of  the orbit, because then this is the so-called conjugate
  suborbit of a suborbit.
  
  [1X3.1-18 OrbitIntersectionMatrix[0m
  
  [2X> OrbitIntersectionMatrix( [0X[3Xr, g[0X[2X ) _________________________________[0Xoperation
  [6XReturns:[0X  An integer matrix
  
  The  argument  [3Xr[0m  must  be  a  suborbit  record as returned by the operation
  [2XFindSuborbits[0m  ([14X3.1-17[0m) above, describing the suborbit structure of an orbit
  with  respect  to a subgroup. [3Xg[0m must be an element of the acting group. If k
  is  the  number  of  suborbits and the suborbits are O_1, ..., O_k, then the
  matrix  returned  by this operation has the integer |O_i * [3Xg[0m cap O_j| in its
  (i,j)-entry.
  
