Quelle interact.xml Sprache: XML

<Chapter Label="Interactive ANUPQ functions">
<Heading>Interactive ANUPQ functions</Heading>

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 <C>pq</C> process (process used in the UNIX sense).
Occasionally, a user needs the <Q>next step</Q>; the functions provided in
this chapter make use of data from previous steps retained by the <C>pq</C>
program, thus allowing the user to interact with the <C>pq</C> program like
one can when one uses the <C>pq</C> program as a stand-alone (see <C>guide.dvi</C>
in the <C>standalone-doc</C> directory).


An interactive &ANUPQ; process is initiated by <C>PqStart</C> and terminated
via <C>PqQuit</C>; these functions are described in
ection <Ref Sect="Starting and Stopping Interactive ANUPQ Processes" Style="Text"/>.


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


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


On <K>quit</K>ting &GAP;, <C>PqQuitAll();</C> is executed, which terminates all
active interactive &ANUPQ; processes. If &GAP; is killed without
<K>quit</K>ting, before all interactive &ANUPQ; processes are terminated,
<E>zombie</E> processes (still living <E>child</E> processes whose <E>parents</E> 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: <C>ps xw | grep pq</C> gives you
information on the <C>pq</C> processes corresponding to any interactive
&ANUPQ; processes started in a &GAP; session; you can then do <C>kill
<A>N</A></C> for each number <A>N</A> appearing in the first column of this output).

<Section Label="Starting and Stopping Interactive ANUPQ Processes">
<Heading>Starting and Stopping Interactive ANUPQ Processes</Heading>

<ManSection>
<Func Name="PqStart" Arg="G, workspace : options" Label="with group and workspace size"/>
<Func Name="PqStart" Arg="G : options" Label="with group"/>
<Func Name="PqStart" Arg="workspace : options" Label="with workspace size"/>
<Func Name="PqStart" Arg=": options"/>
<Description>
activate an iostream for an interactive &ANUPQ; process (i.e. <C>PqStart</C>
starts up a <C>pq</C> process and opens a &GAP; iostream to <Q>talk</Q> to that
process) and returns an integer <A>i</A> that can be used to identify that
process. The argument <A>G</A> should be an <E>fp group</E> or <E>pc group</E> that the
user intends to manipulate using interactive &ANUPQ; functions. If the
function is called without specifying <A>G</A>, a group can be read in by
using the function <C>PqRestorePcPresentation</C> (see <Ref Func="PqRestorePcPresentation" Style="Text"/>).
If <C>PqStart</C> is given an integer argument <A>workspace</A>, then the <C>pq</C>
program is started up with a workspace (an integer array) of size
<A>workspace</A> (i.e. <M>4 \times <A>workspace</A></M> bytes in a 32-bit environment);
otherwise, the <C>pq</C> program sets a default workspace of <M>10000000</M>.


