Main Branches

Downloads  Installation  Overview  Data Libraries  Packages  Documentation  Contacts  FAQ  GAP 3 

1999 Linz Workshop on Advanced Programming in GAP 4

In collaboration with the Applied Algebra Group in Linz we held a workshop on advanced programming in GAP 4 from 6th-10th of April 1999 in Linz, Austria.

This page gives copies of the slides used by some of the speakers. They are probably not self-contained and might be insufficient without having heard the actual talks. It also contains an adapted text from the talk by Alexander Hulpke about the GAP library.

Thomas Breuer

Bettina Eick

The AutPGrp share package (TeX file)
Example of a share package
Creating new objects: Automorphisms of p-groups (TeX file)
How the AutPGrp declares a new automorphism representation.

Willem de Graaf

Using algebras in GAP (postscript file)
Constructing a new type of algebra (postscript file)

Alexander Hulpke

Conversion to GAP 4 (pdf (Acrobat) or postscript file)
Some strategies how to convert existing GAP 3 code to GAP 4.
Performance Engineering (pdf (Acrobat) or postscript file)
How to find performance bottlenecks and how to avoid them and improve performance.
External Sets (pdf (Acrobat) or postscript file)
The way GAP 4 represents $G$-sets and group operations.
GAP Tools (pdf (Acrobat) or postscript file)
Tools used internally for development.
Finding your way through the library (pdf (Acrobat) or postscript file)
A short description of the GAP library. See also its adapted version below.

Stefan Kohl

Integer factorization (zoo archive with several files)

Steve Linton

Method Selection

Werner Nickel

The GAP compiler - compiling GAP code and extending the kernel.
The talk explained how C code obtained from GAP code by using the GAP compiler is structured. Examples were discussed with respect to optimizing the C code for speed and building it into the GAP kernel.

Andrew Solomon

New Features for Semigroups in GAP (postscript file)
Introduces some of the major new features supporting semigroup theory.
Extending GAP for Dummies (postscript file)
Tips and tricks for young players.

(If your talk is not listed here but you want it here, please tell us)

How to find your way through the GAP Library?

The following text is an adapted version of the talk by Alexander Hulpke at this Summer School.

Finding your way through the GAP Library


The library contains three types of files:


Files to bootstrap the library. Library parts of the Method selection. Library declarations for some kernel objects. The help system. One might consider almost everything implemented in .g files as part of the generalized language and programming environment.


Contain all other declarations.


Contains the methods and function installations. Usually there is a correspondence between .gd and .gi files, but there are a few more .gi files if only methods get added without new declarations.

A few representation declarations are in .gi files.

Dynamic family declarations are in functions and thus in .gi files. First the .g files, then the .gd files and finally the .gi files are read. (There are few exceptions.)


Forward references become almost obsolete by first reading all declarations and then the implementations.

Everything that is not just used locally within a well defined group of files should be declared

In the few situations when a forward declaration is still needed, usually the variable is assigned to the string "2bdefined".

Within declarations or implementations the reading order becomes mostly harmless.

Exceptions concern mostly declarations of "general" things such as lists, collections and arithmetic.


The main library is contained in the lib directory. Operations that construct groups are contained in the grp directory, as well as trans (transitive groups) prim (primitive groups), small (small groups). The startup process also loads those packages that are marked as autoloadable.

All reading is triggered by init.g. It in turn reads files read1.g to read8.g that read the whole library.

If completion files are present they are read instead of read2.g ff.. In this case function bodies are left for completion.
If you change any of the files read in, you will have to either rebuild, or delete the completion files, or read in without completion (-N option).

The components: libraries of small, primitive, transitive groups are read in if present. Reading depends on the first file in the bunch to read properly. This file must call DeclareComponent to tell that the component will be available. Global variables TRANS_AVAILABLE &c. are assigned and can be use to test the existence of components.

Finally the init.g files of those packages in pkg are read that are not explicitly indicated for being omitted.

As the last step GAP prints version number (set in system.g) and architecture (set in the kernel), loaded components and packages and displays the prompt.

The read files

read1 Library bootstrap, Method selection, List functions.
read2 File functions
read3 Declarations
read4 Profiling, Help and Package mechanism
read5 Implementations
read6 Basic group constructions, perfect groups. (The grp directory)
read7 Character table declaration and implementation
read8 Overloading


We aim (if we have lots of time ...) to split the library into separate modules, similar to components and packages. Modules would interface only via clean declaration interfaces and it would be possible to update a single module separately.

A Library File

