Debugging and Profiling Facilities

This chapter describes some functions that are useful mainly for debugging and profiling purposes.

Probably the most important debugging tool in &GAP; is the break loop (see Section ) which can be entered by putting an statement into your code or by hitting Control-C. In the break loop one can inspect variables, stack traces and issue commands as usual in an interactive &GAP; session. See also the , and functions.

Sections and show how to get information about the methods chosen by the method selection mechanism (see chapter ).

The final sections describe functions for collecting statistics about computations (see , ).

Recovery from NoMethodFound-Errors

When the method selection fails because there is no applicable method, an error as in the following example occurs and a break loop is entered:

gap> IsNormal(2,2); Error, no method found! For debugging hints type ?Recovery from NoMethodFound Error, no 1st choice method found for `IsNormal' on 2 arguments called from <function>( <arguments> ) called from read-eval-loop Entering break read-eval-print loop ... you can 'quit;' to quit to outer loop, or you can 'return;' to continue brk>

This only says, that the method selection tried to find a method for IsNormal on two arguments and failed. In this situation it is crucial to find out, why this happened. Therefore there are a few functions which can display further information. Note that you can leave the break loop by the quit command (see ) and that the information about the incident is no longer accessible afterwards.

<#Include Label="ShowArguments"> <#Include Label="ShowArgument"> <#Include Label="ShowDetails"> <#Include Label="ShowMethods"> <#Include Label="ShowOtherMethods">

Inspecting Applicable Methods
<#Include Label="ApplicableMethod">

Tracing Methods
<#Include Label="TraceMethods"> <#Include Label="UntraceMethods"> <#Include Label="TraceImmediateMethods">

Info Functions

The mechanism permits operations to display intermediate results or information about the progress of the algorithms. Information is always given according to one or more info classes. Each of the info classes defined in the &GAP; library usually covers a certain range of algorithms, so for example InfoLattice covers all the cyclic extension algorithms for the computation of a subgroup lattice.

The amount of information to be displayed can be specified by the user for each info class separately by a level, the higher the level the more information will be displayed. Ab initio all info classes have level zero except which initially has level 1.

creates a new info class with name name.

creates a new info class with name name and binds it to the global variable name. The variable must previously be writable, and is made readonly by this function.

Sets the info level for infoclass to level.

returns the info level of infoclass.

If the info level of infoclass is at least level the remaining arguments, info and possibly moreinfo and so on, are evaluated. (Technically, is a keyword and not a function.)

By default, they are viewed, preceded by the string "#I " and followed by a newline. Otherwise the third and subsequent arguments are not evaluated. (The latter can save substantial time when displaying difficult results.)

The behaviour can be customized with .

gap> InfoExample:=NewInfoClass("InfoExample");; gap> Info(InfoExample,1,"one");Info(InfoExample,2,"two"); gap> SetInfoLevel(InfoExample,1); gap> Info(InfoExample,1,"one");Info(InfoExample,2,"two"); #I one gap> SetInfoLevel(InfoExample,2); gap> Info(InfoExample,1,"one");Info(InfoExample,2,"two"); #I one #I two gap> InfoLevel(InfoExample); 2 gap> Info(InfoExample,3,Length(Combinations([1..9999])));

Note that the last call is executed without problems, since the actual level 2 of InfoExample causes to ignore the last argument, which prevents Length(Combinations([1..9999])) from being evaluated; note that an evaluation would be impossible due to memory restrictions.

A set of info classes (called an info selector) may be passed to a single statement. As a shorthand, info classes and selectors may be combined with + rather than . In this case, the message is triggered if the level of any of the classes is high enough.

gap> InfoExample:=NewInfoClass("InfoExample");; gap> SetInfoLevel(InfoExample,0); gap> Info(InfoExample + InfoWarning, 1, "hello"); #I hello gap> Info(InfoExample + InfoWarning, 2, "hello"); gap> SetInfoLevel(InfoExample,2); gap> Info(InfoExample + InfoWarning, 2, "hello"); #I hello gap> InfoLevel(InfoWarning); 1
Customizing statements
nothing
This allows to customize what happens in an Info(infoclass, level, ...) statement.

In the first function handler must be a function with three arguments infoclass, level, list. Here list is the list containing the third to last argument of the call.

The default handler is the function DefaultInfoHandler. DefaultInfoHandler It prints "#I ", then the third and further arguments of the info statement, and finally a "\n".

If the first argument of an statement is a sum of Info classes, the handler of the first summand is used.

The file or stream to which statements for individual classes print can be changed with . The initial default for all classes is the string "*Print*" which means the current output file. The default can be changed with . The argument out can be a filename or an open stream, the special names "*Print*", "*errout* and "*stdout* are also recognized.

For example, SetDefaultInfoOutput("*errout*"); would send output to standard error, which can be interesting if &GAP;s output is redirected.
is an info class to which general warnings are sent at level 1, which is its default level. More specialised warnings are shown via calls of at level 2, e.g. information about the autoloading of &GAP; packages and the initial line matched when displaying an on-line help topic.
Assertions

Assertions are used to find errors in algorithms. They test whether intermediate results conform to required conditions and issue an error if not.

assigns the global assertion level to lev. By default it is zero.

returns the current assertion level.

With two arguments, if the global assertion level is at least lev, condition cond is tested and if it does not return true an error is raised. Thus Assert(lev, cond) is equivalent to the code if AssertionLevel() >= lev and not <cond> then Error("Assertion failure"); fi;

With the message argument form of the statement, if the global assertion level is at least lev, condition cond is tested and if it does not return true then message is evaluated and printed.

Assertions are used at various places in the library. Thus turning assertions on can slow code execution significantly.
Timing
returns a record with components bound to integers or fail. Each integer is the cpu time (processor time) in milliseconds spent by &GAP; in a certain status:

user_time
cpu time spent with &GAP; functions (without child processes).
system_time
cpu time spent in system calls, e.g., file access (fail if not available).
user_time_children
cpu time spent in child processes (fail if not available).
system_time_children
cpu time spent in system calls by child processes (fail if not available).

Note that this function is not fully supported on all systems. Only the user_time component is (and may on some systems include the system time).

The following example demonstrates tasks which contribute to the different time components:

gap> Runtimes(); # after startup rec( user_time := 3980, system_time := 60, user_time_children := 0, system_time_children := 0 ) gap> Exec("cat /usr/bin/*||wc"); # child process with a lot of file access 893799 7551659 200928302 gap> Runtimes(); rec( user_time := 3990, system_time := 60, user_time_children := 1590, system_time_children := 600 ) gap> a:=0;;for i in [1..100000000] do a:=a+1; od; # GAP user time gap> Runtimes(); rec( user_time := 12980, system_time := 70, user_time_children := 1590, system_time_children := 600 ) gap> ?blabla # first call of help, a lot of file access Help: no matching entry found gap> Runtimes(); rec( user_time := 13500, system_time := 440, user_time_children := 1590, system_time_children := 600 )
returns the time spent by &GAP; in milliseconds as an integer. It is the same as the value of the user_time component given by , as explained above.

See for a translation from milliseconds into hour/minute format.
In the read-eval-print loop, stores the time the last command took.
Profiling

Profiling of code can be used to determine in which parts of a program how much time has been spent and how much memory has been allocated during runtime. The idea is that first one switches on profiling for those &GAP; functions the performance of which one wants to check, then one runs some &GAP; computations, then one looks at the profile information collected during these computations, then one runs more computations (perhaps clearing all profile information before, see ), and finally one switches off profiling.

For switching on and off profiling, &GAP; supports entering a list of functions (see , ) or a list of operations whose methods shall be (un)profiled (, ), and can be used to show profile information about functions in a given list.

Besides these functions, , , and can be used for switching on or off profiling for all global functions, operations, and operations together with all their methods, respectively, and for showing profile information about these functions.

Note that &GAP; will perform more slowly when profiling than when not.

<#Include Label="ProfileGlobalFunctions"> <#Include Label="ProfileOperations"> <#Include Label="ProfileOperationsAndMethods">

<#Include Label="ProfileFunctions"> <#Include Label="UnprofileFunctions"> <#Include Label="ProfileMethods"> <#Include Label="UnprofileMethods">

<#Include Label="DisplayProfile"> <#Include Label="ClearProfile">

An Example of Profiling

Let us suppose we want to get information about the computation of the conjugacy classes of a certain permutation group. For that, first we create the group, then we start profiling for all global functions and for all operations and their methods, then we compute the conjugacy classes, and then we stop profiling.

gap> g:= PrimitiveGroup( 24, 1 );; gap> ProfileGlobalFunctions( true ); gap> ProfileOperationsAndMethods( true ); gap> ConjugacyClasses( g );; gap> ProfileGlobalFunctions( false ); gap> ProfileOperationsAndMethods( false );

Now the profile information is available. We can list the information for all profiled functions with .

gap> DisplayProfile(); count self/ms chld/ms stor/kb chld/kb package function 17647 0 0 275 0 GAP BasePoint 10230 0 0 226 0 (oprt.) ShallowCopy 10139 0 0 0 0 PositionSortedOp: for* 10001 0 0 688 0 UniteSet: for two int* 10001 8 0 28 688 (oprt.) UniteSet 14751 12 0 0 0 =: for two families: * 10830 8 4 182 276 GAP Concatenation 2700 20 12 313 55 GAP AddRefinement 2444 28 4 3924 317 GAP ConjugateStabChain 4368 0 32 7 714 (oprt.) Size 2174 32 4 1030 116 GAP List 585 4 32 45 742 GAP RRefine 1532 32 8 194 56 GAP AddGeneratorsExtendSc* 1221 8 32 349 420 GAP Partition 185309 28 12 0 0 (oprt.) Length 336 4 40 95 817 GAP ExtendSeriesPermGroup 4 28 20 488 454 (oprt.) Sortex 2798 0 52 54 944 GAP StabChainForcePoint 560 4 48 83 628 GAP StabChainSwap 432 16 40 259 461 GAP SubmagmaWithInversesNC 185553 48 8 915 94 (oprt.) Add 26 0 64 0 2023 (oprt.) CentralizerOp 26 0 64 0 2023 GAP CentralizerOp: perm g* 26 0 64 0 2023 GAP Centralizer: try to e* 152 4 64 0 2024 (oprt.) Centralizer 1605 0 68 0 2032 (oprt.) StabilizerOfExternalS* 26 0 68 0 2024 GAP Meth(StabilizerOfExte* 382 0 96 69 1922 GAP TryPcgsPermGroup 5130 4 96 309 3165 GAP ForAll 7980 24 116 330 6434 GAP ChangeStabChain 12076 12 136 351 6478 GAP ProcessFixpoint 192 0 148 4 3029 GAP StabChainMutable: cal* 2208 4 148 3 3083 (oprt.) StabChainMutable 217 0 160 0 3177 (oprt.) StabChainOp 217 12 148 60 3117 GAP StabChainOp: group an* 216 36 464 334 12546 GAP PartitionBacktrack 1479 12 668 566 18474 GAP RepOpElmTuplesPermGro* 1453 12 684 56 18460 GAP in: perm class rep 126 0 728 13 19233 GAP ConjugacyClassesTry 1 0 736 0 19671 GAP ConjugacyClassesByRan* 2 0 736 2 19678 (oprt.) ConjugacyClasses 1 0 736 0 19675 GAP ConjugacyClasses: per* 13400 1164 0 0 0 (oprt.) Position 484 12052 OTHER 2048 23319 TOTAL

We can restrict the list to global functions with .

gap> ProfileGlobalFunctions(); count self/ms chld/ms stor/kb chld/kb package function 17647 0 0 275 0 GAP BasePoint 10830 8 4 182 276 GAP Concatenation 2700 20 12 313 55 GAP AddRefinement 2444 28 4 3924 317 GAP ConjugateStabChain 2174 32 4 1030 116 GAP List 585 4 32 45 742 GAP RRefine 1532 32 8 194 56 GAP AddGeneratorsExtendSc* 1221 8 32 349 420 GAP Partition 336 4 40 95 817 GAP ExtendSeriesPermGroup 2798 0 52 54 944 GAP StabChainForcePoint 560 4 48 83 628 GAP StabChainSwap 432 16 40 259 461 GAP SubmagmaWithInversesNC 382 0 96 69 1922 GAP TryPcgsPermGroup 5130 4 96 309 3165 GAP ForAll 7980 24 116 330 6434 GAP ChangeStabChain 12076 12 136 351 6478 GAP ProcessFixpoint 216 36 464 334 12546 GAP PartitionBacktrack 1479 12 668 566 18474 GAP RepOpElmTuplesPermGro* 126 0 728 13 19233 GAP ConjugacyClassesTry 1 0 736 0 19671 GAP ConjugacyClassesByRan* 1804 14536 OTHER 2048 23319 TOTAL

We can restrict the list to operations with .

gap> ProfileOperations(); count self/ms chld/ms stor/kb chld/kb package function 10230 0 0 226 0 (oprt.) ShallowCopy 10001 8 0 28 688 (oprt.) UniteSet 4368 0 32 7 714 (oprt.) Size 185309 28 12 0 0 (oprt.) Length 4 28 20 488 454 (oprt.) Sortex 185553 48 8 915 94 (oprt.) Add 26 0 64 0 2023 (oprt.) CentralizerOp 152 4 64 0 2024 (oprt.) Centralizer 1605 0 68 0 2032 (oprt.) StabilizerOfExternalS* 2208 4 148 3 3083 (oprt.) StabChainMutable 217 0 160 0 3177 (oprt.) StabChainOp 2 0 736 2 19678 (oprt.) ConjugacyClasses 13400 1164 0 0 0 (oprt.) Position 764 21646 OTHER 2048 23319 TOTAL

We can restrict the list to operations and their methods with .

gap> ProfileOperationsAndMethods(); count self/ms chld/ms stor/kb chld/kb package function 10230 0 0 226 0 (oprt.) ShallowCopy 10139 0 0 0 0 PositionSortedOp: for* 10001 0 0 688 0 UniteSet: for two int* 10001 8 0 28 688 (oprt.) UniteSet 14751 12 0 0 0 =: for two families: * 4368 0 32 7 714 (oprt.) Size 185309 28 12 0 0 (oprt.) Length 4 28 20 488 454 (oprt.) Sortex 185553 48 8 915 94 (oprt.) Add 26 0 64 0 2023 (oprt.) CentralizerOp 26 0 64 0 2023 GAP CentralizerOp: perm g* 26 0 64 0 2023 GAP Centralizer: try to e* 152 4 64 0 2024 (oprt.) Centralizer 1605 0 68 0 2032 (oprt.) StabilizerOfExternalS* 26 0 68 0 2024 GAP Meth(StabilizerOfExte* 192 0 148 4 3029 GAP StabChainMutable: cal* 2208 4 148 3 3083 (oprt.) StabChainMutable 217 0 160 0 3177 (oprt.) StabChainOp 217 12 148 60 3117 GAP StabChainOp: group an* 1453 12 684 56 18460 GAP in: perm class rep 2 0 736 2 19678 (oprt.) ConjugacyClasses 1 0 736 0 19675 GAP ConjugacyClasses: per* 13400 1164 0 0 0 (oprt.) Position 728 20834 OTHER 2048 23319 TOTAL

Finally, we can restrict the list to explicitly given functions with , by entering the list of functions as an argument.

gap> DisplayProfile( [ StabChainOp, Centralizer ] ); count self/ms chld/ms stor/kb chld/kb package function 152 4 64 0 2024 (oprt.) Centralizer 217 0 160 0 3177 (oprt.) StabChainOp 2044 23319 OTHER 2048 23319 TOTAL
<#Include Label="DisplayCacheStats"> <#Include Label="ClearCacheStats">

Information about the version used
GAPInfo.Version

The global variable GAPInfo.Version (see ) contains the version number of the version of &GAP;. Its value can be checked other version number using .

To produce sample citations for the used version of &GAP; or for a package available in this &GAP; installation, use .

If you wish to report a problem to &GAP; Support or &GAP; Forum, it may be useful to not only report the version used, but also to include the &GAP; banner displays the information about the architecture for which the &GAP; binary is built, used libraries and loaded packages.
Test Files

Test files are used to check that &GAP; produces correct results in certain computations. A selection of test files for the library can be found in the tst directory of the &GAP; distribution.

<#Include Label="ReadTest"> <#Include Label="StartStopTest">

<#Include Label="[1]{testinstall.g}">

test file GAP4stones time(msec) ------------------------------------------- testing: ................/gap4r5/tst/zlattice.tst zlattice.tst 0 0 testing: ................/gap4r5/tst/gaussian.tst gaussian.tst 0 10 [ further lines deleted ]
<#Include Label="[1]{testall.g}">

<#Include Label="Test">

Debugging Recursion

The &GAP; interpreter monitors the level of nesting of &GAP; functions during execution. By default, whenever this nesting reaches a multiple of 5000, &GAP; enters a break loop () allowing you to terminate the calculation, or enter Return; to continue it.

gap> dive:= function(depth) if depth>1 then dive(depth-1); fi; return; end; function( depth ) ... end gap> dive(100); gap> OnBreak:= function() Where(1); end; # shorter traceback function( ) ... end gap> dive(6000); recursion depth trap (5000) at dive( depth - 1 ); called from dive( depth - 1 ); called from ... Entering break read-eval-print loop ... you can 'quit;' to quit to outer loop, or you may 'return;' to continue brk> return; gap> dive(11000); recursion depth trap (5000) at dive( depth - 1 ); called from dive( depth - 1 ); called from ... Entering break read-eval-print loop ... you can 'quit;' to quit to outer loop, or you may 'return;' to continue brk> return; recursion depth trap (10000) at dive( depth - 1 ); called from dive( depth - 1 ); called from ... Entering break read-eval-print loop ... you can 'quit;' to quit to outer loop, or you may 'return;' to continue brk> return; gap>

This behaviour can be controlled using the following procedure.

interval must be a non-negative small integer (between 0 and 2^{28}). An interval of 0 suppresses the monitoring of recursion altogether. In this case excessive recursion may cause &GAP; to crash.

gap> dive:= function(depth) if depth>1 then dive(depth-1); fi; return; end; function( depth ) ... end gap> SetRecursionTrapInterval(1000); gap> dive(2500); recursion depth trap (1000) at dive( depth - 1 ); called from dive( depth - 1 ); called from ... Entering break read-eval-print loop ... you can 'quit;' to quit to outer loop, or you may 'return;' to continue brk> return; recursion depth trap (2000) at dive( depth - 1 ); called from dive( depth - 1 ); called from ... Entering break read-eval-print loop ... you can 'quit;' to quit to outer loop, or you may 'return;' to continue brk> return; gap> SetRecursionTrapInterval(-1); SetRecursionTrapInterval( <interval> ): <interval> must be a non-negative smal\ l integer not in any function Entering break read-eval-print loop ... you can 'quit;' to quit to outer loop, or you can replace <interval> via 'return <interval>;' to continue brk> return (); SetRecursionTrapInterval( <interval> ): <interval> must be a non-negative smal\ l integer not in any function Entering break read-eval-print loop ... you can 'quit;' to quit to outer loop, or you can replace <interval> via 'return <interval>;' to continue brk> return 0; gap> dive(20000); gap> dive(2000000); Segmentation fault
Global Memory Information

The &GAP; environment provides automatic memory management, so that the programmer does not need to concern themselves with allocating space for objects, or recovering space when objects are no longer needed. The component of the kernel which provides this is called GASMAN (&GAP; Storage MANager). Messages reporting garbage collections performed by GASMAN can be switched on by the -g command line option (see section ). There are also some facilities to access information from GASMAN from &GAP; programs.

<#Include Label="GasmanStatistics"> <#Include Label="GasmanMessageStatus"> <#Include Label="GasmanLimits">