The only <A>options</A> currently recognised by <C>PqStart</C> are <C>Prime</C>,
<C>Exponent</C> and <C>Relators</C> (see Chapter <Ref Chap="ANUPQ Options" Style="Text"/> 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.
</Description>
</ManSection>

<ManSection>
<Func Name="PqQuit" Arg="i"/>
<Func Name="PqQuit" Arg="" Label="for default process"/>
<Description>
closes the stream of the <A>i</A>th or default interactive &ANUPQ; process
and unbinds its <C>ANUPQData.io</C> record.


<E>Note:</E>
It can happen that the <C>pq</C> process, and hence the &GAP; iostream
assigned to communicate with it, can die, e.g. by the user typing a
<C>Ctrl-C</C> while the <C>pq</C> process is engaged in a long calculation.
<C>IsPqProcessAlive</C> (see <Ref Func="IsPqProcessAlive" Style="Text"/>) is provided to check the
status of the &GAP; iostream (and hence the status of the <C>pq</C> process
it was communicating with).
</Description>
</ManSection>

<ManSection>
<Func Name="PqQuitAll" Arg=""/>
<Description>
is provided as a convenience, to terminate all active interactive
&ANUPQ; processes with a single command. It is equivalent to executing
<C>PqQuit(<A>i</A>)</C> for all active interactive &ANUPQ; processes <A>i</A>
(see <Ref Func="PqQuit" Style="Text"/>).
</Description>
</ManSection>

</Section>

<Section Label="Interactive ANUPQ Process Utility Functions">
<Heading>Interactive ANUPQ Process Utility Functions</Heading>

<ManSection>
<Func Name="PqProcessIndex" Arg="i"/>
<Func Name="PqProcessIndex" Arg="" Label="for default process"/>
<Description>
With argument <A>i</A>, which must be a positive integer, <C>PqProcessIndex</C>
returns <A>i</A> if it corresponds to an active interactive process, or raises
an error. With no arguments it returns the default active interactive
process or returns <K>fail</K> and emits a warning message to <C>Info</C> at
<C>InfoANUPQ</C> or <C>InfoWarning</C> level 1.


<E>Note:</E>
Essentially, an interactive &ANUPQ; process <A>i</A> is <Q>active</Q> if
<C>ANUPQData.io[<A>i</A>]</C> is bound (i.e. we still have some data telling us
about it). Also see <Ref Func="PqStart" Style="Text"/>.
</Description>
</ManSection>

<ManSection>
<Func Name="PqProcessIndices" Arg=""/>
<Description>
returns the list of integer indices of all active interactive &ANUPQ;
processes (see <Ref Func="PqProcessIndex" Style="Text"/> for the meaning of <Q>active</Q>).
</Description>
</ManSection>

<ManSection>
<Func Name="IsPqProcessAlive" Arg="i"/>
<Func Name="IsPqProcessAlive" Arg="" Label="for default process"/>
<Description>
return <K>true</K> if the &GAP; iostream of the <A>i</A>th (or default)
interactive &ANUPQ; process started by <C>PqStart</C> is alive (i.e. can
still be written to), or <K>false</K>, otherwise. (See the notes for <Ref Func="PqStart" Style="Text"/>
and <Ref Func="PqQuit" Style="Text"/>.)


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


The &GAP; iostream of an interactive &ANUPQ; process will also die if
the <C>pq</C> 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.
</Description>
</ManSection>

</Section>

<Section Label="Interactive Versions of Non-interactive ANUPQ Functions">
<Heading>Interactive Versions of Non-interactive ANUPQ Functions</Heading>

<ManSection>
<Func Name="Pq" Arg="i : options" Label="interactive"/>
<Func Name="Pq" Arg=": options" Label="interactive, for default process"/>
<Description>
return, for the fp or pc group (let us call it <A>F</A>), of the <A>i</A>th or
default interactive &ANUPQ; process, the <M>p</M>-quotient of <A>F</A>
specified by <A>options</A>, as a pc group; <A>F</A> must previously have been
given (as first argument) to <C>PqStart</C> to start the interactive
&ANUPQ; process (see <Ref Func="PqStart" Style="Text"/>) or restored from file using the
function <C>PqRestorePcPresentation</C> (see <Ref Func="PqRestorePcPresentation" Style="Text"/>).
Following the colon <A>options</A> is a selection of the options listed for
the non-interactive <C>Pq</C> function (see <Ref Func="Pq" Style="Text"/>), separated by commas like
record components (see Section <Ref BookName="ref" Label="Function Call With Options" Style="Text"/> in the
&GAP; Reference Manual), except that the options <C>SetupFile</C> or
<C>PqWorkspace</C> are ignored by the interactive <C>Pq</C>, and <C>RedoPcp</C> is an
option only recognised by the interactive <C>Pq</C> i.e. the following
options are recognised by the interactive <C>Pq</C> function:

<List>
<Item>
 <C>Prime := <A>p</A></C><Index>option Prime</Index>
</Item>
<Item>
 <C>ClassBound := <A>n</A></C><Index>option ClassBound</Index>
</Item>
<Item>
 <C>Exponent := <A>n</A></C><Index>option Exponent</Index>
</Item>
<Item>
 <C>Relators := <A>rels</A></C><Index>option Relators</Index>
</Item>
<Item>
 <C>Metabelian</C><Index>option Metabelian</Index>
</Item>
<Item>
 <C>Identities := <A>funcs</A></C><Index>option Identities</Index>
</Item>
<Item>
 <C>GroupName := <A>name</A></C><Index>option GroupName</Index>
</Item>
<Item>
 <C>OutputLevel := <A>n</A></C><Index>option OutputLevel</Index>
</Item>
<Item>
 <C>RedoPcp</C><Index>option RedoPcp</Index>
</Item>
</List>

Detailed descriptions of the above options may be found in Chapter <Ref Chap="ANUPQ Options" Style="Text"/>.


As a minimum the <C>Pq</C> function <E>must</E> have a value for the <C>Prime</C>
option, though <C>Prime</C> need not be passed again in the case it has
previously been provided, e.g. to <C>PqStart</C> (see <Ref Func="PqStart" Style="Text"/>) when starting
the interactive process.


The behaviour of the interactive <C>Pq</C> function depends on the current
state of the pc presentation stored by the <C>pq</C> program:

<Enum>
<Item>
If no pc presentation has yet been computed (the case immediately after
the <C>PqStart</C> call initiating the process) then the quotient group of the
input group of the process of largest lower exponent-<A>p</A> class bounded by
the value of the <C>ClassBound</C> option (see <Ref Label="option ClassBound" Style="Text"/>) is
returned.
</Item>

<Item>
If the current pc presentation of the process was determined by a
previous call to <C>Pq</C> or <C>PqEpimorphism</C>, and the current call has a
larger value <C>ClassBound</C> 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-<A>p</A> class is returned.
</Item>

<Item>
If the current pc presentation of the process was determined by a
previous call to <C>PqPCover</C> then a consistent pc presentation of a
quotient for the current class is determined before proceeding as in 2.
</Item>

<Item>
If the <C>RedoPcp</C> option is supplied the current pc presentation is
scrapped, all options must be re-supplied (in particular, <C>Prime</C> <E>must</E>
be supplied) and then the <C>Pq</C> function proceeds as in 1.
</Item>
</Enum>

See Section <Ref Sect="Attributes and a Property for fp and pc p-groups" Style="Text"/> for the
attributes and property <C>NuclearRank</C>, <C>MultiplicatorRank</C> and
<C>IsCapable</C> which may be applied to the group returned by <C>Pq</C>.


The following is one of the examples for the non-interactive <C>Pq</C> redone
with the interactive version. Also, we set the option <C>OutputLevel</C> to 1
(see <Ref Label="option OutputLevel" Style="Text"/>), in order to see the orders of the quotients
of all the classes determined, and we set the <C>InfoANUPQ</C> level to 2
(see <Ref Func="InfoANUPQ" Style="Text"/>), so that we catch the timing information.

<Example><![CDATA[
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>
]]></Example>
</Description>
</ManSection>

<ManSection>
<Func Name="PqEpimorphism" Arg="i : options" Label="interactive"/>
<Func Name="PqEpimorphism" Arg=": options" Label="interactive, for default process"/>
<Description>
return, for the fp or pc group (let us call it <A>F</A>), of the <A>i</A>th or
default interactive &ANUPQ; process, an epimorphism from <A>F</A> onto the
<M>p</M>-quotient of <A>F</A> specified by <A>options</A>; <A>F</A> must previously have been
given (as first argument) to <C>PqStart</C> to start the interactive &ANUPQ;
process (see <Ref Func="PqStart" Style="Text"/>). Since the underlying interactions with the <C>pq</C>
program effected by the interactive <C>PqEpimorphism</C> are identical to
those effected by the interactive <C>Pq</C>, everything said regarding the
requirements and behaviour of the interactive <C>Pq</C> function
(see <Ref Func="Pq" Label="interactive" Style="Text"/>) is also the case for the interactive
<C>PqEpimorphism</C>.


<E>Note:</E>
See Section <Ref Sect="Attributes and a Property for fp and pc p-groups" Style="Text"/> for the
attributes and property <C>NuclearRank</C>, <C>MultiplicatorRank</C> and
<C>IsCapable</C> which may be applied to the image group of the epimorphism
returned by <C>PqEpimorphism</C>.
</Description>
</ManSection>

<ManSection>
<Func Name="PqPCover" Arg="i : options" Label="interactive"/>
<Func Name="PqPCover" Arg=": options" Label="interactive, for default process"/>
<Description>
return, for the fp or pc group of the <A>i</A>th or default interactive
&ANUPQ; process, the <M>p</M>-covering group of the <M>p</M>-quotient <C>Pq(<A>i</A> :
<A>options</A>)</C> or <C>Pq(: <A>options</A>)</C>, modulo the following:

<Enum>
<Item>
If no pc presentation has yet been computed (the case immediately after
the <C>PqStart</C> call initiating the process) and the group <A>F</A> of the
process is already a <M>p</M>-group, in the sense that <C>HasIsPGroup(<A>F</A>) and
IsPGroup(<A>F</A>)</C> is <K>true</K>, then
 <List>
 <C>Prime</C>
 <Item>
 defaults to <C>PrimePGroup(<A>F</A>)</C>, if not supplied and <C>HasPrimePGroup(<A>F</A>)
 = true</C>; and
 </Item>
 <C>ClassBound</C>
 <Item>
 defaults to <C>PClassPGroup(<A>F</A>)</C> if <C>HasPClassPGroup(<A>F</A>) = true</C> if not
 supplied, or to the usual default of 63, otherwise.
 </Item>
 </List>
</Item>

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

<Listing><![CDATA[
Pq(i : options);
PqPCover(i);
]]></Listing>
</Item>

<Item>
If the <C>RedoPcp</C> option is supplied the current pc presentation is
scrapped, and <C>PqPCover</C> proceeds as in 1. or 2. but without the
<C>RedoPcp</C> option.
</Item>
</Enum>
</Description>
</ManSection>

<Index>automorphisms<Subkey>of <M>p</M>-groups</Subkey></Index>
<ManSection>
<Func Name="PqStandardPresentation" Arg="[ i ]: options" Label="interactive"/>
<Func Name="StandardPresentation" Arg="[ i ]: options" Label="interactive"/>
<Description>
return, for the <A>i</A>th or default interactive &ANUPQ; process, the
<A>p</A>-quotient of the group <A>F</A> of the process, specified by <A>options</A>, as
an <E>fp group</E> which has a standard presentation. Here <A>options</A> is a
selection of the options from the following list (see Chapter <Ref Chap="ANUPQ Options" Style="Text"/> for detailed descriptions); this list is the same as for the
non-interactive version of <C>PqStandardPresentation</C> except for the
omission of options <C>SetupFile</C> and <C>PqWorkspace</C>
(see <Ref Func="PqStandardPresentation" Style="Text"/>).

<List>
<Item>
 <C>Prime := <A>p</A></C><Index>option Prime</Index>
</Item>
<Item>
 <C>pQuotient := <A>Q</A></C><Index>option pQuotient</Index>
</Item>
<Item>
 <C>ClassBound := <A>n</A></C><Index>option ClassBound</Index>
</Item>
<Item>
 <C>Exponent := <A>n</A></C><Index>option Exponent</Index>
</Item>
<Item>
 <C>Metabelian</C><Index>option Metabelian</Index>
</Item>
<Item>
 <C>GroupName := <A>name</A></C><Index>option GroupName</Index>
</Item>
<Item>
 <C>OutputLevel := <A>n</A></C><Index>option OutputLevel</Index>
</Item>
<Item>
 <C>StandardPresentationFile := <A>filename</A></C><Index>option StandardPresentationFile</Index>
</Item>
</List>

Unless <A>F</A> is a pc <A>p</A>-group, or the option <C>Prime</C> has been passed to a
previous interactive function for the process to compute a <A>p</A>-quotient
for <A>F</A>, the user <E>must</E> supply either the option <C>Prime</C> or the option
<C>pQuotient</C> (if both <C>Prime</C> and <C>pQuotient</C> are supplied, the prime <A>p</A>
is determined by applying <C>PrimePGroup</C> (see <Ref BookName="ref" Attr="PrimePGroup" Style="Text"/> in the
Reference Manual) to the value of <C>pQuotient</C>).


Taking one of the examples for the non-interactive version of
<C>StandardPresentation</C> (see <Ref Func="StandardPresentation" Style="Text"/>) that required two
separate calls to the <C>pq</C> program, we now show how it can be done by
setting up a dialogue with just the one <C>pq</C> process, using the
interactive version of <C>StandardPresentation</C>:

<Example><![CDATA[
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>
]]></Example>

<E>Notes</E>


In contrast to the function <C>Pq</C> (see <Ref Func="Pq" Style="Text"/>) which returns a pc group,
<C>PqStandardPresentation</C> or <C>StandardPresentation</C> 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 <C>PcGroupFpGroup</C>
(see <Ref BookName="ref" Func="PcGroupFpGroup" Style="Text"/> in the
&GAP; Reference Manual) to form a pc group.


If the user does not supply a <A>p</A>-quotient <A>Q</A> via the
<C>pQuotient</C> option, and the prime <A>p</A> is either supplied, stored, or
<A>F</A> is a pc <A>p</A>-group, then a <A>p</A>-quotient <A>Q</A> is
computed. (The value of the prime <A>p</A> is stored if passed initially to
<C>PqStart</C> or to a subsequent interactive process.) Note that a stored
value for <C>pQuotient</C> (from a prior call to <C>Pq</C>) does <E>not</E>
have precedence over a value for the prime <A>p</A>. If the user does supply a
<A>p</A>-quotient <A>Q</A> via the <C>pQuotient</C> option, the package
&AutPGrp; is called to compute the automorphism group of <A>Q</A>; 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 <C>PqStandardPresentation</C>,
<C>StandardPresentation</C>, <C>EpimorphismPqStandardPresentation</C> or
<C>EpimorphismStandardPresentation</C> 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
<C>SPepi</C> and <C>SP</C> fields of the data record associated with the
process. See the example for the interactive
<C>EpimorphismStandardPresentation</C>
(<Ref Func="EpimorphismStandardPresentation" Label="interactive" Style="Text"/>).


The attributes and property <C>NuclearRank</C>, <C>MultiplicatorRank</C> and
<C>IsCapable</C> are set for the group returned by <C>PqStandardPresentation</C> or
<C>StandardPresentation</C> (see Section <Ref Sect="Attributes and a Property for fp and pc p-groups" Style="Text"/>).
</Description>
</ManSection>

<ManSection>
<Func Name="EpimorphismPqStandardPresentation" Arg="[ i ]: options" Label="interactive"/>
<Meth Name="EpimorphismStandardPresentation" Arg="[ i ]: options" Label="interactive"/>
<Description>
Each of the above functions accepts the same arguments and options as the
interactive form of <C>StandardPresentation</C>
(see <Ref Func="StandardPresentation" Label="interactive" Style="Text"/>) and returns an epimorphism from
the fp or pc group <A>F</A> of the <A>i</A>th or default interactive &ANUPQ;
process onto the finitely presented group given by a standard
presentation, i.e. if <A>S</A> is the standard presentation computed for the
<M>p</M>-quotient of <A>F</A> by <C>StandardPresentation</C> then
<C>EpimorphismStandardPresentation</C> returns the epimorphism from <A>F</A> to the
group with presentation <A>S</A>. The group <A>F</A> must have been given (as first
argument) to <C>PqStart</C> to start the interactive &ANUPQ; process
(see <Ref Func="PqStart" Style="Text"/>).


Taking our earlier non-interactive example
(see <Ref Func="EpimorphismPqStandardPresentation" Style="Text"/>) and modifying it a little, we
illustrate, as for the interactive <C>StandardPresentation</C>
(see <Ref Func="StandardPresentation" Label="interactive" Style="Text"/>), how something that required two
separate calls to the <C>pq</C> program can now be achieved with a dialogue
with just one <C>pq</C> process. Also, observe that calls to one of the
standard presentation functions (as mentioned in the notes
of <Ref Func="StandardPresentation" Label="interactive" Style="Text"/>) 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.

<Example><![CDATA[
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
]]></Example>

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


<E>Note:</E>
The notes for <C>PqStandardPresentation</C> or <C>StandardPresentation</C>
(see <Ref Func="PqStandardPresentation" Label="interactive" Style="Text"/>) apply also to
<C>EpimorphismPqStandardPresentation</C> or <C>EpimorphismStandardPresentation</C>
except that their return value is an <E>epimorphism onto</E> an fp group,
i.e. one should interpret the phrase <Q>returns an fp group</Q> as <Q>returns
an epimorphism onto an fp group</Q> etc.
</Description>
</ManSection>

<ManSection>
<Func Name="PqDescendants" Arg="i : options" Label="interactive"/>
<Func Name="PqDescendants" Arg=": options" Label="interactive, for default process"/>
<Description>
return for the pc group <A>G</A> of the <A>i</A>th or default interactive &ANUPQ;
process, which must be of prime power order with a confluent pc
presentation (see <Ref BookName="ref" Func="IsConfluent" Label="for pc groups" Style="Text"/> in the &GAP; Reference
Manual), a list of descendants (pc groups) of <A>G</A>. The group <A>G</A> is
usually given as first argument to <C>PqStart</C> when starting the
interactive &ANUPQ; process (see <Ref Func="PqStart" Style="Text"/>). Alternatively, one may
initiate the process with an fp group, use <C>Pq</C> interactively
(see <Ref Func="Pq" Label="interactive" Style="Text"/>) to create a pc group and use
<C>PqSetPQuotientToGroup</C> (see <Ref Func="PqSetPQuotientToGroup" Style="Text"/>), which involves
<E>no</E> computation, to set the pc group returned by <C>Pq</C> as the group of
the process. Note that repeating a call to <C>PqDescendants</C> for the same
interactive &ANUPQ; process simply returns the list of descendants
originally calculated; a warning is emitted at <C>InfoANUPQ</C> level 1
reminding you of this should you do this.


After the colon, <A>options</A> a selection of the options listed for the
non-interactive <C>PqDescendants</C> function (see <Ref Func="PqDescendants" Style="Text"/>), should be
given, separated by commas like record components (see
Section <Ref BookName="ref" Label="Function Call With Options" Style="Text"/> in the &GAP; Reference Manual),
except that the options <C>SetupFile</C> or <C>PqWorkspace</C> are ignored by the
interactive <C>PqDescendants</C>, i.e. the following options are recognised by
the interactive <C>PqDescendants</C> function:

<List>
<Item>
 <C>ClassBound := <A>n</A></C><Index>option ClassBound</Index>
</Item>
<Item>
 <C>Relators := <A>rels</A></C><Index>option Relators</Index>
</Item>
<Item>
 <C>OrderBound := <A>n</A></C><Index>option OrderBound</Index>
</Item>
<Item>
 <C>StepSize := <A>n</A></C>, <C>StepSize := <A>list</A></C>
 <Index>option StepSize</Index>
</Item>
<Item>
 <C>RankInitialSegmentSubgroups := <A>n</A></C><Index>option RankInitialSegmentSubgroups</Index>
</Item>
<Item>
 <C>SpaceEfficient</C><Index>option SpaceEfficient</Index>
</Item>
<Item>
 <C>CapableDescendants</C><Index>option CapableDescendants</Index>
</Item>
<Item>
 <C>AllDescendants := false</C><Index>option AllDescendants</Index>
</Item>
<Item>
 <C>Exponent := <A>n</A></C><Index>option Exponent</Index>
</Item>
<Item>
 <C>Metabelian</C><Index>option Metabelian</Index>
</Item>
<Item>
 <C>GroupName := <A>name</A></C><Index>option GroupName</Index>
</Item>
<Item>
 <C>SubList := <A>sub</A></C><Index>option SubList</Index>
</Item>
<Item>
 <C>BasicAlgorithm</C><Index>option BasicAlgorithm</Index>
</Item>
<Item>
 <C>CustomiseOutput := <A>rec</A></C><Index>option CustomiseOutput</Index>
</Item>
</List>

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


The attributes and property <C>NuclearRank</C>, <C>MultiplicatorRank</C> and
<C>IsCapable</C> are set for each group of the list returned by
<C>PqDescendants</C> (see Section <Ref Sect="Attributes and a Property for fp and pc p-groups" Style="Text"/>).


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

<Example><![CDATA[
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 ]
]]></Example>

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

