  
  [1X9 Orbit enumeration by suborbits[0X
  
  The  code  described  in  this  chapter  is quite complicated and one has to
  understand  quite  a  lot of theory to use it. The reason for this is that a
  lot  of  preparatory  data has to be found and supplied by the user in order
  for this code to run at all. Also the situations in which it can be used are
  quite  special.  However,  in  such  a  situation, the user is rewarded with
  impressive performance.
  
  The  main  reference  for the theory is [MNW07]. We briefly recall the basic
  setup:  Let  G  be  a  group acting from the right on some set X. Let k be a
  natural number, set X_{k+1} := X, and let
  
  
       U_1 < U_2 < \ldots < U_k < U_{{k+1}} = G
  
  
  be  a chain of "helper" subgroups. Further, for 1 <= i <= k let X_i be a U_i
  set and let pi_i : X_{i+1} -> X_i be a homomorphism of U_i-sets.
  
  This chapter starts with a section about the main orbit enumeration function
  and the corresponding preparation functions. It then proceeds with a section
  on  the  used  data  structures, which will necessarily be rather technical.
  Finally,  the  chapter  concludes  with  a  section  on  higher  level  data
  structures like lists of orbit-by-suborbit objects and their administration.
  Note that there are quite a few examples in Chapter [14X11[0m.
  
  
  [1X9.1 [10XOrbitBySuborbits[1X and its resulting objects[0X
  
  [1X9.1-1 OrbitBySuborbit[0m
  
  [2X> OrbitBySuborbit( [0X[3Xsetup, p, j, l, i, percentage[0X[2X ) _________________[0Xfunction
  [6XReturns:[0X  an orbit-by-suborbit object
  
  This  is  the  main  function  in the whole business. All notations from the
  beginning  of  this  Chapter [14X9[0m remain in place. The argument [3Xsetup[0m must be a
  setup record lying in the filter [2XIsOrbitBySuborbitSetup[0m ([14X9.3-1[0m) described in
  detail     in     Section     [14X9.3[0m    and    produced    for    example    by
  [2XOrbitBySuborbitBootstrapForVectors[0m                 ([14X9.2-1[0m)                or
  [2XOrbitBySuborbitBootstrapForLines[0m  ([14X9.2-2[0m) described below. In particular, it
  contains  all  the  generators  for G and the helper subgroups acting on the
  various  sets.  The argument [3Xp[0m must be the starting point of the orbit. Note
  that  the  function  possibly  does  not take [3Xp[0m itself as starting point but
  rather  its U_k-minimalisation, which is a point in the same U_k-orbit as [3Xp[0m.
  This  information  is  important  for  the  resulting  stabiliser  and words
  representing the U_k-suborbits.
  
  The  integers  [3Xj[0m,  [3Xl[0m,  and  [3Xi[0m,  for  which k+1 ge [3Xj[0m ge [3Xl[0m > [3Xi[0m ge 1 must hold,
  determine  the  running  mode. [3Xj[0m indicates in which set X_j the point [3Xp[0m lies
  and  thus  in  which  set  the  orbit  enumeration  takes  place, with j=k+1
  indicating  the original set X. The value [3Xl[0m indicates which group to use for
  orbit  enumeration. So the result will be a U_l orbit, with [3Xl[0m=[3Xk[0m+1 indicating
  a  G-orbit.  Finally,  the  value [3Xi[0m indicates which group to use for the "by
  suborbit"  part, that is, the orbit will be enumerated "by U_[3Xi[0m-orbits". Note
  that  nearly  all  possible combinations of these parameters actually occur,
  because  this  function  is  also  used  in  the "on-the-fly" precomputation
  happening  behind the scenes. The most common usage of this function for the
  user is [3Xj[0m=[3Xl[0m=[3Xk[0m+1 and [3Xi[0m=k.
  
  Finally,  the  integer [3Xpercentage[0m says, how much of the full orbit should be
  enumerated, the value is in percent, thus 100 means the full orbit. Usually,
  only  values  greater  than  50 are sensible, because one can only prove the
  size of the orbit after enumerating at least half of it.
  
  The  result  is  an  "orbit-by-suborbit"  object.  For  such  an  object  in
  particular  the  operations [2XSize[0m ([14X9.1-3[0m), [2XSeed[0m ([14X9.1-4[0m), [2XSuborbitsDb[0m ([14X9.1-5[0m),
  [2XWordsToSuborbits[0m  ([14X9.1-6[0m),  [2XMemory[0m  ([14X9.1-7[0m),  [2XStabilizer[0m  ([14X9.1-8[0m),  and [2XSeed[0m
  ([14X9.1-4[0m) are defined, see below.
  
  [1X9.1-2 OrbitBySuborbitKnownSize[0m
  
  [2X> OrbitBySuborbitKnownSize( [0X[3Xsetup, p, j, l, i, percentage, knownsize[0X[2X ) [0Xfunction
  [6XReturns:[0X  an orbit-by-suborbit object
  
  Basically  does the same as [2XOrbitBySuborbit[0m ([14X9.1-1[0m) but does not compute the
  stabiliser  by  evaluating Schreier words. Instead, the size of the orbit to
  enumerate  must already be known and be given in the argument [3Xknownsize[0m. The
  other arguments are as for the function [2XOrbitBySuborbit[0m ([14X9.1-1[0m).
  
  [1X9.1-3 Size[0m
  
  [2X> Size( [0X[3Xorb[0X[2X ) ________________________________________________________[0Xmethod
  [6XReturns:[0X  an integer
  
  Returns the number of points in the orbit-by-suborbit [3Xorb[0m.
  
  [1X9.1-4 Seed[0m
  
  [2X> Seed( [0X[3Xorb[0X[2X ) ________________________________________________________[0Xmethod
  [6XReturns:[0X  a point in the orbit
  
  Returns  the  starting  point  of  the  orbit-by-suborbit  [3Xorb[0m.  It  is  the
  U_i-minimalisation of the starting point given to [2XOrbitBySuborbit[0m ([14X9.1-1[0m).
  
  [1X9.1-5 SuborbitsDb[0m
  
  [2X> SuborbitsDb( [0X[3Xorb[0X[2X ) ______________________________________________[0Xoperation
  [6XReturns:[0X  a database of suborbits
  
  Returns  the  data base of suborbits of the orbit-by-suborbit object [3Xorb[0m. In
  particular,  such  a  database  object has methods for the operations [2XMemory[0m
  ([14X9.1-7[0m),   [2XTotalLength[0m   ([14X9.1-11[0m),   and   [2XRepresentatives[0m   ([14X9.1-12[0m).   For
  descriptions see below.
  
  [1X9.1-6 WordsToSuborbits[0m
  
  [2X> WordsToSuborbits( [0X[3Xorb[0X[2X ) _________________________________________[0Xoperation
  [6XReturns:[0X  a list of words
  
  Returns  a list of words in the groups U_* reaching each of the suborbits in
  the  orbit-by-suborbit  [3Xorb[0m.  Here  a  word  is a list of integers. Positive
  numbers  index  generators in following numbering: The first few numbers are
  numbers  of  generators  of  U_1  the  next  few  adjacent numbers index the
  generators  of  U_2 and so on until the generators of G in the end. Negative
  numbers indicate the corresponding inverses of these generators.
  
  Note  that  [2XOrbitBySuborbit[0m  ([14X9.1-1[0m)  takes  the  U_i-minimalisation  of the
  starting  point as its starting point and the words here are all relative to
  this new starting point.
  
  [1X9.1-7 Memory[0m
  
  [2X> Memory( [0X[3Xob[0X[2X ) ____________________________________________________[0Xoperation
  [6XReturns:[0X  an integer
  
  Returns the amount of memory needed by the object [3Xob[0m, which can be either an
  orbit-by-suborbit  object,  a  suborbit database object, or an object in the
  filter [2XIsOrbitBySuborbitSetup[0m ([14X9.3-1[0m). The amount of memory used is given in
  bytes.  Note  that this includes all hashes, databases, and preparatory data
  of  substantial  size.  For  orbit-by-suborbits  the  memory  needed for the
  precomputation is not included, ask the setup object for that.
  
  [1X9.1-8 Stabilizer[0m
  
  [2X> Stabilizer( [0X[3Xorb[0X[2X ) __________________________________________________[0Xmethod
  [6XReturns:[0X  a permutation group
  
  Returns the stabiliser of the starting point of the orbit-by-suborbit in [3Xorb[0m
  in  form  of  a  permutation  group,  using  the  given faithful permutation
  representation in the setup record.
  
  Note  that  [2XOrbitBySuborbit[0m  ([14X9.1-1[0m)  takes  the  U_i-minimalisation  of the
  starting point as its starting point and the stabiliser returned here is the
  one of this new starting point.
  
  [1X9.1-9 StabWords[0m
  
  [2X> StabWords( [0X[3Xorb[0X[2X ) ________________________________________________[0Xoperation
  [6XReturns:[0X  a list of words
  
  Returns  generators  for  the  stabiliser  of  the  starting  point  of  the
  orbit-by-suborbit  in  [3Xorb[0m  in form of words as described with the operation
  [2XWordsToSuborbits[0m  ([14X9.1-6[0m). Note again that [2XOrbitBySuborbit[0m ([14X9.1-1[0m) takes the
  U_i-minimalisation  of  the  starting  point  as  its starting point and the
  stabiliser returned here is the one of this new starting point.
  
  [1X9.1-10 SavingFactor[0m
  
  [2X> SavingFactor( [0X[3Xorb[0X[2X ) _____________________________________________[0Xoperation
  [6XReturns:[0X  an integer
  
  Returns   the  quotient  of  the  total  number  of  points  stored  in  the
  orbit-by-suborbit  [3Xorb[0m and the total number of U-minimal points stored. Note
  that the memory for the precomputations is not considered here!
  
  The following operations apply to orbit-by-suborbit database objects:
  
  [1X9.1-11 TotalLength[0m
  
  [2X> TotalLength( [0X[3Xdb[0X[2X ) _______________________________________________[0Xoperation
  [6XReturns:[0X  an integer
  
  Returns  the  total  number  of  points  stored  in  all  suborbits  in  the
  orbit-by-suborbit database [3Xdb[0m.
  
  [1X9.1-12 Representatives[0m
  
  [2X> Representatives( [0X[3Xdb[0X[2X ) ___________________________________________[0Xoperation
  [6XReturns:[0X  a list of points
  
  Returns   a   list  of  representatives  of  the  suborbits  stored  in  the
  orbit-by-suborbit database [3Xdb[0m.
  
  [1X9.1-13 SavingFactor[0m
  
  [2X> SavingFactor( [0X[3Xdb[0X[2X ) ______________________________________________[0Xoperation
  [6XReturns:[0X  an integer
  
  Returns  the  quotient  of the total number of points stored in the suborbit
  database  [3Xdb[0m  and the total number of U-minimal points stored. Note that the
  memory for the precomputations is not considered here!
  
  [1X9.1-14 OrigSeed[0m
  
  [2X> OrigSeed( [0X[3Xorb[0X[2X ) _________________________________________________[0Xoperation
  [6XReturns:[0X  a point
  
  Returns the original starting point for the orbit, not yet minimalised.
  
  
  [1X9.2 Preparation functions for [2XOrbitBySuborbit[1X ([14X9.1-1[1X)[0X
  
  [1X9.2-1 OrbitBySuborbitBootstrapForVectors[0m
  
  [2X> OrbitBySuborbitBootstrapForVectors( [0X[3Xgens, permgens, sizes, codims, opt[0X[2X ) [0Xfunction
  [6XReturns:[0X  a setup record in the filter [2XIsOrbitBySuborbitSetup[0m ([14X9.3-1[0m)
  
  All  notations  from  the  beginning of this Chapter [14X9[0m remain in place. This
  function  is  for  the  action of matrices on row vectors, so all generators
  must  be matrices. The set X thus is a row space usually over a finite field
  and  the sets X_i are quotient spaces. The matrix generators for the various
  groups  have  to  be  adjusted  with  a base change, such that the canonical
  projection onto X_i is just to take the first few entries in a vector, which
  means,  that  the  submodules divided out are generated by the last standard
  basis vectors.
  
  The  first  argument  [3Xgens[0m  must be a list of lists of generators. The outer
  list  must  have length k+1 with entry i being a list of matrices generating
  U_i,  given in the action on X=X_{k+1}. The above mentioned base change must
  have  been done. The second argument [3Xpermgens[0m must be an analogous list with
  generator  lists  for  the  U_i.  These  representations are used to compute
  membership  and  group orders of stabilisers. In its simplest form, [3Xpermgens[0m
  is a list of permutation representations of the same degree, giving a set of
  generators  for each individual group U_i. Alternatively, if for some U_i, i
  > 1, it is required that the stabilizer of its action is to be calculated as
  a  matrix  group,  generators  of  U_i  in some matrix representation may be
  supplied.  However,  it  is  then  mandatory  that  for all 1 < i <= k+1 the
  generator  lists  have the following format: The i-th entry of [3Xpermgens[0m is a
  list  concatenating the generator lists of U_1 up to U_i (in this order) all
  of   whose   elements   are  in  either  some  permutation  or  some  matrix
  representation. Note that currently, the generators of U_1 need to be always
  given  in a permutation representation. The argument [3Xsizes[0m must be a list of
  length  k+1  and  entry i must be the group order of U_i (again with U_{k+1}
  being G). Finally, the argument [3Xcodims[0m must be a list of length k containing
  integers  with  the  ith  entry  being  the codimension of the U_i-invariant
  subspace Y_i of X with X_i = X/Y_i. These codimensions must not decrease for
  obvious  reasons, but some of them may be equal. The last argument [3Xopt[0m is an
  options record. See below for possible entries.
  
  The function does all necessary steps to fill a setup record (see [14X9.3[0m) to be
  used with [2XOrbitBySuborbit[0m ([14X9.1-1[0m). For details see the code.
  
  Currently,  the  following  components  in  the  options  record  [3Xopt[0m have a
  meaning:
  
  [8X[10Xregvecfachints[0m[8X[0m
        If  bound it must be a list. In position i for i>1 there may be a list
        of  vectors  in  the  i-th  quotient  space  X_i  that  can be used to
        distinguish  the  left U_{i-1} cosets in U_i. All vectors in this list
        are tried and the first one that actually works is used.
  
  [8X[10Xregvecfullhints[0m[8X[0m
        If  bound it must be a list. In position i for i>1 there may be a list
        of  vectors  in  the  full space X that can be used to distinguish the
        left U_{i-1} cosets in U_i. All vectors in this list are tried and the
        first one that actually works is used.
  
  [8X[10Xstabchainrandom[0m[8X[0m
        If bound the value is copied into the [10Xstabchainrandom[0m component of the
        setup record.
  
  [8X[10Xnostabchainfullgroup[0m[8X[0m
        If bound it must be [9Xtrue[0m or [9Xfalse[0m. If it is unbound or set to [9Xtrue[0m, no
        stabilizer chain is computed for the group U_k+1. Its default value is
        [9Xfalse[0m.
  
  [1X9.2-2 OrbitBySuborbitBootstrapForLines[0m
  
  [2X> OrbitBySuborbitBootstrapForLines( [0X[3Xgens, permgens, sizes, codims, opt[0X[2X ) [0Xfunction
  [6XReturns:[0X  a setup record in the filter [2XIsOrbitBySuborbitSetup[0m ([14X9.3-1[0m)
  
  All  notations  from  the  beginning of this Chapter [14X9[0m remain in place. This
  does  exactly  the same as [2XOrbitBySuborbitBootstrapForVectors[0m ([14X9.2-1[0m) except
  that  it  handles  the case of matrices acting on one-dimensional subspaces.
  Those one-dimensional subspaces are represented by normalised vectors, where
  a vector is normalised if its first non-vanishing entry is equal to 1.
  
  [1X9.2-3 OrbitBySuborbitBootstrapForSpaces[0m
  
  [2X> OrbitBySuborbitBootstrapForSpaces( [0X[3Xgens, permgens, sizes, codims, spcdim, opt[0X[2X ) [0Xfunction
  [6XReturns:[0X  a setup record in the filter [2XIsOrbitBySuborbitSetup[0m ([14X9.3-1[0m)
  
  All  notations  from  the  beginning of this Chapter [14X9[0m remain in place. This
  does  exactly  the same as [2XOrbitBySuborbitBootstrapForVectors[0m ([14X9.2-1[0m) except
  that it handles the case of matrices acting on [3Xspcdim[0m-dimensional subspaces.
  Those subspaces are represented by fully echelonised bases.
  
  
  [1X9.3 Data structures for orbit-by-suborbits[0X
  
  The  description  in this section is necessarily technical. It is meant more
  as  extended  annotations  to  the  source  code than as user documentation.
  Usually  it  should  not  be  necessary  for  the  user  to know the details
  presented  here.  The  function [2XOrbitBySuborbit[0m ([14X9.1-1[0m) needs an information
  record of the following form:
  
  [1X9.3-1 IsOrbitBySuborbitSetup[0m
  
  [2X> IsOrbitBySuborbitSetup( [0X[3Xob[0X[2X ) _____________________________________[0XCategory
  [6XReturns:[0X  [9Xtrue[0m or [9Xfalse[0m
  
  Objects  in  this  category  are  also in [10XIsComponentObjRep[0m. We describe the
  components, refering to the setup at the beginning of this Chapter [14X9[0m.
  
  [8X[10Xk[0m[8X[0m
        The number of helper subgroups.
  
  [8X[10Xsize[0m[8X[0m
        A  list  of  length  k+1  containing  the  orders  of  the groups U_i,
        including U_{k+1} = G.
  
  [8X[10Xindex[0m[8X[0m
        A  list  of length k with the index [U_i:U_{i-1}] in position i (U_0 =
        {1}).
  
  [8X[10Xels[0m[8X[0m
        A  list  of  length  k+1  containing generators of the groups in their
        action  on various sets. In position i we store all the generators for
        all  groups acting on X_i, that is for the groups U_1, ..., U_i (where
        position  k+1  includes  the  generators  for  G. In each position the
        generators of all those groups are concatentated starting with U_1 and
        ending with U_i.
  
  [8X[10Xelsinv[0m[8X[0m
        The  inverses  of  all  the  elements in the [10Xels[0m component in the same
        arrangement.
  
  [8X[10Xtrans[0m[8X[0m
        A  list  of  length  k  in which position i for i>1 contains a list of
        words  in the generators for a transversal of U_{i-1} in U_i (with U_0
        = 1).
  
  [8X[10Xpifunc[0m[8X[0m
        Projection  functions.  This  is  a  list  of length k+1 containing in
        position  j  a  list  of  length  j-1  containing  in position i a [5XGAP[0m
        function doing the projection X_j -> X_i. These [5XGAP[0m functions take two
        arguments,  namely  the  point to map and secondly the value of the [10Xpi[0m
        component  at  positions  [10X[j][i][0m.  Usually  [10Xpifunc[0m is just the slicing
        operator  in  [5XGAP[0m  and [10Xpi[0m contains the components to project onto as a
        range object.
  
  [8X[10Xpi[0m[8X[0m
        See the description of the [10Xpifunc[0m component.
  
  [8X[10Xop[0m[8X[0m
        A  list  of  k+1  [5XGAP[0m operation functions, each taking a point p and a
        generator g in the action given by the index and returning pg.
  
  [8X[10Xinfo[0m[8X[0m
        A  list  of  length  k containing a hash table with the minimalisation
        lookup  data.  These  hash  tables  grow  during orbit enumerations as
        precomputations are done behind the scenes.
  
        [10Xinfo[1][0m  contains  precomputation  data for X_1. Assume x in X_1 to be
        U_1-minimal.  For  all z in xU_1 with z <> x we store the number of an
        element  in  the  [10Xwordcache[0m  mapping z to x. For z=x we store a record
        with  two  components  [10Xgens[0m and [10Xsize[0m, where [10Xgens[0m stores generators for
        the stabiliser Stab_{U_1}(x) as words in the group generators and [10Xsize[0m
        stores the size of that stabiliser.
  
        [10Xinfo[i][0m  for i>1 contains precomputation data for X_i. Assume x in X_i
        to  be  U_i-minimal.  For  all U_{i-1}-minimal z in xU_i \ xU_{i-1} we
        store  the  number  of an element in [10Xtrans[i][0m mapping z into xU_{i-1}.
        For  all  U_{i-1}-minimal  z  in  xU_{i-1}  with  z  <> x we store the
        negative  of  the  number  of  a  word  in  [10Xwordcache[0m  that  is in the
        generators of U_{i-1} and maps z to x. For z=x we store the stabiliser
        information as in the case i=1.
  
        This  information  together  with  the  information  in  the following
        componente allows the minimalisation function to do its job.
  
  [8X[10Xcosetrecog[0m[8X[0m
        A list of length k beginning with the index 1. The entry at position i
        is  bound to a function taking 3 arguments, namely i itself, a word in
        the group generators of U_1, ..., U_k which lies in U_i, and the setup
        record.  The function computes the number [10Xj[0m of an element in [10Xtrans[i][0m,
        such that the element of U_i described by the word lies in [10Xtrans[i][j]
        U_{{i-1}}[0m.
  
  [8X[10Xcosetinfo[0m[8X[0m
        A list of things that can be used by the functions in [10Xcosetrecog[0m.
  
  [8X[10Xsuborbnr[0m[8X[0m
        A  list  of  length  k  that  contains  in  position  i  the number of
        U_i-orbits in X_i archived in [10Xinfo[i][0m during precomputation.
  
  [8X[10Xsumstabl[0m[8X[0m
        A  list  of  length k that contains in position i the sum of the point
        stabiliser  sizes  of  all  U_i-orbits  X_i archived in [10Xinfo[i][0m during
        precomputation.
  
  [8X[10Xpermgens[0m[8X[0m
        A list of length k+1 containing in position i generators for U_1, ...,
        U_i in a faithful permutation representation of U_i. Generators fit to
        the  generators  in  [10Xels[0m.  For  the  variant  [2XOrbitBySuborbitKnownSize[0m
        ([14X9.1-2[0m) the k+1 entry can be unbound.
  
  [8X[10Xpermgensinv[0m[8X[0m
        The inverses of the generators in [10Xpermgens[0m in the same arrangement.
  
  [8X[10Xsample[0m[8X[0m
        A list of length k+1 containing sample points in the sets X_i.
  
  [8X[10Xstabchainrandom[0m[8X[0m
        The  value  is  used  as the value for the [10Xrandom[0m option for [10XStabChain[0m
        calculations  to  determine stabiliser sizes. Note that the algorithms
        are randomized if you use this feature with a value smaller than 1000.
  
  [8X[10Xwordhash[0m[8X[0m
        A  hash to quickly recognise already used words. For every word in the
        hash  the  position  of  that  word in the [10Xwordcache[0m list is stored as
        value in the hash.
  
  [8X[10Xwordcache[0m[8X[0m
        A list of words in the wordcache for indexing purposes.
  
  [8X[10Xhashlen[0m[8X[0m
        Initial  length  of  hash  tables used for the enumeration of lists of
        U_i-minimal points.
  
  [8X[10Xstaborblenlimit[0m[8X[0m
        This  contains  the  limit,  up  to  which  orbits  of stabilisers are
        computed  using word action. After this limit, the stabiliser elements
        are actually evaluated in the group.
  
  [8X[10Xstabsizelimitnostore[0m[8X[0m
        If  the  stabiliser  in  the  quotient  is larger than this limit, the
        suborbit is not stored.
  
  [8X[10Xcache[0m[8X[0m
        A  linked  list  cache  object  (see [2XLinkedListCache[0m ([14X5.2-1[0m)) to store
        already  computed transversal elements. The cache nodes are referenced
        in the [10Xtranscache[0m component and are stored in the cache [10Xcache[0m.
  
  [8X[10Xtranscache[0m[8X[0m
        This  is  a  list  of  lists of weak pointer objects. The weak pointer
        object   at  position  [10X[i][j][0m  holds  references  to  cache  nodes  of
        transversal elements of U_i-1 in U_i in representation j.
  
  
  [1X9.3-2 The global record [10XORB[1X[0X
  
  In  this  section  we  describe  the  global record [10XORB[0m, which contains some
  entries  that can tune the behaviour of the orbit-by-suborbit functions. The
  record has the following components:
  
  [8X[10XMINSHASHLEN[0m[8X[0m
        This  positive  integer  is  the  initial  value of the hash size when
        enumerating orbits of stored stabilisers to find all or search through
        U_{i-1}-minimal vectors in an U_i-orbit. The default value is 1000.
  
  [8X[10XORBITBYSUBORBITDEPTH[0m[8X[0m
        This    integer    indicates    how    many    recursive    calls   to
        [10XOrbitBySubOrbitInner[0m  have  been  done.  The  initial  value  is  0 to
        indicate  that  no  such call has happened. This variable is necessary
        since  the  minimalisation routine sometimes uses [10XOrbitBySubOrbitInner[0m
        recursively  to  complete some precomputation "on the fly" during some
        other orbit-by-suborbit enumeration. This component is always set to 0
        automatically     when     calling    [2XOrbitBySuborbit[0m    ([14X9.1-1[0m)    or
        [2XOrbitBySuborbitKnownSize[0m  ([14X9.1-2[0m)  so the user should usually not have
        to worry about it at all.
  
  [8X[10XPATIENCEFORSTAB[0m[8X[0m
        This integer indicates how many Schreier generators for the stabiliser
        are  tried before assuming that the stabiliser is complete. Whenever a
        new  generator  for the stabiliser is found that increases the size of
        the  currently known stabiliser, the count is reset to 0 that is, only
        when  [10XORB.PATIENCEFORSTAB[0m  unsuccessful  Schreier generators have been
        tried  no  more Schreier generators are created. The default value for
        this  component  is  1000.  This  feature  is  purely  heuristical and
        therefore this value has to be adjusted for some orbit enumerations.
  
  [8X[10XPLEASEEXITNOW[0m[8X[0m
        This value is usually set to [9Xfalse[0m. Setting it to [9Xtrue[0m in a break loop
        tells  the  orbit-by-suborbit  routines to exit gracefully at the next
        possible  time.  Simply  leaving  such  a break loop with [9Xquit;[0m is not
        safe,  since  the  routines  might  be  in  the  process  of  updating
        precomputation  data  and  the  data structures might be left corrupt.
        Always use this component to leave an orbit enumeration prematurely.
  
  [8X[10XREPORTSUBORBITS[0m[8X[0m
        This  positive  integer  governs  how often information messages about
        newly  found  suborbits  are printed. The default value is 1000 saying
        that  after  every  1000  suborbits  a message is printed, if the info
        level  is at its default value 1. If the info level is increased, then
        this  component  does  no  longer  affect  the  printing and all found
        suborbits are reported.
  
  [8X[10XTRIESINQUOTIENT[0m[8X and [10XTRIESINWHOLESPACE[0m[8X[0m
        The  bootstrap  routines  [2XOrbitBySuborbitBootstrapForVectors[0m  ([14X9.2-1[0m),
        [2XOrbitBySuborbitBootstrapForLines[0m              ([14X9.2-2[0m)              and
        [2XOrbitBySuborbitBootstrapForSpaces[0m   ([14X9.2-3[0m)   all   need   to  compute
        transversals  of  one  helper subgroup in the next one. They use orbit
        enumerations   in  various  spaces  to  achieve  this.  The  component
        [10XTRIESINQUOTIENT[0m must be a non-negative integer and indicates how often
        a  random  vector in the corresponding quotient space is tried to find
        an  orbit  that  can  distinguish  between cosets. The other component
        [10XTRIESINWHOLESPACE[0m  also  must  be a non-negative integer and indicates
        how  often  a  random  vector in the whole space is tried. The default
        values are 3 and 20 resepectively.
  
  
  [1X9.4 Lists of orbit-by-suborbit objects[0X
  
  There   are   a   few   functions   that   help  to  administrate  lists  of
  orbit-by-suborbits.
  
  [1X9.4-1 InitOrbitBySuborbitList[0m
  
  [2X> InitOrbitBySuborbitList( [0X[3Xsetup, nrrandels[0X[2X ) ______________________[0Xfunction
  [6XReturns:[0X  a list of orbit-by-suborbits object
  
  Creates  an  object  that  stores a list of orbit-by-suborbits. The argument
  [3Xsetup[0m  must  be  an  orbit-by-suborbit setup record and [3Xnrrandels[0m must be an
  integer.  It  indicates how many random elements in G should be used to do a
  probabilistic  check  for  membership  in  case an orbit-by-suborbit is only
  partially known.
  
  [1X9.4-2 IsVectorInOrbitBySuborbitList[0m
  
  [2X> IsVectorInOrbitBySuborbitList( [0X[3Xv, obsol[0X[2X ) ________________________[0Xfunction
  [6XReturns:[0X  [9Xfail[0m or an integer
  
  Checks  probabilistically,  if  the  element  [3Xv[0m lies in one of the partially
  enumerated orbit-by-suborbits in the orbit-by-suborbit list object [3Xobsol[0m. If
  yes,  the  number  of  that  orbit-by-suborbit is returned and the answer is
  guaranteed to be correct. If the answer is [9Xfail[0m there is a small probability
  that  the  point  actually  lies  in one of the orbits but this could not be
  shown.
  
  [1X9.4-3 OrbitsFromSeedsToOrbitList[0m
  
  [2X> OrbitsFromSeedsToOrbitList( [0X[3Xobsol, li[0X[2X ) __________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  Takes  the elements in the list [3Xli[0m as seeds for orbit-by-suborbits. For each
  such   seed   it   is   first   checked  whether  it  lies  in  one  of  the
  orbit-by-suborbits in [3Xobsol[0m, which must be an orbit-by-suborbit list object.
  If  not  found,  51%  of the orbit-by-suborbit of the seed is enumerated and
  added to the list [3Xobsol[0m.
  
  This  function  is  a  good  way  to  quickly  enumerate a greater number of
  orbit-by-suborbits.
  
  [1X9.4-4 VerifyDisjointness[0m
  
  [2X> VerifyDisjointness( [0X[3Xobsol[0X[2X ) ______________________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0m or [9Xfalse[0m
  
  This  function  checks  deterministically, whether the orbit-by-suborbits in
  the  orbit-by-suborbit list object [3Xobsol[0m are disjoint or not and returns the
  corresponding  boolean  value.  This  is not a Monte-Carlo algorithm. If the
  answer  is  [9Xfalse[0m,  the  function  writes  out,  which  orbits  are  in fact
  identical.
  
  [1X9.4-5 Memory[0m
  
  [2X> Memory( [0X[3Xobsol[0X[2X ) _________________________________________________[0Xoperation
  [6XReturns:[0X  an integer
  
  Returns   the   total   memory   used  for  all  orbit-by-suborbits  in  the
  orbit-by-suborbit-list  [3Xobsol[0m.  Precomputation data is not included, ask the
  setup object instead.
  
  [1X9.4-6 TotalLength[0m
  
  [2X> TotalLength( [0X[3Xobsol[0X[2X ) ____________________________________________[0Xoperation
  [6XReturns:[0X  an integer
  
  Returns  the  total number of points stored in all orbit-by-suborbits in the
  orbit-by-suborbit-list [3Xobsol[0m.
  
  [1X9.4-7 Size[0m
  
  [2X> Size( [0X[3Xobsol[0X[2X ) ______________________________________________________[0Xmethod
  [6XReturns:[0X  an integer
  
  Returns the total number of points in the orbit-by-suborbit-list [3Xobsol[0m.
  
  [1X9.4-8 SavingFactor[0m
  
  [2X> SavingFactor( [0X[3Xobsol[0X[2X ) ___________________________________________[0Xoperation
  [6XReturns:[0X  an integer
  
  Returns   the  quotient  of  the  total  number  of  points  stored  in  all
  orbit-by-suborbits  in the orbit-by-suborbit-list [3Xobsol[0m and the total number
  of  U-minimal  points stored, which is the average saving factor considering
  all   orbit-by-suborbits   together.   Note   that   the   memory   for  the
  precomputations is not considered here!
  
