[Top] [Up] [Previous] [Next] [Index]

# 7 Debugging and Profiling Facilities

### Sections

1. Recovery from NoMethodFound-Errors
2. ApplicableMethod
3. Tracing Methods
4. Info Functions
5. Assertions
6. Timing
7. Profiling
8. Information about the version used
9. Test Files
10. Debugging Recursion
11. Global Memory Information

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

The sections ApplicableMethod and Tracing Methods show how to get information about the methods chosen by the method selection mechanism (see chapter Method Selection in the programmer's manual).

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

## 7.1 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 quit) and that the information about the incident is no longer accessible afterwards.

- `ShowArguments( ) F`

  This function is only available within a break loop caused by a ``No Method Found''-error. It prints as a list the arguments of the operation call for which no method was found.

- `ShowArgument(` nr`) F`

  This function is only available within a break loop caused by a ``No Method Found''-error. It prints the nr-th arguments of the operation call for which no method was found. `ShowArgument` needs exactly one argument which is an integer between 0 and the number of arguments the operation was called with.

- `ShowDetails( ) F`

  This function is only available within a break loop caused by a ``No Method Found''-error. It prints the details of this error: The operation, the number of arguments, a flag which indicates whether the operation is being traced, a flag which indicates whether the operation is a constructor method, and the number of methods that refused to apply by calling `TryNextMethod`. The last number is called `Choice` and is printed as an ordinal. So if exactly k methods were found but called `TryNextMethod` and there were no more methods it says `Choice: kth`.

- `ShowMethods( ) F`
- `ShowMethods(` verbosity`) F`

  This function is only available within a break loop caused by a ``No Method Found''-error. It prints an overview about the installed methods for those arguments the operation was called with (using `ApplicableMethod`, see ApplicableMethod). The verbosity can be controlled by the optional integer parameter verbosity. The default is 2, which lists all applicable methods. With verbosity 1 `ShowMethods` only shows the number of installed methods and the methods matching, which can only be those that were already called but refused to work by calling `TryNextMethod`. With verbosity 3 not only all installed methods but also the reasons why they do not match are displayed.

- `ShowOtherMethods( ) F`
- `ShowOtherMethods(` verbosity`) F`

  This function is only available within a break loop caused by a ``No Method Found''-error. It prints an overview about the installed methods for a different number of arguments than the number of arguments the operation was called with (using `ApplicableMethod`, see ApplicableMethod). The verbosity can be controlled by the optional integer parameter verbosity. The default is 1 which lists only the number of applicable methods. With verbosity 2 `ShowOtherMethods` lists all installed methods and with verbosity 3 also the reasons, why they are not applicable. Calling `ShowOtherMethods` with verbosity 3 in this function will normally not make any sense, because the different numbers of arguments are simulated by supplying the corresponding number of ones, for which normally no reasonable methods will be installed.

  ## 7.2 ApplicableMethod

- `ApplicableMethod(` opr`,` args`[,` printlevel`] ) F`
- `ApplicableMethod(` opr`,` args`,` printlevel`,` nr`) F`
- `ApplicableMethod(` opr`,` args`,` printlevel`, "all" ) F`
- `ApplicableMethodTypes(` opr`,` args`[,` printlevel`] ) F`
- `ApplicableMethodTypes(` opr`,` args`,` printlevel`,` nr`) F`
- `ApplicableMethodTypes(` opr`,` args`,` printlevel`, "all" ) F`

  In the first form, `ApplicableMethod` returns the method of highest rank that is applicable for the operation opr with the arguments in the list args. The default printlevel is `0`. If no method is applicable then `fail` is returned.

  In the second form, if nr is a positive integer then `ApplicableMethod` returns the nr-th applicable method for the operation opr with the arguments in the list args, where the methods are ordered according to descending rank. If less than nr methods are applicable then `fail` is returned.

  If the fourth argument is the string `"all"` then `ApplicableMethod` returns a list of all applicable methods for opr with arguments args, ordered according to descending rank.

  Depending on the integer value printlevel, additional information is printed. Admissible values and their meaning are as follows.

  0
    no information,

  1
    information about the applicable method,

  2
    also information about the not applicable methods of higher rank,

  3
    also for each not applicable method the first reason why it is not applicable,

  4
    also for each not applicable method all reasons why it is not applicable.

  6
    also the function body of the selected method(s)

  When a method returned by `ApplicableMethod` is called then it returns either the desired result or the string `TRY_NEXT_METHOD`, which corresponds to a call to `TryNextMethod` in the method and means that the method selection would call the next applicable method.

  Note: The kernel provides special treatment for the infix operations `\+`, `\-`, `\*`, `\/`, `\^`, `\mod` and `\in`. For some kernel objects (notably cyclotomic numbers, finite field elements and vectors thereof) it calls kernel methods circumventing the method selection mechanism. Therefore for these operations `ApplicableMethod` may return a method which is not the kernel method actually used.

  `ApplicableMethod` does not work for constructors (for example `GeneralLinearGroupCons` is a constructor).

  The function `ApplicableMethodTypes` takes the types or filters of the arguments as argument (if only filters are given of course family predicates cannot be tested).

  ## 7.3 Tracing Methods

- `TraceMethods(` oprs`) F`

  After the call of `TraceMethods` with a list oprs of operations, whenever a method of one of the operations in oprs is called the information string used in the installation of the method is printed.

- `UntraceMethods(` oprs`) F`

  turns the tracing off for all operations in oprs.

      gap> TraceMethods( [ Size ] );
      gap> g:= Group( (1,2,3), (1,2) );;
      gap> Size( g );
      #I  Size: for a permutation group
      #I  Setter(Size): system setter
      #I  Size: system getter
      #I  Size: system getter
      6
      gap> UntraceMethods( [ Size ] );

- `TraceImmediateMethods(` flag`) F`

  If flag is true, tracing for all immediate methods is turned on. If flag is false it is turned off. (There is no facility to trace specific immediate methods.)

      gap> TraceImmediateMethods( true );
      gap> g:= Group( (1,2,3), (1,2) );;
      #I  immediate: Size
      #I  immediate: IsCyclic
      #I  immediate: IsCommutative
      #I  immediate: IsTrivial
      #I  immediate: IsStabChainViaChainSubgroup
      #I  immediate: IsChainTypeGroup
      gap> Size( g );
      #I  immediate: IsNonTrivial
      #I  immediate: Size
      #I  immediate: IsStabChainViaChainSubgroup
      #I  immediate: IsChainTypeGroup
      #I  immediate: IsNonTrivial
      #I  immediate: GeneralizedPcgs
      #I  immediate: IsPerfectGroup
      #I  immediate: IsEmpty
      6
      gap> TraceImmediateMethods( false );
      gap> UntraceMethods( [ Size ] );

  This example gives an explanation for the two calls of the ``system getter'' for `Size`. Namely, there are immediate methods that access the known size of the group. Note that the group `g` was known to be finitely generated already before the size was computed, the calls of the immediate method for `IsFinitelyGeneratedGroup` after the call of `Size` have other arguments than `g`.

  ## 7.4 Info Functions

  The `Info` 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 `InfoWarning` (see InfoWarning) which initially has level 1.

- `NewInfoClass(` name`) O`

  creates a new info class with name name.

- `DeclareInfoClass(` name`) F`

  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.

- `SetInfoLevel(` infoclass`,` level`) O`

  Sets the info level for infoclass to level.

- `InfoLevel(` infoclass`) O`

  returns the info level of infoclass.

- `Info(` infoclass`,` level`,` info`[,`moreinfo`. . .] )`

  If the info level of infoclass is at least level the remaining arguments (info and possibly moreinfo and so on) are evaluated and viewed, preceded by '#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.)

      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 `Info` call is executed without problems, since the actual level `2` of `InfoExample` causes `Info` 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 `Info` statement. As a shorthand, info classes and selectors may be combined with `+` rather than `Union`. 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

- `InfoWarning V`

  is an info class to which general warnings are sent at level 1, which is its default level. More specialised warnings are `Info`-ed at `InfoWarning` level 2, e.g. information about the autoloading of GAP packages and the initial line matched when displaying an on-line help topic.

  ## 7.5 Assertions

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

- `SetAssertionLevel(` lev`) F`

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

- `AssertionLevel() F`

  returns the current assertion level.

- `Assert(` lev`,` cond`) F`
- `Assert(` lev`,` cond`,` message`) F`

  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 `Assert` 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.

  ## 7.6 Timing

- `Runtimes() F`

  `Runtimes` 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 )

