<html><head><title>[ANUPQ] 3 Infrastructure</title></head>
<body text="#000000" bgcolor="#ffffff">
[<a href = "chapters.htm">Up</a>] [<a href ="CHAP002.htm">Previous</a>] [<a href ="CHAP004.htm">Next</a>] [<a href = "theindex.htm">Index</a>]
<h1>3 Infrastructure</h1><p>
<P>
<H3>Sections</H3>
<oL>
<li> <A HREF="CHAP003.htm#SECT001">Loading the ANUPQ Package</a>
<li> <A HREF="CHAP003.htm#SECT002">The ANUPQData Record</a>
<li> <A HREF="CHAP003.htm#SECT003">Setting the Verbosity of ANUPQ via Info and InfoANUPQ</a>
<li> <A HREF="CHAP003.htm#SECT004">Utility Functions</a>
<li> <A HREF="CHAP003.htm#SECT005">Attributes and a Property for fp and pc p-groups</a>
<li> <A HREF="CHAP003.htm#SECT006">Hints and Warnings regarding the use of Options</a>
</ol><p>
<p>
Most of the details in this chapter are of a technical nature; the user
need only skim over this chapter on a first reading. Mostly, it is enough
to know that
<p>
<ul>
<p>
<li>
you must do a <code>LoadPackage("anupq");</code> before you can expect to use a
command defined by the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package (details are in Section <a href="CHAP003.htm#SECT001">Loading the ANUPQ Package</a>);
<p>
<li>
partial results of <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> commands and some other data are stored in
the <code>ANUPQData</code> global variable (details are in Section <a href="CHAP003.htm#SECT002">The ANUPQData Record</a>);
<p>
<li>
doing <code>SetInfoLevel(InfoANUPQ, </code><var>n</var><code>);</code> for <var>n</var> greater than the default
value 1 will give progressively more information of what is going on
``behind the scenes'' (details are in Section <a href="CHAP007.htm#SECT003">Setting the Verbosity of ANUPQ via Info and InfoANUPQ</a>);
<p>
<li>
in Section <a href="CHAP007.htm#SECT004">Utility functions</a> we describe some utility functions and
functions that run examples from the collection of examples of this
package;
<p>
<li>
in Section <a href="CHAP003.htm#SECT005">Attributes and a Property for fp and pc p-groups</a> we describe
the attributes and property <code>NuclearRank</code>, <code>MultiplicatorRank</code> and
<code>IsCapable</code>; and
<p>
<li>
in Section <a href="CHAP003.htm#SECT006">Hints and Warnings regarding the use of Options</a> we describe
some troubleshooting strategies. Also this section describes how setting
<code>ANUPQWarnOfOtherOptions := true;</code> may be useful (particularly for novice
users) for detecting misspelt options and diagnosing other option usage
problems.
<p>
</ul>
<p>
<p>
<h2><a name="SECT001">3.1 Loading the ANUPQ Package</a></h2>
<p><p>
<a name = "I0"></a>
To use the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package, as with any <font face="Gill Sans,Helvetica,Arial">GAP</font> package, it must be
requested explicitly. This is done by calling
<p>
<pre>
gap> LoadPackage( "anupq" );
-------------------------------------------------------------
Loading ANUPQ 3.0 (ANU p-Quotient package)
C code by Eamonn O'Brien <obrien@math.auckland.ac.nz>
(ANU pq binary version: 1.8)
GAP code by Werner Nickel <nickel@mathematik.tu-darmstadt.de>
and Greg Gamble <gregg@math.rwth-aachen.de>
For help, type: ?ANUPQ
-------------------------------------------------------------
true
</pre>
<p>
<a name = "I1"></a>
In version 2.2 of the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package there was an option <code>pkgbanner</code>
that allowed the user some control on how the banner above was displayed.
This only worked with <font face="Gill Sans,Helvetica,Arial">GAP</font> 4.3. Since, the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package now
requires at least <font face="Gill Sans,Helvetica,Arial">GAP</font> 4.4, this option has been removed. If you still
have <font face="Gill Sans,Helvetica,Arial">GAP</font> 4.3 (at least fix4), you will need to use <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> 2.2.
<p>
Note that since the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package uses the <code>AutomorphimGroupPGroup</code>
function of the <font face="Gill Sans,Helvetica,Arial">AutPGrp</font> package and, in any case, often needs other
<font face="Gill Sans,Helvetica,Arial">AutPGrp</font> functions when computing descendants, the user must ensure
that the <font face="Gill Sans,Helvetica,Arial">AutPGrp</font> package is also installed, at least version 1.2. If
the <font face="Gill Sans,Helvetica,Arial">AutPGrp</font> package is not installed, the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package will <code>fail</code>
to load.
<p>
Also, if <font face="Gill Sans,Helvetica,Arial">GAP</font> cannot find a working <code>pq</code> binary, the call to
<code>LoadPackage</code> will return <code>fail</code>.
<p>
If you want to load the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package by default, you can put the
<code>LoadPackage</code> command into your <code>.gaprc</code> file (see Section <a href="../../../doc/htm/ref/CHAP003.htm#SECT004">The .gaprc file</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual). By the way, the novice user
of the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package should probably also append the line
<p>
<pre>
ANUPQWarnOfOtherOptions := true;
</pre>
<p>
to their <code>.gaprc</code> file, somewhere after the <code>LoadPackage( "anupq" );</code>
command (see <a href="CHAP003.htm#SSEC006.1">ANUPQWarnOfOtherOptions</a>).
<p>
<p>
<h2><a name="SECT002">3.2 The ANUPQData Record</a></h2>
<p><p>
This section contains fairly technical details which may be skipped on an
initial reading.
<p>
<a name = "SSEC002.1"></a>
<li><code>ANUPQData V</code>
<p>
is a <font face="Gill Sans,Helvetica,Arial">GAP</font> record in which the essential data for an <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> session
within <font face="Gill Sans,Helvetica,Arial">GAP</font> is stored; its fields are:
<p>
<p>
<dl compact>
<p>
<dt> <code>binary</code> <dd> the path of the <code>pq</code> binary;
<p>
<dt> <code>tmpdir</code> <dd> the path of the temporary directory used by the <code>pq</code>
binary and <font face="Gill Sans,Helvetica,Arial">GAP</font> (i.e. the directory in which all the <code>pq</code>'s temporary
files are created) (also see <a href="CHAP003.htm#SSEC002.2">ANUPQDirectoryTemporary</a> below);
<p>
<dt> <code>outfile</code><dd> the full path of the default <code>pq</code> output file;
<p>
<dt> <code>SPimages</code><dd> the full path of the file <code>GAP_library</code> to which the
<code>pq</code> program writes its Standard Presentation images;
<p>
<dt> <code>version</code><dd> the version of the current <code>pq</code> binary;
<p>
<dt> <code>ni</code> <dd> a data record used by non-interactive functions (see below
and Chapter <a href="CHAP004.htm">Non-interactive ANUPQ Functions</a>);
<p>
<dt> <code>io</code> <dd> list of data records for <code>PqStart</code> (see below and <a href="CHAP005.htm#SSEC001.1">PqStart</a>)
processes;
<p>
<dt> <code>topqlogfile</code> <dd> name of file logged to by <code>ToPQLog</code> (see <a href="CHAP003.htm#SSEC004.7">ToPQLog</a>);
and
<p>
<dt> <code>logstream</code> <dd> stream of file logged to by <code>ToPQLog</code> (see <a href="CHAP003.htm#SSEC004.7">ToPQLog</a>).
<p>
</dl>
<p>
Each time an interactive <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> process is initiated via <code>PqStart</code>
(see <a href="CHAP005.htm#SSEC001.1">PqStart</a>), an identifying number <var>ioIndex</var> is generated for the
interactive process and a record <code>ANUPQData.io[</code><var>ioIndex</var><code>]</code> with some or
all of the fields listed below is created. Whenever a non-interactive
function is called (see Chapter <a href="CHAP004.htm">Non-interactive ANUPQ Functions</a>), the
record <code>ANUPQData.ni</code> is updated with fields that, if bound, have exactly
the same purpose as for a <code>ANUPQData.io[</code><var>ioIndex</var><code>]</code> record.
<p>
<p>
<dl compact>
<p>
<dt> <code>stream</code><dd> the IOStream opened for interactive <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> process
<var>ioIndex</var> or non-interactive <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> function;
<p>
<dt> <code>group</code><dd> the group given as first argument to <code>PqStart</code>, <code>Pq</code>,
<code>PqEpimorphism</code>, <code>PqDescendants</code> or <code>PqStandardPresentation</code> (or any
synonymous methods);
<p>
<dt> <code>haspcp</code><dd> is bound and set to <code>true</code> when a pc presentation is first
set inside the <code>pq</code> program (e.g. by <code>PqPcPresentation</code> or
<code>PqRestorePcPresentation</code> or a higher order function like <code>Pq</code>,
<code>PqEpimorphism</code>, <code>PqPCover</code>, <code>PqDescendants</code> or <code>PqStandardPresentation</code>
that does a <code>PqPcPresentation</code> operation, but <strong>not</strong> <code>PqStart</code> which only
starts up an interactive <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> process);
<p>
<dt> <code>gens</code><dd> a list of the generators of the group <code>group</code> as strings
(the same as those passed to the <code>pq</code> program);
<p>
<dt> <code>rels</code><dd> a list of the relators of the group <code>group</code> as strings (the
same as those passed to the <code>pq</code> program);
<p>
<dt> <code>name</code><dd> the name of the group whose pc presentation is defined by a
call to the <code>pq</code> program (according to the <code>pq</code> program -- unless you
have used the <code>GroupName</code> option (see e.g. <a href="CHAP004.htm#SSEC001.1">Pq</a>) or applied the function
<code>SetName</code> (see <a href="../../../doc/htm/ref/CHAP012.htm#SSEC008.1">SetName</a>) to the group, the ``generic'' name
<code>"[grp]"</code> is set as a default);
<p>
<dt> <code>gpnum</code><dd> if not a null string, the ``number'' (i.e. the unique label
assigned by the <code>pq</code> program) of the last descendant processed;
<p>
<dt> <code>class</code><dd> the largest lower exponent-<i>p</i> central class of a quotient
group of the group (usually <code>group</code>) found by a call to the <code>pq</code> program;
<p>
<dt> <code>forder</code><dd> the factored order of the quotient group of largest lower
exponent-<i>p</i> central class found for the group (usually <code>group</code>) by a
call to the <code>pq</code> program (this factored order is given as a list <code>[<i>p</i>,
<i>n</i>]</code>, indicating an order of <i>p</i><sup><i>n</i></sup>);
<p>
<dt> <code>pcoverclass</code><dd> the lower exponent-<i>p</i> central class of the
<i>p</i>-covering group of a <i>p</i>-quotient of the group (usually <code>group</code>) found
by a call to the <code>pq</code> program;
<p>
<dt> <code>workspace</code><dd> the workspace set for the <code>pq</code> process (either given as
a second argument to <code>PqStart</code>, or set by default to 10000000);
<p>
<dt> <code>menu</code><dd> the current menu of the <code>pq</code> process (the <code>pq</code> program is
managed by various menus, the details of which the user shouldn't
normally need to know about -- the <code>menu</code> field remembers which menu the
<code>pq</code> process is currently ``in'');
<p>
<dt> <code>outfname</code> <dd> is the file to which <code>pq</code> output is directed, which is
always <code>ANUPQData.outfile</code>, except when option <code>SetupFile</code> is used with a
non-interactive function, in which case <code>outfname</code> is set to
<code>"PQ_OUTPUT"</code>;
<p>
<dt> <code>pQuotient</code> <dd> is set to the value returned by <code>Pq</code> (see <a href="CHAP004.htm#SSEC001.1">Pq</a>) (the
field <code>pQepi</code> is also set at the same time);
<p>
<dt> <code>pQepi</code> <dd> is set to the value returned by <code>PqEpimorphism</code>
(see <a href="CHAP004.htm#SSEC001.2">PqEpimorphism</a>) (the field <code>pQuotient</code> is also set at the same
time);
<p>
<dt> <code>pCover</code> <dd> is set to the value returned by <code>PqPCover</code>
(see <a href="CHAP004.htm#SSEC001.3">PqPCover</a>);
<p>
<dt> <code>SP</code> <dd> is set to the value returned by <code>PqStandardPresentation</code> or
<code>StandardPresentation</code> (see <a href="CHAP005.htm#SSEC003.4">PqStandardPresentation!interactive</a>) when
called interactively, for process <var>i</var> (the field <code>SPepi</code> is also set at
the same time);
<p>
<dt> <code>SPepi</code> <dd> is set to the value returned by
<code>EpimorphismPqStandardPresentation</code> or <code>EpimorphismStandardPresentation</code>
(see <a href="CHAP005.htm#SSEC003.5">EpimorphismPqStandardPresentation!interactive</a>) when called
interactively, for process <var>i</var> (the field <code>SP</code> is also set at the same
time);
<p>
<dt> <code>descendants</code> <dd> is set to the value returned by
<code>PqDescendants</code> (see <a href="CHAP004.htm#SSEC004.1">PqDescendants</a>);
<p>
<dt> <code>treepos</code> <dd> if set by a call to <code>PqDescendantsTreeCoclassOne</code>
(see <a href="CHAP00A.htm#SSEC004.1">PqDescendantsTreeCoclassOne</a>), it contains a record with fields
<code>class</code>, <code>node</code> and <code>ndes</code> being the information that determines the last
descendant with a non-zero number of descendants processed;
<p>
<dt> <code>xgapsheet</code> <dd> if set by a call to <code>PqDescendantsTreeCoclassOne</code>
(see <a href="CHAP00A.htm#SSEC004.1">PqDescendantsTreeCoclassOne</a>) during an <font face="Gill Sans,Helvetica,Arial">XGAP</font> session, it
contains the <font face="Gill Sans,Helvetica,Arial">XGAP</font> <code>Sheet</code> on which the descendants tree is displayed;
and
<p>
<dt> <code>nextX</code> <dd> if set by a call to <code>PqDescendantsTreeCoclassOne</code>
(see <a href="CHAP00A.htm#SSEC004.1">PqDescendantsTreeCoclassOne</a>) during an <font face="Gill Sans,Helvetica,Arial">XGAP</font> session, it
contains a list of integers, the <var>i</var>th entry of which is the
<var>x</var>-coordinate of the next node (representing a descendant) for the <var>i</var>th
class.
<p>
</dl>
<p>
<a name = "SSEC002.2"></a>
<li><code>ANUPQDirectoryTemporary( </code><var>dir</var><code> ) F</code>
<p>
calls the UNIX command <code>mkdir</code> to create <var>dir</var>, which must be a string,
and if successful a directory object for <var>dir</var> is both assigned to
<code>ANUPQData.tmpdir</code> and returned. The field <code>ANUPQData.outfile</code> is also
set to be a file in <code>ANUPQData.tmpdir</code>, and on exit from <font face="Gill Sans,Helvetica,Arial">GAP</font> <var>dir</var> is
removed. Most users will never need this command; by default, <font face="Gill Sans,Helvetica,Arial">GAP</font>
typically chooses a ``random'' subdirectory of <code>/tmp</code> for
<code>ANUPQData.tmpdir</code> which may occasionally have limits on what may be
written there. <code>ANUPQDirectoryTemporary</code> permits the user to choose a
directory (object) where one is not so limited.
<p>
<p>
<h2><a name="SECT003">3.3 Setting the Verbosity of ANUPQ via Info and InfoANUPQ</a></h2>
<p><p>
<li><code>InfoANUPQ V</code>
<p>
The input to and the output from the <code>pq</code> program is, by default, not
displayed. However the user may choose to see some, or all, of this
input/output. This is done via the <code>Info</code> mechanism (see
Chapter <a href="../../../doc/htm/ref/CHAP007.htm#SECT004">Info Functions</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual). For this
purpose, there is the <var>InfoClass</var> <code>InfoANUPQ</code>. If the <code>InfoLevel</code> of
<code>InfoANUPQ</code> is high enough each line of <code>pq</code> input/output is directed to
a call to <code>Info</code> and will be displayed for the user to see. By default,
the <code>InfoLevel</code> of <code>InfoANUPQ</code> is 1, and it is recommended that you leave
it at this level, or higher. Messages that the user should presumably
want to see and output from the <code>pq</code> program influenced by the value of
the option <code>OutputLevel</code> (see the options listed in Section <a href="CHAP004.htm#SSEC001.1">Pq</a>), other
than timing and memory usage are directed to <code>Info</code> at <code>InfoANUPQ</code> level
1.
<p>
To turn off <strong>all</strong> <code>InfoANUPQ</code> messaging, set the <code>InfoANUPQ</code> level to 0.
<p>
There are five other user-intended <code>InfoANUPQ</code> levels: 2, 3, 4, 5 and 6.
<p>
<pre>
gap> SetInfoLevel(InfoANUPQ, 2);
</pre>
<p>
enables the display of most timing and memory usage data from the <code>pq</code>
program, and also the number of identity instances when the <code>Identities</code>
option is used. (Some timing and memory usage data, particularly when
profuse in quantity, is <code>Info</code>-ed at <code>InfoANUPQ</code> level 3 instead.) Note
that the the <font face="Gill Sans,Helvetica,Arial">GAP</font> functions <code>time</code> and <code>Runtime</code> (see <a href="../../../doc/htm/ref/CHAP007.htm#SSEC006.2">Runtime</a> in
the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual) count the time spent by <font face="Gill Sans,Helvetica,Arial">GAP</font> and <strong>not</strong> the
time spent by the (external) <code>pq</code> program.
<p>
<pre>
gap> SetInfoLevel(InfoANUPQ, 3);
</pre>
<p>
enables the display of output of the nature of the first two <code>InfoANUPQ</code>
that was not directly invoked by the user (e.g. some commands require
<font face="Gill Sans,Helvetica,Arial">GAP</font> to discover something about the current state known to the <code>pq</code>
program). The identity instances processed under the <code>Identities</code> option
are also displayed at this level. In some cases, the <code>pq</code> program
produces a lot of output despite the fact that the <code>OutputLevel</code>
(see <a href="CHAP006.htm#SSEC001.9">option OutputLevel</a>) is unset or is set to 0; such output is also
<code>Info</code>-ed at <code>InfoANUPQ</code> level 3.
<p>
<pre>
gap> SetInfoLevel(InfoANUPQ, 4);
</pre>
<p>
enables the display of all the commands directed to the <code>pq</code> program,
behind a ``<code>ToPQ> </code>'' prompt (so that you can distinguish it from the
output from the <code>pq</code> program). See Section <a href="CHAP003.htm#SECT006">Hints and Warnings regarding the use of Options</a> for an example of how this can be a useful
troubleshooting tool.
<p>
<pre>
gap> SetInfoLevel(InfoANUPQ, 5);
</pre>
<p>
enables the display of the <code>pq</code> program's prompts for input. Finally,
<p>
<pre>
gap> SetInfoLevel(InfoANUPQ, 6);
</pre>
<p>
enables the display of all other output from the <code>pq</code> program, namely the
banner and menus. However, the timing data printed when the <code>pq</code> program
exits can never be observed.
<p>
<p>
<h2><a name="SECT004">3.4 Utility Functions</a></h2>
<p><p>
<li><code>PqLeftNormComm( </code><var>elts</var><code> ) F</code>
<p>
returns for a list of elements of some group (e.g. <var>elts</var> may be a list
of words in the generators of a free or fp group) the left normed
commutator of <var>elts</var>, e.g. if <var>w1</var>, <var>w2</var>, <var>w3</var> are such elements then
<code>PqLeftNormComm( [</code><var>w1</var><code>, </code><var>w2</var><code>, </code><var>w3</var><code>] );</code> is equivalent to <code>Comm( Comm(
</code><var>w1</var><code>, </code><var>w2</var><code> ), </code><var>w3</var><code> );</code>.
<p>
<strong>Note:</strong> <var>elts</var> must contain at least two elements.
<p>
<li><code>PqGAPRelators( </code><var>group</var><code>, </code><var>rels</var><code> ) F</code>
<p>
returns a list of words that <font face="Gill Sans,Helvetica,Arial">GAP</font> understands, given a list <var>rels</var> of
strings in the string representations of the generators of the fp group
<var>group</var> prepared as a list of relators for the <code>pq</code> program.
<p>
<strong>Note:</strong>
The <code>pq</code> program does not use <code>/</code> to indicate multiplication by an
inverse and uses square brackets to represent (left normed) commutators.
Also, even though the <code>pq</code> program accepts relations, all elements of
<var>rels</var> <strong>must</strong> be in relator form, i.e. a relation of form <code></code><var>w1</var><code> = </code><var>w2</var><code></code>
must be written as <code></code><var>w1</var><code>*(</code><var>w2</var><code>)^-1</code>.
<p>
Here is an example:
<p>
<pre>
gap> F := FreeGroup("a", "b");
<free group on the generators [ a, b ]>
gap> PqGAPRelators(F, [ "a*b^2", "[a,b]^2*a", "([a,b,a,b,b]*a*b)^2*a" ]);
[ a*b^2, a^-1*b^-1*a*b*a^-1*b^-1*a*b*a, b^-1*a^-1*b^-1*a^-1*b*a*b^-1*a*b*a^
-1*b*a^-1*b^-1*a*b*a*b^-1*a^-1*b^-1*a^-1*b*a*b^-1*a*b^-1*a^-1*b*a^-1*b^
-1*a*b*a*b*a^-1*b*a*b^-1*a*b*a^-1*b*a^-1*b^-1*a*b*a*b^-1*a^-1*b^-1*a^
-1*b*a*b^-1*a*b^-1*a^-1*b*a^-1*b^-1*a*b*a*b^2*a*b*a ]
</pre>
<p>
<a name = "SSEC004.3"></a>
<li><code>PqParseWord( </code><var>word</var><code>, </code><var>n</var><code> ) F</code>
<p>
parses a <var>word</var>, a string representing a word in the pc generators
<code>x1,...,x</code><var>n</var><code></code>, through <font face="Gill Sans,Helvetica,Arial">GAP</font>. This function is provided as a
rough-and-ready check of <var>word</var> for syntax errors. A syntax error will
cause the entering of a <code>break</code>-loop, in which the error message may or
may not be meaningful (depending on whether the syntax error gets caught
at the <font face="Gill Sans,Helvetica,Arial">GAP</font> or kernel level).
<p>
<strong>Note:</strong>
The reason the generators <strong>must</strong> be <code>x1,...,x</code><var>n</var><code></code> is that these are the
pc generator names used by the <code>pq</code> program (as distinct from the
generator names for the group provided by the user to a function like
<code>Pq</code> that invokes the <code>pq</code> program).
<p>
<a name = "SSEC004.4"></a>
<li><code>PqExample() F</code>
<li><code>PqExample( </code><var>example</var><code>[, PqStart][, Display] ) F</code>
<li><code>PqExample( </code><var>example</var><code>[, PqStart][, </code><var>filename</var><code>] ) F</code>
<p>
With no arguments, or with single argument <code>"index"</code>, or a string
<var>example</var> that is not the name of a file in the <code>examples</code> directory, an
index of available examples is displayed.
<p>
With just the one argument <var>example</var> that is the name of a file in the
<code>examples</code> directory, the example contained in that file is executed in
its simplest form. Some examples accept options which you may use to
modify some of the options used in the commands of the example. To find
out which options an example accepts, use one of the mechanisms for
displaying the example described below.
<p>
Some examples have both non-interactive and interactive forms; those that
are non-interactive only have a name ending in <code>-ni</code>; those that are
interactive only have a name ending in <code>-i</code>; examples with names ending
in <code>.g</code> also have only one form; all other examples have both
non-interactive and interactive forms and for these giving <code>PqStart</code> as
second argument invokes <code>PqStart</code> initially and makes the appropriate
adjustments so that the example is executed or displayed using
interactive functions.
<p>
If <code>PqExample</code> is called with last (second or third) argument <code>Display</code>
then the example is displayed without being executed. If the last
argument is a non-empty string <var>filename</var> then the example is also
displayed without being executed but is also written to a file with that
name. Passing an empty string as last argument has the same effect as
passing <code>Display</code>.
<p>
<strong>Note:</strong>
The variables used in <code>PqExample</code> are local to the running of
<code>PqExample</code>, so there's no danger of having some of your variables
over-written. However, they are not completely lost either. They are
saved to a record <code>ANUPQData.examples.vars</code>, i.e. if <code>F</code> is a variable
used in the example then you will be able to access it after <code>PqExample</code>
has finished as <code>ANUPQData.examples.vars.F</code>.
<p>
<a name = "SSEC004.5"></a>
<li><code>AllPqExamples() F</code>
<p>
returns a list of all currently available examples in default
UNIX-listing (i.e. alphabetic) order.
<p>
<a name = "SSEC004.6"></a>
<li><code>GrepPqExamples( </code><var>string</var><code> ) F</code>
<p>
runs the UNIX command <code>grep </code><var>string</var><code></code> over the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> examples and
returns the list of examples for which there is a match. The actual
matches are <code>Info</code>-ed at <code>InfoANUPQ</code> level 2.
<p>
<a name = "SSEC004.7"></a>
<li><code>ToPQLog([ </code><var>filename</var><code> ]) F</code>
<p>
With string argument <var>filename</var>, <code>ToPQLog</code> opens the file with name
<var>filename</var> for logging; all commands written to the <code>pq</code> binary (that are
<code>Info</code>-ed behind a ``<code>ToPQ> </code>'' prompt at <code>InfoANUPQ</code> level 4) are then
also written to that file (but without prompts). With no argument,
<code>ToPQLog</code> stops logging to whatever file was being logged to. If a file
was already being logged to, that file is closed and the file with name
<var>filename</var> is opened for logging.
<p>
<p>
<h2><a name="SECT005">3.5 Attributes and a Property for fp and pc p-groups</a></h2>
<p><p>
<a name = "SSEC005.1"></a>
<li><code>NuclearRank( </code><var>G</var><code> ) A</code>
<a name = "SSEC005.1"></a>
<li><code>MultiplicatorRank( </code><var>G</var><code> ) A</code>
<a name = "SSEC005.1"></a>
<li><code>IsCapable( </code><var>G</var><code> ) P</code>
<p>
return the nuclear rank of <var>G</var>, <i>p</i>-multiplicator rank of <var>G</var>, and
whether <var>G</var> is capable (i.e. <code>true</code> if it is, or <code>false</code> if it is not),
respectively.
<p>
These attributes and property are set automatically if <var>G</var> is one of the
following:
<p>
<ul>
<p>
<li> an fp group returned by <code>PqStandardPresentation</code> or
<code>StandardPresentation</code> (see <a href="CHAP004.htm#SSEC002.1">PqStandardPresentation</a>);
<p>
<li> the image (fp group) of the epimorphism returned by an
<code>EpimorphismPqStandardPresentation</code> or <code>EpimorphismStandardPresentation</code>
call (see <a href="CHAP004.htm#SSEC002.2">EpimorphismPqStandardPresentation</a>); or
<p>
<li> one of the pc groups of the list of descendants returned by
<code>PqDescendants</code> (see <a href="CHAP004.htm#SSEC004.1">PqDescendants</a>).
<p>
</ul>
<p>
If <var>G</var> is an fp group or a pc <i>p</i>-group and not one of the above and the
attribute or property has not otherwise been set for <var>G</var>, then
<code>PqStandardPresentation</code> is called to set all three of <code>NuclearRank</code>,
<code>MultiplicatorRank</code> and <code>IsCapable</code>, before returning the value of the
attribute or property actually called. Such a group <var>G</var> must know in
advance that it is a <i>p</i>-group; this is the case for the groups returned
by the functions <code>Pq</code> and <code>PqPCover</code>, and the image group of the
epimorphism returned by <code>PqEpimorphism</code>. Otherwise, if you know the group
to be a <i>p</i>-group, then this can be set by typing
<p>
<code>SetFeatureObj( </code><var>G</var><code>, IsPGroup, true );</code>
<p>
or by invoking <code>IsPGroup( </code><var>G</var><code> )</code>. Note that for an fp group <var>G</var>, the
latter may result in a coset enumeration which might not terminate in a
reasonable time.
<p>
<strong>Note:</strong> For <var>G</var> such that <code>HasNuclearRank(</code><var>G</var><code>) = true</code>, <code>IsCapable(</code><var>G</var><code>)</code>
is equivalent to (the truth or falsity of) <code>NuclearRank( </code><var>G</var><code> ) = 0</code>.
<p>
<p>
<h2><a name="SECT006">3.6 Hints and Warnings regarding the use of Options</a></h2>
<p><p>
On a first reading we recommend you skip this section and come back to it
if and when you run into trouble.
<p>
<a name = "I2"></a>
<a name = "I3"></a>
<strong>Note:</strong>
By ``options'' we refer to <font face="Gill Sans,Helvetica,Arial">GAP</font> options. The <code>pq</code> program also uses the
term ``option''; to distinguish the two usages of ``option'', in this
manual we use the term <strong>menu item</strong> to refer to what the <code>pq</code> program
refers to as an ``option''.
<p>
Options are passed to the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> interface functions in either of the
two usual mechanisms provided by <font face="Gill Sans,Helvetica,Arial">GAP</font>, namely:
<p>
<ul>
<p>
<li> options may be set globally using the function <code>PushOptions</code>
(see Chapter <a href="../../../doc/htm/ref/CHAP008.htm">Options Stack</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual); or
<p>
<li> options may be appended to the argument list of any function
call, separated by a colon from the argument list (see
Chapter <a href="../../../doc/htm/ref/CHAP004.htm#SECT010">Function Calls</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual), in which
case they are then passed on recursively to any subsequent inner function
call, which may in turn have options of their own.
<p>
</ul>
<p>
Particularly, when one is using the interactive functions of
Chapter <a href="CHAP005.htm">Interactive ANUPQ Functions</a>, one should, in general, avoid
using the global method of passing options. In fact, it is recommended
that prior to calling <code>PqStart</code> the <code>OptionsStack</code> be empty. The
essential problem with setting options globally using the function
<code>PushOptions</code> is that options pushed onto <code>OptionsStack</code>, in this way,
(generally) remain there until an explicit <code>PopOptions()</code> call is made.
<p>
In contrast, options passed in the usual way behind a colon following a
function's arguments (see <a href="../../../doc/htm/ref/CHAP004.htm#SECT010">Function Calls</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference
Manual) are local, and disappear from <code>OptionsStack</code> after the function
has executed successfully. If the function does <strong>not</strong> execute
successfully, i.e. it runs into error and the user <code>quit</code>s the resulting
<code>break</code> loop (see Section <a href="../../../doc/htm/ref/CHAP006.htm#SECT003">Break loops</a> in the Reference Manual)
rather than attempting to repair the problem and typing <code>return;</code> then
(since version <font face="Gill Sans,Helvetica,Arial">GAP</font> 4.3), unless the error at the kernel level, the
<code>OptionsStack</code> is reset. If an error is detected inside the kernel
(hopefully, this should occur only rarely, if at all) then the options of
that function will <strong>not</strong> be cleared from <code>OptionsStack</code>; in such cases:
<p>
<pre>
gap> ResetOptionsStack();
#I Options stack is already empty
</pre>
<p>
is usually necessary (see Chapter <a href="../../../doc/htm/ref/CHAP008.htm">ResetOptionsStack</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font>
Reference Manual), which recursively calls <code>PopOptions()</code> until
<code>OptionsStack</code> is empty, or as in the above case warns you that the
<code>OptionsStack</code> is already empty.
<p>
Note that a function, that is passed options after the colon, will also
see any global options or any options passed down recursively from
functions calling that function, unless those options are over-ridden by
options passed via the function. Also, note that duplication of option
names for different programs may lead to misinterpretations, and
mis-spelled options will not be ``seen''.
<p>
The non-interactive functions of Chapter <a href="CHAP004.htm">Non-interactive ANUPQ Functions</a> that have <code>Pq</code> somewhere in their name provide an alternative
method of passing options as additional arguments. This has the
advantages that options can be abbreviated and mis-spelled options will
be trapped.
<p>
<a name = "I4"></a>
<a name = "SSEC006.1"></a>
<li><code>ANUPQWarnOfOtherOptions V</code>
<p>
is a global variable that is by default <code>false</code>. If it is set to <code>true</code>
then any function provided by the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> function that recognises at
least one option, will warn you of ``other'' options, i.e. options that
the function does not recognise. These warnings are emitted at
<code>InfoWarning</code> or <code>InfoANUPQ</code> level 1. This is useful for detecting
mis-spelled options. Here is an example using the function <code>Pq</code> (first
described in Chapter <a href="CHAP004.htm">Non-interactive ANUPQ functions</a>):
<p>
<pre>
gap> SetInfoLevel(InfoANUPQ, 1); # Set InfoANUPQ to default level
gap> ANUPQWarnOfOtherOptions := true;;
gap> # The following makes entry into break loops very ``quiet'' ...
gap> OnBreak := function() Where(0); end;;
gap> F := FreeGroup( "a", "b" );
<free group on the generators [ a, b ]>
gap> Pq( F : Prime := 2, Classbound := 1 );
#I ANUPQ Warning: Options: [ "Classbound" ] ignored
#I (invalid for generic function: `Pq').
user interrupt at
moreOfline := ReadLine( iostream );
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
</pre>
<p>
Here we mistyped <code>ClassBound</code> as <code>Classbound</code>, and after seeing the
<code>Info</code>-ed warning that <code>Classbound</code> was ignored, we typed a <var>control</var>-C
(that's the ``<code>user interrupt at</code>'' message) which took us into a break
loop. Since the <code>Pq</code> command was not able to finish, the options <code>Prime</code>
and <code>Classbound</code>, in particular, will still be on the <code>OptionsStack</code>:
<p>
<pre>
brk> OptionsStack;
[ rec( Prime := 2, Classbound := 1 ),
rec( Prime := 2, Classbound := 1, PqEpiOrPCover := "pQuotient" ) ]
</pre>
<p>
The option <code>PqEpiOrPCover</code> is a behind-the-scenes option that need not
concern the user. Since <font face="Gill Sans,Helvetica,Arial">GAP</font> 4.3, on <code>quit</code>ting the <code>break</code>-loop the
<code>OptionsStack</code> is reset and a warning telling you this is emitted:
<p>
<pre>
brk> quit; # to get back to the `gap>' prompt
#I Options stack has been reset
</pre>
<p>
Above, we altered <code>OnBreak</code> (see <a href="../../../doc/htm/ref/CHAP006.htm#SSEC003.3">OnBreak</a> in the Reference manual)
to reduce the back-tracing on entry into a break loop. We now restore
<code>OnBreak</code> to its usual value.
<p>
<pre>
gap> OnBreak := Where;;
</pre>
<p>
<strong>Notes</strong>
<p>
In cases where functions recursively call others with options (e.g. when
using <code>PqExample</code> with options), setting <code>ANUPQWarnOfOtherOptions :=
true</code> may give rise to spurious ``other'' option detections.
<p>
It is recommended that the novice user set <code>ANUPQWarnOfOtherOptions</code> to
<code>true</code> in their <code>.gaprc</code> file (see Section <a href="CHAP003.htm#SECT001">Loading the ANUPQ Package</a>).
<p>
<strong>Other Troubleshooting Strategies</strong>
<p>
There are some other strategies which may have helped us to see our error
above. The function <code>Pq</code> recognises the option <code>OutputLevel</code> (see <a href="CHAP006.htm#SSEC001.9">option OutputLevel</a>); if this option is set to at least 1, the <code>pq</code> program
provides information on each class quotient as it is generated:
<p>
<pre>
gap> ANUPQWarnOfOtherOptions := false;; # Set back to normal
gap> F := FreeGroup( "a", "b" );;
gap> Pq( F : Prime := 2, Classbound := 1, 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^10
#I Group: [grp] to lower exponent-2 central class 4 has order 2^18
#I Group: [grp] to lower exponent-2 central class 5 has order 2^32
#I Group: [grp] to lower exponent-2 central class 6 has order 2^55
#I Group: [grp] to lower exponent-2 central class 7 has order 2^96
#I Group: [grp] to lower exponent-2 central class 8 has order 2^167
#I Group: [grp] to lower exponent-2 central class 9 has order 2^294
#I Group: [grp] to lower exponent-2 central class 10 has order 2^520
#I Group: [grp] to lower exponent-2 central class 11 has order 2^932
#I Group: [grp] to lower exponent-2 central class 12 has order 2^1679
[... output truncated ...]
</pre>
<p>
After seeing the information for the class 2 quotient we may have got the
idea that the <code>Classbound</code> option was not recognised and may have
realised that this was due to a mis-spelling. The above will ordinarily
cause the available space to be exhausted, necessitating
user-intervention by typing <var>control</var>-C and <code>quit;</code> (to escape the break
loop); otherwise <code>Pq</code> terminates when the class reaches 63 (the default
value of <code>ClassBound</code>).
<p>
If you have some familiarity with ``keyword'' command input to the <code>pq</code>
binary, then setting the level of <code>InfoANUPQ</code> to 4 would also have
indicated a problem:
<p>
<pre>
gap> ResetOptionsStack(); # Necessary, if a break-loop was entered above
gap> SetInfoLevel(InfoANUPQ, 4);
gap> Pq( F : Prime := 2, Classbound := 1 );
#I ToPQ> 7 #to (Main) p-Quotient Menu
#I ToPQ> 1 #define group
#I ToPQ> name [grp]
#I ToPQ> prime 2
#I ToPQ> class 63
#I ToPQ> exponent 0
#I ToPQ> output 0
#I ToPQ> generators { a,b }
#I ToPQ> relators { };
[... output truncated ...]
</pre>
<p>
Here the line ``<code>#I ToPQ> class 63</code>'' indicates that a directive to set
the classbound to 63 was sent to the <code>pq</code> program.
<p>
<p>
[<a href = "chapters.htm">Up</a>] [<a href ="CHAP002.htm">Previous</a>] [<a href ="CHAP004.htm">Next</a>] [<a href = "theindex.htm">Index</a>]
<P>
<address>ANUPQ manual<br>Januar 2006
</address></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
5e1854624d3bc613bdd0dd13d1ef9ac7
>
files
>
743