<Example><![CDATA[
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> ]
]]></Example>

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

<Example><![CDATA[
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( d, Order ) ) );
[ 5, 5, 5 ]
]]></Example>
</Description>
</ManSection>

<ManSection>
<Func Name="PqSetPQuotientToGroup" Arg="i"/>
<Func Name="PqSetPQuotientToGroup" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, set the
<M>p</M>-quotient previously computed by the interactive <C>Pq</C> function
(see <Ref Func="Pq" Label="interactive" Style="Text"/>) to be the group of the process. This function is
supplied to enable the computation of descendants of a <M>p</M>-quotient that
is already known to the <C>pq</C> program, via the interactive <C>PqDescendants</C>
function (see <Ref Func="PqDescendants" Label="interactive" Style="Text"/>), thus avoiding the need to
re-submit it and have the <C>pq</C> program recompute it.


<E>Note:</E> See the function <C>PqPGSetDescendantToPcp</C>
(<Ref Func="PqPGSetDescendantToPcp" Style="Text"/>) for a mechanism to make (the <M>p</M>-cover of) a
particular descendants the current group of the process.


The following example of the usage of <C>PqSetPQuotientToGroup</C>, which is
essentially equivalent to what is obtained by running
<C>PqExample("PqDescendants-1-i");</C>, redoes the first example of
<Ref Func="PqDescendants" Label="interactive" Style="Text"/> (which computes the descendants of the Klein
four group).

