  
  [1X3 [33X[0;0YBasic orbit enumeration[133X[101X
  
  [33X[0;0YThis package contains a new implementation of the standard orbit enumeration
  algorithm. The design principles for this implementation have been:[133X
  
  [30X    [33X[0;6YAllow partial orbit enumeration and later continuation.[133X
  
  [30X    [33X[0;6YConsequently use hashing techniques.[133X
  
  [30X    [33X[0;6YImplement stabiliser calculation and Schreier transversals on demand.[133X
  
  [30X    [33X[0;6YAllow for searching in orbits during orbit enumeration.[133X
  
  [33X[0;0YSome  of  these  design  principles  made  it  necessary  to change the user
  interface in comparison to the standard [5XGAP[105X one.[133X
  
  
  [1X3.1 [33X[0;0YEnumerating orbits[133X[101X
  
  [33X[0;0YThe  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.[133X
  
  [33X[0;0YFor orbit object creation there is the following function:[133X
  
  [1X3.1-1 Orb[101X
  
  [29X[2XOrb[102X( [3Xgens[103X, [3Xpoint[103X, [3Xop[103X[, [3Xopt[103X] ) [32X function
  [6XReturns:[106X  [33X[0;10YAn orbit object[133X
  
  [33X[0;0YThe  argument  [3Xgens[103X  is  either a [5XGAP[105X group, semigroup or monoid object or a
  list  of generators of the magma acting, [3Xpoint[103X is a point in the orbit to be
  enumerated,  [3Xop[103X is a [5XGAP[105X function describing the action of the generators on
  points  in  the usual way, that is, [10X[3Xop[103X[10X(p,g)[110X returns the result of the action
  of the element [10Xg[110X on the point [10Xp[110X.[133X
  
  [33X[0;0YNote  that  in the case of a semigroup or monoid acting not all options make
  sense  (for  example  stabilisers  only  work  for groups). In this case the
  [21Xdirected[121X or [21Xweak[121X orbit is computed.[133X
  
  [33X[0;0YThe  optional  argument  [3Xopt[103X  is  a [5XGAP[105X record which can contain quite a few
  options  changing  the orbit enumeration. For a list of possible options see
  Subsection [14X3.1-4[114X at the end of this section.[133X
  
  [33X[0;0YThe  function returns an [21Xorbit[121X object that can later be used to enumerate (a
  part of) the orbit of [3Xpoint[103X under the action of the group generated by [3Xgens[103X.[133X
  
  [33X[0;0YIf  [3Xgens[103X  is  a  group,  semigroup or monoid object, then its generators are
  taken  as  the  list of generators acting. If a group object knows its size,
  then  this  size  is  used  to  speed  up orbit and in particular stabiliser
  computations.[133X
  
  [33X[0;0YThe following operation actually starts the orbit enumeration:[133X
  
  [1X3.1-2 Enumerate[101X
  
  [29X[2XEnumerate[102X( [3Xorb[103X[, [3Xlimit[103X] ) [32X operation
  [6XReturns:[106X  [33X[0;10YThe orbit object [3Xorb[103X[133X
  
  [33X[0;0Y[3Xorb[103X  must  be  an orbit object created by [2XOrb[102X ([14X3.1-1[114X). The optional argument
  [3Xlimit[103X  must  be a positive integer meaning that the orbit enumeration should
  stop  if  [3Xlimit[103X  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[102X operation. If the argument [3Xlimit[103X is omitted, the whole
  orbit is enumerated, unless other options lead to prior termination.[133X
  
  [33X[0;0YTo see whether an orbit is closed you can use the following filter:[133X
  
  [1X3.1-3 IsClosed[101X
  
  [29X[2XIsClosed[102X( [3Xorb[103X ) [32X filter
  [6XReturns:[106X  [33X[0;10Y[9Xtrue[109X or [9Xfalse[109X[133X
  
  [33X[0;0YThe result indicates, whether the orbit [3Xorb[103X is already complete or not.[133X
  
  [33X[0;0YHere is an example of an orbit enumeration:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27Xg := GeneratorsOfGroup(MathieuGroup(24)); [127X[104X
    [4X[28X[ (1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23), [128X[104X
    [4X[28X  (3,17,10,7,9)(4,13,14,19,5)(8,18,11,12,23)(15,20,22,21,16), [128X[104X
    [4X[28X  (1,24)(2,23)(3,12)(4,16)(5,18)(6,10)(7,20)(8,14)(9,21)(11,17)[128X[104X
    [4X[28X  (13,22)(15,19) [128X[104X
    [4X[28X ][128X[104X
    [4X[25Xgap>[125X [27Xo := Orb(g,2,OnPoints);[127X[104X
    [4X[28X<open Int-orbit, 1 points>[128X[104X
    [4X[25Xgap>[125X [27XEnumerate(o,20);[127X[104X
    [4X[28X<open Int-orbit, 21 points>[128X[104X
    [4X[25Xgap>[125X [27XIsClosed(o);[127X[104X
    [4X[28Xfalse[128X[104X
    [4X[25Xgap>[125X [27XEnumerate(o);   [127X[104X
    [4X[28X<closed Int-orbit, 24 points>[128X[104X
    [4X[25Xgap>[125X [27XIsClosed(o);    [127X[104X
    [4X[28Xtrue[128X[104X
  [4X[32X[104X
  
  [33X[0;0YThe  orbit object [10Xo[110X 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[102X  ([14X3.1-20[114X)).  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![133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XLength(o);[127X[104X
    [4X[28X24[128X[104X
    [4X[25Xgap>[125X [27Xo[1];[127X[104X
    [4X[28X2[128X[104X
    [4X[25Xgap>[125X [27Xo[2];[127X[104X
    [4X[28X3[128X[104X
    [4X[25Xgap>[125X [27Xo{[3..5]};[127X[104X
    [4X[28X[ 23, 4, 17 ][128X[104X
    [4X[25Xgap>[125X [27X17 in o;[127X[104X
    [4X[28Xtrue[128X[104X
    [4X[25Xgap>[125X [27XPosition(o,17);[127X[104X
    [4X[28X5[128X[104X
  [4X[32X[104X
  
  
  [1X3.1-4 [33X[0;0YOptions for orbits[133X[101X
  
  [33X[0;0YThe optional fourth argument [3Xopt[103X of the function [2XOrb[102X ([14X3.1-1[114X) is a [5XGAP[105X 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:[133X
  
  [8X[10Xeqfunc[110X[108X
        [33X[0;6YThis  component  always  has  to  be given together with the component
        [10Xhashfunc[110X.  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.[133X
  
        [33X[0;6YNote  that  if  you  use  this  feature,  the  hash  table cannot grow
        automatically  any  more, unless you also use the components [10Xhfbig[110X and
        [10Xhfdbig[110X  as  well.  See  the  description  of  [2XGrowHT[102X  ([14X4.4-5[114X)  for  an
        explanation how to use this feature.[133X
  
  [8X[10Xgenstoapply[110X[108X
        [33X[0;6YThis is only used internally and is intentionally not documented.[133X
  
  [8X[10Xgradingfunc[110X[108X
        [33X[0;6YIf  this  component is bound it must be bound to a function taking two
        arguments,  the  first is the orbit object, the second is a new point.
        This function is called for every new point and is supposed to compute
        a  [21Xgrade[121X  for  the  point  which  can  be an arbitrary [5XGAP[105X object. The
        resulting  values  are  then  stored  in a list of equal length to the
        orbit  and can later be queried with the [2XGrades[102X ([14X3.1-11[114X) operation. If
        this  feature  is  used  the  orbit  object  will  lie  in  the filter
        [2XIsGradedOrbit[102X  ([14X3.1-10[114X).  In connection with the [10Xonlygrades[110X option the
        enumeration  of an orbit can be limited to points with certain grades,
        see below.[133X
  
  [8X[10Xgrpsizebound[110X[108X
        [33X[0;6YPossible  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[110X), 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.[133X
  
  [8X[10Xforflatplainlists[110X[108X
        [33X[0;6YIf this component is set to [9Xtrue[109X then the user guarantees that all the
        points  in  the  orbit  will be flat plain lists, that is, plain lists
        with  no  subobjects.  For  example  lists  of immediate integers will
        fulfill   this   requirement,  but  ranges  don't.  In  this  case,  a
        particularly  good  and  efficient hash function will automatically be
        taken  and  the components [10Xhf[110X, [10Xhfd[110X, [10Xhfbig[110X and [10Xhfdbig[110X are ignored. Note
        that this cannot be automatically detected because it depends not only
        on  the  first  point of the orbit but also on the other points in the
        orbit and thus on the group generators given.[133X
  
  [8X[10Xhashfunc[110X[108X
        [33X[0;6YThis  component  always  has  to  be  given  together  with the [10Xeqfunc[110X
        component  (see  also  there).  The  value  should  be  a  record with
        components  [10Xfunc[110X  and  [10Xdata[110X.  The  former is used as the hash function
        (component  [10Xhf[110X  in  the options to [2XHTCreate[102X ([14X4.3-1[114X)) and the latter as
        data argument (component [10Xhfd[110X). The length of the hash is determined by
        the  value of the component [10Xhashlen[110X. If a tree hash is to be used, the
        component  [10Xtreehashsize[110X has to be used instead of [10Xhashlen[110X. If you want
        to  use  a  hash  table that can grow automatically, use the [10Xhfbig[110X and
        [10Xhtdbig[110X  components  together  with  [10Xhashlen[110X  for the initial size. See
        [2XHTCreate[102X ([14X4.3-1[114X) for details.[133X
  
  [8X[10Xhashlen[110X[108X
        [33X[0;6YPossible  values  are positive integers. This component determines the
        initial  size  of the hash used for the orbit enumeration. The default
        value is [22X10000[122X. 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.[133X
  
  [8X[10Xhfbig[110X and [10Xhfdbig[110X[108X
        [33X[0;6YThese  components  can  only  be  used  in  connection with [10Xeqfunc[110X and
        [10Xhashfunc[110X  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.5[114X for more details.[133X
  
  [8X[10Xtreehashsize[110X[108X
        [33X[0;6YThis  component  indicates  that instead of a normal hash table a tree
        hash  table  (TreeHashTab) should be used (see Section [14X4.1[114X). If bound,
        it  must be set to the length of the tree hash table. You should still
        choose this length big enough, however, this type of hash table should
        be  more  resilient  to  bad  hash  functions since the performance of
        operations  will only deteriorate up to [22Xlog(n)[122X instead of to [22Xn[122X (number
        of  entries). If you use this option your hash keys must be comparable
        by  [10X<[110X  and not only by [10X=[110X. You can supply your own three-way comparison
        function (see [2XHTCreate[102X ([14X4.3-1[114X)) by using the [10Xcmpfunc[110X component.[133X
  
  [8X[10Xcmpfunc[110X[108X
        [33X[0;6YIf  the  previous  component  [10Xtreehashsize[110X is bound, you can specify a
        three-way comparison function for the hash keys in this component. See
        [2XHTCreate[102X ([14X4.3-1[114X) and [2XAVLCmp[102X ([14X8.2-2[114X) for details.[133X
  
  [8X[10Xlog[110X[108X
        [33X[0;6YIf  this component is set to [9Xtrue[109X then a log of the enumeration of the
        orbit  is  written  into  the components [10Xlog[110X, [10Xlogind[110X and [10Xlogpos[110X. 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[110X is
        stored in [10Xlogind[110X and the end of those entries is marked by storing the
        number of the last generator producing a new point negated.[133X
  
        [33X[0;6YThe  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[102X
        ([14X3.1-20[114X) for details.[133X
  
        [33X[0;6YA log needs roughly 3 machine words per point in the orbit as memory.[133X
  
  [8X[10Xlookingfor[110X[108X
        [33X[0;6YThis  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[110X. 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[110X.
        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[105X function into [10Xopt.lookingfor[110X 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[109X or [9Xtrue[109X
        and in the latter case the orbit enumeration is stopped.[133X
  
        [33X[0;6YWhenever  the  orbit enumeration is stopped the component [10Xfound[110X is set
        to the number of the found point in the orbit. Access this information
        using [10XPositionOfFound(orb)[110X.[133X
  
  [8X[10Xmatgens[110X[108X
        [33X[0;6YThis is not yet implemented. It will allow for stabiliser computations
        in matrix groups.[133X
  
  [8X[10Xonlygrades[110X[108X
        [33X[0;6YThis  option  is to limit the orbit enumeration to points with certain
        grades (see option [10Xgradingfunc[110X). The primary way to do this is to bind
        [10Xonlygrades[110X  to a function taking two arguments. The first is the grade
        value,  the  second  is  the  value bound to the option [10Xonlygradesdata[110X
        below. The function is then called for every new point after its grade
        is  computed.  If the function returns [9Xtrue[109X the point is stored in the
        orbit  as  usual,  if it returns [9Xfalse[109X the point is dropped. Note that
        using  this  option can (and ought to) lead to incomplete orbits which
        claim to be closed.[133X
  
        [33X[0;6YAs  a  shorthand  notation  one  can  bind a list or hash table to the
        component  [10Xonlygrades[110X.  In this case a standard membership test of the
        grade  value  in the list or hash table is performed to decide whether
        or not the point is stored. One does not have to assign [10Xonlygradesdata[110X
        in this case.[133X
  
  [8X[10Xonlygradesdata[110X[108X
        [33X[0;6YAs  described  above  this  component  holds  the  data for the second
        argument of the [10Xonlygrades[110X test function. See option [10Xonlygrades[110X above.[133X
  
  [8X[10Xonlystab[110X[108X
        [33X[0;6YIf  this  boolean flag is set to [9Xtrue[109X 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[110X  option  and  when  more  than  half  of the orbit is
        already found, or when [10Xopt.stabsizebound[110X is given.[133X
  
  [8X[10Xorbsizebound[110X[108X
        [33X[0;6YPossible  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.[133X
  
  [8X[10Xorbitgraph[110X[108X
        [33X[0;6YIf  this component is [9Xtrue[109X then the so called orbit graph is computed.
        The  vertices  of  this  graph  are  the  points  of the orbit and the
        (directed) edges are given by the generators acting. So if a generator
        [22Xg[122X maps point [22Xa[122X to [22Xb[122X then there is a directed edge from the vertex [22Xa[122X to
        the  vertex  [22Xb[122X.  This  graph can later be queried using the [2XOrbitGraph[102X
        ([14X3.1-12[114X)  and [2XOrbitGraphAsSets[102X ([14X3.1-13[114X) operations. The data format in
        which the graph is returned is described there.[133X
  
  [8X[10Xpermbase[110X[108X
        [33X[0;6YThis  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[110X  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.[133X
  
  [8X[10Xpermgens[110X[108X
        [33X[0;6YIf  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[103X[10X)[110X with [3Xorb[103X being the orbit object
        and  get the stabiliser as a permutation group. The stabiliser is also
        stored  in  the  [10Xstab[110X  component of the orbit object. Furthermore, the
        size  of  the  stabiliser  is  stored in the [10Xstabsize[110X component of the
        orbit  object  and  the  component  [10Xstabwords[110X  contains the stabiliser
        generators  as  words  in  the original group generators. Access these
        words  with  [10XStabWords(orb)[110X. Here, a word is a list of integers, where
        positive  integers  are numbers of generators and a negative integer [22Xi[122X
        indicates  the  inverse  of the generator with number [22X-i[122X. In this way,
        complete  information  about  the  stabiliser  can be derived from the
        orbit object.[133X
  
  [8X[10Xreport[110X[108X
        [33X[0;6YPossible  values  are  non-negative  integers.  This  value asks for a
        status   report   whenever  the  orbit  enumeration  has  applied  all
        generators  to  [10Xopt.report[110X points. A value of [22X0[122X, which is the default,
        switches  off  this report. In each report, the total number of points
        already found are given.[133X
  
  [8X[10Xschreier[110X[108X
        [33X[0;6YThis  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[102X  ([14X3.1-16[114X) and [2XTraceSchreierTreeBack[102X ([14X3.1-17[114X).
        A Schreier tree needs two additional machine words of memory per point
        in  the  orbit.  The  [10Xopt.schreier[110X  flag  is  automatically set when a
        stabiliser  is  computed  during  orbit  enumeration  (see  components
        [10Xopt.permgens[110X and [10Xopt.matgens[110X).[133X
  
  [8X[10Xschreiergenaction[110X[108X
        [33X[0;6YThe  value  of this component must be a function with 4 arguments: the
        orbit  object,  an  index  [3Xi[103X,  an  integer  [3Xj[103X, and an index [3Xpos[103X. It is
        called,  whenever  during the orbit enumeration generator number [3Xj[103X was
        applied  to  point  number [3Xi[103X and the result was an already known point
        with  number [3Xpos[103X. The function has to return [9Xtrue[109X or [9Xfalse[109X. The former
        case is used internally and triggers the evaluation of some conditions
        for  stabiliser  computations.  Simply return [9Xfalse[109X if you do not want
        this to happen.[133X
  
        [33X[0;6YOnce  the  component  [10Xstabcomplete[110X  is  set  to  [9Xtrue[109X during the orbit
        computation  (which happens when there is evidence that the stabiliser
        is  already completely determined), no more calls to [10Xschreiergenaction[110X
        happen.[133X
  
        [33X[0;6YThis  component  is mainly used internally when the [10Xpermgens[110X component
        was set and the stabiliser is calculated.[133X
  
  [8X[10Xseeds[110X[108X
        [33X[0;6YIn  this  component  you can specify a list of additional seed points,
        which are appended to the orbit before the enumeration starts.[133X
  
  [8X[10Xstab[110X[108X
        [33X[0;6YThis 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[110X
        stabilising the starting point into this component.[133X
  
  [8X[10Xstabchainrandom[110X[108X
        [33X[0;6YThis  value  can  be  a  positive  integer  between  [22X1[122X  and  [22X1000[122X.  If
        [10Xopt.permgens[110X  is  given,  an  integer  value is used to set the [10Xrandom[110X
        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  [22X1000[122X  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.[133X
  
  [8X[10Xstabsizebound[110X[108X
        [33X[0;6YPossible  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[110X or [10Xopt.grpsizebound[110X are given or when [10Xopt.onlystab[110X is
        set.[133X
  
  [8X[10Xstorenumbers[110X[108X
        [33X[0;6YThis  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 ([22X4[122X or [22X8[122X 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[110X is always fast, but [10XPosition([3Xorb[103X[10X, [3Xpoint[103X[10X)[110X is only
        fast  if [10Xopt.storenumbers[110X was set to [9Xtrue[109X or the orbit is [21Xpermutations
        acting on positive integers[121X. In the latter case this flag is ignored.[133X
  
  [33X[0;0YFor some examples using these options see Chapter [14X11[114X.[133X
  
  
  [1X3.1-5 [33X[0;0YOutput components of orbits[133X[101X
  
  [33X[0;0YThe  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
  [21X[10X.~[110X[121X  dot exclamation mark notation and you should avoid using these if at all
  possible.[133X
  
  [8X[10Xdepth[110X and [10Xdepthmarks[110X[108X
        [33X[0;6YIf  the  orbit has either a Schreier tree or a log, then the component
        [10Xdepth[110X  holds  its  depth,  that  is  the  maximal  number of generator
        applications needed to reach any point in the orbit. The corresponding
        component  [10Xdepthmarks[110X is a list of indices, at position [22Xi[122X it holds the
        index of the first point in the orbit in depth [22Xi[122X in the Schreier tree.[133X
  
  [8X[10Xgens[110X[108X
        [33X[0;6YThe list of group generators.[133X
  
  [8X[10Xht[110X[108X
        [33X[0;6YIf the orbit uses a hash table it is stored in this component.[133X
  
  [8X[10Xop[110X[108X
        [33X[0;6YThe operation function.[133X
  
  [8X[10Xorbind[110X[108X
        [33X[0;6YIf  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[110X
        contains  in  position  [22Xi[122X  the index under which the [22Xi[122X-th point in the
        breadth-first  search  using the new generating set is actually stored
        in the orbit.[133X
  
  [8X[10Xschreiergen[110X and [10Xschreierpos[110X[108X
        [33X[0;6YIf  a  Schreier  tree of the orbit was kept then both these components
        are lists containing integers. If point number [22Xi[122X was found by applying
        generator number [22Xj[122X to point number [22Xp[122X then position [22Xi[122X of [10Xschreiergen[110X is
        [22Xj[122X  and  position  [22Xi[122X  of  [10Xschreierpos[110X  is [22Xp[122X. You can use the operations
        [2XTraceSchreierTreeForward[102X  ([14X3.1-16[114X)  and [2XTraceSchreierTreeBack[102X ([14X3.1-17[114X)
        to compute words in the generators using these two components.[133X
  
  [8X[10Xtab[110X[108X
        [33X[0;6YFor  an  orbit  in  which  permutations  act on positive integers this
        component is bound to a list containing in position [22Xi[122X the index in the
        orbit, where the number [22Xi[122X is stored.[133X
  
  [33X[0;0YThe  following  operations  help  to  ask additional information about orbit
  objects:[133X
  
  [1X3.1-6 StabWords[101X
  
  [29X[2XStabWords[102X( [3Xorb[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YA list of words[133X
  
  [33X[0;0YIf  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.[133X
  
  [1X3.1-7 PositionOfFound[101X
  
  [29X[2XPositionOfFound[102X( [3Xorb[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YAn integer[133X
  
  [33X[0;0YIf during the orbit enumeration the option [10Xlookingfor[110X 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.[133X
  
  [1X3.1-8 UnderlyingPlist[101X
  
  [29X[2XUnderlyingPlist[102X( [3Xorb[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YAn plain list[133X
  
  [33X[0;0YThis returns the current elements in the orbit represented by [3Xorb[103X as a plain
  list.  This  is  guaranteed  to be a very fast operation using only constant
  time.  However,  it  does  give you a part of the internal data structure of
  [3Xorb[103X.  Note  that  it  is not allowed to change the resulting list in any way
  because that would corrupt the data structures of the orbit.[133X
  
  [1X3.1-9 DepthOfSchreierTree[101X
  
  [29X[2XDepthOfSchreierTree[102X( [3Xorb[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YAn integer[133X
  
  [33X[0;0YIf  a  Schreier tree or a log was stored during orbit enumeration, then this
  operation returns the depth of the Schreier tree.[133X
  
  [1X3.1-10 IsGradedOrbit[101X
  
  [29X[2XIsGradedOrbit[102X( [3Xorb[103X ) [32X filter
  [6XReturns:[106X  [33X[0;10Y[9Xtrue[109X or [9Xfalse[109X[133X
  
  [33X[0;0YIf the option [10Xgradingfunc[110X has been used when creating the orbit object, then
  a  [21Xgrade[121X  is  computed  for every point in the orbit. In this case the orbit
  object lies in this filter. The list of grades can then be queried using the
  [2XGrades[102X ([14X3.1-11[114X) operation below.[133X
  
  [1X3.1-11 Grades[101X
  
  [29X[2XGrades[102X( [3Xorb[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10Ya list of grades[133X
  
  [33X[0;0YIf the option [10Xgradingfunc[110X has been used when creating the orbit object, then
  a  [21Xgrade[121X  is computed for every point in the orbit. This operation retrieves
  the list of grades from the orbit object [3Xorb[103X. Note that this is in general a
  mutable  list which must not be changed. It needs to be mutable if the orbit
  enumeration  goes  on  and  this  operation  does not copy it for efficiency
  reasons.[133X
  
  [1X3.1-12 OrbitGraph[101X
  
  [29X[2XOrbitGraph[102X( [3Xorb[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10Ya list of lists[133X
  
  [33X[0;0YThe  vertices  of  the  orbit  graph  are  the  points  of the orbit and the
  (directed)  edges  are  given  by the generators acting. So if a generator [22Xg[122X
  maps  point  [22Xa[122X  to  [22Xb[122X then there is a directed edge from the vertex [22Xa[122X to the
  vertex  [22Xb[122X.  This  operation  returns  the  orbit  graph can in the following
  format:  The  result  is  a  list  of  equal length as the orbit. Each entry
  (corresponding  to  a  point  in  the  orbit) contains a list of orbit point
  numbers,  one  for  each  generator used for the orbit enumeration. That is,
  position [22X[i][j][122X in the list contains the number in the orbit of the image of
  orbit point number [22Xi[122X under the generator with number [22Xj[122X.[133X
  
  [33X[0;0YNote that if the [10Xgradingfunc[110X and [10Xonlygrades[110X options are used some entries in
  these lists can be unbound. This shows that some edges of the complete orbit
  graph  leave  the  part  of the orbit which has been enumerated by the grade
  restriction.[133X
  
  [1X3.1-13 OrbitGraphAsSets[101X
  
  [29X[2XOrbitGraphAsSets[102X( [3Xorb[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10Ya list of sets[133X
  
  [33X[0;0YThis  operation  returns the same graph as [2XOrbitGraph[102X ([14X3.1-12[114X) in a slightly
  different format. The neighbours of a point are reported as a set of numbers
  rather  than as a tuple. That is, position [22X[i][122X of the resulting lists is the
  set of numbers of the (directed) neighbours of point number [22Xi[122X.[133X
  
  [33X[0;0YWe  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[110X command on this orbit as a permutation:[133X
  
  [1X3.1-14 ActionOnOrbit[101X
  
  [29X[2XActionOnOrbit[102X( [3Xorb[103X, [3Xgrpels[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YA permutation or [9Xfail[109X[133X
  
  [33X[0;0Y[3Xorb[103X  must  be  an orbit object and [3Xgrpels[103X a list of group elements acting on
  the  orbit.  This  operation  calculates  the action of [3Xgrpels[103X on [3Xorb[103X as [5XGAP[105X
  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[110X described in
  Subsection [14X3.1-4[114X.[133X
  
  [1X3.1-15 OrbActionHomomorphism[101X
  
  [29X[2XOrbActionHomomorphism[102X( [3Xg[103X, [3Xorb[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YAn action homomorphism[133X
  
  [33X[0;0YThe  argument  [3Xg[103X  must  be  a  group and [3Xorb[103X an orbit on which [3Xg[103X acts in the
  action  of  the  orbit  object. This operation returns a homomorphism into a
  permutation group acquired by taking the action of [3Xg[103X on the orbit.[133X
  
  [1X3.1-16 TraceSchreierTreeForward[101X
  
  [29X[2XTraceSchreierTreeForward[102X( [3Xorb[103X, [3Xnr[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YA word in the generators[133X
  
  [33X[0;0Y[3Xorb[103X  must  be  an  orbit  object  with  a Schreier tree, that is, the option
  [10Xschreier[110X  must have been set during creation, and [3Xnr[103X 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[103X.  Here,  a  word  is  a  list  of  positive integers which are numbers of
  generators of the orbit.[133X
  
  [1X3.1-17 TraceSchreierTreeBack[101X
  
  [29X[2XTraceSchreierTreeBack[102X( [3Xorb[103X, [3Xnr[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YA word in the generators[133X
  
  [33X[0;0Y[3Xorb[103X  must  be  an  orbit  object  with  a Schreier tree, that is, the option
  [10Xschreier[110X  must have been set during creation, and [3Xnr[103X must be the number of a
  point  in  the  orbit. This operation traces the Schreier tree and returns a
  word in the inverses of the generators that maps the point with number [3Xnr[103X to
  the  starting  point.  As  above, a word is here a list of positive integers
  which are numbers of inverses of the generators of the orbit.[133X
  
  [1X3.1-18 ActWithWord[101X
  
  [29X[2XActWithWord[102X( [3Xgens[103X, [3Xw[103X, [3Xop[103X, [3Xp[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YA point[133X
  
  [33X[0;0Y[3Xgens[103X  must be a list of group generators, [3Xw[103X a list of positive integers less
  than  or  equal  to the length of [3Xgens[103X, [3Xop[103X an action function and [3Xp[103X a point.
  This  operation  computes the action of the word [3Xw[103X in the generators [3Xgens[103X on
  the point [3Xp[103X and returns the result.[133X
  
  [1X3.1-19 EvaluateWord[101X
  
  [29X[2XEvaluateWord[102X( [3Xgens[103X, [3Xw[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YA group element[133X
  
  [33X[0;0Y[3Xgens[103X  must be a list of group generators, [3Xw[103X a list of positive integers less
  than  or equal to the length of [3Xgens[103X. This operation evaluates the word [3Xw[103X in
  the generators [3Xgens[103X and returns the result.[133X
  
  [1X3.1-20 AddGeneratorsToOrbit[101X
  
  [29X[2XAddGeneratorsToOrbit[102X( [3Xorb[103X, [3Xl[103X[, [3Xp[103X] ) [32X operation
  [6XReturns:[106X  [33X[0;10YThe orbit object [3Xorb[103X[133X
  
  [33X[0;0Y[3Xorb[103X  must  be  an  orbit object, [3Xl[103X a list of new generators and, if given, [3Xp[103X
  must  be a list of permutations of equal length. [3Xp[103X must be given if and only
  if  the  component [10Xpermgens[110X 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[113X list of generators. Note that the order of
  the  points  already  enumerated  will [13Xnot[113X be changed. However, the Schreier
  tree changes, the component [10Xorbind[110X 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[110X and [10Xdepthmarks[110X are changed.[133X
  
  [33X[0;0YNote  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![133X
  
  [33X[0;0YNote  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[133X
  
  [1X3.1-21 MakeSchreierTreeShallow[101X
  
  [29X[2XMakeSchreierTreeShallow[102X( [3Xorb[103X[, [3Xd[103X] ) [32X operation
  [6XReturns:[106X  [33X[0;10Ynothing[133X
  
  [33X[0;0YThe  argument  [3Xorb[103X  must  be a closed orbit object with a log and a Schreier
  tree,  that  is,  the  options  [10Xlog[110X  and [10Xschreier[110X must have been set to true
  during creation.[133X
  
  [33X[0;0YUses  [2XAddGeneratorsToOrbit[102X  ([14X3.1-20[114X)  to add more generators to the orbit in
  order  to make the Schreier tree shallower. If [3Xd[103X it is given, generators are
  added  until  the  depth  is  less  than  or  equal to [3Xd[103X or until three more
  generators  did  not  reduce the depth any more. If [3Xd[103X is not given, then the
  logarithm to base 2 of the orbit length is taken as a default value.[133X
  
  [1X3.1-22 FindSuborbits[101X
  
  [29X[2XFindSuborbits[102X( [3Xorb[103X, [3Xsubgens[103X[, [3Xnrsuborbits[103X] ) [32X operation
  [6XReturns:[106X  [33X[0;10YA record[133X
  
  [33X[0;0YThe  argument  [3Xorb[103X  must  be  a  closed orbit object with a Schreier vector,
  [3Xsubgens[103X  a list of generators for a subgroup of the originally acting group.
  If given, [3Xnrsuborbits[103X must be a lower limit for the number of suborbits.[133X
  
  [33X[0;0YThe  returned record describes the suborbit structure of [3Xorb[103X with respect to
  the   group   generated   by   [3Xsubgens[103X   using   the  following  components:
  [10Xissuborbitrecord[110X  is  bound to [9Xtrue[109X, [10Xo[110X is bound to [3Xorb[103X, [10Xnrsuborbits[110X is bound
  to  the  number  of  suborbits  and  [10Xreps[110X  is  a  list of length [10Xnrsuborbits[110X
  containing  the  index  in  the orbit of a representative for each suborbit.
  Likewise, [10Xwords[110X contains words in the original group generators of the orbit
  that map the starting point of the orbit to those representatives. [10Xlens[110X is a
  list containing the lengths of the suborbits. The component [10Xsuborbs[110X is bound
  to  a  list  of  lists,  one for each suborbit containing the indices of the
  points  in  the orbit. The component [10Xsuborbnr[110X is a list with the same length
  as  the  orbit, containing in position [22Xi[122X the number of the suborbit in which
  point [22Xi[122X in the orbit is contained.[133X
  
  [33X[0;0YFinally,   the   component  [10Xconjsuborbit[110X  is  bound  to  a  list  of  length
  [10Xnrsuborbits[110X,  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[103X 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.[133X
  
  [1X3.1-23 OrbitIntersectionMatrix[101X
  
  [29X[2XOrbitIntersectionMatrix[102X( [3Xr[103X, [3Xg[103X ) [32X operation
  [6XReturns:[106X  [33X[0;10YAn integer matrix[133X
  
  [33X[0;0YThe  argument  [3Xr[103X  must  be  a  suborbit  record as returned by the operation
  [2XFindSuborbits[102X  ([14X3.1-22[114X) above, describing the suborbit structure of an orbit
  with  respect  to a subgroup. [3Xg[103X must be an element of the acting group. If [22Xk[122X
  is  the  number  of  suborbits and the suborbits are [22XO_1, ..., O_k[122X, then the
  matrix  returned  by  this  operation has the integer [22X|O_i ⋅ [3Xg[103X ∩ O_j|[122X in its
  [22X(i,j)[122X-entry.[133X
  
  [1X3.1-24 ORB_EstimateOrbitSize[101X
  
  [29X[2XORB_EstimateOrbitSize[102X( [3Xgens[103X, [3Xpt[103X, [3Xop[103X, [3XL[103X, [3Xlimit[103X, [3Xtimeout[103X ) [32X function
  [6XReturns:[106X  [33X[0;10Y[9Xfail[109X or a record[133X
  
  [33X[0;0YThe  argument [3Xgens[103X is a list of group generators for a group [22XG[122X, the argument
  [3Xpt[103X  a  point  and  [3Xop[103X  and action function for a group action of [22XG[122X acting on
  points  like [3Xpt[103X. This function starts to act with random elements of [22XG[122X on [3Xpt[103X
  producing random elements of the orbit [22X[3Xpt[103X*G[122X and uses the birthday paradox to
  estimate  the orbit size. To this end it creates points of the orbit until [3XL[103X
  coincidences  (points  found  twice) have been found. If before this happens
  [3Xlimit[103X  tries  have  been  reached  or if more than [3Xtimeout[103X milliseconds have
  ellapsed, the function gives up and returns [9Xfail[109X. Otherwise it estimates the
  orbit  size  giving  an  estimate  in  the  component [10Xestimate[110X, a confidence
  interval  described  by  the components [10Xlowerbound[110X and [10Xupperbound[110X, a list of
  generators  for  the  stabiliser  in  the  component [10XSgens[110X and the number of
  coincidences  that were caused by picking the same group element. The length
  of  [10XSgens[110X is [22X[3XL[103X-[122X[10Xgrpcoinc[110X. Use at least [22X15[122X for [3XL[103X, otherwise the statistics are
  not valid.[133X
  
