1 The ANUPQ package
2 -----------------
3
4The ANUPQ package is a GAP4 interface with the ANU pq C program written
5by Eamonn O'Brien. The ANU pq C program provides access to
6implementations of the following algorithms:
7
81. A p-quotient algorithm to compute a power-commutator presentation for
9a group of prime power order. The algorithm implemented here is based on
10that described in Newman and O'Brien (1996), Havas and Newman (1980), and
11papers referred to there. Another description of the algorithm appears in
12Vaughan-Lee (1990). A FORTRAN implementation of this algorithm was
13programmed by Alford and Havas. The basic data structures of that
14implementation are retained.
15
162. A p-group generation algorithm to generate descriptions of groups of
17prime power order. The algorithm implemented here is based on the
18algorithms described in Newman (1977) and O'Brien (1990). A FORTRAN
19implementation of this algorithm was earlier developed by Newman and
20O'Brien.
21
223. A standard presentation algorithm used to compute a canonical
23power-commutator presentation of a p-group. The algorithm implemented
24here is described in O'Brien (1994).
25
264. An algorithm which can be used to compute the automorphism group of a
27p-group. The algorithm implemented here is described in O'Brien (1994).
28
29The following section describes the installation of the ANUPQ package. A
30description of the functions available in the ANUPQ package is given in
31the package manual in the doc directory. For details about the
32implementation and the standalone version see the README and guide.dvi in
33the standalone-doc directory.
34
35 Obtaining the ANUPQ package
36 ---------------------------
37
38Note that, owing to its C code component, the ANUPQ package can be
39installed under UNIX or in environments similar to UNIX. In particular
40it is known to work on Linux and Mac OS X, and also on Windows equipped
41with cygwin.
42
43You can download `anupq-XXX.tar.gz' (where `XXX' is the package version
44number) from the home page for the ANUPQ package
45
46https://gap-packages.github.io/anupq/
47
48or via the GAP web site
49
50https://www.gap-system.org/Packages/anupq.html
51
52 Installing the ANUPQ package
53 ----------------------------
54
55To install the ANUPQ package, move the file `anupq-<XXX>.tar.gz' into the
56`pkg' directory in which you plan to install ANUPQ. Usually, this will be
57the directory `pkg' in the hierarchy of your version of GAP 4. (However,
58it is also possible to keep an additional `pkg' directory in your private
59directories, see section "ref:Installing GAP Packages" of the GAP 4
60reference manual for details on how to do this.)
61
62ANUPQ package requires at least GAP 4.8 and AutPGrp 1.5, although we
63recommend using the most recent versions of each. ANUPQ optionally
64supports using GMP for large integer support.
65
66Unpack the archive `anupq-<XXX>.tar.gz' in the `pkg' directory.
67
68Change directory to the newly created `anupq' directory. Now you need to
69call `configure'. If you installed ANUPQ into the main `pkg' directory,
70simply do this:
71
72 ./configure
73
74If you installed ANUPQ in another directory than the usual 'pkg'
75subdirectory, do
76
77 ./configure --with-gaproot=path
78
79where 'path' is a path to the GAP home directory. See
80
81 ./configure --help
82
83for further options.
84
85Afterwards, you can simply call
86
87 make
88
89to compile the binary and to install it in the appropriate place.
90
91The path of GAP (see *Note* below) used by the `pq' binary (the value
92`GAP' is set to in the `make' command) may be over-ridden by setting the
93environment variable `ANUPQ_GAP_EXEC'. These values are only of interest
94when the `pq' program is run as a standalone; however, the `testPq'
95script assumes you have set one of these correctly (see Section "Testing
96your ANUPQ installation"). When the `pq' program is started from GAP
97communication occurs via an iostream, so that the `pq' binary does not
98actually need to know a valid path for GAP is this case.
99
100*Note.* By ``path of GAP'' we mean the path of the command used to invoke
101GAP (which should be a script, e.g. the `gap.sh' script generated in the
102`bin' directory for the version of GAP when GAP was compiled). The usual
103strategy is to copy the `gap.sh' script to a standard location, e.g.
104`/usr/local/bin/gap'. It is a mistake to copy the GAP executable `gap'
105(in a directory with name of form `bin/<compile-platform>') to the
106standard location, since direct invocation of the executable results in
107GAP starting without being able to find its own library (a fatal error).
108
109 The ANUPQ package documentation
110 -------------------------------
111
112The ANUPQ package documentation source files, now XML (for GAPDoc), are
113found in the `doc' directory. There you should also find `manual.pdf', a
114PDF version of the manual, and various HTML files constituting the HTML
115version of the manual (actually there are two HTML versions of the manual,
116the one with `_mj' files have MathJax enabled). The initial page for
117the HTML version of the manual is `chap0.html' (or `chap0_mj.html' with
118MathJax enabled), but you can toggle between the versions, once you have
119opened either, with your favourite browser.
120
121 Testing the ANUPQ package installation
122 --------------------------------------
123
124Now it is time to test the installation. After doing `configure' and
125`make' you will have a `testPq' script. The script assumes that, if the
126environment variable `ANUPQ_GAP_EXEC' is set, it is a correct path for
127GAP, or otherwise that the `make' call that compiled the `pq' program set
128`GAP' to a correct path for GAP (see Section "Running the pq program as a
129standalone" in the ANUPQ package manual for more details). To run the
130tests, just type:
131
132 ./testPq
133
134Some of the tests the script runs take a while. Please be patient.
135The output you see should be something like the following:
136
137 Made dir: /tmp/testPq
138 Testing installation of ANUPQ Package (version 3.2.1)
139
140 The first two tests check that the pq C program compiled ok.
141 Testing the pq binary ... OK.
142 Testing the pq binary's stack size ... OK.
143 The pq C program compiled ok! We test it's the right one below.
144
145 The next tests check that you have the right version of GAP
146 for version 3.1 of the ANUPQ package and that GAP is finding
147 the right versions of the ANUPQ and AutPGrp packages.
148
149 Checking GAP ...
150 pq binary made with GAP set to: /usr/local/bin/gap
151 Starting GAP to determine version and package availability ...
152 GAP version (4.10.1) ... OK.
153 GAP found ANUPQ package (version 3.2.1) ... good.
154 GAP found pq binary (version 1.9) ... good.
155 GAP found AutPGrp package (version 1.5) ... good.
156 GAP is OK.
157
158 Checking the link between the pq binary and GAP ... OK.
159 Testing the standard presentation part of the pq binary ... OK.
160 Doing p-group generation (final GAP/ANUPQ) test ... OK.
161 Tests complete.
162 Removed dir: /tmp/testPq
163 Enjoy using your functional ANUPQ package!
164
165 Bug reports
166 -----------
167
168For bug reports, feature requests and suggestions, please refer to
169
170 https://github.com/gap-packages/anupq/issues
171
172When sending a bug report, remember we will need to be able to reproduce
173the problem; so please include:
174
175 * The version of GAP you are using; either look at the header when
176 you start up GAP, or at the gap> prompt type: GAPInfo.Version;
177 * The operating system you are using e.g. Linux, Mac OS X, Windows,
178 FreeBSD, Solaris...
179 * The compiler you used to compile `pq' and the options you used.
180 Type: gcc -v or: cc -version, and look in Makefile for the
181 value of CC to find out.
182 * A script, either in GAP or standalone `pq', that demonstrates the
183 bug, along with a description of why it's a bug (e.g. by adding
184 comments to the script - recall, comments, both in GAP or
185 standalone `pq', begin with a #).
186