# First session with GAP

## Overview

Teaching:30 min

Exercises:10 minQuestions

Working with the GAP command line

Objectives

Time-saving tips and tricks

Using GAP’s help system

Basic objects and constructions in the GAP language

If GAP is installed correctly you should be able to start it. Exactly how
you start GAP will depend on your operating system and how you installed
GAP. GAP starts with the *banner* displaying information about the version of
the system and loaded components, and then displays the command line prompt
`gap>`

, for example:

```
┌───────┐ GAP 4.9.2 of 04-Jul-2018
│ GAP │ https://www.gap-system.org
└───────┘ Architecture: x86_64-apple-darwin16.7.0-default64
Configuration: gmp 6.1.2, readline
Loading the library and packages ...
Packages: AClib 1.3, Alnuth 3.1.0, AtlasRep 1.5.1, AutPGrp 1.9,
Browse 1.8.8, CRISP 1.4.4, Cryst 4.1.17, CrystCat 1.1.8,
CTblLib 1.2.2, FactInt 1.6.2, FGA 1.4.0, GAPDoc 1.6.1, IO 4.5.1,
IRREDSOL 1.4, LAGUNA 3.9.0, Polenta 1.3.8, Polycyclic 2.14,
PrimGrp 3.3.1, RadiRoot 2.8, ResClasses 4.7.1, SmallGrp 1.3,
Sophus 1.24, SpinSym 1.5, TomLib 1.2.6, TransGrp 2.0.2,
utils 0.54
Try '??help' for help. See also '?copyright', '?cite' and '?authors'
gap>
```

To leave GAP, type `quit;`

at the GAP prompt. Remember that all GAP commands,
including this one, must be finished with a semicolon! Practice entering
`quit;`

to leave GAP, and then starting a new GAP session. Before continuing, you
may wish to enter the following command to display GAP prompts and user inputs
in different colours:

```
ColorPrompt(true);
```

The easiest way to start trying GAP out is as a calculator:

```
( 1 + 2^32 ) / (1 - 2*3*107 );
```

```
-6700417
```

If you want to record what you did in a GAP session, so you can look over it
later, you can enable logging with the `LogTo`

function, like this.

```
LogTo("gap-intro.log");
```

This will create a file file `gap-intro.log`

in the current directory which
will contain all subsequent input and output that appears on your terminal.
To stop logging, you can call `LogTo`

without arguments, as in `LogTo();`

,
or leave GAP. Note that `LogTo`

blanks the file before starting, if it
already exists!

It can be useful to leave some comments in the log file in case you
return to it in the future. A comment in GAP starts with the symbol `#`

and
continues to the end of the line. You can enter the following after the
GAP prompt:

```
# GAP Software Carpentry Lesson
```

then after pressing the Return key, GAP will display a new prompt but the comment will be written to the log file.

The log file records all interaction with GAP that happens after the call
to `LogTo`

, but not before. We can repeat our calculation from above
if we want to record it as well. Instead of retyping it, we will use the Up and Down
arrow keys to scroll the *command line history*. Repeat this until you see
the formula again, then press Return (the location of the cursor in the command
line does not matter):

```
( 1 + 2^32 ) / (1 - 2*3*107 );
```

```
-6700417
```

You can also edit existing commands. Press Up once more, and then use the Left and Right arrow keys, Delete or Backspace to edit it and replace 32 by 64 (some other useful shortcuts are Ctrl-A and Ctrl-E to move the cursor to the beginning and end of the line, respectively). Now press the Return key (at any position of the cursor in the command line):

```
( 1 + 2^64 ) / (1 - 2*3*107 );
```

```
-18446744073709551617/641
```

It is useful to know that if the command line history is long, one could perform a partial search by typing the initial part of the command and using Up and Down arrow keys after that, to scroll only the lines that begin with the same string.

If you want to store a value for later use, you can assign it to a name
using `:=`

```
universe := 6*7;
```

`:=`

,`=`

and`<>`

In other languages you might be more familiar with using

`=`

, to assign variables, but GAP uses`:=`

