[Up] [Previous] [Next] [Index]

# 5 Interactive ANUPQ functions

### Sections

1. Starting and Stopping Interactive ANUPQ Processes
2. Interactive ANUPQ Process Utility Functions
3. Interactive Versions of Non-interactive ANUPQ Functions
4. Low-level Interactive ANUPQ Functions based on menu items of the pq program
5. Primitive Interactive ANUPQ Process Read/Write Functions

Here we describe the interactive functions defined by the ANUPQ package, i.e. the functions that manipulate and initiate interactive ANUPQ processes. These are functions that extract information via a dialogue with a running `pq` process (process used in the UNIX sense). Occasionally, a user needs the ``next step''; the functions provided in this chapter make use of data from previous steps retained by the `pq` program, thus allowing the user to interact with the `pq` program like one can when one uses the `pq` program as a stand-alone (see `guide.dvi` in the `standalone-doc` directory).

An interactive ANUPQ process is initiated by `PqStart` and terminated via `PqQuit`; these functions are described in Section Starting and Stopping Interactive ANUPQ Processes.

Each interactive ANUPQ function that manipulates an already started interactive ANUPQ process, has a form where the first argument is the integer i returned by the initiating `PqStart` command, and a second form with one argument fewer (where the integer i is discovered by a default mechanism, namely by determining the least integer i for which there is a currently active interactive ANUPQ process). We will thus commonly say that ``for the ith (or default) interactive ANUPQ process'' a certain function performs a given action. In each case, it is an error if i is not the index of an active interactive process, or there are no current active interactive processes.

Notes: The global method of passing options (via `PushOptions`), should not be used with any of the interactive functions. In fact, the `OptionsStack` should be empty at the time any of the interactive functions is called.

On `quit`ting GAP, `PqQuitAll();` is executed, which terminates all active interactive ANUPQ processes. If GAP is killed without `quit`ting, before all interactive ANUPQ processes are terminated, zombie processes (still living child processes whose parents have died), may result. Since zombie processes do consume resources, in such an event, the responsible computer user should seek out and terminate those zombie processes (e.g. on Linux: `ps xw | grep pq` gives you information on the `pq` processes corresponding to any interactive ANUPQ processes started in a GAP session; you can then do `kill` N`` for each number N appearing in the first column of this output).

## 5.1 Starting and Stopping Interactive ANUPQ Processes

- `PqStart(` G`,` workspace`:` options`) F`
- `PqStart(` G`:` options`) F`
- `PqStart(` workspace`:` options`) F`
- `PqStart(:` options`) F`

  activate an iostream for an interactive ANUPQ process (i.e. `PqStart` starts up a `pq` process and opens a GAP iostream to ``talk'' to that process) and returns an integer i that can be used to identify that process. The argument G should be an fp group or pc group that the user intends to manipulate using interactive ANUPQ functions. If the function is called without specifying G, a group can be read in by using the function `PqRestorePcPresentation` (see PqRestorePcPresentation). If `PqStart` is given an integer argument workspace, then the `pq` program is started up with a workspace (an integer array) of size workspace (i.e. 4 ×workspace bytes in a 32-bit environment); otherwise, the `pq` program sets a default workspace of 10000000.

  The only options currently recognised by `PqStart` are `Prime`, `Exponent` and `Relators` (see Chapter ANUPQ options for detailed descriptions of these options) and if provided they are essentially global for the interactive ANUPQ process, except that any interactive function interacting with the process and passing new values for these options will over-ride the global values.

- `PqQuit(` i`) F`
- `PqQuit() F`

  closes the stream of the ith or default interactive ANUPQ process and unbinds its `ANUPQData.io` record.

  Note: It can happen that the `pq` process, and hence the GAP iostream assigned to communicate with it, can die, e.g. by the user typing a `Ctrl-C` while the `pq` process is engaged in a long calculation. `IsPqProcessAlive` (see IsPqProcessAlive) is provided to check the status of the GAP iostream (and hence the status of the `pq` process it was communicating with).

- `PqQuitAll() F`

  is provided as a convenience, to terminate all active interactive ANUPQ processes with a single command. It is equivalent to executing `PqQuit(`i`)` for all active interactive ANUPQ processes i (see PqQuit).

  ## 5.2 Interactive ANUPQ Process Utility Functions

- `PqProcessIndex(` i`) F`
- `PqProcessIndex() F`

  With argument i, which must be a positive integer, `PqProcessIndex` returns i if it corresponds to an active interactive process, or raises an error. With no arguments it returns the default active interactive process or returns `fail` and emits a warning message to `Info` at `InfoANUPQ` or `InfoWarning` level 1.

  Note: Essentially, an interactive ANUPQ process i is ``active'' if `ANUPQData.io[`i`]` is bound (i.e. we still have some data telling us about it). Also see PqStart.

- `PqProcessIndices() F`

  returns the list of integer indices of all active interactive ANUPQ processes (see PqProcessIndex for the meaning of ``active'').

- `IsPqProcessAlive(` i`) F`
- `IsPqProcessAlive() F`

  return `true` if the GAP iostream of the ith (or default) interactive ANUPQ process started by `PqStart` is alive (i.e. can still be written to), or `false`, otherwise. (See the notes for PqStart and PqQuit.)

  If the user does not yet have a `gap>` prompt then usually the `pq` program is still away doing something and an ANUPQ interface function is still waiting for a reply. Typing a `Ctrl-C` (i.e. holding down the `Ctrl` key and typing `c`) will stop the waiting and send GAP into a `break`-loop, from which one has no option but to `quit;`. The typing of `Ctrl-C`, in such a circumstance, usually causes the stream of the interactive ANUPQ process to die; to check this we provide `IsPqProcessAlive` (see IsPqProcessAlive).

  The GAP iostream of an interactive ANUPQ process will also die if the `pq` program has a segmentation fault. We do hope that this never happens to you, but if it does and the failure is reproducible, then it's a bug and we'd like to know about it. Please read the `README` that comes with the ANUPQ package to find out what to include in a bug report and who to email it to.

  ## 5.3 Interactive Versions of Non-interactive ANUPQ Functions

- `Pq(` i`:` options`) F`
- `Pq( :` options`) F`

  return, for the fp or pc group (let us call it F), of the ith or default interactive ANUPQ process, the p-quotient of F specified by options, as a pc group; F must previously have been given (as first argument) to `PqStart` to start the interactive ANUPQ process (see PqStart) or restored from file using the function `PqRestorePcPresentation` (see PqRestorePcPresentation). Following the colon options is a selection of the options listed for the non-interactive `Pq` function (see Pq), separated by commas like record components (see Section function call!with options in the GAP Reference Manual), except that the options `SetupFile` or `PqWorkspace` are ignored by the interactive `Pq`, and `RedoPcp` is an option only recognised by the interactive `Pq` i.e. the following options are recognised by the interactive `Pq` function:

  - `Prime :=` p``

  - `ClassBound :=` n``

  - `Exponent :=` n``

  - `Relators :=` rels``

  - `Metabelian`

  - `Identities :=` funcs``

  - `GroupName :=` name``

  - `OutputLevel :=` n``

  - `RedoPcp`

  Detailed descriptions of the above options may be found in Chapter ANUPQ options.

  As a minimum the `Pq` function must have a value for the `Prime` option, though `Prime` need not be passed again in the case it has previously been provided, e.g. to `PqStart` (see PqStart) when starting the interactive process.

  The behaviour of the interactive `Pq` function depends on the current state of the pc presentation stored by the `pq` program:

  1. If no pc presentation has yet been computed (the case immediately after the `PqStart` call initiating the process) then the quotient group of the input group of the process of largest lower exponent-p class bounded by the value of the `ClassBound` option (see option ClassBound) is returned.

  2. If the current pc presentation of the process was determined by a previous call to `Pq` or `PqEpimorphism`, and the current call has a larger value `ClassBound` then the class is extended as much as is possible and the quotient group of the input group of the process of the new lower exponent-p class is returned.

  3. If the current pc presentation of the process was determined by a previous call to `PqPCover` then a consistent pc presentation of a quotient for the current class is determined before proceeding as in 2.

  4. If the `RedoPcp` option is supplied the current pc presentation is scrapped, all options must be re-supplied (in particular, `Prime` must be supplied) and then the `Pq` function proceeds as in 1.

  See Section Attributes and a Property for fp and pc p-groups for the attributes and property `NuclearRank`, `MultiplicatorRank` and `IsCapable` which may be applied to the group returned by `Pq`.

  The following is one of the examples for the non-interactive `Pq` redone with the interactive version. Also, we set the option `OutputLevel` to 1 (see option Outputlevel), in order to see the orders of the quotients of all the classes determined, and we set the `InfoANUPQ` level to 2 (see InfoANUPQ), so that we catch the timing information.

      gap> F := FreeGroup("a", "b");; a := F.1;; b := F.2;;
      gap> G := F / [a^4, b^4];
      <fp group on the generators [ a, b ]>
      gap> PqStart(G);
      1
      gap> SetInfoLevel(InfoANUPQ, 2); #To see timing information
      gap> Pq(: Prime := 2, ClassBound := 3, OutputLevel := 1 );
      #I  Lower exponent-2 central series for [grp]
      #I  Group: [grp] to lower exponent-2 central class 1 has order 2^2
      #I  Group: [grp] to lower exponent-2 central class 2 has order 2^5
      #I  Group: [grp] to lower exponent-2 central class 3 has order 2^8
      #I  Computation of presentation took 0.00 seconds
      <pc group of size 256 with 8 generators>

