GAP 4.8.9 installation with standard packages -- copy to your CoCalc project to get it
<Chapter Label="Infrastructure">1<Heading>Infrastructure</Heading>23Most of the details in this chapter are of a technical nature; the user4need only skim over this chapter on a first reading. Mostly, it is enough5to know that6<List>7<Item>8you must do a <C>LoadPackage("anupq");</C> before you can expect to use a9command defined by the &ANUPQ; package10(details are in Section <Ref Sect="Loading the ANUPQ Package" Style="Text"/>);11</Item>1213<Item>14partial results of &ANUPQ; commands and some other data are stored in15the <C>ANUPQData</C> global variable16(details are in Section <Ref Sect="The ANUPQData Record" Style="Text"/>);17</Item>1819<Item>20doing <C>SetInfoLevel(InfoANUPQ, <A>n</A>);</C> for <A>n</A> greater than the default21value 1 will give progressively more information of what is going on22<Q>behind the scenes</Q> (details are in23Section <Ref Sect="Setting the Verbosity of ANUPQ via Info and InfoANUPQ" Style="Text"/>);24</Item>2526<Item>27in Section <Ref Sect="Utility-Functions" Style="Text"/> we describe some utility functions and28functions that run examples from the collection of examples of this29package;30</Item>3132<Item>33in Section <Ref Sect="Attributes and a Property for fp and pc p-groups" Style="Text"/> we describe34the attributes and property <C>NuclearRank</C>, <C>MultiplicatorRank</C> and35<C>IsCapable</C>; and36</Item>3738<Item>39in Section <Ref Sect="Hints and Warnings regarding the use of Options" Style="Text"/> we describe40some troubleshooting strategies. Also this section explains the utility41of setting <C>ANUPQWarnOfOtherOptions := true;</C> (particularly for novice42users) for detecting misspelt options and diagnosing other option usage43problems.44</Item>45</List>4647<Section Label="Loading the ANUPQ Package">48<Heading>Loading the ANUPQ Package</Heading>4950<Index>banner</Index>51To use the &ANUPQ; package, as with any &GAP; package, it must be52requested explicitly. This is done by calling5354<Example><![CDATA[55gap> LoadPackage( "anupq" );56---------------------------------------------------------------------------57Loading ANUPQ (ANU p-Quotient) 3.158GAP code by Greg Gamble <[email protected]> (address for59correspondence)60Werner Nickel (http://www.mathematik.tu-darmstadt.de/~nickel/)61[uses ANU pq binary (C code program) version: 1.9]62C code by Eamonn O'Brien (http://www.math.auckland.ac.nz/~obrien)63Co-maintained by Max Horn <[email protected]>6465For help, type: ?ANUPQ66---------------------------------------------------------------------------67true68]]></Example>6970Note that since the &ANUPQ; package uses the <C>AutomorphimGroupPGroup</C>71function of the &AutPGrp; package and, in any case, often needs other72&AutPGrp; functions when computing descendants, the user must ensure73that the &AutPGrp; package is also installed, at least version 1.5. If74the &AutPGrp; package is not installed, the &ANUPQ; package will <K>fail</K>75to load.76<P/>7778Also, if &GAP; cannot find a working <C>pq</C> binary, the call to79<C>LoadPackage</C> will return <K>fail</K>.80<P/>8182If you want to load the &ANUPQ; package by default, you can put the83<C>LoadPackage</C> command into your <C>gap.ini</C> file (see84Section <Ref BookName="ref" Label="The gap.ini and gaprc files" Style="Text"/>85in the &GAP; Reference Manual). By the way, the novice user86of the &ANUPQ; package should probably also append the line8788<Log><![CDATA[89ANUPQWarnOfOtherOptions := true;90]]></Log>9192to their <C>gap.ini</C> file, somewhere after the <C>LoadPackage( "anupq" );</C>93command (see <Ref Func="ANUPQWarnOfOtherOptions" Style="Text"/>).9495</Section>96979899<Section Label="The ANUPQData Record">100<Heading>The ANUPQData Record</Heading>101102This section contains fairly technical details which may be skipped on an103initial reading.104105<ManSection>106<Var Name="ANUPQData"/>107<Description>108is a &GAP; record in which the essential data for an &ANUPQ; session109within &GAP; is stored; its fields are:110111<List>112<Mark><C>binary</C></Mark>113<Item>114the path of the <C>pq</C> binary;115</Item>116<Mark><C>tmpdir</C></Mark>117<Item>118the path of the temporary directory used by the <C>pq</C>119binary and &GAP; (i.e. the directory in which all the <C>pq</C>'s temporary120files are created) (also see <Ref Func="ANUPQDirectoryTemporary" Style="Text"/> below);121</Item>122<Mark><C>outfile</C></Mark>123<Item>124the full path of the default <C>pq</C> output file;125</Item>126<Mark><C>SPimages</C></Mark>127<Item>128the full path of the file <C>GAP_library</C> to which the129<C>pq</C> program writes its Standard Presentation images;130</Item>131<Mark><C>version</C></Mark>132<Item>133the version of the current <C>pq</C> binary;134</Item>135<Mark><C>ni</C></Mark>136<Item>137a data record used by non-interactive functions (see below138and Chapter <Ref Chap="non-interact" Style="Text"/>);139</Item>140<Mark><C>io</C></Mark>141<Item>142list of data records for <C>PqStart</C> (see below and <Ref Func="PqStart" Style="Text"/>)143processes;144</Item>145<Mark><C>topqlogfile</C></Mark>146<Item>147name of file logged to by <C>ToPQLog</C> (see <Ref Func="ToPQLog" Style="Text"/>);148and149</Item>150<Mark><C>logstream</C></Mark>151<Item>152stream of file logged to by <C>ToPQLog</C> (see <Ref Func="ToPQLog" Style="Text"/>).153</Item>154</List>155156Each time an interactive &ANUPQ; process is initiated via <C>PqStart</C>157(see <Ref Func="PqStart" Style="Text"/>), an identifying number <A>ioIndex</A> is generated for the158interactive process and a record <C>ANUPQData.io[<A>ioIndex</A>]</C> with some or159all of the fields listed below is created. Whenever a non-interactive160function is called (see Chapter <Ref Chap="non-interact" Style="Text"/>), the161record <C>ANUPQData.ni</C> is updated with fields that, if bound, have exactly162the same purpose as for a <C>ANUPQData.io[<A>ioIndex</A>]</C> record.163164<List>165<Mark><C>stream</C></Mark>166<Item>167the IOStream opened for interactive &ANUPQ; process168<A>ioIndex</A> or non-interactive &ANUPQ; function;169</Item>170<Mark><C>group</C></Mark>171<Item>172the group given as first argument to <C>PqStart</C>, <C>Pq</C>,173<C>PqEpimorphism</C>, <C>PqDescendants</C> or <C>PqStandardPresentation</C> (or any174synonymous methods);175</Item>176<Mark><C>haspcp</C></Mark>177<Item>178is bound and set to <K>true</K> when a pc presentation is first179set inside the <C>pq</C> program (e.g. by <C>PqPcPresentation</C> or180<C>PqRestorePcPresentation</C> or a higher order function like <C>Pq</C>,181<C>PqEpimorphism</C>, <C>PqPCover</C>, <C>PqDescendants</C> or <C>PqStandardPresentation</C>182that does a <C>PqPcPresentation</C> operation, but <E>not</E> <C>PqStart</C> which only183starts up an interactive &ANUPQ; process);184</Item>185<Mark><C>gens</C></Mark>186<Item>187a list of the generators of the group <C>group</C> as strings188(the same as those passed to the <C>pq</C> program);189</Item>190<Mark><C>rels</C></Mark>191<Item>192a list of the relators of the group <C>group</C> as strings (the193same as those passed to the <C>pq</C> program);194</Item>195<Mark><C>name</C></Mark>196<Item>197the name of the group whose pc presentation is defined by a198call to the <C>pq</C> program (according to the <C>pq</C> program -- unless you199have used the <C>GroupName</C> option (see e.g. <Ref Func="Pq" Style="Text"/>) or applied the function200<C>SetName</C> (see <Ref BookName="ref" Func="SetName" Style="Text"/>) to the group, the <Q>generic</Q> name201<C>"[grp]"</C> is set as a default);202</Item>203<Mark><C>gpnum</C></Mark>204<Item>205if not a null string, the <Q>number</Q> (i.e. the unique label206assigned by the <C>pq</C> program) of the last descendant processed;207</Item>208<Mark><C>class</C></Mark>209<Item>210the largest lower exponent-<M>p</M> central class of a quotient211group of the group (usually <C>group</C>) found by a call to the <C>pq</C> program;212</Item>213<Mark><C>forder</C></Mark>214<Item>215the factored order of the quotient group of largest lower216exponent-<M>p</M> central class found for the group (usually <C>group</C>) by a217call to the <C>pq</C> program (this factored order is given as a list218<!-- FIXME: [p,n] reformatted -->219<C>[p,n]</C>, indicating an order of <M>p^n</M>);220</Item>221<Mark><C>pcoverclass</C></Mark>222<Item>223the lower exponent-<M>p</M> central class of the224<M>p</M>-covering group of a <M>p</M>-quotient of the group (usually <C>group</C>) found225by a call to the <C>pq</C> program;226</Item>227<Mark><C>workspace</C></Mark>228<Item>229the workspace set for the <C>pq</C> process (either given as230a second argument to <C>PqStart</C>, or set by default to 10000000);231</Item>232<Mark><C>menu</C></Mark>233<Item>234the current menu of the <C>pq</C> process (the <C>pq</C> program is235managed by various menus, the details of which the user shouldn't236normally need to know about -- the <C>menu</C> field remembers which menu the237<C>pq</C> process is currently <Q>in</Q>);238</Item>239<Mark><C>outfname</C></Mark>240<Item>241is the file to which <C>pq</C> output is directed, which is242always <C>ANUPQData.outfile</C>, except when option <C>SetupFile</C> is used with a243non-interactive function, in which case <C>outfname</C> is set to244<C>"PQ_OUTPUT"</C>;245</Item>246<Mark><C>pQuotient</C></Mark>247<Item>248is set to the value returned by <C>Pq</C> (see <Ref Func="Pq" Style="Text"/>) (the249field <C>pQepi</C> is also set at the same time);250</Item>251<Mark><C>pQepi</C></Mark>252<Item>253is set to the value returned by <C>PqEpimorphism</C>254(see <Ref Func="PqEpimorphism" Style="Text"/>) (the field <C>pQuotient</C> is also set at the same255time);256</Item>257<Mark><C>pCover</C></Mark>258<Item>259is set to the value returned by <C>PqPCover</C>260(see <Ref Func="PqPCover" Style="Text"/>);261</Item>262<Mark><C>SP</C></Mark>263<Item>264is set to the value returned by <C>PqStandardPresentation</C> or265<C>StandardPresentation</C> (see <Ref Func="PqStandardPresentation" Label="interactive" Style="Text"/>) when266called interactively, for process <A>i</A> (the field <C>SPepi</C> is also set at267the same time);268</Item>269<Mark><C>SPepi</C></Mark>270<Item>271is set to the value returned by272<C>EpimorphismPqStandardPresentation</C> or <C>EpimorphismStandardPresentation</C>273(see <Ref Func="EpimorphismPqStandardPresentation" Label="interactive" Style="Text"/>) when called274interactively, for process <A>i</A> (the field <C>SP</C> is also set at the same275time);276</Item>277<Mark><C>descendants</C></Mark>278<Item>279is set to the value returned by280<C>PqDescendants</C> (see <Ref Func="PqDescendants" Style="Text"/>);281</Item>282<Mark><C>treepos</C></Mark>283<Item>284if set by a call to <C>PqDescendantsTreeCoclassOne</C>285(see <Ref Func="PqDescendantsTreeCoclassOne" Style="Text"/>), it contains a record with fields286<C>class</C>, <C>node</C> and <C>ndes</C> being the information that determines the last287descendant with a non-zero number of descendants processed;288</Item>289<Mark><C>xgapsheet</C></Mark>290<Item>291if set by a call to <C>PqDescendantsTreeCoclassOne</C>292(see <Ref Func="PqDescendantsTreeCoclassOne" Style="Text"/>) during an &XGAP; session, it293contains the &XGAP; <C>Sheet</C> on which the descendants tree is displayed;294and295</Item>296<Mark><C>nextX</C></Mark>297<Item>298if set by a call to <C>PqDescendantsTreeCoclassOne</C>299(see <Ref Func="PqDescendantsTreeCoclassOne" Style="Text"/>) during an &XGAP; session, it300contains a list of integers, the <A>i</A>th entry of which is the301<A>x</A>-coordinate of the next node (representing a descendant) for the <A>i</A>th302class.303</Item>304</List>305</Description>306</ManSection>307308309<ManSection>310<Func Name="ANUPQDirectoryTemporary" Arg="dir"/>311<Description>312calls the UNIX command <C>mkdir</C> to create <A>dir</A>, which must be a string,313and if successful a directory object for <A>dir</A> is both assigned to314<C>ANUPQData.tmpdir</C> and returned. The field <C>ANUPQData.outfile</C> is also315set to be a file in <C>ANUPQData.tmpdir</C>, and on exit from &GAP; <A>dir</A> is316removed. Most users will never need this command; by default, &GAP;317typically chooses a <Q>random</Q> subdirectory of <C>/tmp</C> for318<C>ANUPQData.tmpdir</C> which may occasionally have limits on what may be319written there. <C>ANUPQDirectoryTemporary</C> permits the user to choose a320directory (object) where one is not so limited.321</Description>322</ManSection>323324</Section>325326327<Section Label="Setting the Verbosity of ANUPQ via Info and InfoANUPQ">328<Heading>Setting the Verbosity of ANUPQ via Info and InfoANUPQ</Heading>329330<ManSection>331<InfoClass Name="InfoANUPQ"/>332<Description>333The input to and the output from the <C>pq</C> program is, by default, not334displayed. However the user may choose to see some, or all, of this335input/output. This is done via the <C>Info</C> mechanism (see336Section <Ref BookName="ref" Label="Info Functions" Style="Text"/> in the &GAP; Reference Manual). For this337purpose, there is the <A>InfoClass</A> <C>InfoANUPQ</C>. If the <C>InfoLevel</C> of338<C>InfoANUPQ</C> is high enough each line of <C>pq</C> input/output is directed to339a call to <C>Info</C> and will be displayed for the user to see. By default,340the <C>InfoLevel</C> of <C>InfoANUPQ</C> is 1, and it is recommended that you leave341it at this level, or higher. Messages that the user should presumably342want to see and output from the <C>pq</C> program influenced by the value of343the option <C>OutputLevel</C> (see the options listed in Section <Ref Func="Pq" Style="Text"/>), other344than timing and memory usage are directed to <C>Info</C> at <C>InfoANUPQ</C> level3451.346<P/>347348To turn off <E>all</E> <C>InfoANUPQ</C> messaging, set the <C>InfoANUPQ</C> level to 0.349<P/>350351There are five other user-intended <C>InfoANUPQ</C> levels: 2, 3, 4, 5 and 6.352353<Example><![CDATA[354gap> SetInfoLevel(InfoANUPQ, 2);355]]></Example>356357enables the display of most timing and memory usage data from the <C>pq</C>358program, and also the number of identity instances when the <C>Identities</C>359option is used. (Some timing and memory usage data, particularly when360profuse in quantity, is <C>Info</C>-ed at <C>InfoANUPQ</C> level 3 instead.) Note361that the the &GAP; functions <C>time</C> and <C>Runtime</C>362(see <Ref BookName="ref" Func="Runtime" Style="Text"/> in363the &GAP; Reference Manual) count the time spent by &GAP; and <E>not</E> the364time spent by the (external) <C>pq</C> program.365366<Example><![CDATA[367gap> SetInfoLevel(InfoANUPQ, 3);368]]></Example>369370enables the display of output of the nature of the first two <C>InfoANUPQ</C>371that was not directly invoked by the user (e.g. some commands require372&GAP; to discover something about the current state known to the <C>pq</C>373program). The identity instances processed under the <C>Identities</C> option374are also displayed at this level. In some cases, the <C>pq</C> program375produces a lot of output despite the fact that the <C>OutputLevel</C>376(see <Ref Label="option OutputLevel" Style="Text"/>) is unset or is set to 0; such output is also377<C>Info</C>-ed at <C>InfoANUPQ</C> level 3.378379<Example><![CDATA[380gap> SetInfoLevel(InfoANUPQ, 4);381]]></Example>382383enables the display of all the commands directed to the <C>pq</C> program,384behind a <Q><C>ToPQ> </C></Q> prompt (so that you can distinguish it from the385output from the <C>pq</C> program). See Section <Ref Sect="Hints and Warnings regarding the use of Options" Style="Text"/> for an example of how this can be a useful386troubleshooting tool.387388<Example><![CDATA[389gap> SetInfoLevel(InfoANUPQ, 5);390]]></Example>391392enables the display of the <C>pq</C> program's prompts for input. Finally,393394<Example><![CDATA[395gap> SetInfoLevel(InfoANUPQ, 6);396]]></Example>397398enables the display of all other output from the <C>pq</C> program, namely the399banner and menus. However, the timing data printed when the <C>pq</C> program400exits can never be observed.401402</Description>403</ManSection>404405</Section>406407408<Section Label="Utility-Functions">409<Heading>Utility Functions</Heading>410411<ManSection>412<Func Name="PqLeftNormComm" Arg="elts"/>413<Description>414returns for a list of elements of some group (e.g. <A>elts</A> may be a list415of words in the generators of a free or fp group) the left normed416commutator of <A>elts</A>, e.g. if <A>w1</A>, <A>w2</A>, <A>w3</A> are such elements then417<C>PqLeftNormComm( [<A>w1</A>, <A>w2</A>, <A>w3</A>] );</C> is equivalent to <C>Comm( Comm(418<A>w1</A>, <A>w2</A> ), <A>w3</A> );</C>.419<P/>420421<E>Note:</E> <A>elts</A> must contain at least two elements.422</Description>423</ManSection>424425<ManSection>426<Func Name="PqGAPRelators" Arg="group, rels"/>427<Description>428returns a list of words that &GAP; understands, given a list <A>rels</A> of429strings in the string representations of the generators of the fp group430<A>group</A> prepared as a list of relators for the <C>pq</C> program.431<P/>432433<E>Note:</E>434The <C>pq</C> program does not use <C>/</C> to indicate multiplication by an435inverse and uses square brackets to represent (left normed) commutators.436Also, even though the <C>pq</C> program accepts relations, all elements of437<A>rels</A> <E>must</E> be in relator form, i.e. a relation of form <C><A>w1</A> = <A>w2</A></C>438must be written as <C><A>w1</A>*(<A>w2</A>)^-1</C>.439<P/>440441Here is an example:442443<Example><![CDATA[444gap> F := FreeGroup("a", "b");445<free group on the generators [ a, b ]>446gap> PqGAPRelators(F, [ "a*b^2", "[a,b]^2*a", "([a,b,a,b,b]*a*b)^2*a" ]);447[ 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^448-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^449-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^450-1*b*a*b^-1*a*b^-1*a^-1*b*a^-1*b^-1*a*b*a*b^2*a*b*a ]451]]></Example>452</Description>453</ManSection>454455<ManSection>456<Func Name="PqParseWord" Arg="word, n"/>457<Description>458parses a <A>word</A>, a string representing a word in the pc generators459<C>x1,...,x<A>n</A></C>, through &GAP;. This function is provided as a460rough-and-ready check of <A>word</A> for syntax errors. A syntax error will461cause the entering of a <C>break</C>-loop, in which the error message may or462may not be meaningful (depending on whether the syntax error gets caught463at the &GAP; or kernel level).464<P/>465466<E>Note:</E>467The reason the generators <E>must</E> be <C>x1,...,x<A>n</A></C> is that these are the468pc generator names used by the <C>pq</C> program (as distinct from the469generator names for the group provided by the user to a function like470<C>Pq</C> that invokes the <C>pq</C> program).471</Description>472</ManSection>473474<ManSection>475<Func Name="PqExample" Arg="" Label="no arguments"/>476<Func Name="PqExample" Arg="example[, PqStart][, Display]"/>477<Func Name="PqExample" Arg="example[, PqStart][, filename]" Label="with filename"/>478<Description>479With no arguments, or with single argument <C>"index"</C>, or a string480<A>example</A> that is not the name of a file in the <C>examples</C> directory, an481index of available examples is displayed.482<P/>483484With just the one argument <A>example</A> that is the name of a file in the485<C>examples</C> directory, the example contained in that file is executed in486its simplest form. Some examples accept options which you may use to487modify some of the options used in the commands of the example. To find488out which options an example accepts, use one of the mechanisms for489displaying the example described below.490<P/>491492Some examples have both non-interactive and interactive forms; those that493are non-interactive only have a name ending in <C>-ni</C>; those that are494interactive only have a name ending in <C>-i</C>; examples with names ending495in <C>.g</C> also have only one form; all other examples have both496non-interactive and interactive forms and for these giving <C>PqStart</C> as497second argument invokes <C>PqStart</C> initially and makes the appropriate498adjustments so that the example is executed or displayed using499interactive functions.500<P/>501502If <C>PqExample</C> is called with last (second or third) argument <C>Display</C>503then the example is displayed without being executed. If the last504argument is a non-empty string <A>filename</A> then the example is also505displayed without being executed but is also written to a file with that506name. Passing an empty string as last argument has the same effect as507passing <C>Display</C>.508<P/>509510<E>Note:</E>511The variables used in <C>PqExample</C> are local to the running of512<C>PqExample</C>, so there's no danger of having some of your variables513over-written. However, they are not completely lost either. They are514saved to a record <C>ANUPQData.examples.vars</C>, i.e. if <C>F</C> is a variable515used in the example then you will be able to access it after <C>PqExample</C>516has finished as <C>ANUPQData.examples.vars.F</C>.517</Description>518</ManSection>519520<ManSection>521<Func Name="AllPqExamples" Arg=""/>522<Description>523returns a list of all currently available examples in default524UNIX-listing (i.e. alphabetic) order.525</Description>526</ManSection>527528<ManSection>529<Func Name="GrepPqExamples" Arg="string"/>530<Description>531runs the UNIX command <C>grep <A>string</A></C> over the &ANUPQ; examples and532returns the list of examples for which there is a match. The actual533matches are <C>Info</C>-ed at <C>InfoANUPQ</C> level 2.534</Description>535</ManSection>536537<ManSection>538<Func Name="ToPQLog" Arg="[ filename ]"/>539<Description>540With string argument <A>filename</A>, <C>ToPQLog</C> opens the file with name541<A>filename</A> for logging; all commands written to the <C>pq</C> binary (that are542<C>Info</C>-ed behind a <Q><C>ToPQ> </C></Q> prompt at <C>InfoANUPQ</C> level 4) are then543also written to that file (but without prompts). With no argument,544<C>ToPQLog</C> stops logging to whatever file was being logged to. If a file545was already being logged to, that file is closed and the file with name546<A>filename</A> is opened for logging.547</Description>548</ManSection>549550</Section>551552553<Section Label="Attributes and a Property for fp and pc p-groups">554<Heading>Attributes and a Property for fp and pc p-groups</Heading>555556<ManSection>557<Attr Name="NuclearRank" Arg="G"/>558<Attr Name="MultiplicatorRank" Arg="G"/>559<Prop Name="IsCapable" Arg="G"/>560<Description>561return the nuclear rank of <A>G</A>, <M>p</M>-multiplicator rank of <A>G</A>, and562whether <A>G</A> is capable (i.e. <K>true</K> if it is, or <K>false</K> if it is not),563respectively.564<P/>565566These attributes and property are set automatically if <A>G</A> is one of the567following:568569<List>570<Item>571an fp group returned by <C>PqStandardPresentation</C> or572<C>StandardPresentation</C> (see <Ref Func="PqStandardPresentation" Style="Text"/>);573</Item>574<Item>575the image (fp group) of the epimorphism returned by an576<C>EpimorphismPqStandardPresentation</C> or <C>EpimorphismStandardPresentation</C>577call (see <Ref Func="EpimorphismPqStandardPresentation" Style="Text"/>); or578</Item>579<Item>580one of the pc groups of the list of descendants returned by581<C>PqDescendants</C> (see <Ref Func="PqDescendants" Style="Text"/>).582</Item>583</List>584585If <A>G</A> is an fp group or a pc <M>p</M>-group and not one of the above and the586attribute or property has not otherwise been set for <A>G</A>, then587<C>PqStandardPresentation</C> is called to set all three of <C>NuclearRank</C>,588<C>MultiplicatorRank</C> and <C>IsCapable</C>, before returning the value of the589attribute or property actually called. Such a group <A>G</A> must know in590advance that it is a <M>p</M>-group; this is the case for the groups returned591by the functions <C>Pq</C> and <C>PqPCover</C>, and the image group of the592epimorphism returned by <C>PqEpimorphism</C>. Otherwise, if you know the group593to be a <M>p</M>-group, then this can be set by typing594<Listing><![CDATA[595SetIsPGroup( G, true );596]]></Listing>597or by invoking <C>IsPGroup( <A>G</A> )</C>. Note that for an fp group <A>G</A>, the598latter may result in a coset enumeration which might not terminate in a599reasonable time.600<P/>601602<E>Note:</E> For <A>G</A> such that <C>HasNuclearRank(<A>G</A>) = true</C>, <C>IsCapable(<A>G</A>)</C>603is equivalent to (the truth or falsity of) <C>NuclearRank( <A>G</A> ) = 0</C>.604</Description>605</ManSection>606607</Section>608609610<Section Label="Hints and Warnings regarding the use of Options">611<Heading>Hints and Warnings regarding the use of Options</Heading>612613On a first reading we recommend you skip this section and come back to it614if and when you run into trouble.615<P/>616<Index Subkey="of pq program">menu item</Index>617<Index Subkey="of pq program is a menu item">option</Index> <!-- FIXME: is this right? -->618<E>Note:</E>619By <Q>options</Q> we refer to &GAP; options. The <C>pq</C> program also uses the620term <Q>option</Q>; to distinguish the two usages of <Q>option</Q>, in this621manual we use the term <E>menu item</E> to refer to what the <C>pq</C> program622refers to as an <Q>option</Q>.623<P/>624625Options are passed to the &ANUPQ; interface functions in either of the626two usual mechanisms provided by &GAP;, namely:627628<List>629<Item>630options may be set globally using the function <C>PushOptions</C>631(see Chapter <Ref BookName="ref" Label="Options Stack" Style="Text"/> in the &GAP; Reference Manual); or632</Item>633<Item>634options may be appended to the argument list of any function635call, separated by a colon from the argument list (see636Chapter <Ref BookName="ref" Label="Function Calls" Style="Text"/> in the &GAP; Reference Manual), in which637case they are then passed on recursively to any subsequent inner function638call, which may in turn have options of their own.639</Item>640</List>641642Particularly, when one is using the interactive functions of643Chapter <Ref Chap="Interactive ANUPQ functions" Style="Text"/>, one should, in general, avoid644using the global method of passing options. In fact, it is recommended645that prior to calling <C>PqStart</C> the <C>OptionsStack</C> be empty. The646essential problem with setting options globally using the function647<C>PushOptions</C> is that options pushed onto <C>OptionsStack</C>, in this way,648(generally) remain there until an explicit <C>PopOptions()</C> call is made.649<P/>650651In contrast, options passed in the usual way behind a colon following a652function's arguments (see <Ref BookName="ref" Label="Function Call With Options" Style="Text"/> in the &GAP; Reference653Manual) are local, and disappear from <C>OptionsStack</C> after the function654has executed successfully. If the function does <E>not</E> execute655successfully, i.e. it runs into error and the user <K>quit</K>s the resulting656<C>break</C> loop (see Section <Ref BookName="ref" Label="Break loops" Style="Text"/> in the Reference Manual)657rather than attempting to repair the problem and typing <C>return;</C> then,658unless the error at the kernel level, the659<C>OptionsStack</C> is reset. If an error is detected inside the kernel660(hopefully, this should occur only rarely, if at all) then the options of661that function will <E>not</E> be cleared from <C>OptionsStack</C>; in such cases:662<Example><![CDATA[663gap> ResetOptionsStack();664#I Options stack is already empty665]]></Example>666667is usually necessary (see Chapter <Ref BookName="ref" Func="ResetOptionsStack" Style="Text"/> in the &GAP;668Reference Manual), which recursively calls <C>PopOptions()</C> until669<C>OptionsStack</C> is empty, or as in the above case warns you that the670<C>OptionsStack</C> is already empty.671<P/>672673Note that a function, that is passed options after the colon, will also674see any global options or any options passed down recursively from675functions calling that function, unless those options are over-ridden by676options passed via the function. Also, note that duplication of option677names for different programs may lead to misinterpretations, and678mis-spelled options will not be <Q>seen</Q>.679<P/>680681The non-interactive functions of Chapter <Ref Chap="non-interact" Style="Text"/> that have <C>Pq</C> somewhere in their name provide an alternative682method of passing options as additional arguments. This has the683advantages that options can be abbreviated and mis-spelled options will684be trapped.685686<Index>troubleshooting tips</Index>687<ManSection>688<Var Name="ANUPQWarnOfOtherOptions"/>689<Description>690is a global variable that is by default <K>false</K>. If it is set to <K>true</K>691then any function provided by the &ANUPQ; function that recognises at692least one option, will warn you of <Q>other</Q> options, i.e. options that693the function does not recognise. These warnings are emitted at694<C>InfoWarning</C> or <C>InfoANUPQ</C> level 1. This is useful for detecting695mis-spelled options. Here is an example using the function <C>Pq</C> (first696described in Chapter <Ref Chap="non-interact" Style="Text"/>):697<Log><![CDATA[698gap> SetInfoLevel(InfoANUPQ, 1); # Set InfoANUPQ to default level699gap> ANUPQWarnOfOtherOptions := true;;700gap> # The following makes entry into break loops very ``quiet'' ...701gap> OnBreak := function() Where(0); end;;702gap> F := FreeGroup( "a", "b" );703<free group on the generators [ a, b ]>704gap> Pq( F : Prime := 2, Classbound := 1 );705#I ANUPQ Warning: Options: [ "Classbound" ] ignored706#I (invalid for generic function: `Pq').707user interrupt at708moreOfline := ReadLine( iostream );709Entering break read-eval-print loop ...710you can 'quit;' to quit to outer loop, or711you can 'return;' to continue712]]></Log>713714Here we mistyped <C>ClassBound</C> as <C>Classbound</C>, and after seeing the715<C>Info</C>-ed warning that <C>Classbound</C> was ignored, we typed a <A>control</A>-C716(that's the <Q><C>user interrupt at</C></Q> message) which took us into a break717loop. Since the <C>Pq</C> command was not able to finish, the options <C>Prime</C>718and <C>Classbound</C>, in particular, will still be on the <C>OptionsStack</C>:719<Log><![CDATA[720brk> OptionsStack;721[ rec( Prime := 2, Classbound := 1 ),722rec( Prime := 2, Classbound := 1, PqEpiOrPCover := "pQuotient" ) ]723]]></Log>724725The option <C>PqEpiOrPCover</C> is a behind-the-scenes option that need not726concern the user. On <K>quit</K>ting the <C>break</C>-loop the727<C>OptionsStack</C> is reset and a warning telling you this is emitted:728<Log><![CDATA[729brk> quit; # to get back to the `gap>' prompt730#I Options stack has been reset731]]></Log>732733Above, we altered <C>OnBreak</C> (see <Ref BookName="ref" Func="OnBreak" Style="Text"/> in the Reference manual)734to reduce the back-tracing on entry into a break loop. We now restore735<C>OnBreak</C> to its usual value.736<Example><![CDATA[737gap> OnBreak := Where;;738]]></Example>739740<E>Notes</E>741<P/>742743In cases where functions recursively call others with options (e.g. when744using <C>PqExample</C> with options), setting <C>ANUPQWarnOfOtherOptions :=745true</C> may give rise to spurious <Q>other</Q> option detections.746<P/>747748It is recommended that the novice user set <C>ANUPQWarnOfOtherOptions</C> to749<K>true</K> in their <C>gap.ini</C> file (see Section <Ref Sect="Loading the ANUPQ Package" Style="Text"/>).750</Description>751</ManSection>752753<E>Other Troubleshooting Strategies</E>754<P/>755756There are some other strategies which may have helped us to see our error757above. The function <C>Pq</C> recognises the option <C>OutputLevel</C>758(see <Ref Label="option OutputLevel" Style="Text"/>); if this option is set to at least 1, the <C>pq</C> program759provides information on each class quotient as it is generated:760<Log><![CDATA[761gap> ANUPQWarnOfOtherOptions := false;; # Set back to normal762gap> F := FreeGroup( "a", "b" );;763gap> Pq( F : Prime := 2, Classbound := 1, OutputLevel := 1 );764#I Lower exponent-2 central series for [grp]765#I Group: [grp] to lower exponent-2 central class 1 has order 2^2766#I Group: [grp] to lower exponent-2 central class 2 has order 2^5767#I Group: [grp] to lower exponent-2 central class 3 has order 2^10768#I Group: [grp] to lower exponent-2 central class 4 has order 2^18769#I Group: [grp] to lower exponent-2 central class 5 has order 2^32770#I Group: [grp] to lower exponent-2 central class 6 has order 2^55771#I Group: [grp] to lower exponent-2 central class 7 has order 2^96772#I Group: [grp] to lower exponent-2 central class 8 has order 2^167773#I Group: [grp] to lower exponent-2 central class 9 has order 2^294774#I Group: [grp] to lower exponent-2 central class 10 has order 2^520775#I Group: [grp] to lower exponent-2 central class 11 has order 2^932776#I Group: [grp] to lower exponent-2 central class 12 has order 2^1679777[... output truncated ...]778]]></Log>779780After seeing the information for the class 2 quotient we may have got the781idea that the <C>Classbound</C> option was not recognised and may have782realised that this was due to a mis-spelling. The above will ordinarily783cause the available space to be exhausted, necessitating784user-intervention by typing <A>control</A>-C and <C>quit;</C> (to escape the break785loop); otherwise <C>Pq</C> terminates when the class reaches 63 (the default786value of <C>ClassBound</C>).787<P/>788789If you have some familiarity with <Q>keyword</Q> command input to the <C>pq</C>790binary, then setting the level of <C>InfoANUPQ</C> to 4 would also have791indicated a problem:792<Log><![CDATA[793gap> ResetOptionsStack(); # Necessary, if a break-loop was entered above794gap> SetInfoLevel(InfoANUPQ, 4);795gap> Pq( F : Prime := 2, Classbound := 1 );796#I ToPQ> 7 #to (Main) p-Quotient Menu797#I ToPQ> 1 #define group798#I ToPQ> name [grp]799#I ToPQ> prime 2800#I ToPQ> class 63801#I ToPQ> exponent 0802#I ToPQ> output 0803#I ToPQ> generators { a,b }804#I ToPQ> relators { };805[... output truncated ...]806]]></Log>807808Here the line <Q><C>#I ToPQ> class 63</C></Q> indicates that a directive to set809the classbound to 63 was sent to the <C>pq</C> program.810811</Section>812</Chapter>813814815