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.
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.
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).
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: 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: 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
.
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.
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.
Runtime() F
Runtime
returns the time spent by GAP in milliseconds as an integer.
This is usually the cpu time, i.e., not the wall clock time.
Also time spent by subprocesses of GAP (see Process) is not counted.
time;
in the read-eval-print loop returns the time the last command took.
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.
DisplayRevision( ) F
Displays the revision numbers of all loaded files from the library.
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
.
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
[Top] [Up] [Previous] [Next] [Index]
GAP 4 manual
May 2002