- `PqEpimorphism(` i`:` options`) F`
- `PqEpimorphism( :` options`) F`

  return, for the fp or pc group (let us call it F), of the ith or default interactive ANUPQ process, an epimorphism from F onto the p-quotient of F specified by options; F must previously have been given (as first argument) to `PqStart` to start the interactive ANUPQ process (see PqStart). Since the underlying interactions with the `pq` program effected by the interactive `PqEpimorphism` are identical to those effected by the interactive `Pq`, everything said regarding the requirements and behaviour of the interactive `Pq` function (see Pq!interactive) is also the case for the interactive `PqEpimorphism`.

  Note: See Section Attributes and a Property for fp and pc p-groups for the attributes and property `NuclearRank`, `MultiplicatorRank` and `IsCapable` which may be applied to the image group of the epimorphism returned by `PqEpimorphism`.

- `PqPCover(` i`:` options`) F`
- `PqPCover( :` options`) F`

  return, for the fp or pc group of the ith or default interactive ANUPQ process, the p-covering group of the p-quotient `Pq(`i`:` options`)` or `Pq(:` options`)`, modulo the following:

  1. If no pc presentation has yet been computed (the case immediately after the `PqStart` call initiating the process) and the group F of the process is already a p-group, in the sense that `HasIsPGroup(`F`) and IsPGroup(`F`)` is `true`, then

  `Prime`
    defaults to `PrimePGroup(`F`)`, if not supplied and `HasPrimePGroup(`F`) = true`; and

  `ClassBound`
    defaults to `PClassPGroup(`F`)` if `HasPClassPGroup(`F`) = true` if not supplied, or to the usual default of 63, otherwise.

  2. If a pc presentation has been computed and none of options is `RedoPcp` or if no pc presentation has yet been computed but 1. does not apply then `PqPCover(`i`:` options`);` is equivalent to:

     `Pq(`i`:` options`);`
     `PqPCover(`i`);`

  3. If the `RedoPcp` option is supplied the current pc presentation is scrapped, and `PqPCover` proceeds as in 1. or 2. but without the `RedoPcp` option.

- `PqStandardPresentation([` i`]:` options`) F`
- `StandardPresentation([` i`]:` options`) M`

  return, for the ith or default interactive ANUPQ process, the p-quotient of the group F of the process, specified by options, as an fp group which has a standard presentation. Here options is a selection of the options from the following list (see Chapter ANUPQ options for detailed descriptions); this list is the same as for the non-interactive version of `PqStandardPresentation` except for the omission of options `SetupFile` and `PqWorkspace` (see PqStandardPresentation).

  - `Prime :=` p``

  - `pQuotient :=` Q``

  - `ClassBound :=` n``

  - `Exponent :=` n``

  - `Metabelian`

  - `GroupName :=` name``

  - `OutputLevel :=` n``

  - `StandardPresentationFile :=` filename``

  Unless F is a pc p-group, or the option `Prime` has been passed to a previous interactive function for the process to compute a p-quotient for F, the user must supply either the option `Prime` or the option `pQuotient` (if both `Prime` and `pQuotient` are supplied, the prime p is determined by applying `PrimePGroup` (see PrimePGroup in the Reference Manual) to the value of `pQuotient`).

  Taking one of the examples for the non-interactive version of `StandardPresentation` (see StandardPresentation) that required two separate calls to the `pq` program, we now show how it can be done by setting up a dialogue with just the one `pq` process, using the interactive version of `StandardPresentation`:

      gap> F4 := FreeGroup( "a", "b", "c", "d" );;
      gap> a := F4.1;; b := F4.2;; c := F4.3;; d := F4.4;;
      gap> G4 := F4 / [ b^4, b^2 / Comm(Comm (b, a), a), d^16,
      >                 a^16 / (c * d), b^8 / (d * c^4) ];
      <fp group on the generators [ a, b, c, d ]>
      gap> SetInfoLevel(InfoANUPQ, 1); #Only essential Info please
      gap> PqStart(G4); #Start a new interactive process for a new group
      2
      gap> K := Pq( 2 : Prime := 2, ClassBound := 1 ); #`pq' process no. is 2
      <pc group of size 4 with 2 generators>
      gap> StandardPresentation( 2 : pQuotient := K, ClassBound := 14 );
      <fp group with 53 generators>

  Notes

  In contrast to the function `Pq` (see Pq) which returns a pc group, `PqStandardPresentation` or `StandardPresentation` returns an fp group. This is because the output is mainly used for isomorphism testing for which an fp group is enough. However, the presentation is a polycyclic presentation and if you need to do any further computation with this group (e.g. to find the order) you can use the function `PcGroupFpGroup` (see PcGroupFpGroup in the GAP Reference Manual) to form a pc group.

  If the user does not supply a p-quotient Q via the `pQuotient` option, and the prime p is either supplied, stored, or F is a pc p-group, then a p-quotient Q is computed. (The value of the prime p is stored if passed initially to `PqStart` or to a subsequent interactive process.) Note that a stored value for `pQuotient` (from a prior call to `Pq`) does not have precedence over a value for the prime p. If the user does supply a p-quotient Q via the `pQuotient` option, the package AutPGrp is called to compute the automorphism group of Q; an error will occur that asks the user to install the package AutPGrp if the automorphism group cannot be computed.

  If any of the interactive functions `PqStandardPresentation`, `StandardPresentation`, `EpimorphismPqStandardPresentation` or `EpimorphismStandardPresentation` has been called previously for an interactive process, a subsequent call to any of these functions for the same process returns the previously computed value. Note that all these functions compute both an epimorphism and an fp group and store the results in the `SPepi` and `SP` fields of the data record associated with the process. See the example for the interactive `EpimorphismStandardPresentation` (EpimorphismStandardPresentation!interactive).

  The attributes and property `NuclearRank`, `MultiplicatorRank` and `IsCapable` are set for the group returned by `PqStandardPresentation` or `StandardPresentation` (see Section Attributes and a Property for fp and pc p-groups).

