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 6.4) which can be entered by putting an Error (6.6-1) 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 DownEnv (6.5-1), UpEnv (6.5-1) and Where (6.4-5) functions.
Sections 7.2 and 7.3 show how to get information about the methods chosen by the method selection mechanism (see chapter 78).
The final sections describe functions for collecting statistics about computations (see Runtime (7.6-2), 7.7).
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 6.4-1) and that the information about the incident is no longer accessible afterwards.
‣ ShowArguments( ) | ( function ) |
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 ) | ( function ) |
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( ) | ( function ) |
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 (78.4-1). The last number is called Choice and is printed as an ordinal. So if exactly k methods were found but called TryNextMethod (78.4-1) and there were no more methods it says Choice: kth.
‣ ShowMethods( [verbosity] ) | ( function ) |
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 7.2. 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 (78.4-1). With verbosity 3 not only all installed methods but also the reasons why they do not match are displayed.
‣ ShowOtherMethods( [verbosity] ) | ( function ) |
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 7.2. 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[, nr]] ) | ( function ) |
‣ ApplicableMethodTypes( opr, args[, printlevel[, nr]] ) | ( function ) |
Called with two arguments, 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.
If a positive integer is given as the fourth argument nr 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 nr 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.
no information,
information about the applicable method,
also information about the not applicable methods of higher rank,
also for each not applicable method the first reason why it is not applicable,
also for each not applicable method all reasons why it is not applicable.
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 (78.4-1) in the method and means that the method selection would call the next applicable method.
Note: The GAP kernel provides special treatment for the infix operations \+, \-, \*, \/, \^, \mod and \in. For some kernel objects (notably cyclotomic numbers, finite field elements and row 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.
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( opr1, opr2, ... ) | ( function ) |
‣ TraceMethods( oprs ) | ( function ) |
After the call of TraceMethods, whenever a method of one of the operations opr1, opr2, ... is called, the information string used in the installation of the method is printed. The second form has the same effect for each operation from the list oprs of operations.
‣ TraceAllMethods( ) | ( function ) |
Invokes TraceMethods for all operations.
‣ UntraceMethods( opr1, opr2, ... ) | ( function ) |
‣ UntraceMethods( oprs ) | ( function ) |
turns the tracing off for all operations opr1, opr2, ... or in the second form, for all operations in the list oprs.
gap> TraceMethods( [ Size ] ); gap> g:= Group( (1,2,3), (1,2) );; gap> Size( g ); #I Size: for a permutation group at /gap5/lib/grpperm.gi:487 #I Setter(Size): system setter #I Size: system getter #I Size: system getter 6 gap> UntraceMethods( [ Size ] );
‣ UntraceAllMethods( ) | ( function ) |
Equivalent to calling UntraceMethods for all operations.
‣ TraceImmediateMethods( [flag] ) | ( function ) |
‣ UntraceImmediateMethods( ) | ( function ) |
TraceImmediateMethods enables tracing for all immediate methods if flag is either true, or not present. UntraceImmediateMethods, or TraceImmediateMethods with flag equal false turns tracing off. (There is no facility to trace specific immediate methods.)
gap> TraceImmediateMethods( ); gap> g:= Group( (1,2,3), (1,2) );; #I immediate: Size #I immediate: IsCyclic #I immediate: IsCommutative #I immediate: IsTrivial gap> Size( g ); #I immediate: IsNonTrivial #I immediate: Size #I immediate: IsFreeAbelian #I immediate: IsTorsionFree #I immediate: IsNonTrivial #I immediate: GeneralizedPcgs #I immediate: IsPerfectGroup #I immediate: IsEmpty 6 gap> UntraceImmediateMethods( ); gap> UntraceMethods( [ Size ] );
This example gives an explanation for the two calls of the "system getter" for Size (30.4-6). 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 (39.15-17) after the call of Size (30.4-6) have other arguments than g.
The Info (7.4-5) 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 (7.4-7) which initially has level 1.
‣ NewInfoClass( name ) | ( operation ) |
creates a new info class with name name.
‣ DeclareInfoClass( name ) | ( function ) |
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 ) | ( operation ) |
Sets the info level for infoclass to level.
‣ InfoLevel( infoclass ) | ( operation ) |
returns the info level of infoclass.
‣ Info( infoclass, level, info[, moreinfo, ...] ) | ( function ) |
If the info level of infoclass is at least level the remaining arguments, info and possibly moreinfo and so on, are evaluated. (Technically, Info 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 SetInfoHandler (7.4-6).
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 (30.5-3). 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
Info (7.4-5) statements‣ SetInfoHandler( infoclass, handler ) | ( function ) |
‣ SetInfoOutput( infoclass, out ) | ( function ) |
‣ SetDefaultInfoOutput( out ) | ( function ) |
Returns: 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 Info (7.4-5) call.
The default handler is the function DefaultInfoHandler. It prints "#I ", then the third and further arguments of the info statement, and finally a "\n".
If the first argument of an Info (7.4-5) statement is a sum of Info classes, the handler of the first summand is used.
The file or stream to which Info (7.4-5) statements for individual Info (7.4-5) classes print can be changed with SetInfoOutput. The initial default for all Info (7.4-5) classes is the string "*Print*" which means the current output file. The default can be changed with SetDefaultInfoOutput. 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 Info (7.4-5) output to standard error, which can be interesting if GAPs output is redirected.
‣ InfoWarning | ( info class ) |
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 Info (7.4-5) 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 ) | ( function ) |
assigns the global assertion level to lev. By default it is zero.
‣ AssertionLevel( ) | ( function ) |
returns the current assertion level.
‣ Assert( lev, cond[, message] ) | ( function ) |
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.
‣ Runtimes( ) | ( function ) |
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_timecpu time spent with GAP functions (without child processes).
system_timecpu time spent in system calls, e.g., file access (fail if not available).
user_time_childrencpu time spent in child processes (fail if not available).
system_time_childrencpu 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( ) | ( function ) |
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 (7.6-1), as explained above.
See StringTime (27.10-9) for a translation from milliseconds into hour/minute format.
‣ time | ( global variable ) |
In the read-eval-print loop, time stores 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 and how much memory has been allocated during runtime. GAP has two different methods of profiling. GAP can either profile by function, or line-by-line. Line by line profiling is currently only used for code coverage, while function profiling tracks memory and time usage.
This section describes how to profiling at the function level. 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 ClearProfile (7.7-10)),
and finally one switches off profiling.
For switching on and off profiling, GAP supports entering a list of functions (see ProfileFunctions (7.7-5), UnprofileFunctions (7.7-6)) or a list of operations whose methods shall be (un)profiled (ProfileMethods (7.7-7), UnprofileMethods (7.7-8)), and DisplayProfile (7.7-9) can be used to show profile information about functions in a given list.
Besides these functions, ProfileGlobalFunctions (7.7-2), ProfileOperations (7.7-3), and ProfileOperationsAndMethods (7.7-4) 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.
‣ ProfileGlobalFunctions( [bool] ) | ( function ) |
Called with argument true, ProfileGlobalFunctions starts profiling of all functions that have been declared via DeclareGlobalFunction (79.18-7). Old profile information for all these functions is cleared. A function call with the argument false stops profiling of all these functions. Recorded information is still kept, so you can display it even after turning the profiling off.
When ProfileGlobalFunctions is called without argument, profile information for all global functions is displayed, see DisplayProfile (7.7-9).
‣ ProfileOperations( [bool] ) | ( function ) |
Called with argument true, ProfileOperations starts profiling of all operations. Old profile information for all operations is cleared. A function call with the argument false stops profiling of all operations. Recorded information is still kept, so you can display it even after turning the profiling off.
When ProfileOperations is called without argument, profile information for all operations is displayed (see DisplayProfile (7.7-9)).
‣ ProfileOperationsAndMethods( [bool] ) | ( function ) |
Called with argument true, ProfileOperationsAndMethods starts profiling of all operations and their methods. Old profile information for these functions is cleared. A function call with the argument false 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 ProfileOperationsAndMethods is called without argument, profile information for all operations and their methods is displayed, see DisplayProfile (7.7-9).
‣ ProfileFunctions( funcs ) | ( function ) |
starts profiling for all function in the list funcs. You can use ProfileGlobalFunctions (7.7-2) to turn profiling on for all globally declared functions simultaneously.
‣ UnprofileFunctions( funcs ) | ( function ) |
stops profiling for all function in the list funcs. Recorded information is still kept, so you can display it even after turning the profiling off.
‣ ProfileMethods( ops ) | ( function ) |
starts profiling of the methods for all operations in the list ops.
‣ UnprofileMethods( ops ) | ( function ) |
stops profiling of the methods for all operations in the list ops. Recorded information is still kept, so you can display it even after turning the profiling off.
‣ DisplayProfile( [functions, ][mincount, mintime] ) | ( function ) |
‣ GAPInfo.ProfileThreshold | ( global variable ) |
Called without arguments, DisplayProfile displays the profile information for profiled operations, methods and functions. If an argument functions is given, only profile information for the functions in the list functions is shown. If two integer values mincount, mintime are given as arguments then the output is restricted to those functions that were called at least mincount times or for which the total time spent (see below) was at least mintime milliseconds. The defaults for mincount and mintime are the entries of the list stored in the global variable GAPInfo.ProfileThreshold.
The default value of GAPInfo.ProfileThreshold is [ 10000, 30 ].
Profile information is displayed in a list of lines for all functions (including operations and methods) which are profiled. For each function, "count" gives the number of times the function has been called. "self/ms" gives the time (in milliseconds) spent in the function itself, "chld/ms" the time (in milliseconds) spent in profiled functions called from within this function, "stor/kb" the amount of storage (in kilobytes) allocated by the function itself, "chld/kb" the amount of storage (in kilobytes) allocated by profiled functions called from within this function, and "package" the name of the GAP package to which the function belongs; the entry "GAP" in this column means that the function belongs to the GAP library, the entry "(oprt.)" means that the function is an operation (which may belong to several packages), and an empty entry means that FilenameFunc (5.1-4) cannot determine in which file the function is defined.
The list is sorted according to the total time spent in the functions, that is the sum of the values in the columns "self/ms" and "chld/ms".
At the end of the list, two lines are printed that show the total time used and the total memory allocated by the profiled functions not shown in the list (label OTHER) and by all profiled functions (label TOTAL), respectively.
An interactive variant of DisplayProfile is the function BrowseProfile (Browse: BrowseProfile) that is provided by the GAP package Browse.
‣ ClearProfile( ) | ( function ) |
clears all stored profile information.
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 DisplayProfile (7.7-9).
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 ProfileGlobalFunctions (7.7-2).
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 ProfileOperations (7.7-3).
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 ProfileOperationsAndMethods (7.7-4).
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 DisplayProfile (7.7-9), 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
Line By Line profiling tracks which lines have been executed in a piece of GAP code. Built into GAP are the methods necessary to generate profiles, the resulting profiles can be displayed with the 'profiling' package.
There are two kinds of profiles GAP can build:
Coverage : This records which lines of code are executed
Timing : This records how much time is spend executing each line of code
A timing profile provides more information, but will take longer to generate and parse. A timing profile is generated using the functions ProfileLineByLine (7.7-14) and UnprofileLineByLine (7.7-16), as follows:
gap> ProfileLineByLine("output.gz"); gap> Size(AlternatingGroup(10)); ; # Execute some GAP code you want to profile gap> UnprofileLineByLine();
For code coverage, use instead the functions CoverageLineByLine (7.7-15) and UncoverageLineByLine (7.7-17). The profiler will only record lines which are read and executed while the profiler is running. If you want to perform code coverage or profile GAP's library, then you can use the GAP command line option '--cover filename.gz', which executes CoverageLineByLine (7.7-15) before GAP starts. Similarly the option '--prof filename.gz' executes ProfileLineByLine (7.7-14) before GAP starts. The profiler is designed for high performance, because of this, there are some limitations which users should be aware of:
By default the profiler records the wall-clock time which has passed, rather than the CPU time taken (because it is lower overhead), so any time taken writing commands will be charged to the last GAP statement which was executed. Therefore it is better to write a function which starts profiling, executes your code, and then stops profiling.
If you end the filename with ".gz", the resulting file will automatically be compressed. This is highly recommended!
The profiler can only track GAP code which occurs in a function -- this is most obvious when looking at code coverage examples, which will appear to miss lines of code in files not in a function.
Profiles are transformed into a human-readable form with 'profiling' package, for example with the 'OutputAnnotatedCodeCoverageFiles' function.
‣ ProfileLineByLine( filename[, options] ) | ( function ) |
ProfileLineByLine begins GAP recording profiling data to the file filename. This file will get *very* large very quickly. This file is compressed using gzip to reduce its size. options is an optional dictionary, which sets various configuration options. These are
Boolean (defaults to false). If this is enabled, only information about which lines are read and executed is stored. Enabling this is the same as calling CoverageLineByLine (7.7-15). Using this ignores all other options.
Boolean (defaults to false). This switches profiling to only consider entire statements, rather than parts of statements. In general this will provide a courser profile, but produce smaller files.
Boolean (defaults to true). Sets if time should be measured using wall-clock time or CPU time. (measuring wall-clock time is lower overhead).
Integer (defaults to 0). How frequently (in nanoseconds) to check which line is being executed. Setting this to a non-zero value improves performance and produces smaller traces, at the cost of accuracy. Setting this to a non-zero value will also make the number of executions per statement become inaccurance. However,i profiling will still accurately record which statements are executed at all.
‣ CoverageLineByLine( filename ) | ( function ) |
CoverageLineByLine begins GAP recording code coverage to the file filename. This is equivalent to calling ProfileLineByLine (7.7-14) with coverage=true.
‣ UnprofileLineByLine( ) | ( function ) |
Stops profiling which was previously started with ProfileLineByLine (7.7-14) or CoverageLineByLine (7.7-15).
‣ UncoverageLineByLine( ) | ( function ) |
Stops profiling which was previously started with ProfileLineByLine (7.7-14) or CoverageLineByLine (7.7-15).
‣ ActivateProfileColour( ) | ( function ) |
Called with argument true, ActivateProfileColour makes GAP colour functions when printing them to show which lines have been executed while profiling was active via ProfileLineByLine (7.7-14) at any time during this GAP session. Passing false disables this behaviour.
‣ IsLineByLineProfileActive( ) | ( function ) |
IsLineByLineProfileActive returns if line-by-line profiling is currently activated.
‣ DisplayCacheStats( ) | ( function ) |
displays statistics about the different caches used by the method selection.
‣ ClearCacheStats( ) | ( function ) |
clears all statistics about the different caches used by the method selection.
The global variable GAPInfo.Version (see GAPInfo (3.5-1)) contains the version number of the version of GAP. Its value can be checked other version number using CompareVersionNumbers (76.3-7).
To produce sample citations for the used version of GAP or for a package available in this GAP installation, use Cite (76.3-16).
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 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.
‣ START_TEST( id ) | ( function ) |
‣ STOP_TEST( file, fac ) | ( function ) |
START_TEST and STOP_TEST may be optionally used in files that are read via Test (7.9-2). If used, START_TEST reinitialize the caches and the global random number generator, in order to be independent of the reading order of several test files. Furthermore, the assertion level (see Assert (7.5-3)) is set to 2 (if it was lower before) by START_TEST and set back to the previous value in the subsequent STOP_TEST call.
To use these options, a test file should be started with a line
gap> START_TEST( "arbitrary identifier string" );
(Note that the gap> prompt is part of the line!)
and should be finished 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 the test file tst/combinat.tst.
Note that the functions in tst/testutil.g temporarily replace STOP_TEST before they call Test (7.9-2).
If you want to run a quick test of your GAP installation (though this is not required), you can read in a test script that exercises some GAP's capabilities.
gap> Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) );
The test requires up to 1 GB of memory and runs about one minute on an Intel Core 2 Duo / 2.53 GHz machine. You will get a large number of lines with output about the progress of the tests.
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 ]
If you want to run a more advanced check (this is not required and make take up to an hour), you can read teststandard.g which is an extended test script performing all tests from the tst directory.
gap> Read( Filename( DirectoriesLibrary( "tst" ), "teststandard.g" ) );
The test requires up to 1 GB of memory and runs about one hour on an Intel Core 2 Duo / 2.53 GHz machine, and produces an output similar to the testinstall.g test.
‣ Test( fname[, optrec] ) | ( function ) |
Returns: true or false.
The argument fname must be the name of a file or an open input stream. The content of this file or stream should contain GAP input and output. The function Test runs the input lines, compares the actual output with the output stored in fname and reports differences. With an optional record as argument optrec details of this process can be adjusted.
More precisely, the content of fname must have the following format.
Lines starting with "gap> " are considered as GAP input, they can be followed by lines starting with "> " if the input is continued over several lines.
To allow for comments in fname the following lines are ignored by default: lines at the beginning of fname that start with "#", and one empty line together with one or more lines starting with "#".
All other lines are considered as GAP output from the preceding GAP input.
By default the actual GAP output is compared exactly with the stored output, and if these are different some information about the differences is printed.
If any differences are found then Test returns false, otherwise true.
If the optional argument optrec is given it must be a record. The following components of optrec are recognized and can change the default behaviour of Test:
ignoreCommentsIf set to false then no lines in fname are ignored as explained above (default is true).
widthThe screen width used for the new output (default is 80).
compareFunctionThis must be a function that gets two strings as input, the newly generated and the stored output of some GAP input. The function must return true or false, indicating if the strings should be considered equivalent or not. By default \= (31.11-1) is used.
Two strings are recognized as abbreviations in this component: "uptowhitespace" checks if the two strings become equal after removing all white space. And "uptonl" compares the string up to trailing newline characters.
reportDiffA function that gets six arguments and reports a difference in the output: the GAP input, the expected GAP output, the newly generated output, the name of tested file, the line number of the input, the time to run the input. (The default is demonstrated in the example below.)
rewriteToFileIf this is bound to a string it is considered as a file name and that file is written with the same input and comment lines as fname but the output substituted by the newly generated version (default is false).
writeTimingsIf this is bound to a string it is considered as a file name, that file is written and contains timing information for each input in fname.
compareTimingsIf this is bound to a string it is considered as name of a file to which timing information was stored via writeTimings in a previous call. The new timings are compared to the stored ones. By default only commands which take more than a threshold of 100 milliseconds are considered, and only differences of more than 20% are considered significant. These defaults can be overwritten by assigning a list [timingfile, threshold, percentage] to this component. (The default of compareTimings is false.)
reportTimeDiffThis component can be used to overwrite the default function to display timing differences. It must be a function with 5 arguments: GAP input, name of test file, line number, stored time, new time.
ignoreSTOP_TESTBy default set to true, in that case the output of GAP input starting with "STOP_TEST" is not checked.
showProgressIf this is true then GAP prints position information and the input line before it is processed (default is false).
subsWindowsLineBreaksIf this is true then GAP substitutes DOS/Windows style line breaks "\r\n" by UNIX style line breaks "\n" after reading the test file. (default is true).
gap> tnam := Filename(DirectoriesLibrary(), "../doc/ref/demo.tst");; gap> mask := function(str) return Concatenation("| ", > JoinStringsWithSeparator(SplitString(str, "\n", ""), "\n| "), > "\n"); end;; gap> Print(mask(StringFile(tnam))); | # this is a demo file for the 'Test' function | # | gap> g := Group((1,2), (1,2,3)); | Group([ (1,2), (1,2,3) ]) | | # another comment following an empty line | # the following fails: | gap> a := 13+29; | 41 gap> ss := InputTextString(StringFile(tnam));; gap> Test(ss); ########> Diff in test stream, line 8: # Input is: a := 13+29; # Expected output: 41 # But found: 42 ######## false gap> RewindStream(ss); true gap> dtmp := DirectoryTemporary();; gap> ftmp := Filename(dtmp,"demo.tst");; gap> Test(ss, rec(reportDiff := Ignore, rewriteToFile := ftmp)); false gap> Test(ftmp); true gap> Print(mask(StringFile(ftmp))); | # this is a demo file for the 'Test' function | # | gap> g := Group((1,2), (1,2,3)); | Group([ (1,2), (1,2,3) ]) | | # another comment following an empty line | # the following fails: | gap> a := 13+29; | 42
‣ TestDirectory( inlist[, optrec] ) | ( function ) |
Returns: true or false.
The argument inlist must be either a single filename or directory name, or a list of filenames and directories. The function TestDirectory will take create a list of files to be tested by taking any files in inlist, and recursively searching any directories in inlist for files ending in .tst. Each of these files is then run through Test (7.9-2), and the results printed, and true returned if all tests passed.
If the optional argument optrec is given it must be a record. The following components of optrec are recognized and can change the default behaviour of TestDirectory:
testOptionsA record which will be passed on as the second argument of Test (7.9-2) if present.
earlyStopIf true, stop as soon as any Test (7.9-2) fails (defaults to false).
showProgressPrint information about how tests are progressing (defaults to true).
suppressStatusMessagesuppress displaying status messages #I Errors detected while testing and #I No errors detected while testing after the test (defaults to false).
exitGAPRather than returning true or false, exit GAP with the return value of GAP set to success or fail, depending on if all tests passed (defaults to false).
stonesLimitOnly try tests which take less than stonesLimit stones (defaults to infinity)
renormaliseStonesRe-normalise the stones number given in every tst files's 'STOP_TEST'
See also TestPackage (76.3-3) for the information on running standard tests for GAP packages.
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 (6.4) 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.
‣ SetRecursionTrapInterval( interval ) | ( function ) |
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
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 3.1). There are also some facilities to access information from GASMAN from GAP programs.
‣ GasmanStatistics( ) | ( function ) |
GasmanStatistics returns a record containing some information from the garbage collection mechanism. The record may contain up to four components: full, partial, npartial, and nfull.
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 preceding 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 should 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 livebagsand livekb only to the numbers and total size of the young bags that were considered for garbage collection, and survived.
The npartial and nfull components will contain the number of full and partial garbage collections performed since GAP started.
‣ GasmanMessageStatus( ) | ( function ) |
‣ SetGasmanMessageStatus( stat ) | ( function ) |
GasmanMessageStatus returns one of the strings "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, respectively.
Calling SetGasmanMessageStatus with the argument stat, which should be one of the three strings mentioned above, sets the garbage collector messaging level.
‣ GasmanLimits( ) | ( function ) |
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.
generated by GAPDoc2HTML