<html><head><title>[ANUPQ] 7 Installing the ANUPQ Package</title></head> <body text="#000000" bgcolor="#ffffff"> [<a href = "chapters.htm">Up</a>] [<a href ="CHAP006.htm">Previous</a>] [<a href ="CHAP00A.htm">Next</a>] [<a href = "theindex.htm">Index</a>] <h1>7 Installing the ANUPQ Package</h1><p> <P> <H3>Sections</H3> <oL> <li> <A HREF="CHAP007.htm#SECT001">Testing your ANUPQ installation</a> <li> <A HREF="CHAP007.htm#SECT002">Running the pq program as a standalone</a> <li> <A HREF="CHAP007.htm#SECT003">Setting the Verbosity of ANUPQ via Info and InfoANUPQ</a> <li> <A HREF="CHAP007.htm#SECT004">Utility Functions</a> </ol><p> <p> The ANU <code>pq</code> program is written in C and the package can be installed under UNIX and in environments similar to UNIX. It has been tested on DECstation running Ultrix, a HP 9000/700 and HP 9000/800 running HP-UX, a MIPS running RISC/os Berkeley, a NeXTstation running NeXTSTEP 3.0, a SUN running SunOS and an Intel Pentium based PC running Linux or Windows equipped with cygwin. <p> The current version of the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package requires <font face="Gill Sans,Helvetica,Arial">GAP</font> 4.4, and version 1.2 of the <font face="Gill Sans,Helvetica,Arial">AutPGrp</font> package. If you still have <font face="Gill Sans,Helvetica,Arial">GAP</font> 4.3 (at least fix4), then you must use <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> 2.2, and <font face="Gill Sans,Helvetica,Arial">AutPGrp</font> 1.1. You should not use earlier versions of the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package since they are known to have bugs. <p> To install the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package, move the file <code>anupq-</code><var>XXX</var><code>.zoo</code> for some version number <var>XXX</var> into the <code>pkg</code> directory in which you plan to install <font face="Gill Sans,Helvetica,Arial">ANUPQ</font>. Usually, this will be the directory <code>pkg</code> in the hierarchy of your version of <font face="Gill Sans,Helvetica,Arial">GAP</font> 4; it is however also possible to keep an additional <code>pkg</code> directory in your private directories. The only essential difference with installing <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> in a <code>pkg</code> directory different to the <font face="Gill Sans,Helvetica,Arial">GAP</font> 4 home directory is that one must start <font face="Gill Sans,Helvetica,Arial">GAP</font> with the <code>-l</code> switch (see Section <a href="../../../doc/htm/ref/CHAP003.htm#SECT001">Command Line Options</a>), e.g. if your private <code>pkg</code> directory is a subdirectory of <code>mygap</code> in your home directory you might type: <p> <code>gap -l ";</code><var>myhomedir</var><code>/mygap"</code> <p> where <var>myhomedir</var> is the path to your home directory, which (since <font face="Gill Sans,Helvetica,Arial">GAP</font> 4.3) may be replaced by a tilde. The empty path before the semicolon is filled in by the default path of the <font face="Gill Sans,Helvetica,Arial">GAP</font> 4 home directory. <p> Then, in your chosen <code>pkg</code> directory, unzoo <code>anupq-</code><var>XXX</var><code>.zoo</code> by <p> <code>unzoo -x anupq-</code><var>XXX</var><code></code> <p> Change to the newly created <code>anupq</code> directory. Now you need to call <code>configure </code><var>path</var><code></code> where <var>path</var> is the path to the <font face="Gill Sans,Helvetica,Arial">GAP</font> home directory. So for example if you install the package in the main <code>pkg</code> directory call <p> <pre> ./configure ../.. </pre> <p> What this does is look for a file <code>sysinfo.gap</code> in the root directory of <font face="Gill Sans,Helvetica,Arial">GAP</font> in order to determine an architecture name for the subdirectory of <code>bin</code> in which to put the compiled <code>pq</code> binary. This only makes sense if <font face="Gill Sans,Helvetica,Arial">GAP</font> was compiled for the same architecture that <code>pq</code> will be. If you have a shared file system mounted across different architectures, then you should run <code>configure</code> and <code>make</code> for <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> for each architecture immediately after compiling <font face="Gill Sans,Helvetica,Arial">GAP</font> on the same architecture. <p> If you had to install the package in your own directory but wish to use the system <font face="Gill Sans,Helvetica,Arial">GAP</font> 4 then you will need to find out what <var>path</var> is. To do this, start up <font face="Gill Sans,Helvetica,Arial">GAP</font> and find out what <font face="Gill Sans,Helvetica,Arial">GAP</font>'s root path is from finding the value of the variable <code>GAPInfo.RootPaths</code> (in <font face="Gill Sans,Helvetica,Arial">GAP</font> 4.4; this was <code>GAP_ROOT_PATHS</code> prior to <font face="Gill Sans,Helvetica,Arial">GAP</font> 4.4), e.g. <p> <pre> gap> GAPInfo.RootPaths; [ "/usr/local/lib/gap4r4/" ] </pre> <p> would tell you to use <code>/usr/local/lib/gap4r4</code> for <var>path</var>. <p> The <code>configure</code> command will fetch the architecture type for which <font face="Gill Sans,Helvetica,Arial">GAP</font> has been compiled last, create a <code>Makefile</code> and list a number of ``targets'' to call <code>make</code> with. If you have one of the standard Linux (or NetBSD or FreeBSD) systems with <code>gcc</code>, wish to compile with <code>-O2</code> optimisation, and have <code>gmp</code> with its include and library files in <code>/usr/local/include</code> and <code>/usr/local/lib</code>, respectively, you can now simply call <p> <pre> make </pre> <p> to compile the binary and to install it in the appropriate place. <p> If you need a special target, e.g. you don't have <code>gmp</code> or are not on a Linux system, and the targets displayed on the screen after the <code>configure</code> step rushed past your eyes and you can't scroll back to see them, you can ``pipe'' those same targets through <code>less</code> or <code>more</code>, e.g. with <code>more</code>: <p> <pre> make unknown | more </pre> <p> An abbreviation of the target list is as follows: <p> <pre> 'linux-iX86-gcc2-gmp' for IBM x86 PCs under linux/BSD with GNU cc 2 and mp 'linux-iX86-cc-gmp' for IBM x86 PCs under linux/BSD with cc and GNU mp 'linux-iX86-gcc2' for IBM x86 PCs under linux/BSD with GNU cc 2 'linux-iX86-cc' for IBM x86 PCs under linux/BSD with cc (GNU) 'iX86-pc-cygwin-gcc-gmp' for IBM x86 PCs under CYGWIN with GNU cc and GNU mp 'iX86-pc-cygwin-gcc' for IBM x86 PCs under CYGWIN with GNU cc [... 16 lines deleted ...] 'sunos-gcc2-gmp' for SunOS with GNU cc 2 and gmp 'sunos-cc-gmp' for SunOS with cc and GNU mp 'sunos-gcc2' for SunOS with GNU cc 2 'sunos-cc' for SunOS with cc 'unix-gmp' for a generic unix system with cc and GNU mp 'unix' for a generic unix system with cc 'clean' remove all created files targets are listed according to preference, i.e., 'sunos-gcc2' is better than 'sunos-cc' no target is the same as choosing 'linux-iX86-gcc2-gmp' additional C compiler and linker flags can be passed with 'make <target> COPTS=<compiler-opts> LOPTS=<linker-opts>', e.g., 'make sunos-cc COPTS=-g LOPTS=-g'. set GAP if GAP4 is not started with the command 'gap', e.g., 'make sunos-cc GAP=/usr/local/bin/gap4'. in order to use the GNU multiple precision (gmp) set 'GNUINC' (default '/usr/local/include') and 'GNULIB' (default '/usr/local/lib') do 'make unknown | more' to see these targets again via more </pre> <p> Let's suppose that the <code>linux-iX86-gcc2-gmp</code> target does not satisfy your requirements, that your system is Solaris 2.8 (i.e. SunOS 5.8), you have <code>gmp</code> but its <code>include</code> and <code>lib</code> directories are somewhere else, and that <code>gap4</code> is the command used to start <font face="Gill Sans,Helvetica,Arial">GAP</font> 4. Then the following might be the appropriate <code>make</code> call: <p> <pre> make sunos-gcc2-gmp GAP=gap4 GNUINC=/opt/local/include GNULIB=/opt/local/lib </pre> <p> If you don't have the <strong>GNU</strong> multiple precision arithmetic (<code>gmp</code>) installed on your system, don't worry, <code>gmp</code> is <strong>not required</strong>; just select an appropriate target without <code>-gmp</code>. <p> <a name = "I0"></a> The path of <font face="Gill Sans,Helvetica,Arial">GAP</font> (see <strong>Note</strong> below) used by the <code>pq</code> binary (the value <code>GAP</code> is set to in the <code>make</code> command) may be over-ridden by setting the environment variable <code>ANUPQ_GAP_EXEC</code>. These values are only of interest when the <code>pq</code> program is run as a standalone; however, the <code>testPq</code> script assumes you have set one of these correctly (see Section <a href="CHAP007.htm#SECT001">Testing your ANUPQ installation</a>). When the <code>pq</code> program is started from <font face="Gill Sans,Helvetica,Arial">GAP</font> communication occurs via an iostream, so that the <code>pq</code> binary does not actually need to know a valid path for <font face="Gill Sans,Helvetica,Arial">GAP</font> is this case. <p> <strong>Note.</strong> By ``path of <font face="Gill Sans,Helvetica,Arial">GAP</font>'' we mean the path of the command used to invoke <font face="Gill Sans,Helvetica,Arial">GAP</font> (which should be a script, e.g. the <code>gap.sh</code> script generated in the <code>bin</code> directory for the version of <font face="Gill Sans,Helvetica,Arial">GAP</font> when <font face="Gill Sans,Helvetica,Arial">GAP</font> was compiled). The usual strategy is to copy the <code>gap.sh</code> script to a standard location, e.g. <code>/usr/local/bin/gap</code>. It is a mistake to copy the <font face="Gill Sans,Helvetica,Arial">GAP</font> executable <code>gap</code> (in a directory with name of form <code>bin/</code><var>compile-platform</var><code></code>) to the standard location, since direct invocation of the executable results in <font face="Gill Sans,Helvetica,Arial">GAP</font> starting without being able to find its own library (a fatal error). <p> <p> <h2><a name="SECT001">7.1 Testing your ANUPQ installation</a></h2> <p><p> <a name = "I1"></a> Now it is time to test the installation. After doing <code>configure</code> and <code>make</code> you will have a <code>testPq</code> script. The script assumes that, if the environment variable <code>ANUPQ_GAP_EXEC</code> is set, it is a correct path for <font face="Gill Sans,Helvetica,Arial">GAP</font>, or otherwise that the <code>make</code> call that compiled the <code>pq</code> program set <code>GAP</code> to a correct path for <font face="Gill Sans,Helvetica,Arial">GAP</font> (see Section <a href="CHAP007.htm#SECT002">Running the pq program as a standalone</a> for more details). To run the tests, just type: <p> <pre> testPq </pre> <p> Some of the tests the script runs take a while. Please be patient. The script checks that you not only have a correct <font face="Gill Sans,Helvetica,Arial">GAP</font> (at least version 4.4) installation that includes the <font face="Gill Sans,Helvetica,Arial">AutPGrp</font> package, but that the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> package and its <code>pq</code> binary interact correctly. You should see something like the following output: <p> <pre> Made dir: /tmp/testPq Testing installation of ANUPQ Package (version 3.0) The first two tests check that the pq C program compiled ok. Testing the pq binary ... OK. Testing the pq binary's stack size ... OK. The pq C program compiled ok! We test it's the right one below. The next tests check that you have the right version of GAP for version 3.0 of the ANUPQ package and that GAP is finding the right versions of the ANUPQ and AutPGrp packages. Checking GAP ... pq binary made with GAP set to: /usr/local/bin/gap Starting GAP to determine version and package availability ... GAP version (4.4.6) ... OK. GAP found ANUPQ package (version 3.0) ... good. GAP found pq binary (version 1.8) ... good. GAP found AutPGrp package (version 1.2) ... good. GAP is OK. Checking the link between the pq binary and GAP ... OK. Testing the standard presentation part of the pq binary ... OK. Doing p-group generation (final GAP/ANUPQ) test ... OK. Tests complete. Removed dir: /tmp/testPq Enjoy using your functional ANUPQ package! </pre> <p> <p> <h2><a name="SECT002">7.2 Running the pq program as a standalone</a></h2> <p><p> <a name = "I2"></a> When the <code>pq</code> program is run as a standalone it sometimes needs to call <font face="Gill Sans,Helvetica,Arial">GAP</font> to compute stabilisers of subgroups; in doing so, it first checks the value of the environment variable <code>ANUPQ_GAP_EXEC</code>, and uses that, if set, or otherwise the value of <code>GAP</code> it was compiled with, as the path for <font face="Gill Sans,Helvetica,Arial">GAP</font>. If you ran <code>testPq</code> (see Section <a href="CHAP007.htm#SECT001">Testing your ANUPQ installation</a>) and you got both <font face="Gill Sans,Helvetica,Arial">GAP</font> is <code>OK</code> and the link between the <code>pq</code> binary and <font face="Gill Sans,Helvetica,Arial">GAP</font> is <code>OK</code>, you should be fine. Otherwise heed the recommendations of the error messages you get and run the <code>testPq</code> until all tests are passed. <p> It is especially important that the <font face="Gill Sans,Helvetica,Arial">GAP</font>, whose path you gave, should know where to find the <font face="Gill Sans,Helvetica,Arial">ANUPQ</font> and <font face="Gill Sans,Helvetica,Arial">AutPGrp</font> packages. To ensure this the path should be to a shell script that invokes <font face="Gill Sans,Helvetica,Arial">GAP</font>. If you needed to install the needed packages in your own directory (because, say, you are not a system administrator) then you should create your own shell script that runs <font face="Gill Sans,Helvetica,Arial">GAP</font> with a correct setting of the <code>-l</code> option and set the path used by the <code>pq</code> binary to the path of that script. To create the script that runs <font face="Gill Sans,Helvetica,Arial">GAP</font> it is easiest to copy the system one and edit it, e.g. start by executing the following UNIX commands (skip the second step if you already have a <code>bin</code> directory; <code>you@unix></code> is your UNIX prompt): <p> <pre> you@unix> cd you@unix> mkdir bin you@unix> cd bin you@unix> which gap /usr/local/bin/gap you@unix> cp /usr/local/bin/gap mygap you@unix> chmod +x mygap </pre> <p> At the second-last step use the path of <font face="Gill Sans,Helvetica,Arial">GAP</font> returned by <code>which gap</code>. Now hopefully you will have a copy of the script that runs the system <font face="Gill Sans,Helvetica,Arial">GAP</font> in <code>mygap</code>. Now use your favourite editor to edit the <code>-l</code> part of the last line of <code>mygap</code> which should initially look something like: <p> <pre> exec $GAP_DIR/bin/$GAP_PRG -m $GAP_MEM -o 970m -l $GAP_DIR $* </pre> <p> so that it becomes (the tilde is a UNIX abbreviation for your home directory): <p> <pre> exec $GAP_DIR/bin/$GAP_PRG -m $GAP_MEM -o 970m -l "$GAP_DIR;~/gapstuff" $* </pre> <p> assuming that your personal <font face="Gill Sans,Helvetica,Arial">GAP</font> <code>pkg</code> directory is a subdirectory of <code>gapstuff</code> in your home directory. Finally, to let the <code>pq</code> program know where <font face="Gill Sans,Helvetica,Arial">GAP</font> is and also know where your <code>pkg</code> directory is that contains <font face="Gill Sans,Helvetica,Arial">ANUPQ</font>, set the environment variable <code>ANUPQ_GAP_EXEC</code> to the complete (i.e. absolute) path of your <code>mygap</code> script (do not use the tilde abbreviation), or at the <code>make</code> step that compiles <code>pq</code> do <p> <code>make GAP=</code><var>absolute-path-of-mygap</var><code></code> <p> <p> <h2><a name="SECT003">7.3 Setting the Verbosity of ANUPQ via Info and InfoANUPQ</a></h2> <p><p> <a name = "SSEC003.1"></a> <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">7.4 Utility Functions</a></h2> <p><p> <a name = "SSEC004.1"></a> <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> <a name = "SSEC004.2"></a> <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 <p> [<a href = "chapters.htm">Up</a>] [<a href ="CHAP006.htm">Previous</a>] [<a href ="CHAP00A.htm">Next</a>] [<a href = "theindex.htm">Index</a>] <P> <address>ANUPQ manual<br>Januar 2006 </address></body></html>