- `EpimorphismPqStandardPresentation([` i`]:` options`) F`
- `EpimorphismStandardPresentation([` i`]:` options`) M`

  Each of the above functions accepts the same arguments and options as the interactive form of `StandardPresentation` (see StandardPresentation!interactive) and returns an epimorphism from the fp or pc group F of the ith or default interactive ANUPQ process onto the finitely presented group given by a standard presentation, i.e. if S is the standard presentation computed for the p-quotient of F by `StandardPresentation` then `EpimorphismStandardPresentation` returns the epimorphism from F to the group with presentation S. The group F must have been given (as first argument) to `PqStart` to start the interactive ANUPQ process (see PqStart).

  Taking our earlier non-interactive example (see EpimorphismPqStandardPresentation) and modifying it a little, we illustrate, as for the interactive `StandardPresentation` (see StandardPresentation!interactive), how something that required two separate calls to the `pq` program can now be achieved with a dialogue with just one `pq` process. Also, observe that calls to one of the standard presentation functions (as mentioned in the notes of StandardPresentation!interactive) computes and stores both an fp group with a standard presentation and an epimorphism; subsequent calls to a standard presentation function for the same process simply return the appropriate stored value.

      gap> F := FreeGroup(6, "F");;
      gap> x := F.1;; y := F.2;; z := F.3;; w := F.4;; a := F.5;; b := F.6;;
      gap> R := [x^3 / w, y^3 / w * a^2 * b^2, w^3 / b,
      >          Comm (y, x) / z, Comm (z, x), Comm (z, y) / a, z^3 ];
      [ F1^3*F4^-1, F2^3*F4^-1*F5^2*F6^2, F4^3*F6^-1, F2^-1*F1^-1*F2*F1*F3^-1,
        F3^-1*F1^-1*F3*F1, F3^-1*F2^-1*F3*F2*F5^-1, F3^3 ]
      gap> Q := F / R;
      <fp group on the generators [ F1, F2, F3, F4, F5, F6 ]>
      gap> PqStart( Q );
      3
      gap> G := Pq( 3 : Prime := 3, ClassBound := 3 );
      <pc group of size 729 with 6 generators>
      gap> lev := InfoLevel(InfoANUPQ);; # Save current InfoANUPQ level
      gap> SetInfoLevel(InfoANUPQ, 2); # To see computation times
      gap> # It is not necessary to pass the `Prime' option to
      gap> # `EpimorphismStandardPresentation' since it was previously
      gap> # passed to `Pq':
      gap> phi := EpimorphismStandardPresentation( 3 : ClassBound := 3 );
      #I  Class 1 3-quotient and its 3-covering group computed in 0.00 seconds
      #I  Order of GL subgroup is 48
      #I  No. of soluble autos is 0
      #I    dim U = 1  dim N = 3  dim M = 3
      #I    nice stabilizer with perm rep
      #I  Computing standard presentation for class 2 took 0.00 seconds
      #I  Computing standard presentation for class 3 took 0.01 seconds
      [ F1, F2, F3, F4, F5, F6 ] -> [ f1*f2^2*f3*f4^2*f5^2, f1*f2*f3*f5, f3^2,
        f4*f6^2, f5, f6 ]
      gap> # Image of phi should be isomorphic to G ...
      gap> # let's check the order is correct:
      gap> Size( Image(phi) );
      729
      gap> # `StandardPresentation' and `EpimorphismStandardPresentation'
      gap> # behave like attributes, so no computation is done when
      gap> # either is called again for the same process ...
      gap> StandardPresentation( 3 : ClassBound := 3 );
      <fp group of size 729 on the generators [ f1, f2, f3, f4, f5, f6 ]>
      gap> # No timing data was Info-ed since no computation was done
      gap> SetInfoLevel(InfoANUPQ, lev); # Restore previous InfoANUPQ level

  A very similar (essential details are the same) example to the above may be executed live, by typing: `PqExample( "EpimorphismStandardPresentation-i" );`.

  Note: The notes for `PqStandardPresentation` or `StandardPresentation` (see PqStandardPresentation!interactive) apply also to `EpimorphismPqStandardPresentation` or `EpimorphismStandardPresentation` except that their return value is an epimorphism onto an fp group, i.e. one should interpret the phrase ``returns an fp group'' as ``returns an epimorphism onto an fp group'' etc.

- `PqDescendants(` i`:` options`) F`
- `PqDescendants( :` options`) F`

  return for the pc group G of the ith or default interactive ANUPQ process, which must be of prime power order with a confluent pc presentation (see IsConfluent!for pc groups in the GAP Reference Manual), a list of descendants (pc groups) of G. The group G is usually given as first argument to `PqStart` when starting the interactive ANUPQ process (see PqStart). Alternatively, one may initiate the process with an fp group, use `Pq` interactively (see Pq!interactive) to create a pc group and use `PqSetPQuotientToGroup` (see PqSetPQuotientToGroup), which involves no computation, to set the pc group returned by `Pq` as the group of the process. Note that repeating a call to `PqDescendants` for the same interactive ANUPQ process simply returns the list of descendants originally calculated; a warning is emitted at `InfoANUPQ` level 1 reminding you of this should you do this.

  Following the colon options a selection of the options listed for the non-interactive `PqDescendants` function (see PqDescendants) should be given, separated by commas like record components (see Section function call!with options in the GAP Reference Manual), except that the options `SetupFile` or `PqWorkspace` are ignored by the interactive `PqDescendants`, i.e. the following options are recognised by the interactive `PqDescendants` function:

  - `ClassBound :=` n``

  - `Relators :=` rels``

  - `OrderBound :=` n``

  - `StepSize :=` n``, `StepSize :=` list``

  - `RankInitialSegmentSubgroups :=` n``

  - `SpaceEfficient`

  - `CapableDescendants`

  - `AllDescendants := false`

  - `Exponent :=` n``

  - `Metabelian`

  - `GroupName :=` name``

  - `SubList :=` sub``

  - `BasicAlgorithm`

  - `CustomiseOutput :=` rec``

  Notes: The function `PqDescendants` uses the automorphism group of G which it computes via the package AutPGrp if the automorphism group of G is not already present. If AutPGrp is not installed an error may be raised. If the automorphism group of G is insoluble the `pq` program will call GAP together with the AutPGrp package for certain orbit-stabilizer calculations.

  The attributes and property `NuclearRank`, `MultiplicatorRank` and `IsCapable` are set for each group of the list returned by `PqDescendants` (see Section Attributes and a Property for fp and pc p-groups).

  Let us now repeat the examples previously given for the non-interactive `PqDescendants`, but this time with the interactive version of `PqDescendants`:

      gap> F := FreeGroup( "a", "b" );; a := F.1;; b := F.2;;
      gap> G := PcGroupFpGroup( F / [ a^2, b^2, Comm(b, a) ] );
      <pc group of size 4 with 2 generators>
      gap> PqStart(G); #This will now be the 4th interactive process running
      4
      gap> des := PqDescendants( 4 : OrderBound := 6, ClassBound := 5 );;
      gap> Length(des);
      83
      gap> List(des, Size);
      [ 8, 8, 8, 16, 16, 16, 32, 16, 16, 16, 16, 16, 32, 32, 64, 64, 32, 32, 32,
        32, 32, 32, 32, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 32, 32, 32, 32,
        64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 32, 32, 32, 32, 32, 64, 64, 64,
        64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64,
        64, 64, 64, 64, 64, 64, 64 ]
      gap> List(des, d -> Length( PCentralSeries( d, 2 ) ) - 1 );
      [ 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,
        3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 4,
        4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
        4, 4, 4, 5, 5, 5, 5, 5 ]

  In the second example we compute all capable descendants of order 27 of the elementary abelian group of order 9.

      gap> F := FreeGroup( 2, "g" );;
      gap> G := PcGroupFpGroup( F / [ F.1^3, F.2^3, Comm(F.1, F.2) ] );
      <pc group of size 9 with 2 generators>
      gap> PqStart(G); #This will now be the 5th interactive process running
      5
      gap> des := PqDescendants( 5 : OrderBound := 3, ClassBound := 2,
      >                              CapableDescendants );
      [ <pc group of size 27 with 3 generators>,
        <pc group of size 27 with 3 generators> ]
      gap> List(des, d -> Length( PCentralSeries( d, 3 ) ) - 1 );
      [ 2, 2 ]
      gap> # For comparison let us now compute all descendants
      gap> # (using the non-interactive Pq function)
      gap> PqDescendants( G : OrderBound := 3, ClassBound := 2);
      [ <pc group of size 27 with 3 generators>,
        <pc group of size 27 with 3 generators>,
        <pc group of size 27 with 3 generators> ]

  In the third example, we compute all capable descendants of the elementary abelian group of order 52 which have exponent-5 class at most 3, exponent 5, and are metabelian.

      gap> F := FreeGroup( 2, "g" );;
      gap> G := PcGroupFpGroup( F / [ F.1^5, F.2^5, Comm(F.2, F.1) ] );
      <pc group of size 25 with 2 generators>
      gap> PqStart(G); #This will now be the 6th interactive process running
      6
      gap> des := PqDescendants( 6 : Metabelian, ClassBound := 3,
      >                              Exponent := 5, CapableDescendants );
      [ <pc group of size 125 with 3 generators>,
        <pc group of size 625 with 4 generators>,
        <pc group of size 3125 with 5 generators> ]
      gap> List(des, d -> Length( PCentralSeries( d, 5 ) ) - 1 );
      [ 2, 3, 3 ]
      gap> List(des, d -> Length( DerivedSeries( d ) ) );
      [ 3, 3, 3 ]
      gap> List(des, d -> Maximum( List( Elements(d), Order ) ) );
      [ 5, 5, 5 ]

