  
  [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
  profiler / code coverage. For this, you need [5XGAP[105X 4.8 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 a 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
  this 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  a  function  without  a  name at line 2942 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 wall (also
        known   as   clock)   time  which  happens  between  [2XProfileLineByLine[102X
        ([14XReference:   ProfileLineByLine[114X)   and  the  next  [2XUnprofileLineByLine[102X
        ([14XReference:   UnprofileLineByLine[114X).   This  is  why  we  put  starting
        profiling, our code, and then stopping profile 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 given 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 true). 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  0).  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 ling 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 older function-based profiler. You can
  read  more  about  this profiler in [5XGAP[105X's documentation, 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
  
