  
  [1X1 [33X[0;0YTutorial[133X[101X
  
  
  [1X1.1 [33X[0;0YLine-by-line profiling[133X[101X
  
  [33X[0;0YThe  purpose  of  this  section  is  to  show  how to use [5XGAP[105X's line-by-line
  profiling / code coverage. For this, you need [5XGAP[105X 4.10 or newer.[133X
  
  [33X[0;0YDo you just care which lines of code are executed? Then you should switch to
  the coverage guide (these two guides are very similar!)[133X
  
  [33X[0;0YWe  will start with a quick guide to profiling, with some brief comments. We
  will explain later how to do these things in greater depth![133X
  
  [33X[0;0YLet's  start  with  some code we want to profile. Here I am going to profile
  the function [10Xf[110X given below, and use a group from the [5XAtlasRep[105X package.[133X
  
  [4X[32X[104X
    [4XLoadPackage("atlasrep");[104X
    [4Xa := AtlasGroup("U6(2)", NrMovedPoints, 12474);[104X
    [4Xb := a^(1,2,3);[104X
    [4Xf := function() Intersection(a,b); end;[104X
  [4X[32X[104X
  
  [33X[0;0YFirstly, we will record a profile of the function [10Xf[110X:[133X
  
  [4X[32X[104X
    [4X# Code between ProfileLineByLine and UnprofileLineByLine is recorded[104X
    [4X# to a file output.gz[104X
    [4XProfileLineByLine("output.gz"); f(); UnprofileLineByLine();[104X
  [4X[32X[104X
  
  [33X[0;0YYou  should write this all on a single line in [5XGAP[105X, as profiling records the
  real  time  spent  executing  code,  so  time  spent typing commands will be
  counted.[133X
  
  [33X[0;0YThis  creates a file called [11Xoutput.gz[111X, which stores the result of running [10Xf[110X.
  Now  we  want  to  turn  that  into a nice output. This requires loading the
  [5Xprofiling[105X package, like this:[133X
  
  [4X[32X[104X
    [4XLoadPackage("profiling");[104X
    [4XOutputAnnotatedCodeCoverageFiles("output.gz", "outdir");[104X
  [4X[32X[104X
  
  [33X[0;0YIf  loading  the  [5Xprofiling[105X  package  produces  errors,  make  sure you have
  compiled both the [5Xprofiling[105X and [5XIO[105X packages.[133X
  
  [33X[0;0Y[2XOutputAnnotatedCodeCoverageFiles[102X   ([14X2.3-1[114X)   reads  the  previously  created
  [11Xoutput.gz[111X and produces HTML output into the directory [11Xoutdir[111X.[133X
  
  [33X[0;0YYou  must view the result of your profiling in a web-browser outside of [5XGAP[105X.
  Open  [11Xindex.html[111X from the [11Xoutdir[111X directory in the web browser of your choice
  to see what happened.[133X
  
  [33X[0;0YAt  the  very top is a link to a flame graph. These give a quick overview of
  which  functions  took  the  most  time.  Functions  are  stacked,  so lower
  functions call higher functions.[133X
  
  [33X[0;0YFrom   this  graph  we  can  see  that  [10Xf[110X  called  [2XIntersection[102X  ([14XReference:
  Intersection[114X), which called the function [10XIntersection2 perm groups[110X near line
  2950   in   [11Xstbcbckt.gi[111X.   This   function   spent   most  of  its  time  in
  [10XPartitionBacktrack[110X, and a little time in [10XStabilizer[110X.[133X
  
  [33X[0;0YWhenever  you  generate a profile which contains timing information, a flame
  graph link will be show on the first page of your generated profile![133X
  
  
  [1X1.2 [33X[0;0YFAQ / Problems[133X[101X
  
  [30X    [33X[0;6Y[2XProfileLineByLine[102X ([14XReference: ProfileLineByLine[114X) records the wall time
        (also  known  as  clock  time)  that  occurs between [2XProfileLineByLine[102X
        ([14XReference:   ProfileLineByLine[114X)   and  the  next  [2XUnprofileLineByLine[102X
        ([14XReference:  UnprofileLineByLine[114X). This is why we start profiling, run
        our code, and then stop profiling all on a single line.[133X
  
  [30X    [33X[0;6YIf you want to profile how long everything in [5XGAP[105X takes, including the
        startup, then you can do this by giving the command line option [10X--prof
        filename[110X  when  starting  [5XGAP[105X.  This  is  equivalent  to  [5XGAP[105X  calling
        [10XProfileLineByLine("filename");[110X  before  loading  any  of  the standard
        library (obviously, give your own filename).[133X
  
  [30X    [33X[0;6YGiving  your  output  file  the  [10Xgz[110X  extension makes [5XGAP[105X automatically
        compress  the  file.  This  is a great idea, because the files can get
        very  big  otherwise!  Even  then, the files can grow quite large very
        quickly, keep an eye on them.[133X
  
  [30X    [33X[0;6Y[2XProfileLineByLine[102X  ([14XReference:  ProfileLineByLine[114X)  takes  an optional
        second  argument  which  is a record, which can set some configuration
        options. Here are some of the options:[133X
  
  [30X    [33X[0;6Y[10XwallTime[110X:  Boolean (defaults to [9Xtrue[109X). Sets if time should be measured
        using  wall-clock  time (true) or CPU time (false). Measuring CPU-time
        has a higher overhead, so avoid it if at all possible![133X
  
  [30X    [33X[0;6Y[10Xresolution[110X:  Integer  (defaults  to  [10X0[110X).  By default [5XGAP[105X will record a
        trace  of  all executed code. When non-zero, [5XGAP[105X instead samples which
        piece  of code is being executed every [10Xresolution[110X nanoseconds. Setting
        this  to  a  non-zero  value improves performance and produces smaller
        traces,  at  the  cost  of  accuracy. [5XGAP[105X will still accurately record
        which  statements  are  executed  at least once. This is mainly useful
        when you wish to consider very long-running code.[133X
  
  
  [1X1.3 [33X[0;0YFunction-based profiling[133X[101X
  
  [33X[0;0YSometimes  you  will  have  code  that  just runs too long to easily profile
  line-by-line.  You  can profile this in [5XGAP[105X's older function-based profiler.
  You  can  read  more about this profiler in [5XGAP[105X's documentation ([14X'Reference:
  Profiling'[114X), but here is a quick example to get you going![133X
  
  [4X[32X[104X
    [4XProfileGlobalFunctions(true);[104X
    [4XProfileOperationsAndMethods(true);[104X
    [4Xf();[104X
    [4XProfileGlobalFunctions(false);[104X
    [4XProfileOperationsAndMethods(false);[104X
    [4XDisplayProfile();[104X
  [4X[32X[104X
  