<Example><![CDATA[
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 ]
]]></Example>
</Description>
</ManSection>

</Section>

<Section Label="Low-level Interactive ANUPQ functions based on menu items of the pq program">
<Heading>Low-level Interactive ANUPQ functions based on menu items of the
pq program</Heading>

The <C>pq</C> 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: <C>guide.dvi</C>. Both <C>guide.dvi</C> and the
<C>pq</C> program refer to the items of these 5 menus as <Q>options</Q>, which do
<E>not</E> correspond in any way to the options used by any of the &GAP;
functions that interface with the <C>pq</C> program.


<E>Warning:</E>
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 <C>pq</C> standalone (in particular, its <Q>advanced</Q>
menus) assumes some expertise of the user; doing the <Q>wrong</Q> thing can
cause the program to crash. While a number of safeguards have been
provided in the &GAP; interface to the <C>pq</C> program, these are <E>not</E>
foolproof, and the user should exercise care and ensure pre-requisites of
the various commands are met.
</Section>

<Section><Heading>General commands</Heading>

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

<ManSection>
<Func Name="PqNrPcGenerators" Arg="i"/>
<Func Name="PqNrPcGenerators" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, return the number
of pc generators of the lower exponent <M>p</M>-class quotient of the group
currently determined by the process. This also applies if the pc
presentation is not consistent.
</Description>
</ManSection>

