  
  [1X3 Stabiliser Chains[0X
  
  This  chapter  describes  the  core  functionality of the package. It mainly
  covers  how to use [5Xgenss[0m to compute stabiliser chains for [5XGAP[0m groups and use
  them to do sifting.
  
  
  [1X3.1 Computing stabiliser chains[0X
  
  The  main  tool to compute a stabiliser chain is the following operation. It
  has many options and can be customised in a very flexible way.
  
  [1X3.1-1 StabilizerChain[0m
  
  [2X> StabilizerChain( [0X[3XG[, opt][0X[2X ) _____________________________________[0Xoperation
  [6XReturns:[0X  a stabiliser chain object or [9Xfail[0m
  
  This  operation  computes  a  stabiliser  chain  for  the  group  [3XG[0m  using a
  randomised  Schreier-Sims  algorithm. The second argument [3Xopt[0m is an optional
  options  record.  See  Section  [14X3.2[0m below for an explanation of the possible
  components.
  
  Note that this is a Monte Carlo algorithm in most cases, so there is a small
  error  probability.  However,  the  only  error possible is that some of the
  subgroups  in  the stabiliser chain are proper subgroups of the actual point
  stabilisers.  So the resulting group order is always a divisor of the actual
  group order and if the two are equal, then the stabiliser chain is proved to
  be  correct.  In  particular,  if the group object [3XG[0m for some reason already
  knows  the  group  order,  then  this procedure always returns a correct and
  proven stabiliser chain for [3XG[0m.
  
  
  [1X3.2 Options for the computation of stabiliser chains[0X
  
  The options record for the [2XStabilizerChain[0m ([14X3.1-1[0m) can contain the following
  components,  which are used to control the behaviour of the computation of a
  stabiliser  chain  for  the  group [3XG[0m. Note that for most of these components
  there  are  default  values  to be found in the global [10XGENSS[0m record. You can
  change  these  defaults  there  if you want but you should know what you are
  doing.  An  explicitly  given  value  in  the  options  record  always takes
  precedence over the default value.
  
  [8X[10XBase[0m[8X[0m
        This  component  can  either  be bound to an existing stabilizer chain
        object  or  to a list of points. In both cases this indicates that the
        base  of  the  stabilizer chain or the list of points respectively are
        known  to  be  a  base  for  the  group  [3XG[0m.  In  the  first  case  the
        corresponding action functions are taken from the stabiliser chain, in
        the  second  case  one  should usually bind the component [10XBaseOps[0m to a
        list  of equal length containing the action functions corresponding to
        the base points.
  
  [8X[10XBaseOps[0m[8X[0m
        If  the  [10XBase[0m  component  is  bound  to  a  list of points the [10XBaseOps[0m
        component  must be a list of equal length containing the corresponding
        action  functions.  If  the  [10XBaseOps[0m component is unbound, a list with
        identical  entries  [10XOnLines[0m is used in projective mode and [10XOnPoints[0m in
        non-projective mode (see component [10XProjective[0m below).
  
  [8X[10XCand[0m[8X[0m
        The [10XCand[0m component can be bound to a record [10Xr[0mwhich contains candidates
        for  base points in the following way. The [10Xr.points[0m component contains
        the  list  of  points,  the  [10Xr.ops[0m  component contains a list of equal
        length with the corresponding action functions. The points and actions
        specified  in the [10XCand[0m component are tried as possible base points for
        [3XG[0m  (and  its  stabilisers)  first before other points are guessed (see
        [2XFindBasePointCandidates[0m  ([14X3.3-1[0m)).  If  a  point  is  fixed  under all
        generators  it is not used, unless the component [10XReduced[0m is explicitly
        set  to  [9Xfalse[0m  (see below). If the component [10XStrictlyUseCandidates[0m is
        [9Xfalse[0m  (the  default,  see  below),  the  algorithm tries to use other
        points of an already found orbit before considering the next candidate
        specified  by  [10XCand[0m.  This  is usually sensible because for an already
        enumerated  orbit  we  have  a  natural  bound  on  the  length of the
        suborbits for the point stabiliser in this orbit.
  
  [8X[10XDeterministicVerification[0m[8X[0m
        Set  this  component to [9Xtrue[0m to switch on a deterministic verification
        routine  after the randomised Schreier-Sims procedure. This is not yet
        implemented.
  
  [8X[10XErrorBound[0m[8X[0m
        Set this component to a rational number between 0 and 1. It will be an
        upper  bound for the error probability. That is, the error probability
        of  the  Monte  Carlo  verification  at the end will be less than this
        rational  number.  This  component overrides everything you specify in
        the [10Xrandom[0m or [10XVerifyElements[0m components.
  
  [8X[10XFailInsteadOfError[0m[8X[0m
        If  no  short  enough  orbit  is  found  during  the  computation, the
        procedure  stops with an error message. If you would rather like it to
        return  [9Xfail[0m  then set this component to [9Xtrue[0m. This option can be used
        to  try  an  stabiliser  chain  computation  automatically and give up
        before you run out of memory.
  
  [8X[10XImmediateVerificationElements[0m[8X[0m
        Whenever  the  randomised  Schreier-Sims  procedure has first computed
        generators for a stabiliser in the chain and has computed a stabiliser
        chain  for  that  stabiliser recursively, an immediate verification is
        done.  This  is  to  spot  early  on that the group found is in fact a
        proper  subgroup  of  the  stabiliser.  This  verification  is done by
        creating  a  few  more  random elements of that stabiliser and sifting
        them through the newly created stabiliser chain. Each such element has
        a  chance  of at least 1/2 to spot this. The number of random elements
        used is stored in the component [10XImmediateVerificationElements[0m.
  
  [8X[10XInitialHashSize[0m[8X[0m
        Set   this   component  to  the  initial  tree  hash  size  for  orbit
        computations in the stabiliser chain.
  
  [8X[10XIsOne[0m[8X[0m
        The  default  for  this  computation  is  the [2XIsOne[0m ([14XReference: IsOne[0m)
        operation  in  the  [5XGAP[0m  library.  Whenever  in  the  stabiliser chain
        computation  it  has  to  be  tested whether or not a group element is
        equal  to  the identity, the function stored in the [10XIsOne[0m component is
        called. The rationale behind this is that you can compute a stabiliser
        chain  for  a  factor group of the group object [3XG[0m. For example, if you
        set  the [10XIsOne[0m component to [2XGENSS_IsOneProjective[0m ([14X3.2-1[0m) for a matrix
        group  [3XG[0m,  scalar multiples of the identity are considered to be equal
        to  the  identity. You will have to specify the base points explicitly
        using  the  [10XCand[0m  and  [10XStrictlyUseCandidates[0m  component (see above and
        below) to only use actions having the normal subgroup in its kernel. A
        shortcut  for computing stabiliser chains of projective groups (matrix
        group  modulo  scalars) is to set the [10XProjective[0m component (see below)
        and switch to projective mode.
  
  [8X[10XLimitShortOrbCandidates[0m[8X[0m
        The  integer  value  of this component limits the number of candidates
        considered  for the finding of short orbits. See the [10XTryShortOrbit[0m and
        [10XTryBirthdayParadox[0m components.
  
  [8X[10XNrRandElsBirthdayParadox[0m[8X[0m
        The  method  using  the  birthday paradox to find short orbits uses at
        most  as many random group elements to estimate the orbit size as this
        component says. See the [10XTryBirthdayParadox[0m component.
  
  [8X[10XNumberPrevOrbitPoints[0m[8X[0m
        After  an  orbit  for  the  stabiliser  chain has been enumerated, the
        randomised Schreier-Sims method first tries [10XNumberPrevOrbitPoints[0m from
        this  orbit  as  next  base  points. Note that this is not done if the
        [10XStrictlyUseCandidates[0m component is set to [9Xtrue[0m.
  
  [8X[10XOrbitLengthLimit[0m[8X[0m
        This component is an absolute upper bound for the length of all orbits
        in  the  stabiliser chain. If an orbit enumeration reaches this limit,
        the stabiliser chain computation is aborted.
  
  [8X[10XOrbitLimitBirthdayParadox[0m[8X[0m
        During the method to find short orbits using the birthday paradox (see
        component [10XTryBirthdayParadox[0m) only orbits whose final estimated length
        is less than [10XOrbitLimitBirthdayParadox[0m are used.
  
  [8X[10XOrbitLimitImmediatelyTake[0m[8X[0m
        During the method to find short orbits using the birthday paradox (see
        component  [10XTryBirthdayParadox[0m)  an  orbit  is  immediately used if its
        currently  estimated  length  is  less than [10XOrbitLimitImmediatelyTake[0m,
        even if the estimate is not yet very reliable.
  
  [8X[10XProjective[0m[8X[0m
        Set  this  component to [9Xtrue[0m if you want to compute a stabiliser chain
        for  a  projective  group  given as a matrix group. Elements which are
        scalar multiples of each other will be considered to be equal. This is
        achieved  by  only  considering  projective actions. Note that in this
        case  a known size of the group object cannot be used, since this size
        is the order of the matrix group!
  
  [8X[10Xrandom[0m[8X[0m
        The  [10Xrandom[0m  component  is there as a compatibility option. It behaves
        exactly  as  for  the  stabiliser chain methods in the [5XGAP[0m library. It
        must  be  set  to a number between 0 and 1000 indicating a lower bound
        for  the  probability  of  a  correct  answer, where the value a means
        a/10%.  Note that currently 1000 is not yet implemented since there is
        no working deterministic verification routine.
  
  [8X[10XRandomElmFunc[0m[8X[0m
        If  this component is bound then it must be bound to a function taking
        no  arguments  and  returning uniformly distributed random elements in
        the group for which the stabiliser chain is to be computed. All random
        elements used for the stabiliser chain will then be created by calling
        this function.
  
  [8X[10XRandomStabGens[0m[8X[0m
        This  component contains the number of random stabiliser elements that
        are generated initially to generate a new stabiliser in the chain.
  
  [8X[10XReduced[0m[8X[0m
        If  this  component  is  bound to [9Xtrue[0m, then no orbits of length 1 are
        allowed  in the stabiliser chain. That is, no points are taken as base
        points  that are fixed under all generators of the current stabiliser.
        Set  this  component  to  [9Xfalse[0m  to  allow for orbits of length 1, for
        example  if  you want the stabiliser chain to run through a prescribed
        base.
  
  [8X[10XReport[0m[8X[0m
        The number in the [10XReport[0m component is taken as the [10XReport[0m component in
        all  orbit enumerations. That is, every [10XReport[0m newly found elements in
        the  orbit  a  message  is  printed saying how far the computation has
        gone.
  
  [8X[10XShortOrbitsInitialLimit[0m[8X[0m
        See the [10XTryShortOrbit[0m component.
  
  [8X[10XShortOrbitsNrRandoms[0m[8X[0m
        See the [10XTryShortOrbit[0m component.
  
  [8X[10XShortOrbitsOrbLimit[0m[8X[0m
        See the [10XTryShortOrbit[0m component.
  
  [8X[10XSize[0m[8X[0m
        If  the [10XSize[0m component is set to a positive integer it is taken as the
        size  of the group [3XG[0m. This information allows to verify the stabiliser
        chain  simply  by  looking  at its size. If the group object knows its
        size  already (and the [10XProjective[0m component was not set to [9Xtrue[0m), then
        the stored size of the group is automatically taken into account, such
        that one does not have to use this option.
  
  [8X[10XStabGenAddSlots[0m[8X[0m
        The  value of the [10XStabGenAddSlots[0m component is directly handed over to
        the  product replacer object which is used to generate random elements
        to find stabiliser generators.
  
  [8X[10XStabGenMaxDepth[0m[8X[0m
        The  value of the [10XStabGenMaxDepth[0m component is directly handed over to
        the  product replacer object which is used to generate random elements
        to find stabiliser generators.
  
  [8X[10XStabGenScrambleFactor[0m[8X[0m
        The  value  of  the [10XStabGenScrambleFactor[0m component is directly handed
        over  to  the product replacer object which is used to generate random
        elements to find stabiliser generators.
  
  [8X[10XStabGenScramble[0m[8X[0m
        The  value of the [10XStabGenScramble[0m component is directly handed over to
        the  product replacer object which is used to generate random elements
        to find stabiliser generators.
  
  [8X[10XStrictlyUseCandidates[0m[8X[0m
        If  this  component  is  set  to [9Xtrue[0m (default is [9Xfalse[0m) then only the
        given   candidate  points  are  taken  as  possible  base  points.  In
        particular,  the  procedure  does  not  take  additional points of the
        previous   orbit   as   candidates  for  base  points  (see  component
        [10XNumberPrevOrbitPoints[0m ). Use this option in combination to [10XReduced[0m set
        to [9Xfalse[0m to enforce a certain known base.
  
  [8X[10XTryBirthdayParadox[0m[8X[0m
        The  method  to try to find short orbits using the birthday paradox is
        used  up  to  [10XTryBirthdayParadox[0m  times  for each new base point. This
        method uses the Murray/O'Brien heuristics to find candidates for short
        orbits and then uses statistics using the birthday paradox to estimate
        the  orbit  lengths. As soon as a point is found whose orbit is either
        estimated  to  be  smaller than [10XOrbitLimitBirthdayParadox[0m with a solid
        statistical   estimate   or   is   estimated   to   be   smaller  than
        [10XOrbitLimitImmediatelyTake[0m with a weak statistical estimate, this point
        is taken as the next base point.
  
  [8X[10XTryShortOrbit[0m[8X[0m
        The   method   to   try  to  find  short  orbits  using  the  standard
        Murray/O'Brien  heuristics  is used up to [10XTryShortOrbit[0m times for each
        new base point. This method uses the heuristics to find candicates for
        short orbits using [10XShortOrbitsNrRandoms[0m random group elements. It then
        enumerates  all  these orbits up to the limit [10XShortOrbitsInitialLimit[0m.
        If any of them closes the corresponding candidate is taken as the next
        base point. Otherwise half of the points are thrown away and the limit
        is  doubled.  This  goes  on until either an orbit closes or the limit
        grows over [10XShortOrbitsOrbLimit[0m.
  
  [8X[10XVerifyElements[0m[8X[0m
        This  component can be used to set it to the number of random elements
        that are used in the end to verify the stabiliser chain statistically.
        Usually  the  user  specifies  the  component  [10XErrorBound[0m  instead and
        [10XVerifyElements[0m  is  then computed automatically from that. However, if
        no  [10XErrorBound[0m is given, the [10XVerifyElements[0m component takes precedence
        over the [10Xrandom[0m component.
  
  [8X[10XVeryShortOrbLimit[0m[8X[0m
        The  very  first  method  tried  to  find  the  next  base point is to
        enumerate  the orbit of the first and the last basis vector and of one
        random  vector  up to the limit [10XVeryShortOrbLimit[0m. If the orbit closes
        before  this limit is reached, the corresponding vector is immediately
        taken.
  
  [1X3.2-1 GENSS_IsOneProjective[0m
  
  [2X> GENSS_IsOneProjective( [0X[3Xx[0X[2X ) _______________________________________[0Xfunction
  [6XReturns:[0X  [10Xtrue[0m or [10Xfalse[0m
  
  This  function tests whether or not the matrix [3Xx[0m is a scalar multiple of the
  identity matrix. This function is useful for projective action.
  
  
  [1X3.3 How base points are chosen[0X
  
  This  section  explains  some internal details of how base points are chosen
  during  a  stabiliser chain computations. As a user, you can probably safely
  skip  this  section  and  ignore it altogether. However, in situations where
  thes  stabiliser  chain  computation is more difficult (for example if it is
  difficult  to find short orbits), then it can be helpful to know about these
  details.
  
  Whenever the stabiliser chain computation needs to set up a new layer in the
  stabiliser  chain it needs a new base point. The first method it tries is to
  take  a  point in the previous orbit one layer up, since for these points we
  have  a natural upper limit for the orbit length, namely the orbit length in
  the  layer  above. If this does not work (either there is no higher layer or
  more  than  the first [10XNumberPrevOrbitPoints[0m (see stabiliser chain options in
  Section   [14X3.2[0m)   in   that   orbit   are  fixed  by  the  current  group  or
  [10XStrictlyUseCandidates[0m  is  [9Xtrue[0m),  it  is  checked  whether  or not there is
  another known candidate for a base point.
  
  Note that if the user supplies candidates for the base points and operations
  (see component [10XCand[0m in the stabiliser chain options in Section [14X3.2[0m), then it
  is entirely possible that all base points come from these candidates and the
  mechanisms described in this sections are not used at all.
  
  However,  if  the  procedure runs out of base points, it needs a way to find
  new candidates. This is done using the following operation:
  
  [1X3.3-1 FindBasePointCandidates[0m
  
  [2X> FindBasePointCandidates( [0X[3Xg, opt, i, S[0X[2X ) _________________________[0Xoperation
  [6XReturns:[0X  a [10XCand[0m record
  
  This  operation returns base point candidates in the form of a record as for
  the [10XCand[0m option for stabiliser chain computations (see Section [14X3.2[0m).
  
  There  are  various  methods  installed to this end which all might fail and
  call  [10XTryNextMethod();[0m. We do not document the details of these methods here
  but  only  give an overview. For permutation groups the choice of candidates
  is  very  straightforward,  one  simply  takes a few integers with the usual
  action  [10XOnPoints[0m.  For matrix group finding a reasonably short orbit is more
  difficult.  The  system  first  handles  the case of a scalar group which is
  easy.  Then  it  hopes to find a "very short orbit" defined by the component
  [10XVeryShortOrbLimit[0m in the stabiliser chain computation options. If this fails
  the  birthday  paradoxon method is used to find an estimate for a reasonably
  short orbit amoung candidates coming from the Murray and O'Brien heuristics.
  If this fails the same heuristics are used but various orbits are enumerated
  up  to a certain point decreasing the number of orbits as the limit goes up.
  If  all  fails  some  of the candidates from the heuristics are simply tried
  with  brute force. The whole computation can fail if some upper orbit length
  limit  is  reached  (see  component [10XOrbitLengthLimit[0m in the stabiliser chain
  computation options).
  
  
  [1X3.4 Using stabiliser chains[0X
  
  The most important thing one can do with a stabiliser chain is sifting. This
  is done with one of the next to operations:
  
  [1X3.4-1 SiftGroupElement[0m
  
  [2X> SiftGroupElement( [0X[3XS, el[0X[2X ) _______________________________________[0Xoperation
  [6XReturns:[0X  a record
  
  The  first  argument  [3XS[0m  must  be  a  stabiliser chain object and the second
  argument  [3Xel[0m  a  group  element  (not  necessarily  contained  in  the group
  described by [3XS[0m). The result is a record describing the result of the sifting
  process. The component [10Xrem[0m contains the remainder of the sifting process. If
  [3Xel[0m  is contained in the group described by [3XS[0m, then the remainder is equal to
  the identity. Note that if the [10XIsOne[0m-component of the options record for the
  stabiliser  chain [3XS[0m is different from the [2XIsOne[0m ([14XReference: IsOne[0m) operation
  then  the [10Xrem[0m component is equal to the identity according to that test. The
  result  of this test ([9Xtrue[0m or [9Xfalse[0m) is stored in the component [10Xisone[0m of the
  resulting  record.  This means, that this component indicates whether or not
  the sifting was successful. The component [10XS[0m is bound to the stabiliser chain
  object  corresponding  to  the layer in which the sifting stopped. If it ran
  through the whole chain this component is bound to [9Xfalse[0m. The component [10XpreS[0m
  is  always  bound  to  the  previous layer, which is the lowest layer if the
  sifting was successful.
  
  [1X3.4-2 SiftGroupElementSLP[0m
  
  [2X> SiftGroupElementSLP( [0X[3XS, el[0X[2X ) ____________________________________[0Xoperation
  [6XReturns:[0X  a record
  
  This  operation  behaves  exactly as [2XSiftGroupElement[0m ([14X3.4-1[0m) except that in
  the   successful   case  the  component  [10Xslp[0m  of  the  resulting  record  is
  additionally bound to a straight line program which expresses the element [3Xel[0m
  in   terms   of   the   strong  generators  of  the  stabiliser  chain  (see
  [2XStrongGenerators[0m ([14X3.4-3[0m)).
  
  [1X3.4-3 StrongGenerators[0m
  
  [2X> StrongGenerators( [0X[3XS[0X[2X ) ___________________________________________[0Xoperation
  [6XReturns:[0X  a list of group elements
  
  This operation returns the strong generators of the stabiliser chain [3XS[0m. This
  means  that  each  stabiliser  in  the  stabiliser chain is generated by the
  subset  of  the set of strong generators which fix the corresponding points.
  Note  that  each  layer  of  the  stabiliser chain uses some subset of these
  strong generators as generators for the orbit object of that layer.
  
  [1X3.4-4 NrStrongGenerators[0m
  
  [2X> NrStrongGenerators( [0X[3XS[0X[2X ) _________________________________________[0Xoperation
  [6XReturns:[0X  a positive integer
  
  This  operation  returns  the  number of strong generators of the stabiliser
  chain [3XS[0m (see [2XStrongGenerators[0m ([14X3.4-3[0m)).
  
  [1X3.4-5 BaseStabilizerChain[0m
  
  [2X> BaseStabilizerChain( [0X[3XS[0X[2X ) ________________________________________[0Xoperation
  [6XReturns:[0X  a record
  
  This  operation  returns  the  base  of  the stabiliser chain [3XS[0m in form of a
  record,  which  can  be  used  as  the [10XCand[0m component for a stabiliser chain
  computation.  That  is,  two components are bound, the [10Xpoints[0m component is a
  list  of base points and the [10Xops[0m component is a corresponding list of action
  functions.
  
  [1X3.4-6 Size[0m
  
  [2X> Size( [0X[3XS[0X[2X ) _______________________________________________________[0Xoperation
  [6XReturns:[0X  a positive integer
  
  This  operation  returns the size (i.e. order) of the group described by the
  stabiliser  chain [3XS[0m. This is simply the product of the lengths of the orbits
  in the chain.
  
  [1X3.4-7 Random[0m
  
  [2X> Random( [0X[3XS[0X[2X ) _____________________________________________________[0Xoperation
  [6XReturns:[0X  a group element
  
  This  operation  can  be  called  with a stabiliser chain object [3XS[0m or with a
  group  object,  if  this  group  object  has  a stored stabiliser chain (see
  [2XSetStabilizerChain[0m  ([14X3.4-11[0m)).  The  method will randomly choose transversal
  elements  and  thus  produce  a  uniformly distributed random element of the
  group.
  
  [1X3.4-8 \in[0m
  
  [2X> \in( [0X[3Xx, S[0X[2X ) _____________________________________________________[0Xoperation
  [6XReturns:[0X  [10Xtrue[0m or [10Xfalse[0m
  
  This  operation  tests  whether or not the group element [3Xx[0m lies in the group
  described  by  the  stabiliser  chain  [3XS[0m  by  sifting  (see [2XSiftGroupElement[0m
  ([14X3.4-1[0m)). The argument [3XS[0m can also be a group object with a stored stabiliser
  chain  (see  [2XSetStabilizerChain[0m  ([14X3.4-11[0m)).  Note that this operation can be
  called with the [9Xin[0m keyword using infix notation.
  
  [1X3.4-9 IsProved[0m
  
  [2X> IsProved( [0X[3XS[0X[2X ) ___________________________________________________[0Xoperation
  [6XReturns:[0X  [10Xtrue[0m or [10Xfalse[0m
  
  This operation returns whether or not the stabiliser chain [3XS[0m is proved to be
  correct.  If  it  has  only  been  verified  by randomised methods, [10Xfalse[0m is
  returned.  At  the  time  of  this  writing  the only possible deterministic
  verification  is  if  the  size  of the group is known before the stabiliser
  chain computation begins.
  
  [1X3.4-10 GroupIteratorByStabilizerChain[0m
  
  [2X> GroupIteratorByStabilizerChain( [0X[3XS[0X[2X ) _____________________________[0Xoperation
  [6XReturns:[0X  an iterator
  
  This operation returns an iterator object which runs through the elements of
  the  group  described by the stabiliser chain object [3XS[0m. The usual operations
  [2XNextIterator[0m   ([14XReference:   NextIterator[0m)  and  [2XIsDoneIterator[0m  ([14XReference:
  IsDoneIterator[0m)  as  well as the [9Xfor[0m loop construction can be used with this
  object.  The  iterator  is  implemented using the stored transversals in the
  Schreier trees of the stabiliser chain.
  
  [1X3.4-11 SetStabilizerChain[0m
  
  [2X> SetStabilizerChain( [0X[3Xg, S[0X[2X ) ______________________________________[0Xoperation
  [6XReturns:[0X  nothing
  
  Once the user is convinced that the stabiliser chain [3XS[0m describes the group [3Xg[0m
  correctly, he can call this operation to store the stabiliser chain together
  with the group object. From then on, additional methods using the stabiliser
  chain  (for  example  [2XSize[0m  ([14X3.4-6[0m),  [2XRandom[0m  ([14X3.4-7[0m) and [2X\in[0m ([14X3.4-8[0m) above)
  become  applicable  for the group object. Note that if a stabiliser chain is
  known  to  be  correct  (for example if the group knew its size beforehand),
  then  the stabiliser chain is stored with the group automatically when it is
  constructed,  which  makes  the  explicit  storing  of  the stabiliser chain
  unnecessary.
  
  The   stored   stabiliser  chain  of  a  group  object  can  be  used  using
  [2XStoredStabilizerChain[0m ([14X3.4-12[0m).
  
  [1X3.4-12 StoredStabilizerChain[0m
  
  [2X> StoredStabilizerChain( [0X[3Xg[0X[2X ) ______________________________________[0Xattribute
  [6XReturns:[0X  a stabiliser chain
  
  This  attribute  for a group object [3Xg[0m contains a stored stabiliser chain for
  the group. See [2XSetStabilizerChain[0m ([14X3.4-11[0m) for details.
  
  [1X3.4-13 StabChainOp[0m
  
  [2X> StabChainOp( [0X[3Xp, S[0X[2X ) ________________________________________________[0Xmethod
  [6XReturns:[0X  a [5XGAP[0m stabiliser chain
  
  This  method  computes  a  standard  [5XGAP[0m  library  stabiliser  chain for the
  permutation  group  [3Xp[0m  using  the  fact that [3XS[0m is a known correct stabiliser
  chain  for  [3Xp[0m. If all base points in [3XS[0m are positive integers and all actions
  are  equal  to  [10XOnPoints[0m,  then  the  same base points are taken for the new
  stabiliser chain.
  
  [1X3.4-14 SiftBaseImage[0m
  
  [2X> SiftBaseImage( [0X[3XS, l[0X[2X ) ___________________________________________[0Xoperation
  [6XReturns:[0X  [10Xtrue[0m or [10Xfalse[0m
  
  This  operation  sifts an image [3Xl[0m of the base points of the stabiliser chain
  [3XS[0m.  This  means  that  the elements of the list [3Xl[0m must be images of the base
  points  under the actions in the various layers of the stabiliser chain. The
  sifting  procedure  using  the  orbits  and Schreier trees in the stabiliser
  chain  decides  if  this  base image is one for a group element of the group
  described by [3XS[0m and returns [10Xtrue[0m or [10Xfalse[0m accordingly.
  
  This operation is mostly used internally.
  
  [1X3.4-15 SLPChainStabilizerChain[0m
  
  [2X> SLPChainStabilizerChain( [0X[3XS, gens[0X[2X ) ______________________________[0Xoperation
  [6XReturns:[0X  a record
  
  This operation assumes that [3XS[0m is a stabiliser chain that correctly describes
  the  group  generated  by the generators [3Xgens[0m. It returns a list of straight
  line  programs expressing successively the stabilisers in the chain, each in
  terms  of  the  generators of the previous, the first in terms of [3Xgens[0m. This
  list  is  stored in the component [10Xslps[0m of the resulting record. The sizes of
  the  groups  in the chain are stored in the component [10Xsizes[0m of the resulting
  record.
  
  The  operations, functions and methods described below use stabiliser chains
  internally:
  
  [1X3.4-16 GroupHomomorphismByImagesNCStabilizerChain[0m
  
  [2X> GroupHomomorphismByImagesNCStabilizerChain( [0X[3Xg, h, images, opt1, opt2[0X[2X ) [0Xfunction
  [6XReturns:[0X  a group homomorphism
  
  This  function creates a group homomorphism object from the group [3Xg[0m into the
  group object [3Xh[0m, mapping the generators of the group [3Xg[0m to the elements [3Ximages[0m
  which  must  lie  in [3Xh[0m. This mapping must be a group homomorphism, note that
  this is not checked!
  
  The  homomorphism  is  computed by computing stabiliser chains on both sides
  such  that  elements  can be mapped in both directions simply be sifting and
  expressing  them  in  terms  of the strong generators. This is where the two
  arguments  [3Xopts1[0m and [3Xopts2[0m come into play. The former is used as the options
  record for the stabiliser computation in [3Xg[0m and the latter for the one in the
  group generated by [3Ximages[0m.
  
  [1X3.4-17 FindShortGeneratorsOfSubgroup[0m
  
  [2X> FindShortGeneratorsOfSubgroup( [0X[3Xg, u[0X[2X ) ______________________________[0Xmethod
  [6XReturns:[0X  a record
  
  This  is  an additional method for matrix or permutation groups implementing
  the          operation          [2XFindShortGeneratorsOfSubgroup[0m          ([14Xorb:
  FindShortGeneratorsOfSubgroup[0m) from the [5Xorb[0m package using stabiliser chains.
  Both  arguments  must be groups and [3Xu[0m must be a subgroup of [3Xg[0m. The resulting
  record  contains  two  components [10Xgens[0m and [10Xslp[0m, where the first is a list of
  generators  for  the  group  [3Xu[0m  and  the  second  is a straight line program
  expressing [10Xgens[0m in terms of the generators of [3Xg[0m. This operation aims to find
  short words in the generators of [3Xg[0m to use as generators for [3Xu[0m.
  
  [1X3.4-18 Stab[0m
  
  [2X> Stab( [0X[3Xg, x, op[, opt][0X[2X ) _________________________________________[0Xoperation
  [6XReturns:[0X  a record or [9Xfail[0m
  
  This  operation  aims  to compute the point stabiliser of the group [3Xg[0m acting
  via  the action function [3Xop[0m of the point [3Xx[0m. The optional last argument is an
  options  record.  The  general  approach of this procedure is to go back and
  forth  between  enumerating a part of the orbit and trying to produce random
  elements  in  the stabiliser using the already enumerated part of the orbit.
  Random  elements in the stabiliser are produced by using product replacement
  in [3Xg[0m to produce random elements of [3Xg[0m and then using the Schreier tree of the
  orbit  to  map  them  back into the stabiliser. If this works, the resulting
  random elements are distributed uniformly in the point stabiliser.
  
  This  routine  is  a  Monte  Carlo  procedure.  If  sufficiently many random
  elements of the stabiliser have been produced and did not increase its size,
  the  program  concludes  that  the  whole  stabiliser is found and returns a
  record describing it. Otherwise it returns [9Xfail[0m after some time.
  
  The  resulting  record  has  the  stabiliser in the component [10Xstab[0m, its size
  estimate in the component [10Xsize[0m, a stabiliser chain for [10Xstab[0m in the component
  [10Xstabilizerchain[0m  and  a  boolean  value  in  the  component [10Xproof[0m indicating
  whether or not the result is certain.
  
  We do not document all possible options in the options record here, since we
  want  to  allow  for  the possibility to change these in later versions. The
  most  important  component in the options record is the component [10XErrorBound[0m
  which  must  be  bound  to a rational number between 0 and 1 and which is an
  upper bound for the error probability.
  
  Please  note  again  that two types of errors can occur in this program: The
  first  is  that  the correct point stabiliser is not found but only a proper
  subgroup  of  it.  The  second  is  that the stabiliser chain computation to
  estimate its size went wrong and returns an incorrect stabiliser chain.
  