- `PqSetPQuotientToGroup(` i`) F`
- `PqSetPQuotientToGroup() F`

  for the ith or default interactive ANUPQ process, set the p-quotient previously computed by the interactive `Pq` function (see Pq!interactive) to be the group of the process. This function is supplied to enable the computation of descendants of a p-quotient that is already known to the `pq` program, via the interactive `PqDescendants` function (see PqDescendants!interactive), thus avoiding the need to re-submit it and have the `pq` program recompute it.

  Note: See the function `PqPGSetDescendantToPcp` (PqPGSetDescendantToPcp) for a mechanism to make (the p-cover of) a particular descendants the current group of the process.

  The following example of the usage of `PqSetPQuotientToGroup`, which is essentially equivalent to what is obtained by running `PqExample("PqDescendants-1-i");`, redoes the first example of PqDescendants!interactive (which computes the descendants of the Klein four group).

      gap> F := FreeGroup( "a", "b" );
      <free group on the generators [ a, b ]>
      gap> procId := PqStart( F : Prime := 2 );
      7
      gap> Pq( procId : ClassBound := 1 );
      <pc group of size 4 with 2 generators>
      gap> PqSetPQuotientToGroup( procId );
      gap> des := PqDescendants( procId : OrderBound := 6, ClassBound := 5 );;
      gap> Length(des);
      83
      gap> List(des, Size);
      [ 8, 8, 8, 16, 16, 16, 32, 16, 16, 16, 16, 16, 32, 32, 64, 64, 32, 32, 32,
        32, 32, 32, 32, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 32, 32, 32, 32,
        64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 32, 32, 32, 32, 32, 64, 64, 64,
        64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64,
        64, 64, 64, 64, 64, 64, 64 ]
      gap> List(des, d -> Length( PCentralSeries( d, 2 ) ) - 1 );
      [ 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,
        3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 4,
        4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
        4, 4, 4, 5, 5, 5, 5, 5 ]

  ## 5.4 Low-level Interactive ANUPQ Functions based on menu items of the pq program

  The `pq` program has 5 menus, the details of which the reader will not normally need to know, but if she wishes to know the details they may be found in the standalone manual: `guide.dvi`. Both `guide.dvi` and the `pq` program refer to the items of these 5 menus as ``options'', which do not correspond in any way to the options used by any of the GAP functions that interface with the `pq` program.

  Warning: The commands provided in this section are intended to provide something like the interactive functionality one has when running the standalone, from within GAP. The `pq` standalone (in particular, its ``advanced'' menus) assumes some expertise of the user; doing the ``wrong'' thing can cause the program to crash. While a number of safeguards have been provided in the GAP interface to the `pq` program, these are not foolproof, and the user should exercise care and ensure pre-requisites of the various commands are met.

  General commands

  The following commands either use a menu item from whatever menu is ``current'' for the `pq` program, or have general application and are not associated with just one menu item of the `pq` program.

- `PqNrPcGenerators(` i`) F`
- `PqNrPcGenerators() F`

  for the ith or default interactive ANUPQ process, return the number of pc generators of the lower exponent p-class quotient of the group currently determined by the process. This also applies if the pc presentation is not consistent.

- `PqFactoredOrder(` i`) F`
- `PqFactoredOrder() F`

  for the ith or default interactive ANUPQ process, return an integer pair `[`p`,` n`]` where p is a prime and n is the number of pc generators (see PqNrPcGenerators) in the pc presentation of the quotient group currently determined by the process. If this presentation is consistent, then pn is the order of the quotient group. Otherwise (if tails have been added but the necessary consistency checks, relation collections, exponent law checks and redundant generator eliminations have not yet been done), pn is an upper bound for the order of the group.

- `PqOrder(` i`) F`
- `PqOrder() F`

  for the ith or default interactive ANUPQ process, return pn where `[`p`,` n`]` is the pair as returned by `PqFactoredOrder` (see PqFactoredOrder).

- `PqPClass(` i`) F`
- `PqPClass() F`

  for the ith or default interactive ANUPQ process, return the lower exponent p-class of the quotient group currently determined by the process.

- `PqWeight(` i`,` j`) F`
- `PqWeight(` j`) F`

  for the ith or default interactive ANUPQ process, return the weight of the jth pc generator of the lower exponent p-class quotient of the group currently determined by the process, or `fail` if there is no such numbered pc generator.

- `PqCurrentGroup(` i`) F`
- `PqCurrentGroup() F`

  for the ith or default interactive ANUPQ process, return the group whose pc presentation is determined by the process as a GAP pc group (either a lower exponent p-class quotient of the start group or the p-cover of such a quotient).

  Notes: See Section Attributes and a Property for fp and pc p-groups for the attributes and property `NuclearRank`, `MultiplicatorRank` and `IsCapable` which may be applied to the group returned by `PqCurrentGroup`.