<ManSection>
<Func Name="PqFactoredOrder" Arg="i"/>
<Func Name="PqFactoredOrder" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, return an integer
pair <C>[<A>p</A>, <A>n</A>]</C> where <A>p</A> is a prime and <A>n</A> is the number of pc
generators (see <Ref Func="PqNrPcGenerators" Style="Text"/>) in the pc presentation of the
quotient group currently determined by the process. If this presentation
is consistent, then <M>p^n</M> 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), <M>p^n</M> is an upper bound for the order of the
group.
</Description>
</ManSection>

<ManSection>
<Func Name="PqOrder" Arg="i"/>
<Func Name="PqOrder" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, return <M>p^n</M>
where <C>[<A>p</A>, <A>n</A>]</C> is the pair as returned by <C>PqFactoredOrder</C>
(see <Ref Func="PqFactoredOrder" Style="Text"/>).
</Description>
</ManSection>

<ManSection>
<Func Name="PqPClass" Arg="i"/>
<Func Name="PqPClass" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, return the lower
exponent <M>p</M>-class of the quotient group currently determined by the
process.
</Description>
</ManSection>

<ManSection>
<Func Name="PqWeight" Arg="i, j"/>
<Func Name="PqWeight" Arg="j" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, return the weight
of the <A>j</A>th pc generator of the lower exponent <M>p</M>-class quotient of the
group currently determined by the process, or <K>fail</K> if there is no such
numbered pc generator.
</Description>
</ManSection>

<ManSection>
<Func Name="PqCurrentGroup" Arg="i"/>
<Func Name="PqCurrentGroup" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th 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 <M>p</M>-class quotient of the start group or the
<M>p</M>-cover of such a quotient).


<E>Notes:</E>
See Section <Ref Sect="Attributes and a Property for fp and pc p-groups" Style="Text"/> for the
attributes and property <C>NuclearRank</C>, <C>MultiplicatorRank</C> and
<C>IsCapable</C> which may be applied to the group returned by
<C>PqCurrentGroup</C>.
</Description>
</ManSection>

<ManSection>
<Func Name="PqDisplayPcPresentation" Arg="i : [OutputLevel := lev ]"/>
<Func Name="PqDisplayPcPresentation" Arg=": [OutputLevel := lev ]" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to display the pc presentation of the lower exponent <M>p</M>-class
quotient of the group currently determined by the process.


Except if the last command communicating with the <C>pq</C> program was a
<M>p</M>-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 <C>PqSetOutputLevel</C> first (see <Ref Func="PqSetOutputLevel" Style="Text"/>), or
equivalently pass the option <C>OutputLevel</C> (see <Ref Label="option OutputLevel" Style="Text"/>).


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqDisplayPcPresentation</C>
performs menu item 4 of the current menu of the <C>pq</C> program.
</Description>
</ManSection>

<ManSection>
<Func Name="PqSetOutputLevel" Arg="i, lev"/>
<Func Name="PqSetOutputLevel" Arg="lev" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to set the output level of the <C>pq</C> program to <A>lev</A>.


<E>Note:</E> For those familiar with the <C>pq</C> program, <C>PqSetOutputLevel</C>
performs menu item 5 of the main (or advanced) <M>p</M>-Quotient menu, or the
Standard Presentation menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqEvaluateIdentities" Arg="i : [ Identities := funcs ]"/>
<Func Name="PqEvaluateIdentities" Arg=": [ Identities := funcs ]" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, invoke the
evaluation of identities defined by the <C>Identities</C> option, and
eliminate any redundant pc generators formed. Since a previous value of
<C>Identities</C> is saved in the data record of the process, it is
unnecessary to pass the <C>Identities</C> if set previously.