- `Runtime() F`

  `Runtime` 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 `Runtimes`, as explained above.

  See `StringTime` (StringTime) for a translation from milliseconds into hour/minute format.

- `time;`

  in the read-eval-print loop returns the time the last command took.

  ## 7.7 Profiling

  Profiling of code can be used to determine in which parts of a program how much time has been spent during runtime.

- `ProfileOperations( [`true/false`] ) F`

  When called with argument true, this function starts profiling of all operations. Old profiling information is cleared. When called with false it stops profiling of all operations. Recorded information is still kept, so you can display it even after turning the profiling off.

  When called without argument, profiling information for all profiled operations is displayed (see DisplayProfile).

- `ProfileOperationsAndMethods( [`true/false`] ) F`

  When called with argument true, this function starts profiling of all operations and their methods. Old profiling information is cleared. When called with false it stops profiling of all operations and their methods. Recorded information is still kept, so you can display it even after turning the profiling off.

  When called without argument, profiling information for all profiled operations and their methods is displayed (see DisplayProfile).

- `ProfileMethods(` ops`) F`

  starts profiling of the methods for all operations in ops.

- `UnprofileMethods(` ops`) F`

  stops profiling of the methods for all operations in ops. Recorded information is still kept, so you can display it even after turning the profiling off.

