Functions in GAP

Overview

Teaching: 40 min
Exercises: 15 min

Questions

Functions as a way of code re-use

Objectives

Using command line for prototyping

Creating functions

Reading GAP code from a file

Just to remind us of our task: for a finite group G, we would like to calculate the average order of its elements (that is, the sum of the orders of its elements divided by the order of the group).

We begin with a very straightforward approach, iterating over all elements of the group in question:

S:=SymmetricGroup(10);

Sym( [ 1 .. 10 ] )

sum:=0;

for g in S do
  sum := sum + Order(g);
od;
sum/Size(S);

39020911/3628800

Now assume that we would like to save this fragment of GAP code and later repeat this calculation for some other groups. We may even reformat it to fit it into one line and use a double semicolon to suppress the output of sum:

sum:=0;; for g in S do sum := sum + Order(g); od; sum/Size(S);

39020911/3628800

Now we may easily copy and paste it into the GAP session the next time we need it. But here we see the first inconvenience: the code expects that the group in question must be stored in a variable named S, so either we have to reset S each time, or we need to edit the code:

S:=AlternatingGroup(10);

Alt( [ 1 .. 10 ] )

sum:=0;; for g in S do sum := sum + Order(g); od; sum/Size(S);

2587393/259200

This works only for rapid prototyping

one could accidentally copy and paste only a part of the code, and incomplete input may trigger a break loop;

even more dangerous: one could forget to reset sum to zero prior to the new calculation and obtain incorrect results;

the group in question may have a different variable name, so the code will have to be changed;

last, but not least: when GAP code is pasted into the interpreter, it is evaluated line by line. If you have a long file with many commands, and a syntax error is in line N, this error will be reported only when GAP completes the evaluation of all preceding lines, and that might be quite time-consuming.

That is why we need to give our GAP code more structure by organising it into functions:

functions are parsed first and may be called later;
any syntax errors will be detected in the parsing stage, and not at the time of the call;
functions may have local variables, and this prevents them being accidentally overwritten just because of reusing the same name of the variable to store something else.

The following function takes an argument G and computes the average order of its elements:

AvgOrdOfGroup := function(G)
local sum, g;
sum := 0;
for g in G do
  sum := sum + Order(g);
od;
return sum/Size(G);
end;

function( G ) ... end

Now we can apply it to another group, passing the group as an argument:

A:=AlternatingGroup(10); AvgOrdOfGroup(A); time;

Alt( [ 1 .. 10 ] )
2587393/259200
837

The example above also demonstrates time – this is the variable which stores the CPU time in milliseconds spent by the last command.

Thus, we may now create new groups and reuse AvgOrdOfGroup to calculate the average order of their elements in the same GAP session. Our next goal is to make it reusable for calculations in future sessions.

Using a text editor (for example, the one that you may have used for previous Software Carpentry lessons), create a text file called avgord.g containing the following function code and comments (a good chance to practise using them!):

#####################################################################
#
# AvgOrdOfGroup(G)
#
# Calculating the average order of an element of G, where G meant to
# be a group but in fact may be any collection of objects having
# multiplicative order
#
AvgOrdOfGroup := function(G)
local sum, g;
sum := 0;
for g in G do
  sum := sum + Order(g);
od;
return sum/Size(G);
end;

Now start a new GAP session and create another group, for example MathieuGroup(11):

M11:=MathieuGroup(11);

Group([ (1,2,3,4,5,6,7,8,9,10,11), (3,7,11,8)(4,10,5,6) ])

Clearly, AvgOrdOfGroup is not defined in this session, so an attempt to call this function results in an error:

AvgOrdOfGroup(M11);

Error, Variable: 'AvgOrdOfGroup' must have a value
not in any function at line 2 of *stdin*

To be available, it should first be loaded using the function Read. Below we assume that the file is in the current directory, so no path is needed.

Read("avgord.g");

This loads the file into GAP, and the function AvgOrdOfGroup is now available:

AvgOrdOfGroup(M11);

53131/7920