<E>Note:</E> This function is mainly implemented at the &GAP; level. It does
not correspond to a menu item of the <C>pq</C> program.
</Description>
</ManSection>

</Section>

<Section><Heading>Commands from the Main <M>p</M>-Quotient menu</Heading>

<ManSection>
<Func Name="PqPcPresentation" Arg="i : options"/>
<Func Name="PqPcPresentation" Arg=": options" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to compute the pc presentation of the quotient (determined by
<A>options</A>) of the group of the process, which for process <A>i</A> is stored
as <C>ANUPQData.io[<A>i</A>].group</C>.


The possible <A>options</A> are the same as for the interactive <C>Pq</C>
(see <Ref Func="Pq" Label="interactive" Style="Text"/>) function, except for <C>RedoPcp</C> (which, in any
case, would be superfluous), namely: <C>Prime</C>, <C>ClassBound</C>, <C>Exponent</C>,
<C>Relators</C>, <C>GroupName</C>, <C>Metabelian</C>, <C>Identities</C> and <C>OutputLevel</C>
(see Chapter <Ref Chap="ANUPQ Options" Style="Text"/> for a detailed description for these
options). The option <C>Prime</C> is required unless already provided to
<C>PqStart</C>.


<E>Notes</E>


The pc presentation is held by the <C>pq</C> program. In contrast to <C>Pq</C>
(see <Ref Func="Pq" Label="interactive" Style="Text"/>), no &GAP; pc group is returned;
see <C>PqCurrentGroup</C> (<Ref Func="PqCurrentGroup" Style="Text"/>) if you need the corresponding
&GAP; pc group.


<C>PqPcPresentation(<A>i</A>: <A>options</A>);</C> is roughly equivalent to the
following sequence of low-level commands:


<Listing><![CDATA[
PqPcPresentation(i: opts); #class 1 call
for c in [2 .. class] do
 PqNextClass(i);
od;
]]></Listing>

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


For those familiar with the <C>pq</C> program, <C>PqPcPresentation</C> performs
menu item 1 of the main <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqSavePcPresentation" Arg="i, filename"/>
<Func Name="PqSavePcPresentation" Arg="filename" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to save the pc presentation previously computed for the quotient
of the group of that process to the file with name <A>filename</A>. If the
first character of the string <A>filename</A> is not <C>/</C>, <A>filename</A> 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
<C>PqRestorePcPresentation</C> (see <Ref Func="PqRestorePcPresentation" Style="Text"/>).


<E>Note:</E> For those familiar with the <C>pq</C> program, <C>PqSavePcPresentation</C>
performs menu item 2 of the main <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqRestorePcPresentation" Arg="i, filename"/>
<Func Name="PqRestorePcPresentation" Arg="filename" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to restore the pc presentation previously saved to <A>filename</A>, by
<C>PqSavePcPresentation</C> (see <Ref Func="PqSavePcPresentation" Style="Text"/>). If the first
character of the string <A>filename</A> is not <C>/</C>, <A>filename</A> is assumed to
be the path of a readable file relative to the directory in which &GAP;
was started.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqRestorePcPresentation</C>
performs menu item 3 of the main <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqNextClass" Arg="i : [ QueueFactor ]"/>
<Func Name="PqNextClass" Arg=": [ QueueFactor ]" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to calculate the next class of <C>ANUPQData.io[<A>i</A>].group</C>.


<Index>option QueueFactor</Index>
<C>PqNextClass</C> accepts the option <C>QueueFactor</C> (see also <Ref Label="option QueueFactor" Style="Text"/>) which should be a positive integer if automorphisms have
been previously supplied. If the <C>pq</C> program requires a queue factor and
none is supplied via the option <C>QueueFactor</C> a default of 15 is taken.


<E>Notes</E>


The single command: <C>PqNextClass(<A>i</A>);</C> is equivalent to executing

<Listing><![CDATA[
PqComputePCover(i);
PqCollectDefiningRelations(i);
PqDoExponentChecks(i);
PqEliminateRedundantGenerators(i);
]]></Listing>

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


For those familiar with the <C>pq</C> program, <C>PqNextClass</C> performs menu item
6 of the main <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqComputePCover" Arg="i"/>
<Func Name="PqComputePCover" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; processi, directi, the <C>pq</C>
program to compute the <M>p</M>-covering group of <C>ANUPQData.io[<A>i</A>].group</C>.
In contrast to the function <C>PqPCover</C> (see <Ref Func="PqPCover" Style="Text"/>), this function does
not return a &GAP; pc group.


<E>Notes</E>


The single command: <C>PqComputePCover(<A>i</A>);</C> is equivalent to executing

<Listing><![CDATA[
PqSetupTablesForNextClass(i);
PqTails(i, 0);
PqDoConsistencyChecks(i, 0, 0);
PqEliminateRedundantGenerators(i);
]]></Listing>

For those familiar with the <C>pq</C> program, <C>PqComputePCover</C> performs menu
item 7 of the main <M>p</M>-Quotient menu.
</Description>
</ManSection>

</Section>

<Section><Heading>Commands from the Advanced <M>p</M>-Quotient menu</Heading>

<ManSection>
<Func Name="PqCollect" Arg="i, word"/>
<Func Name="PqCollect" Arg="word" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, instruct the <C>pq</C>
program to do a collection on <A>word</A>, a word in the current pc generators
(the form of <A>word</A> required is described below). <C>PqCollect</C> 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 <A>word</A>; see
below).


The argument <A>word</A> may be input in either of the following ways:

<Enum>
<Item>
<A>word</A> may be a string, where the <A>i</A>th pc generator is represented by
<C>x<A>i</A></C>, e.g. <C>"x3*x2^2*x1"</C>. This way is quite versatile as parentheses
and left-normed commutators -- using square brackets, in the same way as
<C>PqGAPRelators</C> (see <Ref Func="PqGAPRelators" Style="Text"/>) -- are permitted; <A>word</A> is checked
for correct syntax via <C>PqParseWord</C> (see <Ref Func="PqParseWord" Style="Text"/>).
</Item>