- `PqDisplayPcPresentation(` i`[: OutputLevel :=` lev`]) F`
- `PqDisplayPcPresentation([: OutputLevel :=` lev`]) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to display the pc presentation of the lower exponent p-class quotient of the group currently determined by the process.

  Except if the last command communicating with the `pq` program was a p-group generation command (for which there is only a verbose output level), to set the amount of information this command displays you may wish to call `PqSetOutputLevel` first (see PqSetOutputLevel), or equivalently pass the option `OutputLevel` (see option OutputLevel).

  Note: For those familiar with the `pq` program, `PqDisplayPcPresentation` performs menu item 4 of the current menu of the `pq` program.

- `PqSetOutputLevel(` i`,` lev`) F`
- `PqSetOutputLevel(` lev`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to set the output level of the `pq` program to lev.

  Note: For those familiar with the `pq` program, `PqSetOutputLevel` performs menu item 5 of the main (or advanced) p-Quotient menu, or the Standard Presentation menu.

- `PqEvaluateIdentities(` i`[: Identities :=` funcs`]) F`
- `PqEvaluateIdentities([: Identities :=` funcs`]) F`

  for the ith or default interactive ANUPQ process, invoke the evaluation of identities defined by the `Identities` option, and eliminate any redundant pc generators formed. Since a previous value of `Identities` is saved in the data record of the process, it is unnecessary to pass the `Identities` if set previously.

  Note: This function is mainly implemented at the GAP level. It does not correspond to a menu item of the `pq` program.

  Commands from the Main p-Quotient menu

- `PqPcPresentation(` i`:` options`) F`
- `PqPcPresentation( :` options`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to compute the pc presentation of the quotient (determined by options) of the group of the process, which for process i is stored as `ANUPQData.io[`i`].group`.

  The possible options are the same as for the interactive `Pq` (see Pq!interactive) function, except for `RedoPcp` (which, in any case, would be superfluous), namely: `Prime`, `ClassBound`, `Exponent`, `Relators`, `GroupName`, `Metabelian`, `Identities` and `OutputLevel` (see Chapter ANUPQ options for a detailed description for these options). The option `Prime` is required unless already provided to `PqStart`.

  Notes

  The pc presentation is held by the `pq` program. In contrast to `Pq` (see Pq!interactive), no GAP pc group is returned; see `PqCurrentGroup` (PqCurrentGroup) if you need the corresponding GAP pc group.

  `PqPcPresentation(`i`:` options`);` is roughly equivalent to the following sequence of low-level commands:

  `PqPcPresentation(`i`:` opts`); #class 1 call`
  `for c in [2 ..` class`] do`
  `PqNextClass(`i`);`
  `od;`

  where opts is options except with the `ClassBound` option set to 1, and class is either the maximum class of a p-quotient of the group of the process or the user-supplied value of the option `ClassBound` (whichever is smaller). If the `Identities` option has been set, both the first `PqPcPresentation` class 1 call and the `PqNextClass` calls invoke `PqEvaluateIdentities(`i`);` as their final step.

  For those familiar with the `pq` program, `PqPcPresentation` performs menu item 1 of the main p-Quotient menu.

- `PqSavePcPresentation(` i`,` filename`) F`
- `PqSavePcPresentation(` filename`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to save the pc presentation previously computed for the quotient of the group of that process to the file with 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. A saved file may be restored by `PqRestorePcPresentation` (see PqRestorePcPresentation).

  Note: For those familiar with the `pq` program, `PqSavePcPresentation` performs menu item 2 of the main p-Quotient menu.

- `PqRestorePcPresentation(` i`,` filename`) F`
- `PqRestorePcPresentation(` filename`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to restore the pc presentation previously saved to filename, by `PqSavePcPresentation` (see PqSavePcPresentation). If the first character of the string filename is not `/`, filename is assumed to be the path of a readable file relative to the directory in which GAP was started.

  Note: For those familiar with the `pq` program, `PqRestorePcPresentation` performs menu item 3 of the main p-Quotient menu.

- `PqNextClass(` i`[: QueueFactor ]) F`
- `PqNextClass([: QueueFactor ]) F`

  for the ith or default interactive ANUPQ process, direct the `pq` to calculate the next class of `ANUPQData.io[`i`].group`.

  `PqNextClass` accepts the option `QueueFactor` (see also option QueueFactor) which should be a positive integer if automorphisms have been previously supplied. If the `pq` program requires a queue factor and none is supplied via the option `QueueFactor` a default of 15 is taken.

  Notes

  The single command: `PqNextClass(`i`);` is equivalent to executing

  `PqComputePCover(`i`);`
  `PqCollectDefiningRelations(`i`);`
  `PqDoExponentChecks(`i`);`
  `PqEliminateRedundantGenerators(`i`);`

  If the `Identities` option is set the `PqEliminateRedundantGenerators(`i`);` step is essentially replaced by `PqEvaluateIdentities(`i`);` (which invokes its own elimination of redundant generators).

  For those familiar with the `pq` program, `PqNextClass` performs menu item 6 of the main p-Quotient menu.

- `PqComputePCover(` i`) F`
- `PqComputePCover() F`

  for the ith or default interactive ANUPQ process, direct the `pq` to compute the p-covering group of `ANUPQData.io[`i`].group`. In contrast to the function `PqPCover` (see PqPCover), this function does not return a GAP pc group.

  Notes

  The single command: `PqComputePCover(`i`);` is equivalent to executing

  `PqSetupTablesForNextClass(`i`);`
  `PqTails(`i`, 0);`
  `PqDoConsistencyChecks(`i`, 0, 0);`
  `PqEliminateRedundantGenerators(`i`);`

  For those familiar with the `pq` program, `PqComputePCover` performs menu item 7 of the main p-Quotient menu.

  Commands from the Advanced p-Quotient menu

- `PqCollect(` i`,` word`) F`
- `PqCollect(` word`) F`

  for the ith or default interactive ANUPQ process, instruct the `pq` program to do a collection on word, a word in the current pc generators (the form of word required is described below). `PqCollect` returns the resulting word of the collection as a list of generator number, exponent pairs (the same form as the second allowed input form of word; see below).

  The argument word may be input in either of the following ways:

  1. word may be a string, where the ith pc generator is represented by `x` i``, e.g. `"x3*x2^2*x1"`. This way is quite versatile as parentheses and left-normed commutators -- using square brackets, in the same way as `PqGAPRelators` (see PqGAPRelators) -- are permitted; word is checked for correct syntax via `PqParseWord` (see PqParseWord).

  2. Otherwise, word must be a list of generator number, exponent pairs of integers, i.e. each pair represents a ``syllable'' so that `[ [3, 1], [2, 2], [1, 1] ]` represents the same word as that of the example given for the first allowed form of word.

  Note: For those familiar with the `pq` program, `PqCollect` performs menu item 1 of the Advanced p-Quotient menu.

- `PqSolveEquation(` i`,` a`,` b`) F`
- `PqSolveEquation(` a`,` b`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to solve a * x = b for x, where a and b are words in the pc generators. For the representation of these words see the description of the function `PqCollect` (PqCollect).

  Note: For those familiar with the `pq` program, `PqSolveEquation` performs menu item 2 of the Advanced p-Quotient menu.

- `PqCommutator(` i`,` words`,` pow`) F`
- `PqCommutator(` words`,` pow`) F`

  for the ith or default interactive ANUPQ process, instruct the `pq` program to compute the left normed commutator of the list words of words in the current pc generators raised to the integer power pow, and return the resulting word as a list of generator number, exponent pairs. The form required for each word of words is the same as that required for the word argument of `PqCollect` (see PqCollect). The form of the output word is also the same as for `PqCollect`.

  Note: For those familiar with the `pq` program, `PqCommutator` performs menu item 3 of the Advanced p-Quotient menu.

- `PqSetupTablesForNextClass(` i`) F`
- `PqSetupTablesForNextClass() F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to set up tables for the next class. As as side-effect, after `PqSetupTablesForNextClass(`i`)` the value returned by `PqPClass(`i`)` will be one more than it was previously.

  Note: For those familiar with the `pq` program, `PqSetupTablesForNextClass` performs menu item 6 of the Advanced p-Quotient menu.

- `PqTails(` i`,` weight`) F`
- `PqTails(` weight`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to compute and add tails of weight weight if weight is in the integer range `[2 .. PqPClass(`i`)]` (assuming i is the number of the process, even in the default case) or for all weights if ``weight`= 0`.

  If weight is non-zero, then tails that introduce new generators for only weight weight are computed and added, and in this case and if ``weight`< PqPClass(`i`)`, it is assumed that the tails that introduce new generators for each weight from `PqPClass(`i`)` down to weight ``weight`+ 1` have already been added. You may wish to call `PqSetMetabelian` (see PqSetMetabelian) prior to calling `PqTails`.

  Notes

  For its use in the context of finding the next class see PqNextClass; in particular, a call to `PqSetupTablesForNextClass` (see PqSetupTablesForNextClass) needs to have been made prior to calling `PqTails`.

  The single command: `PqTails(`i`,` weight`);` is equivalent to

  `PqComputeTails(`i`,` weight`);`
  `PqAddTails(`i`,` weight`);`

  For those familiar with the `pq` program, `PqTails` uses menu item 7 of the Advanced p-Quotient menu.

- `PqComputeTails(` i`,` weight`) F`
- `PqComputeTails(` weight`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to compute tails of weight weight if weight is in the integer range `[2 .. PqPClass(`i`)]` (assuming i is the number of the process, even in the default case) or for all weights if ``weight`= 0`. See `PqTails` (PqTails) for more details.

  Note: For those familiar with the `pq` program, `PqComputeTails` uses menu item 7 of the Advanced p-Quotient menu.

- `PqAddTails(` i`,` weight`) F`
- `PqAddTails(` weight`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to add the tails of weight weight, previously computed by `PqComputeTails` (see PqComputeTails), if weight is in the integer range `[2 .. PqPClass(`i`)]` (assuming i is the number of the process, even in the default case) or for all weights if ``weight`= 0`. See `PqTails` (PqTails) for more details.

  Note: For those familiar with the `pq` program, `PqAddTails` uses menu item 7 of the Advanced p-Quotient menu.

- `PqDoConsistencyChecks(` i`,` weight`,` type`) F`
- `PqDoConsistencyChecks(` weight`,` type`) F`

  for the ith or default interactive ANUPQ process, do consistency checks for weight weight if weight is in the integer range `[3 .. PqPClass(`i`)]` (assuming i is the number of the process) or for all weights if ``weight`= 0`, and for type type if type is in the range `[1, 2, 3]` (see below) or for all types if ``type`= 0`. (For its use in the context of finding the next class see PqNextClass.)

  The type of a consistency check is defined as follows. `PqDoConsistencyChecks(`i`,` weight`,` type`)` for weight in `[3 .. PqPClass(`i`)]` and the given value of type invokes the equivalent of the following `PqDoConsistencyCheck` calls (see PqDoConsistencyCheck):

  ``type`= 1`:
    `PqDoConsistencyCheck(`i`,` a`,` a`,` a`)` checks `2 * PqWeight(`i`,` a`) + 1 =` weight``, for pc generators of index a.

  ``type`= 2`:
    `PqDoConsistencyCheck(`i`,` b`,` b`,` a`)` checks for pc generators of indices b, a satisfying ``b`>` a`` and `PqWeight(`i`,` b`) + PqWeight(`i`,` a`) + 1 =` weight``.

  ``type`= 3`:
    `PqDoConsistencyCheck(`i`,` c`,` b`,` a`)` checks for pc generators of indices c, b, a satisfying ``c`>` b`>` a`` and the sum of the weights of these generators equals weight.

  Notes

  `PqWeight(`i`,` j`)` returns the weight of the jth pc generator, for process i (see PqWeight).

  It is assumed that tails for the given weight (or weights) have already been added (see PqTails).

  For those familiar with the `pq` program, `PqDoConsistencyChecks` performs menu item 8 of the Advanced p-Quotient menu.

- `PqCollectDefiningRelations(` i`) F`
- `PqCollectDefiningRelations() F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to collect the images of the defining relations of the original fp group of the process, with respect to the current pc presentation, in the context of finding the next class (see PqNextClass). If the tails operation is not complete then the relations may be evaluated incorrectly.

  Note: For those familiar with the `pq` program, `PqCollectDefiningRelations` performs menu item 9 of the Advanced p-Quotient menu.

- `PqCollectWordInDefiningGenerators(` i`,` word`) F`
- `PqCollectWordInDefiningGenerators(` word`) F`

  for the ith or default interactive ANUPQ process, take a user-defined word word in the defining generators of the original presentation of the fp or pc group of the process. Each generator is mapped into the current pc presentation, and the resulting word is collected with respect to the current pc presentation. The result of the collection is returned as a list of generator number, exponent pairs.

  The word argument may be input in either of the two ways described for `PqCollect` (see PqCollect).

  Note: For those familiar with the `pq` program, `PqCollectDefiningGenerators` performs menu item 23 of the Advanced p-Quotient menu.

- `PqCommutatorDefiningGenerators(` i`,` words`,` pow`) F`
- `PqCommutatorDefiningGenerators(` words`,` pow`) F`

  for the ith or default interactive ANUPQ process, take a list words of user-defined words in the defining generators of the original presentation of the fp or pc group of the process, and an integer power pow. Each generator is mapped into the current pc presentation. The list words is interpreted as a left-normed commutator which is then raised to pow and collected with respect to the current pc presentation. The result of the collection is returned as a list of generator number, exponent pairs.

  Note For those familiar with the `pq` program, `PqCommutatorDefiningGenerators` performs menu item 24 of the Advanced p-Quotient menu.

- `PqDoExponentChecks(` i`[: Bounds :=` list`]) F`
- `PqDoExponentChecks([: Bounds :=` list`]) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to do exponent checks for weights (inclusively) between the bounds of `Bounds` or for all weights if `Bounds` is not given. The value list of `Bounds` (assuming the interactive process is numbered i) should be a list of two integers low, high satisfying 1 £ low £ high £ `PqPClass``(`i `)` (see PqPClass). If no exponent law has been specified, no exponent checks are performed.

  Note: For those familiar with the `pq` program, `PqDoExponentChecks` performs menu item 10 of the Advanced p-Quotient menu.

- `PqEliminateRedundantGenerators(` i`) F`
- `PqEliminateRedundantGenerators() F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to eliminate redundant generators of the current p-quotient.

  Note: For those familiar with the `pq` program, `PqEliminateRedundantGenerators` performs menu item 11 of the Advanced p-Quotient menu.

- `PqRevertToPreviousClass(` i`) F`
- `PqRevertToPreviousClass() F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to abandon the current class and revert to the previous class.

  Note: For those familiar with the `pq` program, `PqRevertToPreviousClass` performs menu item 12 of the Advanced p-Quotient menu.

- `PqSetMaximalOccurrences(` i`,` noccur`) F`
- `PqSetMaximalOccurrences(` noccur`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to set maximal occurrences of the weight 1 generators in the definitions of pcp generators of the group of the process. This can be used to avoid the definition of generators of which one knows for theoretical reasons that they would be eliminated later on.

  The argument noccur must be a list of non-negative integers of length the number of weight 1 generators (i.e. the rank of the class 1 p-quotient of the group of the process). An entry of `0` for a particular generator indicates that there is no limit on the number of occurrences for the generator.

  Note: For those familiar with the `pq` program, `PqSetMaximalOccurrences` performs menu item 13 of the Advanced p-Quotient menu.

- `PqSetMetabelian(` i`) F`
- `PqSetMetabelian() F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to enforce metabelian-ness.

  Note: For those familiar with the `pq` program, `PqSetMetabelian` performs menu item 14 of the Advanced p-Quotient menu.

- `PqDoConsistencyCheck(` i`,` c`,` b`,` a`) F`
- `PqDoConsistencyCheck(` c`,` b`,` a`) F`
- `PqJacobi(` i`,` c`,` b`,` a`) F`
- `PqJacobi(` c`,` b`,` a`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to do the consistency check for the pc generators with indices c, b, a which should be non-increasing positive integers, i.e. c ³ b ³ a .

  There are 3 types of consistency checks:

  (an)a
  =
  a(an)
  (Type 1)
  (bn)a
  =
  b(n-1)(ba), b(an) = (ba)a(n-1)
  (Type 2)
  c(ba)
  =
  (cb)a
  (Type 3)

  The reason some people talk about Jacobi relations instead of consistency checks becomes clear when one looks at the consistency check of type 3:

  c(ba)
  =
  a c[c,a] b[b,a] = acb [c,a][c,a,b][b,a] = ...
  (cb)a
  =
  b c[c,b] a = a b[b,a] c[c,a] [c,b][c,b,a] = abc [b,a] [b,a,c] [c,a] [c,b] [c,b,a] = ...

  Each collection would normally carry on further. But one can see already that no other commutators of weight 3 will occur. After all terms of weight one and weight two have been moved to the left we end up with:

  abc [b,a] [c,a] [c,b] [c,a,b] ...
  =
  abc [b,a] [c,a] [c,b] [c,b,a] [b,a,c] ...

  Modulo terms of weight 4 this is equivalent to

  [c,a,b] [b,c,a] [a,b,c] = 1

  which is the Jacobi identity.

  See also `PqDoConsistencyChecks` (PqDoConsistencyChecks).

  Note: For those familiar with the `pq` program, `PqDoConsistencyCheck` and `PqJacobi` perform menu item 15 of the Advanced p-Quotient menu.

- `PqCompact(` i`) F`
- `PqCompact() F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to do a compaction of its work space. This function is safe to perform only at certain points in time.

  Note: For those familiar with the `pq` program, `PqCompact` performs menu item 16 of the Advanced p-Quotient menu.

- `PqEchelonise(` i`) F`
- `PqEchelonise() F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to echelonise the word most recently collected by `PqCollect` or `PqCommutator` against the relations of the current pc presentation, and return the number of the generator made redundant or `fail` if no generator was made redundant. A call to `PqCollect` (see PqCollect) or `PqCommutator` (see PqCommutator) needs to be performed prior to using this command.

  Note: For those familiar with the `pq` program, `PqEchelonise` performs menu item 17 of the Advanced p-Quotient menu.

- `PqSupplyAutomorphisms(` i`,` mlist`) F`
- `PqSupplyAutomorphisms(` mlist`) F`

  for the ith or default interactive ANUPQ process, supply the automorphism data provided by the list mlist of matrices with non-negative integer coefficients. Each matrix in mlist describes one automorphism in the following way.

  - The rows of each matrix correspond to the pc generators of weight one.

  - Each row is the exponent vector of the image of the corresponding weight one generator under the respective automorphism.

  Note: For those familiar with the `pq` program, `PqSupplyAutomorphisms` uses menu item 18 of the Advanced p-Quotient menu.

- `PqExtendAutomorphisms(` i`) F`
- `PqExtendAutomorphisms() F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to extend automorphisms of the p-quotient of the previous class to the p-quotient of the present class.

  Note: For those familiar with the `pq` program, `PqExtendAutomorphisms` uses menu item 18 of the Advanced p-Quotient menu.

- `PqApplyAutomorphisms(` i`,` qfac`) F`
- `PqApplyAutomorphisms(` qfac`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to apply automorphisms; qfac is the queue factor e.g. `15`.

  Note: For those familiar with the `pq` program, `PqCloseRelations` performs menu item 19 of the Advanced p-Quotient menu.

- `PqDisplayStructure(` i`[: Bounds :=` list`]) F`
- `PqDisplayStructure([: Bounds :=` list`]) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to display the structure for the pcp generators numbered (inclusively) between the bounds of `Bounds` or for all generators if `Bounds` is not given. The value list of `Bounds` (assuming the interactive process is numbered i) should be a list of two integers low, high satisfying 1 £ low £ high £ `PqNrPcGenerators``(`i `)` (see PqNrPcGenerators). `PqDisplayStructure` also accepts the option `OutputLevel` (see option OutputLevel).

  Explanation of output

  New generators are defined as commutators of previous generators and generators of class 1 or as p-th powers of generators that have themselves been defined as p-th powers. A generator is never defined as p-th power of a commutator.

  Therefore, there are two cases: all the numbers on the righthand side are either the same or they differ. Below, `g` i`` refers to the ith defining generator.

  - If the righthand side numbers are all the same, then the generator is a p-th power (of a p-th power of a p-th power, etc.). The number of repeated digits say how often a p-th power has to be taken.

    In the following example, the generator number 31 is the eleventh power of generator 17 which in turn is an eleventh power and so on:

        #I  31 is defined on 17^11 = 1 1 1 1 1

    So generator 31 is obtained by taking the eleventh power of generator 1 five times.

  - If the numbers are not all the same, the generator is defined by a commutator. If the first two generator numbers differ, the generator is defined as a left-normed commutator of the weight one generators, e.g.

        #I  19 is defined on [11, 1] = 2 1 1 1 1

    Here, generator 19 is defined as the commutator of generator 11 and generator 1 which is the same as the left-normed commutator `[x2, x1, x1, x1, x1]`. One can check this by tracing back the definition of generator 11 until one gets to a generator of class 1.

  - If the first two generator numbers are identical, then the left most component of the left-normed commutator is a p-th power, e.g.

        #I  25 is defined on [14, 1] = 1 1 2 1 1

    In this example, generator 25 is defined as commutator of generator 14 and generator 1. The left-normed commutator is

    [(`x` `1`11)11, `x` `2`, `x` `1`, `x` `1`]

    Again, this can be verified by tracing back the definitions.

  Note: For those familiar with the `pq` program, `PqDisplayStructure` performs menu item 20 of the Advanced p-Quotient menu.

- `PqDisplayAutomorphisms(` i`[: Bounds :=` list`]) F`
- `PqDisplayAutomorphisms([: Bounds :=` list`]) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to display the automorphism actions on the pcp generators numbered (inclusively) between the bounds of `Bounds` or for all generators if `Bounds` is not given. The value list of `Bounds` (assuming the interactive process is numbered i) should be a list of two integers low, high satisfying 1 £ low £ high £ `PqNrPcGenerators``(`i `)` (see PqNrPcGenerators). `PqDisplayStructure` also accepts the option `OutputLevel` (see option OutputLevel).

  Note: For those familiar with the `pq` program, `PqDisplayAutomorphisms` performs menu item 21 of the Advanced p-Quotient menu.

- `PqWritePcPresentation(` i`,` filename`) F`
- `PqWritePcPresentation(` filename`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to write a pc presentation of a previously-computed quotient of the group of that process, to the file with name filename. Here the group of a process is the one given as first argument when `PqStart` was called to initiate that process (for process i the group is stored as `ANUPQData.io[`i`].group`). 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 a pc presentation has not been previously computed by the `pq` program, then `pq` is called to compute it first, effectively invoking `PqPcPresentation` (see PqPcPresentation).

  Note: For those familiar with the `pq` program, `PqPcWritePresentation` performs menu item 25 of the Advanced p-Quotient menu.

  Commands from the Standard Presentation menu

- `PqSPComputePcpAndPCover(` i`:` options`) F`
- `PqSPComputePcpAndPCover( :` options`) F`

  for the ith or default interactive ANUPQ process, directs the `pq` program to compute for the group of that process a pc presentation up to the p-quotient of maximum class or the value of the option `ClassBound` and the p-cover of that quotient, and sets up tabular information required for computation of a standard presentation. Here the group of a process is the one given as first argument when `PqStart` was called to initiate that process (for process i the group is stored as `ANUPQData.io[`i`].group`).

  The possible options are `Prime`, `ClassBound`, `Relators`, `Exponent`, `Metabelian` and `OutputLevel` (see Chapter ANUPQ Options for detailed descriptions of these options). The option `Prime` is normally determined via `PrimePGroup`, and so is not required unless the group doesn't know it's a p-group and `HasPrimePGroup` returns `false`.

  Note: For those familiar with the `pq` program, `PqSPComputePcpAndPCover` performs option 1 of the Standard Presentation menu.

- `PqSPStandardPresentation(` i`[,` mlist`][:` options`]) F`
- `PqSPStandardPresentation( [`mlist`][:` options`]) F`

  for the ith or default interactive ANUPQ process, inputs data given by options to compute a standard presentation for the group of that process. If argument mlist is given it is assumed to be the automorphism group data required. Otherwise it is assumed that a call to either `Pq` (see Pq!interactive) or `PqEpimorphism` (see PqEpimorphism!interactive) has generated a p-quotient and that GAP can compute its automorphism group from which the necessary automorphism group data can be derived. The group of the process is the one given as first argument when `PqStart` was called to initiate the process (for process i the group is stored as `ANUPQData.io[`i`].group` and the p-quotient if existent is stored as `ANUPQData.io[`i`].pQuotient`). If mlist is not given and a p-quotient of the group has not been previously computed a class 1 p-quotient is computed.

  `PqSPStandardPresentation` accepts three options, all optional:

  - `ClassBound :=` n``

  - `PcgsAutomorphisms`

  - `StandardPresentationFile :=` filename``

  If `ClassBound` is omitted it defaults to 63.

  Detailed descriptions of the above options may be found in Chapter ANUPQ options.

  Note: For those familiar with the `pq` program, `PqSPPcPresentation` performs menu item 2 of the Standard Presentation menu.

- `PqSPSavePresentation(` i`,` filename`) F`
- `PqSPSavePresentation(` filename`) F`

  for the ith or default interactive ANUPQ process, directs the `pq` program to save the standard presentation previously computed for the group of that process to the file with name filename, where the group of a process is the one given as first argument when `PqStart` was called to initiate that process. 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.

  Note: For those familiar with the `pq` program, `PqSPSavePresentation` performs menu item 3 of the Standard Presentation menu.

- `PqSPCompareTwoFilePresentations(` i`,` f1`,` f2`) F`
- `PqSPCompareTwoFilePresentations(` f1`,` f2`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to compare the presentations in the files with names f1 and f2 and returns `true` if they are identical and `false` otherwise. For each of the strings f1 and f2, if the first character is not a `/` then it is assumed to be the path of a readable file relative to the directory in which GAP was started.

  Notes

  The presentations in files f1 and f2 must have been generated by the `pq` program but they do not need to be standard presentations. If If the presentations in files f1 and f2 have been generated by `PqSPStandardPresentation` (see PqSPStandardPresentation) then a `false` response from `PqSPCompareTwoFilePresentations` says the groups defined by those presentations are not isomorphic.

  For those familiar with the `pq` program, `PqSPCompareTwoFilePresentations` performs menu item 6 of the Standard Presentation menu.

- `PqSPIsomorphism(` i`) F`
- `PqSPIsomorphism() F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to compute the isomorphism mapping from the p-group of the process to its standard presentation. This function provides a description only; for a GAP object, use `EpimorphismStandardPresentation` (see EpimorphismStandardPresentation!interactive).

  Note: For those familiar with the `pq` program, `PqSPIsomorphism` performs menu item 8 of the Standard Presentation menu.

  Commands from the Main p-Group Generation menu

  Note that the p-group generation commands can only be applied once the `pq` program has produced a pc presentation of some quotient group of the ``group of the process''.

- `PqPGSupplyAutomorphisms(` i`[,` mlist`] :` options`) F`
- `PqPGSupplyAutomorphisms([`mlist`] :` options`) F`

  for the ith or default interactive ANUPQ process, supply the `pq` program with the automorphism group data needed for the current quotient of the group of that process (for process i the group is stored as `ANUPQData.io[`i`].group`). For a description of the format of mlist see PqSupplyAutomorphisms. The options possible are `NumberOfSolubleAutomorphisms` and `RelativeOrders`. (Detailed descriptions of these options may be found in Chapter ANUPQ Options.)

  If mlist is omitted, the automorphism data is determined from the group of the process which must have been a p-group in pc presentation.

  Note: For those familiar with the `pq` program, `PqPGSupplyAutomorphisms` performs menu item 1 of the main p-Group Generation menu.

- `PqPGExtendAutomorphisms(` i`) F`
- `PqPGExtendAutomorphisms() F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to compute the extensions of the automorphisms of the p-quotient of the previous class to the p-quotient of the current class. You may wish to set the `InfoLevel` of `InfoANUPQ` to 2 (or more) in order to see the output from the `pq` program (see InfoANUPQ).

  Note: For those familiar with the `pq` program, `PqPGExtendAutomorphisms` performs menu item 2 of the main or advanced p-Group Generation menu.

- `PqPGConstructDescendants(` i`:` options`) F`
- `PqPGConstructDescendants( :` options`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to construct descendants prescribed by options, and return the number of descendants constructed (compare function PqDescendants which returns the list of descendants). The options possible are `ClassBound`, `OrderBound`, `StepSize`, `PcgsAutomorphisms`, `RankInitialSegmentSubgroups`, `SpaceEfficient`, `CapableDescendants`, `AllDescendants`, `Exponent`, `Metabelian`, `BasicAlgorithm`, `CustomiseOutput`. (Detailed descriptions of these options may be found in Chapter ANUPQ Options.)

  `PqPGConstructDescendants` requires that the `pq` program has previously computed a pc presentation and a p-cover for a p-quotient of some class of the group of the process.

  Note: For those familiar with the `pq` program, `PqPGConstructDescendants` performs menu item 5 of the main p-Group Generation menu.

- `PqPGSetDescendantToPcp(` i`,` cls`,` n`) F`
- `PqPGSetDescendantToPcp(` cls`,` n`) F`
- `PqPGSetDescendantToPcp(` i`[: Filename :=` name`]) F`
- `PqPGSetDescendantToPcp([: Filename :=` name`]) F`
- `PqPGRestoreDescendantFromFile(`i`,` cls`,` n`) F`
- `PqPGRestoreDescendantFromFile(` cls`,` n`) F`
- `PqPGRestoreDescendantFromFile(` i`[: Filename :=` name`]) F`
- `PqPGRestoreDescendantFromFile([: Filename :=` name`]) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to restore group n of class cls from a temporary file, where cls and n are positive integers, or the group stored in name. `PqPGSetDescendantToPcp` and `PqPGRestoreDescendantFromFile` are synonyms; they make sense only after a prior call to construct descendants by say `PqPGConstructDescendants` (see PqPGConstructDescendants) or the interactive `PqDescendants` (see PqDescendants!interactive). In the `Filename` option forms, the option defaults to the last filename in which a presentation was stored by the `pq` program.

  Notes

  Since the `PqPGSetDescendantToPcp` and `PqPGRestoreDescendantFromFile` are intended to be used in calculation of further descendants the `pq` program computes the p-cover of the restored descendant. Hence, `PqCurrentGroup` used immediately after one of these commands returns the p-cover of the restored descendant rather than the descendant itself.

  For those familiar with the `pq` program, `PqPGSetDescendantToPcp` and `PqPGRestoreDescendantFromFile` perform menu item 3 of the main or advanced p-Group Generation menu.

  Commands from the Advanced p-Group Generation menu

  The functions below perform the component algorithms of `PqPGConstructDescendants` (see PqPGConstructDescendants). You can get some idea of their usage by trying `PqExample("Nott-APG-Rel-i");`. You can get some idea of the breakdown of `PqPGConstructDescendants` into these functions by comparing the previous output with `PqExample("Nott-PG-Rel-i");`.

  These functions are intended for use only by ``experts''; please contact the authors of the package if you genuinely have a need for them and need any amplified descriptions.

- `PqAPGDegree(` i`,` step`,` rank`[: Exponent :=` n`]) F`
- `PqAPGDegree(` step`,` rank`[: Exponent :=` n`]) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to invoke menu item 6 of the Advanced p-Group Generation menu. Here the step-size step and the rank rank are positive integers and are the arguments required by the `pq` program. See option Exponent for the one recognised option `Exponent`.

- `PqAPGPermutations(` i`:` options`) F`
- `PqAPGPermutations( :` options`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` program to perform menu item 7 of the Advanced p-Group Generation menu. Here the options options recognised are `PcgsAutomorphisms`, `SpaceEfficient`, `PrintAutomorphisms` and `PrintPermutations` (see Chapter ANUPQ Options for details).

- `PqAPGOrbits(` i`:` options`) F`
- `PqAPGOrbits( :` options`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` to perform menu item 8 of the Advanced p-Group Generation menu.

  Here the options options recognised are `PcgsAutomorphisms`, `SpaceEfficient`, and `CustomiseOutput` (see Chapter ANUPQ Options for details). For the `CustomiseOutput` option only the setting of the `orbit` is recognised (all other fields if set are ignored).

- `PqAPGOrbitRepresentatives(` i`:` options`) F`
- `PqAPGOrbitRepresentatives(:` options`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` to perform item 9 of the Advanced p-Group Generation menu.

  The options options may be any selection of the following: `PcgsAutomorphisms`, `SpaceEfficient`, `Exponent`, `Metabelian`, `CapableDescendants` (or `AllDescendants`), `CustomiseOutput` (where only the `group` and `autgroup` fields are recognised) and `Filename` (see Chapter ANUPQ Options for details). If `Filename` is omitted the reduced p-cover is written to the file `"redPCover"` in the temporary directory whose name is stored in `ANUPQData.tmpdir`.

- `PqAPGSingleStage(` i`:` options`) F`
- `PqAPGSingleStage( :` options`) F`

  for the ith or default interactive ANUPQ process, direct the `pq` to perform option 5 of the Advanced p-Group Generation menu.

  The possible options are `StepSize`, `PcgsAutomorphisms`, `RankInitialSegmentSubgroups`, `SpaceEfficient`, `CapableDescendants`, `AllDescendants`, `Exponent`, `Metabelian`, `BasicAlgorithm` and `CustomiseOutput`. (Detailed descriptions of these options may be found in Chapter ANUPQ Options.)

  ## 5.5 Primitive Interactive ANUPQ Process Read/Write Functions

  For those familiar with using the `pq` program as a standalone we provide primitive read/write tools to communicate directly with an interactive ANUPQ process, started via `PqStart`. For the most part, it is up to the user to translate the output strings from `pq` program into a form useful in GAP.

- `PqRead(` i`) F`
- `PqRead() F`

  read a complete line of ANUPQ output, from the ith or default interactive ANUPQ process, if there is output to be read and returns `fail` otherwise. When successful, the line is returned as a string complete with trailing newline, colon, or question-mark character. Please note that it is possible to be ``too quick'' (i.e. the return can be `fail` purely because the output from ANUPQ is not there yet), but if `PqRead` finds any output at all, it waits for a complete line. `PqRead` also writes the line read via `Info` at `InfoANUPQ` level 2. It doesn't try to distinguish banner and menu output from other output of the `pq` program.

- `PqReadAll(` i`) F`
- `PqReadAll() F`

  read and return as many complete lines of ANUPQ output, from the ith or default interactive ANUPQ process, as there are to be read, at the time of the call, as a list of strings with any trailing newlines removed and returns the empty list otherwise. `PqReadAll` also writes each line read via `Info` at `InfoANUPQ` level 2. It doesn't try to distinguish banner and menu output from other output of the `pq` program. Whenever `PqReadAll` finds only a partial line, it waits for the complete line, thus increasing the probability that it has captured all the output to be had from ANUPQ.

- `PqReadUntil(` i`,` IsMyLine`) F`
- `PqReadUntil(` IsMyLine`) F`
- `PqReadUntil(` i`,` IsMyLine`,` Modify`) F`
- `PqReadUntil(` IsMyLine`,` Modify`) F`

  read complete lines of ANUPQ output, from the ith or default interactive ANUPQ process, ``chomps'' them (i.e. removes any trailing newline character), emits them to `Info` at `InfoANUPQ` level 2 (without trying to distinguish banner and menu output from other output of the `pq` program), and applies the function Modify (where Modify is just the identity map/function for the first two forms) until a ``chomped'' line line for which ``IsMyLine`(` Modify`(`line`) )` is true. `PqReadUntil` returns the list of Modify-ed ``chomped'' lines read.

  Notes: When provided by the user, Modify should be a function that accepts a single string argument.

  IsMyLine should be a function that is able to accept the output of Modify (or take a single string argument when Modify is not provided) and should return a boolean.

  If ``IsMyLine`(` Modify`(`line`) )` is never true, `PqReadUntil` will wait indefinitely.

- `PqWrite(` i`,` string`) F`
- `PqWrite(` string`) F`

  write string to the ith or default interactive ANUPQ process; string must be in exactly the form the ANUPQ standalone expects. The command is echoed via `Info` at `InfoANUPQ` level 3 (with a ```ToPQ>` '' prompt); i.e. do `SetInfoLevel(InfoANUPQ, 3);` to see what is transmitted to the `pq` program. `PqWrite` returns `true` if successful in writing to the stream of the interactive ANUPQ process, and `fail` otherwise.

  Note: If `PqWrite` returns `fail` it means that the ANUPQ process has died.

  [Up] [Previous] [Next] [Index]