-
Notifications
You must be signed in to change notification settings - Fork 3
/
intro.xml
317 lines (275 loc) · 11.5 KB
/
intro.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
<Chapter Label="smallsemi"><Heading>Introduction</Heading>
This manual describes the <Package>Smallsemi</Package>
package (Version &VERSION;) for &GAP;.<P/>
The <Package>Smallsemi</Package> package is a data library of semigroups
of small size. It provides all semigroups with at most 8 elements as well as
various information
about these objects. The reason that semigroups of higher
orders are not included is the huge number of such objects.
The numbers of semigroups of sizes 1 to 9 are given in the table
below<Alt Not="Text"> (orders not included in the library are in
italics)</Alt>. The number of semigroups of size 10 is not known at
the time of writing.
<Table Align="|r|r|" Label="nrobjects">
<HorLine/>
<Row>
<Item>Size</Item><Item>Number of semigroups</Item>
</Row>
<HorLine/>
<HorLine/>
<Row>
<Item>1</Item><Item>1</Item>
</Row>
<HorLine/>
<Row>
<Item>2</Item><Item>4</Item>
</Row>
<HorLine/>
<Row>
<Item>3</Item><Item>18</Item>
</Row>
<HorLine/>
<Row>
<Item>4</Item><Item>126</Item>
</Row>
<HorLine/>
<Row>
<Item>5</Item><Item>1 160</Item>
</Row>
<HorLine/>
<Row>
<Item>6</Item><Item>15 973</Item>
</Row>
<HorLine/>
<Row>
<Item>7</Item><Item>836 021</Item>
</Row>
<HorLine/>
<Row>
<Item>8</Item><Item>1 843 120 128</Item>
</Row>
<HorLine/>
<Row>
<Item>9</Item><Item><E>52 989 400 714 478</E></Item>
</Row>
<HorLine/>
</Table>
The initial idea for <Package>Smallsemi</Package> was developed out of
the wish for an extensive number of examples of semigroups of moderate
size. This lead to the idea of an electronical database. As an
existing example the <Package>SmallGroups Library</Package>
<Cite Key="smallgroups"/> was an inspiration on how such a project could be
established. Unfortunately the number of semigroups is so much bigger,
and most of them bare so little structure, that new techniques to store
and handle the semigroups had to be developed. Of course, the
first step was to actually construct all the semigroups.
<P/>
In the remainder of the introduction we explain
what you need to do to install and optimize <Package>Smallsemi</Package>; see
Subsections <Ref Subsect="reqs"/> and <Ref Subsect="install"/>. <P/>
In Chapter <Ref Chap="data"/> we
explain how the semigroups where obtained, what exactly is stored and
how, and which additional properties have been precomputed. <P/>
The the types of use <Package>Smallsemi</Package> is intended for and its
limitations are described in Chapter <Ref Chap="examples"/>.
The extensive examples can be used as a quick-start guide and as something to
come back to after reading the technical details about available
functionality in the subsequent sections. <P/>
Chapter <Ref Chap="small"/> has all the information about available functions.
<Section Label="reqs"><Heading>Requirements</Heading>
This software is written for &GAP; 4. It requires an existing installation of
&GAP; in version 4.5 or higher.
<P/>
It is recommended but not necessary to have the &GAP; 4 packages
<Package>Citrus</Package> and <Package>sgpviz</Package> installed as
well. <Package>Citrus</Package> provides a wide range of functionality
for working with semigroups which is not available in the &GAP; core
system while <Package>sgpviz</Package> is recommended for its ability to
graphically represent small semigroups.
<P/>
<Subsection Label="os"><Heading>Operating System</Heading>
The current version of <Package>Smallsemi</Package> was created for
use under Unix. It will also work under Windows but only if all files
in the directory <F>smallsemi/data</F> and all of its subdirectories
are uncompressed.
See Subsection <Ref Subsect="diskspace"/> for additional comments on
working with <Package>Smallsemi</Package> under Windows.
</Subsection>
<Subsection Label="ram"><Heading>RAM</Heading>
Working with <Package>Smallsemi</Package> can be memory expensive. We
recommend to have at least 1 GB of RAM available. With less than 512
MB not all the semigroups of size 8 can be accessed.
<P/>
You should be able to use the semigroups of orders 1 through 7 having
128 MB of RAM only. If you have a system with little memory or want to
use as little memory as possible for the &GAP; process try using <Ref Func=
"UnloadSmallsemiData"/> to free memory after every access to the
library. This is likely to slow down computations though. <P/>
For further infomation on how &GAP; uses memory see <Ref Subsect="memory"/> or
<Ref Sect="Command Line Options" BookName="ref"/>.
</Subsection>
<Subsection Label="diskspace"><Heading>Disk Space</Heading>
As the data in the library is compressed, 30 MB of disk
space will be sufficient to install <Package>Smallsemi</Package> under
Unix. To use the library under Windows the data has to be
uncompressed and will then occupy approx. 1.6 GB.
<P/>
All data files are compressed using <F>gzip</F>. Under Unix &GAP; can access
the original contents of a gzipped file without uncompressing it as a whole
by using a pipe. On 32-bit systems this might fail in extreme
circumstances. In that case &GAP; has to be restarted.
This functionality is <E>not</E> currently available under
Windows (or for any other compression type).
<P/>
It should be possible to use <Package>Smallsemi</Package> under
Windows after unzipping all data files. (These are located in
the directory <F>data</F> and its subdirectories and have the file
extension <F>.gz</F>.)
</Subsection>
</Section>
<Section Label="install"><Heading>Installation and Setup</Heading>
<Subsection>
<Heading>Download and Extract <Package>Smallsemi</Package></Heading>
The installation follows standard &GAP; rules as outlined in the
following two steps; see <Ref Sect="Installing a GAP Package" BookName="ref"/>
for further details.
<Enum>
<Item> Download one of the archives <F>&ARCHIVENAME;.tar.gz</F> or
<F>&ARCHIVENAME;.tar.bz2</F> from
<Br></Br>
<URL>http://www-groups.mcs.st-andrews.ac.uk/~jamesm/smallsemi.php</URL>
</Item>
<Item> Move the archive inside a <F>pkg</F> directory. This can be
either the main <F>pkg</F> directory in your &GAP; installation or
your personal <F>pkg</F> directory.
</Item>
<Item> Complete the installation by unpacking the archive, e.g. under
Linux type <F>tar -xzf &ARCHIVENAME;.tar.gz</F> at the prompt for the
gzipped <F>tar</F>-archive.
A subdirectory <F>smallsemi</F> will be created inside the <F>pkg</F>
directory.
</Item>
</Enum>
</Subsection>
<Subsection><Heading>Contents</Heading>
In the subdirectory <F>smallsemi</F> you should find the following
files and folders:
<Table Align="ll">
<Row><Item><F>CHANGELOG</F></Item>
<Item>documents changes to previous versions</Item></Row>
<Row><Item><F>data</F></Item>
<Item>contains the data files for semigroups</Item></Row>
<Row><Item><F>doc</F></Item>
<Item>contains the documentation</Item></Row>
<Row><Item><F>gap</F></Item>
<Item>contains the &GAP; code</Item></Row>
<Row><Item><F>LICENSE</F></Item>
<Item>version 3 of the GNU General Public License</Item></Row>
<Row><Item><F>init.g</F></Item>
<Item>implementation file of <Package>Smallsemi</Package></Item></Row>
<Row><Item><F>PackageInfo.g</F></Item>
<Item>meta information about <Package>Smallsemi</Package></Item></Row>
<Row><Item><F>read.g</F></Item>
<Item>declaration file of <Package>Smallsemi</Package></Item></Row>
<Row><Item><F>README.txt</F></Item>
<Item>the README file of <Package>Smallsemi</Package></Item></Row>
<Row><Item><F>tst</F></Item>
<Item>contains test files</Item></Row>
</Table>
<!--General information about the files in a &GAP; package can be found in
<Ref Sect="The Files of a GAP Package" BookName="ext"/>.-->
</Subsection>
<Subsection Label="load"><Heading>Loading</Heading>
To use the package, start a &GAP; session and type
<C>LoadPackage("smallsemi");</C> at the &GAP; prompt. You should see
the following:
<Log><![CDATA[
gap> LoadPackage("smallsemi");
-----------------------------------------------------------------------------
Smallsemi - A library of small semigroups
by Andreas Distler & James Mitchell
For contents, type: ?Smallsemi:
Loading Smallsemi &VERSION; ...
-----------------------------------------------------------------------------
true
gap>
]]></Log>
You might want to start &GAP; with a specified amount of memory; see Subsection <Ref Subsect="memory"/>.
</Subsection>
<Subsection Label="memory"><Heading>Memory Issues</Heading>
As mentioned in Subsection <Ref Subsect="ram"/>, working with <Package>smallsemi
</Package> can be memory expensive. It is therefore necessary to either:
<Enum>
<Item>start &GAP; with 1 GB of memory (if possible), for example, by typing
<C>gap -m 1g</C>; or
</Item>
<Item>extend the amount memory used by typing <C>return;</C> in the
break-loop whenever &GAP; runs out of memory. For example,
<Log><![CDATA[
gap> s:=SmallSemigroup(8, 183244314);
#I Loading 'smallsemi' data. Please be patient.
#I Loading 'smallsemi' data.
Error, exceeded the permitted memory (`-o' command line option)
SplitString( StringFile( file ), "\n" ) called from
READ_3NIL_DATA( diag ); called from
RecoverMultiplicationTable( size, nr ) called from
<function>( <arguments> ) called from read-eval-loop
you can 'return;'
brk>
]]></Log>
</Item>
</Enum>
</Subsection>
<Subsection><Heading>Testing</Heading>
You should verify the success of the installation by running the test
file. This is done by the following command and should return a
similar output (the timings will differ depending on the speed of your
machine):
<Log><![CDATA[
gap> ReadPackage( "smallsemi", "tst/testall.g" );
Architecture: aarch64-apple-darwin21.3.0-default64-kv8
testing: smallsemi/tst/coclass.tst
2350 ms (323 ms GC) and 471MB allocated for coclass.tst
testing: smallsemi/tst/enums.tst
3452 ms (923 ms GC) and 2.69GB allocated for enums.tst
testing: smallsemi/tst/greensstar.tst
173 ms (109 ms GC) and 90.1MB allocated for greensstar.tst
testing: smallsemi/tst/properties.tst
574 ms (233 ms GC) and 213MB allocated for properties.tst
testing: smallsemi/tst/small.tst
322 ms (201 ms GC) and 174MB allocated for small.tst
testing: smallsemi/tst/smallsemi01.tst
323 ms (56 ms GC) and 128MB allocated for smallsemi01.tst
testing: smallsemi/tst/smallsemi02.tst
2079 ms (587 ms GC) and 1.23GB allocated for smallsemi02.tst
-----------------------------------
total 9273 ms (2432 ms GC) and 4.98GB allocated
0 failures in 7 files
#I No errors detected while testing
]]></Log>
</Subsection>
<Subsection><Heading>Customizing</Heading>
If you are using <Package>Smallsemi</Package> regularly you might want
to put the command <C>LoadPackage("smallsemi");</C> into your
<F>.gaprc</F> file; see <Ref Sect="The gap.ini and gaprc files"
BookName="ref"/>.
Another option is to save a workspace after
loading <Package>Smallsemi</Package> and executing the following commands
<Log><![CDATA[
gap> SmallSemigroup(7,1);; MOREDATA2TO8;;
#I smallsemi: loading data for semigroups of size 7.
#I smallsemi: loading data for semigroup properties. Please be patient.
gap> SaveWorkspace( "<filename for the workspace>" );
]]></Log>
Doing this will mean that it is not necessary to load the data from the library
every time you start a new &GAP; session; see
<Ref Sect="Saving and Loading a Workspace" BookName="ref"/>.<P/>
The size of the file containing the saved workspace will be around 76
MB. Loading this workspace is much quicker than starting a new &GAP;
session and all the data for semigroups of orders 1 through 7 is
immediately available. (If you are working under Unix you can make use
of the functionality mentioned in Subsection <Ref Subsect="diskspace"/>
and compress the workspace with gzip to roughly 10 MB.)
</Subsection>
</Section>
</Chapter>