<Item>
Otherwise, <A>word</A> must be a list of generator number, exponent pairs of
integers, i.e. each pair represents a <Q>syllable</Q> so that <C>[ [3, 1],
[2, 2], [1, 1] ]</C> represents the same word as that of the example given
for the first allowed form of <A>word</A>.
</Item>
</Enum>

<E>Note:</E> For those familiar with the <C>pq</C> program, <C>PqCollect</C> performs
menu item 1 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqSolveEquation" Arg="i, a, b"/>
<Func Name="PqSolveEquation" Arg="a, b" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to solve <M><A>a</A> * <A>x</A> = <A>b</A></M> for <A>x</A>, where <A>a</A> and <A>b</A> are words
in the pc generators. For the representation of these words see the
description of the function <C>PqCollect</C> (<Ref Func="PqCollect" Style="Text"/>).


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqSolveEquation</C> performs
menu item 2 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqCommutator" Arg="i, words, pow"/>
<Func Name="PqCommutator" Arg="words, pow" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, instruct the <C>pq</C>
program to compute the left normed commutator of the list <A>words</A> of
words in the current pc generators raised to the integer power <A>pow</A>, and
return the resulting word as a list of generator number, exponent pairs.
The form required for each word of <A>words</A> is the same as that required
for the <A>word</A> argument of <C>PqCollect</C> (see <Ref Func="PqCollect" Style="Text"/>). The form of the
output word is also the same as for <C>PqCollect</C>.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqCommutator</C> performs menu
item 3 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqSetupTablesForNextClass" Arg="i"/>
<Func Name="PqSetupTablesForNextClass" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to set up tables for the next class. As as side-effect,
after <C>PqSetupTablesForNextClass(<A>i</A>)</C> the value returned by
<C>PqPClass(<A>i</A>)</C> will be one more than it was previously.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqSetupTablesForNextClass</C>
performs menu item 6 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqTails" Arg="i, weight"/>
<Func Name="PqTails" Arg="weight" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to compute and add tails of weight <A>weight</A> if <A>weight</A> is in the
integer range <C>[2 .. PqPClass(<A>i</A>)]</C> (assuming <A>i</A> is the number of the
process, even in the default case) or for all weights if <C><A>weight</A> = 0</C>.


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


<E>Notes</E>


For its use in the context of finding the next class see <Ref Func="PqNextClass" Style="Text"/>;
in particular, a call to <C>PqSetupTablesForNextClass</C>
(see <Ref Func="PqSetupTablesForNextClass" Style="Text"/>) needs to have been made prior to
calling <C>PqTails</C>.


The single command: <C>PqTails(<A>i</A>, <A>weight</A>);</C> is equivalent to

<Listing><![CDATA[
PqComputeTails(i, weight);
PqAddTails(i, weight);
]]></Listing>

For those familiar with the <C>pq</C> program, <C>PqTails</C> uses menu item 7 of
the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqComputeTails" Arg="i, weight"/>
<Func Name="PqComputeTails" Arg="weight" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to compute tails of weight <A>weight</A> if <A>weight</A> is in the integer
range <C>[2 .. PqPClass(<A>i</A>)]</C> (assuming <A>i</A> is the number of the process,
even in the default case) or for all weights if <C><A>weight</A> = 0</C>. See
<C>PqTails</C> (<Ref Func="PqTails" Style="Text"/>) for more details.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqComputeTails</C> uses menu item
7 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqAddTails" Arg="i, weight"/>
<Func Name="PqAddTails" Arg="weight" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to add the tails of weight <A>weight</A>, previously computed by
<C>PqComputeTails</C> (see <Ref Func="PqComputeTails" Style="Text"/>), if <A>weight</A> is in the integer
range <C>[2 .. PqPClass(<A>i</A>)]</C> (assuming <A>i</A> is the number of the process,
even in the default case) or for all weights if <C><A>weight</A> = 0</C>. See
<C>PqTails</C> (<Ref Func="PqTails" Style="Text"/>) for more details.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqAddTails</C> uses menu item 7 of
the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqDoConsistencyChecks" Arg="i, weight, type"/>
<Func Name="PqDoConsistencyChecks" Arg="weight, type" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, do consistency
checks for weight <A>weight</A> if <A>weight</A> is in the integer range <C>[3 ..
PqPClass(<A>i</A>)]</C> (assuming <A>i</A> is the number of the process) or for all
weights if <C><A>weight</A> = 0</C>, and for type <A>type</A> if <A>type</A> is in the range
<C>[1, 2, 3]</C> (see below) or for all types if <C><A>type</A> = 0</C>. (For its use in
the context of finding the next class see <Ref Func="PqNextClass" Style="Text"/>.)


The <E>type</E> of a consistency check is defined as follows.
<C>PqDoConsistencyChecks(<A>i</A>, <A>weight</A>, <A>type</A>)</C> for <A>weight</A> in <C>[3 ..
PqPClass(<A>i</A>)]</C> and the given value of <A>type</A> invokes the equivalent of
the following <C>PqDoConsistencyCheck</C> calls (see <Ref Func="PqDoConsistencyCheck" Style="Text"/>):

<List>
<C><A>type</A> = 1</C>:
<Item>
<C>PqDoConsistencyCheck(<A>i</A>, <A>a</A>, <A>a</A>, <A>a</A>)</C> checks <C>2 * PqWeight(<A>i</A>, <A>a</A>)
+ 1 = <A>weight</A></C>, for pc generators of index <A>a</A>.
</Item>
<C><A>type</A> = 2</C>:
<Item>
<C>PqDoConsistencyCheck(<A>i</A>, <A>b</A>, <A>b</A>, <A>a</A>)</C> checks for pc generators of
indices <A>b</A>, <A>a</A> satisfyingx both <C><A>b</A> > <A>a</A></C> and <C>PqWeight(<A>i</A>, <A>b</A>) +
PqWeight(<A>i</A>, <A>a</A>) + 1 = <A>weight</A></C>.
</Item>
<C><A>type</A> = 3</C>:
<Item>
<C>PqDoConsistencyCheck(<A>i</A>, <A>c</A>, <A>b</A>, <A>a</A>)</C> checks for pc generators of
indices <A>c</A>, <A>b</A>, <A>a</A> satisfying <C><A>c</A> > <A>b</A> > <A>a</A></C> and the sum of the
weights of these generators equals <A>weight</A>.
</Item>
</List>

