chap6.txt

  
  6 ANUPQ Options
  
  
  6.1 Overview
  
  In  this  chapter we describe in detail all the options used by functions of
  the  ANUPQ package. Note that by options we mean GAP options that are passed
  to functions after the arguments and separated from the arguments by a colon
  as  described  in Chapter Reference: Function Calls in the Reference Manual.
  The  user  is strongly advised to read Section 'Hints and Warnings regarding
  the use of Options'.
  
  6.1-1 AllANUPQoptions
  
  AllANUPQoptions(  )  function
  
  lists all the GAP options defined for functions of the ANUPQ package:
  
    Example  
    gap> AllANUPQoptions();
    [ "AllDescendants", "BasicAlgorithm", "Bounds", "CapableDescendants", 
      "ClassBound", "CustomiseOutput", "Exponent", "Filename", "GroupName", 
      "Identities", "Metabelian", "NumberOfSolubleAutomorphisms", "OrderBound", 
      "OutputLevel", "PcgsAutomorphisms", "PqWorkspace", "Prime", 
      "PrintAutomorphisms", "PrintPermutations", "QueueFactor", 
      "RankInitialSegmentSubgroups", "RedoPcp", "RelativeOrders", "Relators", 
      "SetupFile", "SpaceEfficient", "StandardPresentationFile", "StepSize", 
      "SubList", "TreeDepth", "pQuotient" ]
  
  
  The  following  global variable gives a partial breakdown of where the above
  options are used.
  
  6.1-2 ANUPQoptions
  
  ANUPQoptions global variable
  
  is  a  record  of lists of names of admissible ANUPQ options, such that each
  field  is  either  the  name  of  a  key  ANUPQ  function  or  other  (for a
  miscellaneous  list of functions) and the corresponding value is the list of
  option  names that are admissible for the function (or miscellaneous list of
  functions).
  
  Also,  from  within  a  GAP  session,  you  may  use GAP's help browser (see
  Chapter Reference: The Help System in the GAP Reference Manual); to find out
  about any particular ANUPQ option, simply type: ?option option, where option
  is one of the options listed above without any quotes, e.g.
  
    Example  
    gap> ?option Prime
  
  
  will  display the sections in this manual that describe the Prime option. In
  fact  the first 4 are for the functions that have Prime as an option and the
  last actually describes the option. So follow up by choosing
  
    Example  
    gap> ?5
  
  
  This  is  also  the  pattern for other options (the last section of the list
  always describes the option; the other sections are the functions with which
  the option may be used).
  
  In  the  section  following  we  describe  in  detail  all ANUPQ options. To
  continue onto the next section on-line using GAP's help browser, type:
  
    Example  
    gap> ?>
  
  
  
  6.2 Detailed descriptions of ANUPQ Options
  
  Prime := p 
        Specifies that the p-quotient for the prime p should be computed.
  
  ClassBound := n 
        Specifies  that  the  p-quotient  to  be computed has lower exponent-p
        class  at  most n. If this option is omitted a default of 63 (which is
        the  maximum  possible  for  the  pq  program)  is  taken,  except for
        PqDescendants  (see PqDescendants  (4.4-1))  and  in a special case of
        PqPCover (see PqPCover (4.1-3)). Let F be the argument (or start group
        of  the  process  in  the interactive case) for the function; then for
        PqDescendants  the default is PClassPGroup(F) + 1, and for the special
        case of PqPCover the default is PClassPGroup(F).
  
  pQuotient := Q 
        This option is only available for the standard presentation functions.
        It  specifies  that a p-quotient of the group argument of the function
        or  group of the process is the pc p-group Q, where Q is of class less
        than  the  provided  (or default) value of ClassBound. If pQuotient is
        provided,  then  the  option  Prime  if also provided, is ignored; the
        prime p is discovered by computing PrimePGroup(Q).
  
  Exponent := n 
        Specifies  that  the  p-quotient to be computed has exponent n. For an
        interactive  process, Exponent defaults to a previously supplied value
        for  the process. Otherwise (and non-interactively), the default is 0,
        which means that no exponent law is enforced.
  
  Relators := rels 
        Specifies  that  the  relators  sent  to the pq program should be rels
        instead of the relators of the argument group F (or start group in the
        interactive  case)  of  the calling function; rels should be a list of
        strings  in  the  string representations of the generators of F, and F
        must be an fp group (even if the calling function accepts a pc group).
        This  option  provides  a  way  of  giving relators to the pq program,
        without  having them pre-expanded by GAP, which can sometimes effect a
        performance  loss  of  the  order  of  100  (see Section 'The Relators
        Option').
  
        Notes
  
        1   The  pq  program does not use / to indicate multiplication by an
              inverse  and  uses  square  brackets  to represent (left normed)
              commutators. Also, even though the pq program accepts relations,
              all elements of rels must be in relator form, i.e. a relation of
              form  w1  =  w2  must be written as w1*(w2)^-1 and then put in a
              pair  of  double-quotes  to  make  it  a string. See the example
              below.
  
        2   To  ensure  there  are no syntax errors in rels, each relator is
              parsed  for  validity via PqParseWord (see PqParseWord (3.4-3)).
              If  they  are  ok,  a  message to say so is Info-ed at InfoANUPQ
              level 2.
  
  Metabelian 
        Specifies  that the largest metabelian p-quotient subject to any other
        conditions  specified by other options be constructed. By default this
        restriction is not enforced.
  
  GroupName := name 
        Specifies  that  the  pq program should refer to the group by the name
        name  (a  string).  If  GroupName  is  not  set and the group has been
        assigned  a  name  via  SetName (see Reference: Name) it is set as the
        name the pq program should use. Otherwise, the generic name "[grp]" is
        set as a default.
  
  Identities := funcs 
        Specifies  that the pc presentation should satisfy the laws defined by
        each  function  in  the  list  funcs. This option may be called by Pq,
        PqEpimorphism, or PqPCover (see Pq (4.1-1)). Each function in the list
        funcs  must return a word in its arguments (there may be any number of
        arguments).  Let  identity be one such function in funcs. Then as each
        lower  exponent  p-class  quotient  is  formed, instances identity(w1,
        dots,  wn)  are  added  as  relators to the pc presentation, where w1,
        dots, wn are words in the pc generators of the quotient. At each class
        the class and number of pc generators is Info-ed at InfoANUPQ level 1,
        the  number  of  instances  is  Info-ed  at InfoANUPQ level 2, and the
        instances  that  are  evaluated  are  Info-ed at InfoANUPQ level 3. As
        usual  timing information is Info-ed at InfoANUPQ level 2; and details
        of the processing of each instance from the pq program (which is often
        quite  voluminous)  is  Info-ed at InfoANUPQ level 3. Try the examples
        "B2-4-Id"  and  "11gp-3-Engel-Id"  which  demonstrate the usage of the
        Identities  option;  these  are  run  using  PqExample  (see PqExample
        (3.4-4)).  Take  note  of  Note  1. below  in  relation to the example
        "B2-4-Id"; the companion example "B2-4" generates the same group using
        the  Exponent  option.  These  examples  are  discussed  at  length in
        Section 'The Identities Option and PqEvaluateIdentities Function'.
  
        Notes
  
        1   Setting  the  InfoANUPQ  level  to  3  or  more when setting the
              Identities option may slow down the computation considerably, by
              overloading GAP with io operations.
  
        2   The  Identities  option  is  implemented  at  the  GAP level. An
              identity  that is just an exponent law should be specified using
              the  Exponent option (see option Exponent), which is implemented
              at  the  C  level  and  is  highly optimised and so is much more
              efficient.
  
        3   The   number  of  instances  of  each  identity  tends  to  grow
              combinatorially  with  the class. So care should be exercised in
              using  the  Identities  option, by including other restrictions,
              e.g. by using the ClassBound option (see option ClassBound).
  
  OutputLevel := n 
        Specifies  the level of verbosity of the information output by the ANU
        pq  program  when computing a pc presentation; n must be an integer in
        the range 0 to 3. OutputLevel := 0 displays at most one line of output
        and  is the default; OutputLevel := 1 displays (usually) slightly more
        output  and  OutputLevels of 2 and 3 are two levels of verbose output.
        To see these messages from the pq program, the InfoANUPQ level must be
        set  to  at  least  1  (see InfoANUPQ (3.3-1)). See Section 'Hints and
        Warnings  regarding  the  use  of  Options'  for  an  example  of  how
        OutputLevel can be used as a troubleshooting tool.
  
  RedoPcp 
        Specifies  that  the  current  pc  presentation  (for  an  interactive
        process)  stored  by the pq program be scrapped and clears the current
        values   stored  for  the  options  Prime,  ClassBound,  Exponent  and
        Metabelian  and  also clears the pQuotient, pQepi and pCover fields of
        the data record of the process.
  
  SetupFile := filename 
        Non-interactively,  this  option  directs that pq should not be called
        and  that  an input file with name filename (a string), containing the
        commands  necessary  for  the  ANU  pq standalone, be constructed. The
        commands  written  to filename are also Info-ed behind a ToPQ>  prompt
        at  InfoANUPQ  level  4  (see InfoANUPQ  (3.3-1)).  Except in the case
        following,  the calling function returns true. If the calling function
        is the non-interactive version of one of Pq, PqPCover or PqEpimorphism
        and  the group provided as argument is trivial given with an empty set
        of generators, then no setup file is written and fail is returned (the
        pq   program   cannot   do   anything   useful  with  such  a  group).
        Interactively, SetupFile is ignored.
  
        Note:  Since  commands emitted to the pq program may depend on knowing
        what  the  current  state  is,  to form a setup file some close enough
        guesses  may  sometimes  be  necessary;  when this occurs a warning is
        Info-ed  at InfoANUPQ or InfoWarning level 1. To determine whether the
        close  enough  guesses give an accurate setup file, it is necessary to
        run the command without the SetupFile option, after either setting the
        InfoANUPQ  level  to  at  least  4  (the setup file script can then be
        compared  with  the  ToPQ>  commands that are Info-ed) or setting a pq
        command log file by using ToPQLog (see ToPQLog (3.4-7)).
  
  PqWorkspace := workspace 
        Non-interactively, this option sets the memory used by the pq program.
        It  sets  the  maximum number of integer-sized elements to allocate in
        its main storage array. By default, the pq program sets this figure to
        10000000.  Interactively,  PqWorkspace  is ignored; the memory used in
        this  case may be set by giving PqStart a second argument (see PqStart
        (5.1-1)).
  
  PcgsAutomorphisms 
  PcgsAutomorphisms := false 
        Let G be the group associated with the calling function (or associated
        interactive  process).  Passing the option PcgsAutomorphisms without a
        value   (or  equivalently  setting  it  to  true),  specifies  that  a
        polycyclic  generating sequence for the automorphism group (which must
        be  soluble)  of  G,  be  computed  and passed to the pq program. This
        increases  the  efficiency of the computation; it also prevents the pq
        from  calling  GAP  for  orbit-stabilizer  calculations.  By  default,
        PcgsAutomorphisms   is  set  to  the  value  returned  by  IsSolvable(
        AutomorphismGroup(  G  )  ),  and  uses the package AutPGrp to compute
        AutomorphismGroup( G ) if it is installed. This flag is set to true or
        false  in  the  background  according  to  the  above criterion by the
        function  PqDescendants  (see PqDescendants  (4.4-1) and PqDescendants
        (5.3-6)).
  
        Note: If PcgsAutomorphisms is used when the automorphism group of G is
        insoluble, an error message occurs.
  
  OrderBound := n 
        Specifies  that  only  descendants  of  size at most p^n, where n is a
        non-negative  integer,  be  generated.  Note  that you cannot set both
        OrderBound and StepSize.
  
  StepSize := n 
  StepSize := list 
        For a positive integer n, StepSize specifies that only those immediate
        descendants  which  are a factor p^n bigger than their parent group be
        generated.
  
        For  a  list list of positive integers such that the sum of the length
        of  list  and  the  exponent-p  class of G is equal to the class bound
        defined by the option ClassBound, StepSize specifies that the integers
        of list are the step sizes for each additional class.
  
  RankInitialSegmentSubgroups := n 
        Sets  the  rank  of  the  initial  segment subgroup chosen to be n. By
        default, this has value 0.
  
  SpaceEfficient 
        Specifies that the pq program performs certain calculations of p-group
        generation more slowly but with greater space efficiency. This flag is
        frequently  necessary  for groups of large Frattini quotient rank. The
        space  saving occurs because only one permutation is stored at any one
        time.  This  option is only available if the PcgsAutomorphisms flag is
        set   to  true  (see option  PcgsAutomorphisms).  For  an  interactive
        process,  SpaceEfficient  defaults  to a previously supplied value for
        the  process.  Otherwise (and non-interactively), SpaceEfficient is by
        default false.
  
  CapableDescendants 
        By  default, all (i.e. capable and terminal) descendants are computed.
        If  this  flag  is set, only capable descendants are computed. Setting
        this   option   is  equivalent  to  setting  AllDescendants  :=  false
        (see option  AllDescendants),  except  if  both CapableDescendants and
        AllDescendants are passed, AllDescendants is essentially ignored.
  
  AllDescendants := false 
        By  default,  all  descendants are constructed. If this flag is set to
        false,  only  capable descendants are computed. Passing AllDescendants
        without  a  value  (which  is  equivalent  to  setting  it to true) is
        superfluous.  This  option is provided only for backward compatibility
        with  the  GAP  3  version  of  the  ANUPQ  package,  where by default
        AllDescendants  was  set to false (rather than true). It is preferable
        to use CapableDescendants (see option CapableDescendants).
  
  TreeDepth := class 
        Specifies     that     the     descendants     tree    developed    by
        PqDescendantsTreeCoclassOne  (see PqDescendantsTreeCoclassOne (A.4-1))
        should be extended to class class, where class is a positive integer.
  
  SubList := sub 
        Suppose  that  L is the list of descendants generated, then for a list
        sub of integers this option causes PqDescendants to return Sublist( L,
        sub ). If an integer n is supplied, PqDescendants returns L[n].
  
  NumberOfSolubleAutomorphisms := n 
        Specifies that the number of soluble automorphisms of the automorphism
        group supplied by PqPGSupplyAutomorphisms (see PqPGSupplyAutomorphisms
        (5.9-1))  in  a  p-group generation calculation is n. By default, n is
        taken  to  be  0;  n  must be a non-negative integer. If n ge 0 then a
        value for the option RelativeOrders (see 6.2) must also be supplied.
  
  RelativeOrders := list 
        Specifies  the  relative  orders  of  each soluble automorphism of the
        automorphism     group     supplied     by     PqPGSupplyAutomorphisms
        (see PqPGSupplyAutomorphisms   (5.9-1))   in   a   p-group  generation
        calculation.  The list list must consist of n positive integers, where
        n  is  the value of the option NumberOfSolubleAutomorphisms (see 6.2).
        By default list is empty.
  
  BasicAlgorithm 
        Specifies  that  an  algorithm  that  the pq program calls its default
        algorithm be used for p-group generation. By default this algorithm is
        not  used.  If  this  option  is  supplied  the  settings  of  options
        RankInitialSegmentSubgroups,  AllDescendants,  Exponent and Metabelian
        are ignored.
  
  CustomiseOutput := rec 
        Specifies  that  fine  tuning of the output is desired. The record rec
        should have any subset (or all) of the the following fields:
  
        perm := list
              where  list  is  a  list of booleans which determine whether the
              permutation  group  output  for  the  automorphism  group should
              contain:   the   degree,   the   extended   automorphisms,   the
              automorphism matrices, and the permutations, respectively.
  
        orbit := list
              where  list  is  a  list of booleans which determine whether the
              orbit  output  of  the  action  of the automorphism group should
              contain:   a   summary,   and  a  complete  listing  of  orbits,
              respectively.  (It's  possible  to  have  both  a  summary and a
              complete listing.)
  
        group := list
              where  list  is  a  list of booleans which determine whether the
              group  output  should  contain:  the  standard  matrix  of  each
              allowable  subgroup,  the  presentation  of  reduced  p-covering
              groups,  the  presentation of immediate descendants, the nuclear
              rank   of   descendants,   and   the   p-multiplicator  rank  of
              descendants, respectively.
  
        autgroup := list
              where  list  is  a  list of booleans which determine whether the
              automorphism group output should contain: the commutator matrix,
              the  automorphism  group  description  of  descendants,  and the
              automorphism group order of descendants, respectively.
  
        trace := val
              where  val  is a boolean which if true specifies algorithm trace
              data  is  desired.  By default, one does not get algorithm trace
              data.
  
        Not  providing  a  field  (or  mis-spelling  it!),  specifies that the
        default  output  is  desired.  As a convenience, 1 is also accepted as
        true, and any value that is neither 1 nor true is taken as false. Also
        for  each  list  above, an unbound list entry is taken as false. Thus,
        for example
  
          Example  
          CustomiseOutput := rec(group := [,,1], autgroup := [,1])
        
  
        specifies for the group output that only the presentation of immediate
        descendants  is  desired,  for  the automorphism group output only the
        automorphism  group description of descendants should be printed, that
        there  should  be no algorithm trace data, and that the default output
        should be provided for the permutation group and orbit output.
  
  StandardPresentationFile := filename 
        Specifies  that the file to which the standard presentation is written
        has  name  filename.  If the first character of the string filename is
        not  /, filename is assumed to be the path of a writable file relative
        to  the  directory in which GAP was started. If this option is omitted
        it  is  written  to  the  file  with the name generated by the command
        Filename(  ANUPQData.tmpdir,  "SPres"  );,  i.e. the  file  with  name
        "SPres" in the temporary directory in which the pq program executes.
  
  QueueFactor := n 
        Specifies  a  queue  factor  of n, where n must be a positive integer.
        This option may be used with PqNextClass (see PqNextClass (5.6-4)).
  
        The  queue  factor  is  used when the pq program uses automorphisms to
        close a set of elements of the p-multiplicator under their action.
  
        The  algorithm  used  is a spinning algorithm: it starts with a set of
        vectors  in  echelonized  form  (elements  of the p-multiplicator) and
        closes   the   span   of   these  vectors  under  the  action  of  the
        automorphisms.  For  this  each automorphism is applied to each vector
        and  it  is checked if the result is contained in the span computed so
        far.  If  not,  the  span  becomes bigger and the vector is put into a
        queue  and  the  automorphisms  are  applied to this vector at a later
        stage. The process terminates when the automorphisms have been applied
        to all vectors and no new vectors have been produced.
  
        For  each  new  vector  it  is  decided,  if  its processing should be
        delayed.  If  the vector contains too many non-zero entries, it is put
        into  a  second  queue.  The elements in this queue are processed only
        when there are no elements in the first queue left.
  
        The  queue  factor  is  a  percentage figure. A vector is put into the
        second  queue  if  the  percentage of its non-zero entries exceeds the
        queue factor.
  
  Bounds := list 
        Specifies a lower and upper bound on the indices of a list, where list
        is  a pair of positive non-decreasing integers. See PqDisplayStructure
        (5.7-23)  and PqDisplayAutomorphisms (5.7-24) where this option may be
        used.
  
  PrintAutomorphisms := list 
        Specifies that automorphism matrices be printed.
  
  PrintPermutations := list 
        Specifies that permutations of the subgroups be printed.
  
  Filename := string 
        Specifies  that  an output or input file to be written to or read from
        by the pq program should have the name string.