- `ProfileFunctions(` funcs`) F`

  turns profiling on for all function in funcs. You can use `ProfileGlobalFunctions` (see ProfileGlobalFunctions) to turn profiling on for all globally declared functions simultaneously.

- `UnprofileFunctions(` funcs`) F`

  turns profiling off for all function in funcs. Recorded information is still kept, so you can display it even after turning the profiling off.

- `ProfileGlobalFunctions( true ) F`
- `ProfileGlobalFunctions( false ) F`

  `ProfileGlobalFunctions(true)` turns on profiling for all functions that have been declared via `DeclareGlobalFunction`. A function call with the argument `false` turns it off again.

- `DisplayProfile( ) F`
- `DisplayProfile(` funcs`) F`

  In the first form, `DisplayProfile` displays the profiling information for profiled operations, methods and functions. If an argument funcs is given, only profiling information for the functions in funcs is given. The information for a profiled function is only displayed if the number of calls to the function or the total time spent in the function exceeds a given threshold (see PROFILETHRESHOLD).

  Profiling information is displayed in a list of lines for all functions (also operations and methods) which are profiled. For each function, ``count'' gives the number of times the function has been called. ``self'' gives the time spent in the function itself, ``child'' the time spent in profiled functions called from within this function. The list is sorted according to the total time spent, that is the sum ``self''+``child''.

- `PROFILETHRESHOLD V`

  This variable is a list [cnt ,time ] of length two. `DisplayProfile` will only display lines for functions which are called at least cnt times or whose total time (``self''+``child'') is at least time. The default value of `PROFILETHRESHOLD` is [10000,30].