<E>Notes</E>


<C>PqWeight(<A>i</A>, <A>j</A>)</C> returns the weight of the <A>j</A>th pc generator, for
process <A>i</A> (see <Ref Func="PqWeight" Style="Text"/>).


It is assumed that tails for the given weight (or weights) have already
been added (see <Ref Func="PqTails" Style="Text"/>).


For those familiar with the <C>pq</C> program, <C>PqDoConsistencyChecks</C> performs
menu item 8 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqCollectDefiningRelations" Arg="i"/>
<Func Name="PqCollectDefiningRelations" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
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 <Ref Func="PqNextClass" Style="Text"/>). If the tails
operation is not complete then the relations may be evaluated
incorrectly.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqCollectDefiningRelations</C>
performs menu item 9 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqCollectWordInDefiningGenerators" Arg="i, word"/>
<Func Name="PqCollectWordInDefiningGenerators" Arg="word" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, take a
user-defined word <A>word</A> 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 <A>word</A> argument may be input in either of the two ways described for
<C>PqCollect</C> (see <Ref Func="PqCollect" Style="Text"/>).


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqCollectDefiningGenerators</C>
performs menu item 23 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqCommutatorDefiningGenerators" Arg="i, words, pow"/>
<Func Name="PqCommutatorDefiningGenerators" Arg="words, pow" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, take a list
<A>words</A> 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
<A>pow</A>. Each generator is mapped into the current pc presentation. The
list <A>words</A> is interpreted as a left-normed commutator which is then
raised to <A>pow</A> and collected with respect to the current pc
presentation. The result of the collection is returned as a list of
generator number, exponent pairs.


<E>Note</E>
For those familiar with the <C>pq</C> program, <C>PqCommutatorDefiningGenerators</C>
performs menu item 24 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqDoExponentChecks" Arg="i : [ Bounds := list ]"/>
<Func Name="PqDoExponentChecks" Arg=": [ Bounds := list ]" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to do exponent checks for weights (inclusively) between the bounds
of <C>Bounds</C> or for all weights if <C>Bounds</C> is not given. The value <A>list</A>
of <C>Bounds</C> (assuming the interactive process is numbered <A>i</A>) should be a
list of two integers <A>low</A>, <A>high</A> satisfying

<M>1 \le <A>low</A> \le <A>high</A> \le </M>
<C>PqPClass(<A>i</A>)</C> (see <Ref Func="PqPClass" Style="Text"/>). If no exponent law has been specified,
no exponent checks are performed.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqDoExponentChecks</C> performs
menu item 10 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqEliminateRedundantGenerators" Arg="i"/>
<Func Name="PqEliminateRedundantGenerators" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to eliminate redundant generators of the current <M>p</M>-quotient.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqEliminateRedundantGenerators</C>
performs menu item 11 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqRevertToPreviousClass" Arg="i"/>
<Func Name="PqRevertToPreviousClass" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to abandon the current class and revert to the previous class.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqRevertToPreviousClass</C>
performs menu item 12 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqSetMaximalOccurrences" Arg="i, noccur"/>
<Func Name="PqSetMaximalOccurrences" Arg="noccur" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
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 <A>noccur</A> must be a list of non-negative integers of length
the number of weight 1 generators (i.e. the rank of the class 1
<M>p</M>-quotient of the group of the process). An entry of <C>0</C> for a
particular generator indicates that there is no limit on the number of
occurrences for the generator.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqSetMaximalOccurrences</C>
performs menu item 13 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqSetMetabelian" Arg="i"/>
<Func Name="PqSetMetabelian" Arg="" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to enforce metabelian-ness.


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqSetMetabelian</C> performs
menu item 14 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
<Func Name="PqDoConsistencyCheck" Arg="i, c, b, a"/>
<Func Name="PqDoConsistencyCheck" Arg="c, b, a" Label="for default process"/>
<Func Name="PqJacobi" Arg="i, c, b, a"/>
<Func Name="PqJacobi" Arg="c, b, a" Label="for default process"/>
<Description>
for the <A>i</A>th or default interactive &ANUPQ; process, direct the <C>pq</C>
program to do the consistency check for the pc generators with indices
<A>c</A>, <A>b</A>, <A>a</A> which should be non-increasing positive integers, i.e. <M><A>c</A>
\ge <A>b</A> \ge <A>a</A></M>.


There are 3 types of consistency checks:
<Display>
\begin{array}{rclrl}
(a^n)a &=& a(a^n) && {\rm (Type\ 1)} \\
(b^n)a &=& b^{(n-1)}(ba), b(a^n) = (ba)a^{(n-1)} && {\rm (Type\ 2)} \\
c(ba) &=& (cb)a && {\rm (Type\ 3)} \\
\end{array}
</Display>
The reason some people talk about Jacobi relations instead of consistency
checks becomes clear when one looks at the consistency check of type 3:
<Display>
\begin{array}{rcl}
c(ba) &=& a c[c,a] b[b,a] = acb [c,a][c,a,b][b,a] = \dots \\
(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] = \dots \\
\end{array}
</Display>
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:
<Display>
\begin{array}{rcl}
& &abc [b,a] [c,a] [c,b] [c,a,b] \dots \\
&=&abc [b,a] [c,a] [c,b] [c,b,a] [b,a,c] \dots \\
\end{array}
</Display>
Modulo terms of weight 4 this is equivalent to
<Display>
[c,a,b] [b,c,a] [a,b,c] = 1
</Display>
which is the Jacobi identity.


See also <C>PqDoConsistencyChecks</C> (<Ref Func="PqDoConsistencyChecks" Style="Text"/>).


<E>Note:</E>
For those familiar with the <C>pq</C> program, <C>PqDoConsistencyCheck</C> and
<C>PqJacobi</C> perform menu item 15 of the Advanced <M>p</M>-Quotient menu.
</Description>
</ManSection>

<ManSection>
--> --------------------

--> maximum size reached

--> --------------------

quality97%

¤ Dauer der Verarbeitung: 0.37 Sekunden (vorverarbeitet) ¤

Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.

Bemerkung:

Die farbliche Syntaxdarstellung ist noch experimentell.