In this example of using Read, a new GAP session was started to make it clear that AvgOrdOfGroup did not exist before the call of Read and was loaded from the file. However, a file with a function like this could be read multiple times in the same GAP session (later you will see cases when re-reading a file is more complicated). Calling Read again executes all code in the file being read. This means that if the code of the function has been modified, and it has no errors (but possibly has warnings), the function will be overwritten. Never ignore the warnings!

For example, let us edit the file and replace the line

return sum/Size(G);

by the line with a deliberate syntax error:

return Float(sum/Size(G);

Now read this file with

Read("avgord.g");

and you will see an error message:

Syntax error: ) expected in avgord.g line 7
return Float(sum/Size(G);
                        ^

Since there was an error, the AvgOrdOfGroup function in our session was not redefined, and remains the same as last time it was successfully read:

Print(AvgOrdOfGroup);

function ( G )
    for g  in G  do
        sum := sum + Order( g );
    od;
    return sum / Size( G );
end

Now correct the error by adding the missing closing bracket, read the file again and recalculate the average order of an element for M11:

Read("avgord.g");
AvgOrdOfGroup(M11);

6.70846

Now let’s see an example of a warning. Since it is only a warning, it will redefine the function, and this may cause some unexpected result. To see what could happen, first edit the file to roll back the change in the type of the result (so it will return a rational instead of a float), and then comment out two lines as follows:

AvgOrdOfGroup := function(G)
# local sum, g;
# sum := 0;
for g in G do
  sum := sum + Order(g);
od;
return sum/Size(G);
end;

Now, when you read the file, you will see warnings:

Read("avgord.g");

Syntax error: warning: unbound global variable in avgord.g line 4
for g in G do
       ^
Syntax error: warning: unbound global variable in avgord.g line 5
  sum := sum + Order(g);
       ^
Syntax error: warning: unbound global variable in avgord.g line 5
  sum := sum + Order(g);
             ^
Syntax error: warning: unbound global variable in avgord.g line 7
return sum/Size(G);
          ^

These warnings mean that because g and sum are not declared as local variables, GAP will expect them to be global variables at the time when the function will be called. Because they did not exist when Read was called, a warning was displayed. However, if they happened to exist by that time, there would be no warning, and any call to AvgOrdOfGroup would overwrite them! This shows how important it is to declare local variables. Let us investigate what happened in slightly more detail:

The function is now redefined, as we can see from its output (or can inspect with PageSource(AvgOrdOfGroup) which will also display any comments):

Print(AvgOrdOfGroup);

function ( G )
    for g in G  do
        sum := sum + Order( g );
    od;
    return sum / Size( G );
end

but an attempt to run it results in a break loop:

AvgOrdOfGroup(M11);

Error, Variable: 'sum' must have an assigned value in
  sum := sum + Order( g ); called from
<function "AvgOrdOfGroup">( <arguments> )
 called from read-eval loop at line 24 of *stdin*
you can 'return;' after assigning a value
brk>

which you can exit using quit;.

What happens next demonstrates how things may go wrong:

sum:=2^64; g:=[1];

18446744073709551616
[ 1 ]

AvgOrdOfGroup(M11);

18446744073709604747/7920

sum; g;

18446744073709604747
(1,2)(3,10,5,6,8,9)(4,7,11)

Now, before reading the next part of the lesson, please revert the last change by uncommenting the two commented lines, so that you have initial version of AvgOrdOfGroup in the file avgord.g again:

AvgOrdOfGroup := function(G)
local sum, g;
sum := 0;
for g in G do
  sum := sum + Order(g);
od;
return sum/Size(G);
end;

Paths

It is important to know how to specify paths to files in all operating systems and where to find your home and current directory.

It is useful to know that path and filename completion is activated by pressing Esc two or four times.

Key Points

Command line is good for prototyping; functions are good for repeated calculations.

Informative function names and comments will make code more readable to your future self and to others.

Beware of undeclared local variables!

previous episode

Programming with GAP

next episode

Functions in GAP

Overview

This works only for rapid prototyping

Paths

Key Points

previous episode

next episode