.GAP uses

`=`

to compare if two things are the same (where other languages might use`==`

).Finally, GAP uses

`<>`

to check if two things are not equal (rather than the`!=`

you might have seen before).

Whitespace characters (i.e. Spaces, Tabs and Returns) are insignificant in GAP, except if they occur inside a string. For example, the previous input could be typed without spaces:

```
(1+2^64)/(1-2*3*107);
```

```
-18446744073709551617/641
```

Whitespace symbols are often used to format more complicated commands for better readability. For example, the following input which creates a 3×3 matrix:

```
m:=[[1,2,3],[4,5,6],[7,8,9]];
```

```
[ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ]
```

We can instead write our matrix over 3 lines. In this case, instead of the full prompt
`gap>`

, a partial prompt `>`

will be displayed until the user finishes
the input with a semicolon:

```
gap> m:=[[ 1, 2, 3 ],
> [ 4, 5, 6 ],
> [ 7, 8, 9 ]];
```

```
[ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ]
```

You can use `Display`

to pretty-print variables, including this matrix:

```
Display(m);
```

```
[ [ 1, 2, 3 ],
[ 4, 5, 6 ],
[ 7, 8, 9 ] ]
```

In general GAP functions like `LogTo`

and `Display`

are called using brackets,
which contain a (possibly empty) list of arguments.

## Functions are also GAP objects

Check what happens if you forget to add brackets, e.g. type

`LogTo;`

and`Factorial;`

We will explain the differences in these outputs later.

Here are some examples of calling other GAP functions:

```
Factorial(100);
```

```
93326215443944152681699238856266700490715968264381621468\
59296389521759999322991560894146397615651828625369792082\
7223758251185210916864000000000000000000000000
```

(the exact width of output will depend on your terminal settings),

```
Determinant(m);
```

```
0
```

and

```
Factors(2^64-1);
```

```
[ 3, 5, 17, 257, 641, 65537, 6700417 ]
```

Functions may be combined in various ways, and may be
used as arguments of other functions, for example, the
`Filtered`

function takes a list and a function, returning
all elements of the list which satisfy the function.
`IsEvenInt`

, unsurprisingly, checks if an integer is even!

```
Filtered( [2,9,6,3,4,5], IsEvenInt);
```

```
[ 2, 6, 4 ]
```

A useful time-saving feature of the GAP command-line interfaces is completion
of identifiers when the Tab key is pressed. For example, type `Fib`

and then
press the Tab key to complete the input to `Fibonacci`

:

```
Fibonacci(100);
```

```
354224848179261915075
```

In the case that a unique completion is not possible, GAP will try to perform
partial completion, and pressing the Tab key second time will display all possible
completions of the identifier. Try, for example, to enter `GroupHomomorphismByImages`

or `NaturalHomomorphismByNormalSubgroup`

using completion.

The way functions are named in GAP will hopefully help you to memorise or even guess names
of library functions. If a variable name consists of several words then the
first letter of each word is capitalised (remember that GAP is case-sensitive!).
Further details on naming conventions used in GAP are documented in the GAP
manual here.
Functions with names in `ALL_CAPITAL_LETTERS`

are internal functions not intended
for general use. Use them with extreme care!

It is important to remember that GAP is case-sensitive. For example, the following input causes an error:

```
factorial(100);
```

```
Error, Variable: 'factorial' must have a value
not in any function at line 14 of *stdin*
```

because the name of the GAP library function is `Factorial`

. Using lowercase
instead of uppercase or vice versa also affects name completion.

Now let’s consider the following problem: for a finite group *G*, calculate the
average order of its elements (that is, the sum of orders of its elements divided
by the order of the group). Where to start?

Enter `?Group`

, and you will see all help entries, starting with `Group`

:

```
┌──────────────────────────────────────────────────────────────────────────────┐
│ Choose an entry to view, 'q' for none (or use ?<nr> later): │
│[1] AutoDoc (not loaded): @Group │
│[2] loops (not loaded): group │
│[3] polycyclic: Group │
│[4] RCWA (not loaded): Group │
│[5] Tutorial: Groups and Homomorphisms │
│[6] Tutorial: Group Homomorphisms by Images │
│[7] Tutorial: group general mapping │
│[8] Tutorial: GroupHomomorphismByImages vs. GroupGeneralMappingByImages │
│[9] Tutorial: group general mapping single-valued │
│[10] Tutorial: group general mapping total │
│[11] Reference: Groups │
│[12] Reference: Group Elements │
│[13] Reference: Group Properties │
│[14] Reference: Group Homomorphisms │
│[15] Reference: GroupHomomorphismByFunction │
│[16] Reference: Group Automorphisms │
│[17] Reference: Groups of Automorphisms │
│[18] Reference: Group Actions │
│[19] Reference: Group Products │
│[20] Reference: Group Libraries │
│ > > > │
└─────────────── [ <Up>/<Down> select, <Return> show, q quit ] ────────────────┘
```

You may use arrow keys to move up and down the list, and open help pages by
pressing Return key. For this exercise, open `Tutorial: Groups and Homomorphisms`

first. Note the navigation instructions at the bottom of the screen. Look at
first two pages, then press `q`

to return to the selection menu. Next, navigate to
`Reference: Groups`

and open it. Within two first pages you will find the
function `Group`

and mentioning of `Order`

.

GAP manual comes in several formats: text is good to view in a terminal,
PDF is good for printing and HTML (especially with MathJax support) is
very efficient for exploring with a browser. If you are running GAP on your
own computer, you can set the help viewer to the default browser. If you are
running GAP on a remote machine, this (probably) will not work. (see
`?WriteGapIniFile`

on how to make this setting permanent):

```
SetHelpViewer("browser");
```

After that, invoke the help again, and see the difference!

Let’s now copy the following input from the first example of the GAP Reference
manual chapter on groups. It shows how to create permutations, and assign values
to variables. This is `Reference: Groups`

. You can select it by typing `?11`

, where
you replace `11`

with whatever number appears before `Reference: Groups`

on your machine.

If you are viewing the GAP documentation in a terminal, you might find it helpful to open two copies of GAP, one for reading documentation and one for writing code!

This guide shows how permutations in GAP are written in cycle notation, and also shows common functions which are used with groups. Also, in some places two semi-colons are used at the end of a line. This stops GAP from showing the result of a computation.

```
a:=(1,2,3);;b:=(2,3,4);;
```

Next, let `G`

be a group generated by `a`

and `b`

:

```
G:=Group(a,b);
```

```
Group([ (1,2,3), (2,3,4) ])
```

We may explore some properties of `G`

and its generators:

```
Size(G); IsAbelian(G); StructureDescription(G); Order(a);
```

```
12
false
"A4"
3
```

Our next task is to find out how to obtain a list of `G`

’s elements and their orders.
Enter `?elements`

and explore the list of help topics. After inspection,
the entry from the Tutorial does not seem relevant, but the entry from the
Reference manual is. It also explains the difference between using `AsSSortedList`

and `AsList`

. So, this is the list of elements of `G`

:

```
AsList(G);
```

```
[ (), (2,3,4), (2,4,3), (1,2)(3,4), (1,2,3), (1,2,4), (1,3,2), (1,3,4),
(1,3)(2,4), (1,4,2), (1,4,3), (1,4)(2,3) ]
```

The returned object is a *list*. We would like to assign it to a variable
to explore and reuse. We forgot to do it when we were calculating it. Of
course, we may use the command line history to restore the last command, edit
it and call again. But instead, we will use `last`

which is a special variable
holding the last result returned by GAP:

```
elts:=last;
```

```
[ (), (2,3,4), (2,4,3), (1,2)(3,4), (1,2,3), (1,2,4), (1,3,2), (1,3,4),
(1,3)(2,4), (1,4,2), (1,4,3), (1,4)(2,3) ]
```

This is a list. Lists in GAP are indexed from 1. The following commands are (hopefully!) self-explanatory:

```
gap> elts[1]; elts[3]; Length(elts);
```