- `ClearProfile( ) F`

  clears all stored profiling information.

      gap> ProfileOperationsAndMethods(true);
      gap> ConjugacyClasses(PrimitiveGroup(24,1));;
      gap> ProfileOperationsAndMethods(false);
      gap> DisplayProfile();
        count  self/ms  chld/ms  function
      [the following is excerpted from a much longer list]
         1620      170       90  CycleStructurePerm: default method
         1620       20      260  CycleStructurePerm
       114658      280        0  Size: for a list that is a collection
          287       20      290  Meth(CyclesOp)
          287        0      310  CyclesOp
           26        0      330  Size: for a conjugacy class
         2219       50      380  Size
            2        0      670  IsSubset: for two collections (loop over the ele*
           32        0      670  IsSubset
           48       10      670  IN: for a permutation, and a permutation group
            2       20      730  Meth(ClosureGroup)
            2        0      750  ClosureGroup
            1        0      780  DerivedSubgroup
            1        0      780  Meth(DerivedSubgroup)
            4        0      810  Meth(StabChainMutable)
           29        0      810  StabChainOp
            3      700      110  Meth(StabChainOp)
            1        0      820  Meth(IsSimpleGroup)
            1        0      820  Meth(IsSimple)
          552       10      830  Meth(StabChainImmutable)
           26      490      480  CentralizerOp: perm group,elm
           26        0      970  Meth(StabilizerOfExternalSet)
          107        0      970  CentralizerOp
          926       10      970  Meth(CentralizerOp)
          819     2100     2340  Meth(IN)
            1       10     4890  ConjugacyClasses: by random search
            1        0     5720  ConjugacyClasses: perm group
            2        0     5740  ConjugacyClasses
                  6920           TOTAL
      gap> DisplayProfile(StabChainOp,DerivedSubgroup); # only two functions
        count  self/ms  chld/ms  function
            1        0      780  DerivedSubgroup
           29        0      810  StabChainOp
                  6920           OTHER
                  6920           TOTAL

  Note that profiling (even the command `ProfileOperationsAndMethods(true)`) can take substantial time and GAP will perform much more slowly when profiling than when not.

- `DisplayCacheStats( ) F`

  displays statistics about the different caches used by the method selection.

- `ClearCacheStats( ) F`

  clears all statistics about the different caches used by the method selection.

  ## 7.8 Information about the version used

- `DisplayRevision( ) F`

  Displays the revision numbers of all loaded files from the library.

  ## 7.9 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.

- `ReadTest(` name-file`) O`

  reads a test file. A test file starts with a line

      gap> START_TEST("arbitrary identifier string");

  (Note that the `gap>` prompt is part of the line!) It continues by lines of GAP input and corresponding output. The input lines again start with the `gap>` prompt (or the `>` prompt if commands exceed one line). The output is exactly as would result from typing in the input interactively to a GAP session (on a screen with 80 characters per line).

  The test file stops with a line

      gap> STOP_TEST( "filename", 10000 );

  Here the string `"filename"` should give the name of the test file. The number is a proportionality factor that is used to output a ``GAPstone'' speed ranking after the file has been completely processed. For the files provided with the distribution this scaling is roughly equalized to yield the same numbers as produced by `combinat.tst`.

  ## 7.10 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 (break loops) 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 procedure

- `SetRecursionTrapInterval(` interval`) F`

  interval must be a non-negative small integer (between 0 and 228). 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

  ## 7.11 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 command line options). There are also some facilities to access information from GASMAN from GAP programs.

- `GasmanStatistics( ) F`

  `GasmanStatistics()` returns a record containing some information from the garbage collection mechanism. The record may contain up to two components: `full` and `partial`

  The `full` component will be present if a full garbage collection has taken place since GAP started. It contains information about the most recent full garbage collection. It is a record, with six components: `livebags` contains the number of bags which survived the garbage collection; `livekb` contains the total number of kilobytes occupied by those bags; `deadbags` contains the total number of bags which were reclaimed by that garbage collection and all the partial garbage collections preceeding it, since the previous full garbage collection; `deadkb` contains the total number of kilobytes occupied by those bags; `freekb` reports the total number of kilobytes available in the GAP workspace for new objects and `totalkb` the actual size of the workspace.

  These figures shouold be viewed with some caution. They are stored internally in fixed length integer formats, and `deadkb` and `deadbags` are liable to overflow if there are many partial collections before a full collection. Also, note that `livekb` and `freekb` will not usually add up to `totalkb`. The difference is essentially the space overhead of the memory management system.

  The `partial` component will be present if there has been a partial garbage collection since the last full one. It is also a record with the same six components as `full`. In this case `deadbags` and `deadkb` refer only to the number and total size of the garbage bags reclaimed in this partial garbage collection and `livebags`and `livekb` only to the numbers and total size of the young bags that were considered for garbage collection, and survived.

- `GasmanMessageStatus( ) F`
- `SetGasmanMessageStatus(` stat`) F`

  `GasmanMessageStatus()` returns one of the string "none", "full" or "all", depending on whether the garbage collector is currently set to print messages on no collections, full collections only or all collections.

  `SetGasmanMessageStatus(` stat`)` sets the garbage collector messaging level. stat should be one of the strings "none", "full" or "all".

- `GasmanLimits( ) F`

  `GasmanLimits()` returns a record with three components: `min` is the minimum workspace size as set by the `-m` command line option in kilobytes. The workspace size will never be reduced below this by the garbage collector. `max` is the maximum workspace size, as set by the '-o' command line option, also in kilobytes. If the workspace would need to grow past this point, GAP will enter a break loop to warn the user. A value of 0 indicates no limit.`kill` is the absolute maximum, set by the `-K` command line option. The workspace will never be allowed to grow past this limit.

  [Top] [Up] [Previous] [Next] [Index]

  GAP 4 manual
  May 2005