The file format may look fussy, but most of it is not compulsory. The main areas are
Title, function description and original Author(s). With older files the headers often tend not to be updated, there may be (substantial) material by other authors.
Revision Entry
A string identifying the revision, assigned to a filename component in the global record Revision. (CVS will replace everything between @(#)$Id: and $ with the string). This may be used in debugging.
Revision.arith_gd :=
The actual declarations, assignments and installations. Usually they are introduced by a ##-hook that describes the declared object. This is used by the manual builder (Tools). A letter describes what is to be declared. Some kind of indentation is recommended but personal formatting styles prevail.
End Hook
Not really needed.

Declaration functions and variable binders

Usually the library does not call NewSomething:


but constructor functions that will use the name string as the variable identifier:

Advantages are:
  • Save typing and get a nicer look
  • No danger of misprints in the name strings
  • The variables generated this way are automatically made read-only (so the famous problem: Z:=Centre(G); is gone.
A similar write protection can be achieved for arbitrary variables with BindGlobal:
  • Some bootstrap files use BIND_GLOBAL
  • Variables that are read only cannot be overwritten - a problem for development.
  • There is Reread, RereadLib &c. that will deliberately overwrite write protected variables.
  • If you must hack, there is MakeReadWriteGlobal &c.

A few special constructs

For several operations stores the value relative to a subgroups parent as an attribute. The library declaration

InParentFOA("Normalizer",IsGroup,IsGroup, NewAttribute)

may be considered a shorthand for:

DeclareOperation("NormalizerOp",IsGroup, IsGroup);
  function(G) return NormalizerOp(Parent(G),G);end);
  if G=Parent(U) then return NormalizerInParent(U);
  else return NormalizerOp(G,U);fi;end;

Similarly there is KeyDependentFOA that creates a user function like SylowSubgroup, an operation SylowSubgroupOp to compute values and a (mutable) attribute which stores computed values for the different keys.

Consequently methods are installed for operations like NormalizerOp. A similar phenomenon occurs with functions calling a NC operation.

Finding code in the library

The easiest way is to use a tool like grep.

For declarations search the .gd or .g files.

For methods search the .gi files for the operation and InstallMethod or for the installation string.

Filenames try to give an idea what the file does but are truncated to 8+3 characters for neolithic operating systems:

init, overload, package, read1, read2, read3, read4, read5 read6, read7, read8, reread
Basic Data Types:
boolean, cyclotom, ffe, function, list, permutat, record, string
Kernel Interface:
compiler, system, global, kernel, variable
Language Extension:
hash, options, wpobj
Debugging, Profiling:
assert, info, profile
Method Selection:
fampred, filter, flag, methsel, methwhy, object, oper, type
Compatibility Mode:
compat3a, compat3b, compat3c, compat3d
File Handling:
files, process, streams
debug, demo, helpbase, helpdef, helpt2t, helpview
Lists and Collections:
coll, set, combinat, listcoef, tuples
Algebra Bootstrap:
addcoset, addmagma, arith, domain, extaset, extlset, extrset, extuset, ideal, magma, mapphomo, mapping, mgmfree
Magmas, semigroups, Monoids
mgmideal, mgmring, monofree, monoid, ring, semiring, semigrp, smgideal, smgrpfre
cyclotom, ffe, field, fieldfin, fldabnum, gaussian, integer, numtheor, padics, rational, unknown, zmodnz
algfld, polyconw, polyfinf, polyrat, ratfun, ratfunul, ringpoly, upoly, upolyirr
Row Vector and Matrix operations:
matblock, matint, matrix, rvecempt, vec8bit, vecmat, zlattice
Linear Algebra:
basis, basismut, modfree, module, modulmat, modulrow, vspc, vspchom, vspcmat, vspcrow
clas, clashom, csetgrp, factgrp, ghom, gprd, grp, grplatt, grpnice, grpreps, grptbl, morpheus, oprtglat
claspcgs, csetpc, ctblpc, ghompcgs, gprdpc, grpcompl, grppc, grppcatr, grppcaut, grppccom, grppcext, grppcfp, grppcint, grppclat, grppcnrm, grppcprp, grppcrep, onecohom, pcgs, pcgscomp, pcgsind, pcgsmodu, pcgsnice, pcgspcg, pcgsspec, randiso, twocohom
Permutation groups:
clasperm, csetperm, ctblperm, ghomperm, gpprmsya, gprdperm, grpperm, grpprmcs, partitio, pcgsperm, stbc, stbcbckt, stbcrand
Group operations:
oprt, oprtpcgs, oprtperm
Matrix groups and Representations:
grpffmat, grpmat, grpramat, meataxe
word, wordass, wordrep
dt, grpfp, grpfree, pquot, quotsys, sgpres, tietze
Rewriting Systems:
rws, rwsdt, rwsgrp, rwspcclt, rwspccoc, rwspcgrp rwspcsng
Character Tables and Tables of Marks:
ctbl, ctblauto, ctblchar, ctblfuns, ctblgrp, ctbllatt, ctblmaps, ctblmoli, ctblmono, ctblpope, ctblsolv, ctblsymm, tom
algebra, algfp, alghom, algmat, algsc, idealalg
Lie Algebras:
alglie, algliess, liefam

Functions and Variables

The following rules are very rough guidelines. Certainly they are violated all over the library.

Function names are composed roughly from right to left explaining what input produces what output: PcgsByPcSequence, GeneratorsOfGroup (while GroupByGenerators does the opposite).

XOfY returns the "attribute" X of an object of kind Y.

XByY creates a new X from parameters that will be its Y.

Composita that are used in the literature are kept together (SylowSubgroup).

Further specifications (IsSolvableGroup) are appended.

Arguments are arranged from larger to smaller. So the argument ordering is

(collection, element) or
(group, subgroup) or
(matrix ring, matrix, vector, scalar).

"System" variables are UNDERSCORE_SEPARATED_UPPER. They are used for:

  • Kernel variables that are declared over with nice identifiers in the library. (For example ONE and OneOp.)
  • Kernel functions that will be installed as methods for library operations.
  • Variables and functions that are required by internal mechanisms of GAP
  • Variables to debug the kernel.

Unless these features are to be worked with these variables should not be used.

All library identifiers should be protected against overwriting, many are.

"Technical" properties (i.e. properties of objects that might depend on certain knowledge about an object and be used to improve performance but are not mathematical properties) are not declared as Property but as simple Filter.

Modifying the Library

One can keep several root paths, trying them all in order to find a file. This permits to override library files with private versions:

gap4 -l "/home/ahulpke/mygap4;/usr/local/gap4"

You cannot Read in again a library file, use Reread instead.

Ceterum ...

The impious maintain that
nonsense is normal in the Library
and that the reasonable
(and even humble and pure coherence)
is an almost miraculous exception.
JORGE LUIS BORGES: The Library of Babel