```
()
(2,4,3)
12
```

## Lists are more than arrays

May contain holes or be empty

May dynamically change their length (with

`Add`

,`Append`

or direct assigment)Not required to contain objects of the same type

See more in GAP Tutorial: Lists and Records

Many functions in GAP refer to `Set`

s. A set in GAP is just a list that happens to have
no repetitions, no holes, and elements in increasing order. Here are some examples:

```
gap> IsSet([1,3,5]); IsSet([1,5,3]); IsSet([1,3,3]);
```

```
true
false
false
```

Now let us consider an interesting calculation – the average order of elements
of `G`

. There are many different ways to do this, we will consider a few of them
here.

A `for`

loop in GAP allows you to do something for every member of a collection.
The general form of a `for`

loop is:

```
for val in collection do
<something with val>
od;
```

For example, to find the average order of our group `G`

we can do.

```
s:=0;;
for g in elts do
s := s + Order(g);
od;
s/Length(elts);
```

```
31/12
```

Actually, we can just directly loop over the elements of `G`

(in general GAP
will let you loop over most types of object). We have to switch to using `Size`

instead of `Length`

, as groups don’t have a length!

```
s:=0;;
for g in G do
s := s + Order(g);
od;
s/Size(G);
```

```
31/12
```

There are other ways of looping. For example, we can instead loop over a range of integers,
and accept `elts`

like an array:

```
s:=0;;
for i in [ 1 .. Length(elts) ] do
s := s + Order( elts[i] );
od;
s/Length(elts);
```

```
31/12
```

However, often there are more compact ways of doing things. Here is a very short way:

```
Sum( List( elts, Order ) ) / Length( elts );
```

```
31/12
```

Let’s break this last part down:

`Order`

finds the order of a single permutation.`List(L,F)`

makes a new list where the function`F`

is applied to each member of the list`L`

.`Sum(L)`

adds up the members of a list`L`

.

## Which approach is best?

Compare these approaches. Which one would you prefer to use?

GAP has very helpful list manipulation tools. We will now show a few more examples.

Sometimes, GAP does not have the exact function we want.
For example, `NrMovedPoints`

gives the number of moved points of a permutation,
but what if we want to find all permutations which move `4`

points? This is where
GAP’s arrow notation comes in. `g -> e`

makes a new function which takes one argument `g`

,
and returns the value of the expression `e`

. Here are some examples:

- finding all elements of
`G`

with no fixed points:

```
Filtered( elts, g -> NrMovedPoints(g) = 4 );
```

```
[ (1,2)(3,4), (1,3)(2,4), (1,4)(2,3) ]
```

- finding a permutation in
`G`

that conjugates (1,2) to (2,3)

```
First( elts, g -> (1,2)^g = (2,3) );
```

```
(1,2,3)
```

Let’s check this (remember that in GAP permutations are multiplied from left to right!):

```
(1,2,3)^-1*(1,2)*(1,2,3)=(2,3);
```

```
true
```

- checking whether all elements of
`G`

move the point 1 to 2:

```
ForAll( elts, g -> 1^g <> 2 );
```

```
false
```

- checking whether there is an element in
`G`

which moves exactly two points:

```
ForAny( elts, g -> NrMovedPoints(g) = 2 );
```

```
false
```

## Use list operations to select from

`elts`

the stabiliser of the point 2 and the centraliser of the permutation (1,2)

`Filtered( elts, g -> 2^g = 2 );`

`Filtered( elts, g -> (1,2)^g = (1,2) );`

## Key Points

Remember that GAP is case-sensitive!

Do not panic if you see

`Error, Variable: 'FuncName' must have a value`

.Care about names of variables and functions.

Use command line editing.

Use autocompletion instead of typing names of functions and variables in full.

Use

`?`

and`??`

to view help pages.Set the default help format to HTML using

`SetHelpViewer`

.Use the

`LogTo`

function to save all GAP input and output into a text file.If calculation takes too long, press

-C to interrupt it. Read ‘A First Session with GAP’ from the GAP Tutorial.