7 Debugging and Profiling Facilities
  
  This  chapter  describes some functions that are useful mainly for debugging
  and profiling purposes.
  
  Probably  the  most  important  debugging tool in GAP is the break loop (see
  Section 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), Where (6.4-5) and
  WhereWithVars (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.8).
  
  
  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:
  
    Example  
    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 at GAPROOT/lib/methsel2.g:250 called from
    <function "HANDLE_METHOD_NOT_FOUND">( <arguments> )
     called from read-eval loop at *stdin*:1
    type 'quit;' to quit to outer loop
    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.
  
  7.1-1 ShowArguments
  
  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.
  
  7.1-2 ShowArgument
  
  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.
  
  7.1-3 ShowDetails
  
  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.5-1).  The last number is called Choice and is printed as an ordinal. So
  if  exactly k methods were found but called TryNextMethod (78.5-1) and there
  were no more methods it says Choice: kth.
  
  7.1-4 ShowMethods
  
  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.5-1).  With  verbosity  3  not  only  all installed methods but also the
  reasons why they do not match are displayed.
  
  7.1-5 ShowOtherMethods
  
  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.
  
  
  7.2 Inspecting Applicable Methods
  
  7.2-1 ApplicableMethod
  
  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.
  
  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  (78.5-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).
  
  
  7.3 Tracing Methods
  
  7.3-1 TraceMethods
  
  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.
  
  7.3-2 TraceAllMethods
  
  TraceAllMethods(  )  function
  
  Invokes TraceMethods for all operations.
  
  7.3-3 UntraceMethods
  
  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.
  
    Example  
    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 ] );
  
  
  7.3-4 UntraceAllMethods
  
  UntraceAllMethods(  )  function
  
  Equivalent to calling UntraceMethods for all operations.
  
  7.3-5 TraceImmediateMethods
  
  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.)
  
    Example  
    gap> TraceImmediateMethods( );
    gap> g:= Group( (1,2,3), (1,2) );;
    #I RunImmediateMethods
    #I  immediate: Size
    #I  immediate: IsCyclic
    #I  immediate: IsCommutative
    #I  immediate: IsTrivial
    gap> Size( g );
    #I  immediate: IsPerfectGroup
    #I  immediate: IsNonTrivial
    #I  immediate: Size
    #I  immediate: IsFreeAbelian
    #I  immediate: IsTorsionFree
    #I  immediate: IsNonTrivial
    #I  immediate: IsPerfectGroup
    #I  immediate: GeneralizedPcgs
    #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-18)  after  the  call of Size (30.4-6) have
  other arguments than g.
  
  7.3-6 TraceInternalMethods
  
  TraceInternalMethods(  )  function
  UntraceInternalMethods(  )  function
  GetTraceInternalMethodsCounts(  )  function
  ClearTraceInternalMethodsCounts(  )  function
  
  TraceInternalMethods  enables  tracing  for  all  internal methods. Internal
  methods  are  methods which implement many fundamental operations in GAP. In
  this version of GAP, the internal methods which can be traced are:
  
  Zero, ZeroMut
        Mutable and Immutable Zero (31.10-3)
  
  AInv, AInvMut
        Mutable and Immutable AdditiveInverse (31.10-9)
  
  One, OneMut
        Mutable and Immutable One (31.10-2)
  
  Inv, InvMut
        Mutable and Immutable Inverse (31.10-8)
  
  Sum
        The operator \+ (31.12-1)
  
  Diff
        The operator - operator
  
  Prod
        The operator \* (31.12-1)
  
  Quo
        The operator \/ (31.12-1)
  
  LQuo
        The left-quotient operator
  
  Pow
        The operator \^ (31.12-1)
  
  Comm
        The operator Comm (31.12-3)
  
  Mod
        The operator \mod (31.12-1)
  
  UntraceInternalMethods  turns  tracing  off.  As these methods can be called
  hundreds  of  thousands of times in simple GAP code, there isn't a statement
  printed    each    time    one    is    called.    Instead,    the    method
  GetTraceInternalMethodsCounts returns how many times each operation has been
  applied  to  each type of variable (the type of a variable can be found with
  the  TNAM_OBJ  method).  The  return  value  for two argument operators is a
  record  of  records  r, where r.op stores information about operator op. For
  one  argument  operators  r.op.i stores how many times op was called with an
  argument  of  type  i,  while for two argument operators r.op.i.j stores how
  many times op was called with arguments of type i and j.
  
    Example  
    gap> TraceInternalMethods();
    true
    gap> 2+3+4+5+6;;
    gap> 2.0+2.0;;
    gap> 3^(1,2,3);;
    gap> GetTraceInternalMethodsCounts();
    rec( Pow := rec( integer := rec( ("permutation (small)") := 1 ) ),
    Sum := rec( integer := rec( integer := 4 ),
        macfloat := rec( macfloat := 1 ) ) )
    # 'macfloat' is a floating point number
    gap> UntraceInternalMethods();
  
  
  
  7.4 Info Functions
  
  The  Info  (7.4-6)  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.
  
  Note  that  not  all  info  classes defined in the GAP library are currently
  documented.  Many  GAP  packages  define  additional info classes, which are
  typically   documented  in  the  corresponding  package  documentation.  The
  function  ShowUsedInfoClasses  (7.4-5)  will show all info classes which GAP
  considers while executing code.
  
  The  amount  of  information  to  be  displayed  by  each  info class can be
  separately  specified  by the user. This is done by selecting a non-negative
  integer  level for the info class: no information will be displayed at level
  0, and the higher the level, the more information that will be displayed. At
  creation,  an  info  class  has  level  0. By default, all built-in GAP info
  classes  have  level  0,  except  for the following info classes, which have
  level 1:
  
      InfoWarning (7.4-8),
  
      InfoPackageLoading (76.2-6),
  
      InfoDebug,
  
      InfoPerformance,
  
      InfoTempDirectories,
  
      InfoPrimeInt, and
  
      InfoSLP.
  
  7.4-1 NewInfoClass
  
  NewInfoClass( name )  operation
  
  creates a new info class with name name.
  
  7.4-2 DeclareInfoClass
  
  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 read-only by
  this function.
  
  7.4-3 SetInfoLevel
  
  SetInfoLevel( infoclass, level )  operation
  
  Sets the info level for infoclass to the non-negative integer level.
  
  7.4-4 InfoLevel
  
  InfoLevel( infoclass )  operation
  
  returns the info level of infoclass.
  
  7.4-5 ShowUsedInfoClasses
  
  ShowUsedInfoClasses( infoclass )  function
  
  Called  with argument true, this makes GAP print the info class and level of
  any  executed  Info (7.4-6) statement. Calling with the argument false stops
  this  printing.  Each  level  of  each  info class is only printed once. The
  history of printed info classes and levels is reset whenever true is passed.
  
    Example  
    gap> ShowUsedInfoClasses(true);
    gap> Intersection(Group((1,3,2,4,5,6)), Group((1,2,3,4,5,6)));
    #I Would print info with SetInfoLevel(InfoBckt,1)
    #I Would print info with SetInfoLevel(InfoBckt,3)
    #I Would print info with SetInfoLevel(InfoBckt,5)
    Group(())
    gap> Intersection(Group((1,3,2,4,5,6)), Group((1,2,3,4,5,6)));
    Group(())
    gap> ShowUsedInfoClasses(false);
  
  
  7.4-6 Info
  
  Info( infoclass, level, info[, moreinfo, ...] )  function
  
  If  the  info  level  of  infoclass  is  at  least level, then the remaining
  arguments,   info,   and   possibly  moreinfo  and  so  on,  are  evaluated.
  (Technically, Info is a keyword and not a function.)
  
  By  default,  the  results  of these evaluations are viewed, preceded by the
  string "#I " and followed by a newline.
  
  If  the  info level of infoclass is strictly less than level, then 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-7).
  
    Example  
    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.
  
    Example  
    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
  
  
  
  7.4-7 Customizing Info (7.4-6) statements
  
  SetInfoHandler( infoclass, handler )  function
  SetInfoOutput( infoclass, out )  function
  UnbindInfoOutput( infoclass )  function
  InfoOutput( infoclass )  function
  SetDefaultInfoOutput( out )  function
  Returns:  nothing
  
  This  allows one 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 argument
  and any subsequent optional arguments of the Info (7.4-6) 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-6) statement is a sum of Info classes,
  the handler of the first summand is used.
  
  The  file  or  stream  to  which Info (7.4-6) statements for individual Info
  (7.4-6)  classes  print can be overridden with SetInfoOutput, retrieved with
  InfoOutput  and  reset  to  the  default  with UnbindInfoOutput. The initial
  default for all Info (7.4-6) 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-6)
  output  to  standard  error,  which  can  be  interesting  if GAPs output is
  redirected.
  
  7.4-8 InfoWarning
  
  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-6)
  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.
  
  7.5-1 SetAssertionLevel
  
  SetAssertionLevel( lev )  function
  
  assigns the global assertion level to lev. By default it is zero.
  
  7.5-2 AssertionLevel
  
  AssertionLevel(  )  function
  
  returns the current assertion level.
  
  7.5-3 Assert
  
  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
  
    Example  
    if AssertionLevel() >= lev and not <cond> then
      Error("Assertion failure");
    fi;
  
  
  If  the message argument form of the Assert statement is provided, and if an
  error is raised, then this message is printed as part of the error.
  
  Assertions  are  used  at  various  places  in  the  library.  Thus  turning
  assertions on can slow code execution significantly.
  
  
  7.6 Timing
  
  7.6-1 Runtimes
  
  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_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:
  
    Example  
    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 )
  
  
  7.6-2 Runtime
  
  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.
  
  7.6-3 NanosecondsSinceEpoch
  
  NanosecondsSinceEpoch(  )  function
  NanosecondsSinceEpochInfo(  )  function
  
  NanosecondsSinceEpoch  returns the time in nanoseconds that has passed since
  some  fixed,  but unspecified time in the past. This function is appropriate
  for  doing wallclock time measurements. The actual resolution depends on the
  system that GAP is run on. Information about the used timers can be obtained
  by  calling  NanosecondsSinceEpochInfo,  which  returns  a record containing
  members Method, Monotonic, Reliable and Resolution.
  
  Method  is  a string describing the method used to obtain timer values. This
  will usually contain the name of the syscall used.
  
  Monotonic  is  a  boolean.  If  it  is  true,  then  the  values returned by
  NanosecondsSinceEpoch are guaranteed to be strictly monotonically increasing
  between two calls, if it is false then there is no such guarantee.
  
  Resolution  is  an  integer  reflecting  the resolution of the timer used in
  nanoseconds.
  
  Reliable  is  a  boolean.  If it is true then the value Resolution is deemed
  reliable in the sense that it was obtained by querying the operating system,
  otherwise Resolution should be treated as an estimate.
  
  7.6-4 time
  
  time  global variable
  
  In the read-eval-print loop, time stores the number of milliseconds the last
  command  took  (see also memory_allocated (7.7-2) for the number of bytes of
  memory it allocated).
  
  7.6-5 Sleep
  
  Sleep( time )  function
  MicroSleep( time )  function
  
  These functions make GAP stop execution for a given period of time. The time
  to stop is given to Sleep in seconds and MicroSleep in microseconds.
  
  
  7.7 Tracking Memory Usage
  
  7.7-1 TotalMemoryAllocated
  
  TotalMemoryAllocated(  )  function
  
  TotalMemoryAllocated  returns  the total amount of memory in bytes allocated
  by the GAP memory manager since GAP started.
  
  7.7-2 memory_allocated
  
  memory_allocated  global variable
  
  In  the read-eval-print loop, memory_allocated stores the number of bytes of
  memory  allocated by the last completed statement (see also time (7.6-4) for
  the number of milliseconds it took).
  
  
  7.8 Profiling
  
  Profiling  of  code can be used to determine in which parts of a program how
  much  time  has  been  spent  and  how much memory has been allocated during
  runtime.  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.
  
  
  7.8-1 Function Profiling
  
  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.8-10)),
  
      and finally one switches off profiling.
  
  For  switching  on  and  off  profiling,  GAP  supports  entering  a list of
  functions  (see  ProfileFunctions  (7.8-5), UnprofileFunctions (7.8-6)) or a
  list  of  operations  whose  methods  shall  be (un)profiled (ProfileMethods
  (7.8-7),  UnprofileMethods  (7.8-8)), and DisplayProfile (7.8-9) can be used
  to show profile information about functions in a given list.
  
  Besides  these  functions, ProfileGlobalFunctions (7.8-2), ProfileOperations
  (7.8-3),  and  ProfileOperationsAndMethods (7.8-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.
  
  7.8-2 ProfileGlobalFunctions
  
  ProfileGlobalFunctions( [bool] )  function
  
  Called  with  argument  true, ProfileGlobalFunctions starts profiling of all
  functions  that  have been declared via DeclareGlobalFunction (79.10-5). 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.8-9).
  
  7.8-3 ProfileOperations
  
  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.8-9)).
  
  7.8-4 ProfileOperationsAndMethods
  
  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.8-9).
  
  7.8-5 ProfileFunctions
  
  ProfileFunctions( funcs )  function
  
  starts   profiling  for  all  function  in  the  list  funcs.  You  can  use
  ProfileGlobalFunctions  (7.8-2)  to  turn  profiling  on  for  all  globally
  declared functions simultaneously.
  
  7.8-6 UnprofileFunctions
  
  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.
  
  7.8-7 ProfileMethods
  
  ProfileMethods( ops )  function
  
  starts profiling of the methods for all operations in the list ops.
  
  7.8-8 UnprofileMethods
  
  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.
  
  7.8-9 DisplayProfile
  
  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.
  
  7.8-10 ClearProfile
  
  ClearProfile(  )  function
  
  clears all stored profile information.
  
  
  7.8-11 An Example of Function Profiling
  
  Let  us  suppose  we  want  to  get information about the computation of the
  conjugacy  classes of a certain permutation group. For that, first we create
  the  group,  then  we  start  profiling for all global functions and for all
  operations  and  their  methods,  then we compute the conjugacy classes, and
  then we stop profiling.
  
    Example  
    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.8-9).
  
    Example  
    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.8-2).
  
    Example  
    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.8-3).
  
    Example  
    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.8-4).
  
    Example  
    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.8-9), by entering the list of functions as an argument.
  
    Example  
    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
  
  
  
  7.8-12 Line By Line Profiling
  
  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.
  
  
  7.8-13 Line by Line profiling example
  
  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.8-14) and UnprofileLineByLine (7.8-16), as follows:
  
    Example  
    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.8-15) and
  UncoverageLineByLine (7.8-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.8-15)
  before  GAP  starts.  Similarly  the  option  '--prof  filename.gz' executes
  ProfileLineByLine  (7.8-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.
  
      If  the  current  GAP  is forked, using the IO_fork function in the IO
        package,  a  new profile output file will be created for the new child
        process,  with  the process ID of the child attached to the end of the
        filename.
  
  Profiles  are  transformed  into  a  human-readable  form  with  'profiling'
  package, for example with the 'OutputAnnotatedCodeCoverageFiles' function.
  
  7.8-14 ProfileLineByLine
  
  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
  
  coverage
        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.8-15). Using this ignores
        all other options.
  
  wallTime
        Boolean  (defaults  to  true).  Sets  if time should be measured using
        wall-clock  time (true) or CPU time (false). (measuring CPU-time has a
        higher overhead).
  
  recordMem
        Boolean  (defaults  to false). Instead of recording the CPU time taken
        by  statements,  record  the  total size of all new objects created by
        each line.
  
  resolution
        Integer  (defaults  to 0). By default profiling will record a trace of
        all executed code. When resolution non-zero, GAP instead samples which
        piece   of  code  is  being  executed  every  resolution  nanoseconds.
        Increasing  this  improves performance and produces smaller traces, at
        the   cost  of  accuracy.  GAP  will  still  accurately  record  which
        statements are executed at least once.
  
  7.8-15 CoverageLineByLine
  
  CoverageLineByLine( filename )  function
  
  CoverageLineByLine  begins GAP recording code coverage to the file filename.
  This is equivalent to calling ProfileLineByLine (7.8-14) with coverage=true.
  
  7.8-16 UnprofileLineByLine
  
  UnprofileLineByLine(  )  function
  
  Stops profiling which was previously started with ProfileLineByLine (7.8-14)
  or CoverageLineByLine (7.8-15).
  
  7.8-17 UncoverageLineByLine
  
  UncoverageLineByLine(  )  function
  
  Stops profiling which was previously started with ProfileLineByLine (7.8-14)
  or CoverageLineByLine (7.8-15).
  
  7.8-18 IsLineByLineProfileActive
  
  IsLineByLineProfileActive(  )  function
  
  IsLineByLineProfileActive  returns  if  line-by-line  profiling is currently
  activated.
  
  7.8-19 DisplayCacheStats
  
  DisplayCacheStats(  )  function
  
  displays statistics about the different caches used by the method selection.
  
  7.8-20 ClearCacheStats
  
  ClearCacheStats(  )  function
  
  clears  all  statistics  about  the  different  caches  used  by  the method
  selection.
  
  
  7.9 Information about the version used
  
  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-9).
  
  To  produce  sample  citations  for the used version of GAP or for a package
  available in this GAP installation, use Cite (76.3-19).
  
  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.
  
  
  7.10 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.
  
  
  7.10-1 Starting and stopping test
  
  START_TEST( name )  function
  STOP_TEST( name )  function
  
  START_TEST  and  STOP_TEST may be optionally used in files that are read via
  Test  (7.10-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
  
    Example  
    gap> START_TEST( "arbitrary identifier string" );
  
  
  (Note that the gap>  prompt is part of the line!)
  
  and should be finished with a line
  
    Example  
    gap> STOP_TEST( "same identifier string as for START_TEST" );
  
  
  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.
  
    Example  
    gap> Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) );
  
  
    Example  
    test file         time(msec)
    -------------------------------------------
    testing: ................/gap4r5/tst/zlattice.tst
    zlattice.tst               0
    testing: ................/gap4r5/tst/gaussian.tst
    gaussian.tst              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.
  
    Example  
    gap> Read( Filename( DirectoriesLibrary( "tst" ), "teststandard.g" ) );
  
  
  7.10-2 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. Note that the
  rewriteToFile option is especially useful for generating test files.
  
  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 "#" or are empty, 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.
  
  Lines  which  begin "#@" define special configuration options for tests. The
  #@local  and  #@exec  options can only be used before any GAP input, and the
  other commands can only be used between individual tests (just before a line
  starting gap>, or at end of the file). Currently defined options are:
  
  #@local identifierlist
        Run  all  the  tests in the input as if it is in a function with local
        variable  list  identifierlist,  which  is  a  comma-separated list of
        identifiers.  Multiple  #@local  lines may be used. These lines should
        not  end  with  a  comma  or semicolon. If this option is used then an
        error  will  occur  unless  all the variables used are included in the
        local list.
  
        As  an  example,  the  Utils  package has a test file tst/iterator.tst
        which starts with the lines:
  
          Example  
          #@local  c3c3, cart, G, h, it1, it2, iter, iter0, iter4, iterL
          #@local  L, n, pairs0, pairs4, pairsL, s3, s4
        
  
  #@exec gapcode
        Execute  the  code  gapcode  before any test in the input is run. This
        allows defining global variables when using #@local.
  
  #@if EXPR ... {#@elif EXPR ...} [#@else ...] #@fi
        A  #@if allows to conditionally skip parts of the test input depending
        on  the  value  of a boolean expression. The exact behavior is done as
        follows:
  
        If  the  first  GAP  expression EXPR evaluates to true, then the lines
        after  the  #@if  are  used  until  either a #@elif, #@else or #@fi is
        reached. If an #@elif is present, then the lines after #@elif are used
        if  and  only  if its EXPR evaluates to true and all previous #@if and
        #@elif  clauses  had expressions evaluating to false. In this case the
        lines  after  #@elif are used until either a #@elif, #@else or #@fi is
        reached.  If  an #@else is present then the lines after the #@else are
        used  if  and  only  if EXPR evaluated to false in all #@if and #@elif
        clauses. Finally, once #fi is reached, evaluation continues normally.
  
        Note  that  each  EXPR  is  evaluated after all #@exec lines have been
        executed  but before any tests are run. Thus, it cannot depend on test
        results  or  packages  loaded  in tests, but it can depend on packages
        loaded via #@exec.
  
        In addition #@if clauses cannot be nested within each other.
  
        As   an   example,   the   GAP  test  suite  contains  the  test  file
        tst/testinstall/pperm.tst which contains the lines:
  
          Example  
          #@if GAPInfo.BytesPerVariable = 8
          gap> HASH_FUNC_FOR_PPERM(f, 10 ^ 6) in [260581, 402746];
          true
          #@else
          gap> HASH_FUNC_FOR_PPERM(f, 10 ^ 6);
          953600
          #@fi
        
  
  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:
  
  ignoreComments
        If  set to false then no lines in fname are ignored as explained above
        (default is true).
  
  width
        The screen width used for the new output (default is 80).
  
  compareFunction
        This  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.
  
  transformFunction
        This  must  be  a  function  that gets one string as input, either the
        newly  generated  or the stored output of some GAP input. The function
        must  return a new string which will be used to compare the actual and
        the expected output. By default IdFunc (5.4-6) is used.
        Two  strings  are  recognized  as  abbreviations  in  this  component:
        "removewhitespace" removes all white space. And "removenl" removes all
        trailing newline characters.
  
  reportDiff
        A  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.)
  
  rewriteToFile
        If  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; if it is bound to
        true,  then  this  is  treated as if it was bound to fname (default is
        false). This is especially useful for generating test files because it
        ensures that the test files are formatted exactly as Test expects them
        to be.
  
  writeTimings
        If  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.
  
  compareTimings
        If  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.)
  
  reportTimeDiff
        This  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_TEST
        By  default set to true, in that case the output of GAP input starting
        with "STOP_TEST" is not checked.
  
  showProgress
        If  this  is  true  then GAP prints position information and the input
        line  before  it  is  processed;  if set to "some", then GAP shows the
        current  line  number of the test being processed; if set to false, no
        progress updates are displayed (default is "some" if GAP's output goes
        to a terminal, otherwise false).
  
  subsWindowsLineBreaks
        If  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).
  
  returnNumFailures
        If this is true then GAP returns the number of input lines of the test
        file  which had differences in their output, instead of returning true
        or false.
  
    Example  
    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
  
  
  7.10-3 TestDirectory
  
  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 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.10-2), and the results printed, and true
  returned if all tests passed.
  
  If  the optional argument optrec is given it must be a record. Note that the
  rewriteToFile  option  is  especially  useful for generating test files. The
  following  components  of  optrec  are recognized and can change the default
  behaviour of TestDirectory:
  
  testOptions
        A  record  which  will  be  passed  on  as the second argument of Test
        (7.10-2) if present.
  
  earlyStop
        If true, stop as soon as any Test (7.10-2) fails (defaults to false).
  
  showProgress
        Print  information about how tests are progressing (defaults to "some"
        if GAP's output goes to a terminal, otherwise false).
  
  suppressStatusMessage
        suppress  displaying  status messages #I Errors detected while testing
        and  #I  No  errors detected while testing after the test (defaults to
        false).
  
  rewriteToFile
        If  true,  then  rewrite  each  test  file  to  disc,  with the output
        substituted  by  the  results of running the test (defaults to false).
        This is especially useful for generating test files because it ensures
        that  the  test  files  are formatted exactly as Test (7.10-2) expects
        them to be.
  
  exclude
        A list of file and directory names which will be excluded from testing
        (defaults to []).
  
  exitGAP
        Rather 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).
  
  See  also TestPackage (76.3-5) for the information on running standard tests
  for GAP packages.
  
  
  7.11 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  (6.4)  allowing you to terminate the calculation, or
  enter Return; to continue it.
  
    Example  
    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 procedures.
  
  7.11-1 SetRecursionTrapInterval
  
  SetRecursionTrapInterval( interval )  function
  GetRecursionDepth(  )  function
  
  GetRecursionDepth  returns the nesting level of the GAP interpreter. This is
  reset  to  0  every time the break loop is entered. SetRecursionTrapInterval
  sets the depth of the stack at which GAP will enter the Break loop. 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.
  
    Example  
    gap> GetRecursionDepth();
    0
    gap> dive := function(depth)
    >  if depth>1 then
    >    dive(depth-1);
    >  else
    >    Print("Depth ", GetRecursionDepth());
    >  fi;
    > end;;
    gap> SetRecursionTrapInterval(1000);
    gap> dive(100);
    Depth 100
    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> GetRecursionDepth();
    0
    brk> return;
    gap> SetRecursionTrapInterval(-1);
    Error, SetRecursionTrapInterval: <interval> must be a small integer greater than 5 (n\
    ot the integer -1)
    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);
    Depth 20000
    gap> dive(2000000);
    Segmentation fault
  
  
  
  7.12 Global Memory Information
  
  
  7.12-1 Garbage Collection
  
  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 memory
  manager  that  shall be used by GAP is specified at compile time. One of the
  choices  is  called GASMAN (GAP Storage MANager). (The name of the currently
  used garbage collector is stored in the variable GAPInfo.KernelInfo.GC.)
  
  If  GAP uses GASMAN then 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, see below.
  
  7.12-2 CollectGarbage
  
  CollectGarbage( full )  function
  Returns:  nothing.
  
  This  function forces a garbage collection. If full is true then it triggers
  a full garbage collection, otherwise a partial one.
  
  GAP  invokes  its garbage collector automatically, thus there is normally no
  need to call CollectGarbage.
  
  The  function  CollectGarbage  was  introduced  in  GAP 4.12.  In  older GAP
  versions,  one  can  use  GASMAN(  "collect"  ) (if full is true) or GASMAN(
  "partial" ) (if full is not true) instead.
  
    Example  
    gap> CollectGarbage( false );
    gap> CollectGarbage( true );
  
  
  7.12-3 GasmanStatistics
  
  GasmanStatistics(  )  function
  
  This  function is meaningful only if GASMAN is the garbage collector used by
  GAP, see Section 7.12-1.
  
  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 eight 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;  totalkb  reports  the actual size of the
  workspace;  time  reports  the  CPU  time  in milliseconds spent on the last
  garbage  collection  and cumulative the total CPU time in milliseconds spent
  on that type of garbage collection since GAP started.
  
  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.
  
  7.12-4 GasmanMessageStatus
  
  GasmanMessageStatus(  )  function
  SetGasmanMessageStatus( stat )  function
  
  This  function is meaningful only if GASMAN is the garbage collector used by
  GAP, see Section 7.12-1.
  
  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.
  
  7.12-5 GasmanLimits
  
  GasmanLimits(  )  function
  
  This  function is meaningful only if GASMAN is the garbage collector used by
  GAP, see Section 7.12-1.
  
  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.