Quelle  chap1_mj.html   Sprache: HTML

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<script type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
<title>GAP (profiling) - Chapter 1: Tutorial</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap1"  onload="jscontent()">


<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0_mj.html">Top</a>  <a href="chap1_mj.html">1</a>  <a href="chap2_mj.html">2</a>  <a href="chapInd_mj.html">Ind</a>  </div>

<div class="chlinkprevnexttop"> <a href="chap0_mj.html">[Top of Book]</a>   <a href="chap0_mj.html#contents">[Contents]</a>    <a href="chap0_mj.html">[Previous Chapter]</a>    <a href="chap2_mj.html">[Next Chapter]</a>   </div>

<p id="mathjaxlink" class="pcenter"><a href="chap1.html">[MathJax off]</a></p>
<p><a id="X81932F777898AD72" name="X81932F777898AD72"></a></p>
<div class="ChapSects"><a href="chap1_mj.html#X81932F777898AD72">1 <span class="Heading">Tutorial</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap1_mj.html#X81D5C73E87484DFC">1.1 <span class="Heading">Line-by-line profiling</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap1_mj.html#X7D806D77799DC543">1.2 <span class="Heading">FAQ / Problems</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap1_mj.html#X7F70AFBB7C6ACE3C">1.3 <span class="Heading">Function-based profiling</span></a>
</span>
</div>
</div>

<h3>1 <span class="Heading">Tutorial</span></h3>

<p><a id="X81D5C73E87484DFC" name="X81D5C73E87484DFC"></a></p>

<h4>1.1 <span class="Heading">Line-by-line profiling</span></h4>

<p>The purpose of this section is to show how to use <strong class="pkg">GAP</strong>'s line-by-line profiling / code coverage. For this, you need <strong class="pkg">GAP</strong> 4.10 or newer.</p>

<p>Do you just care which lines of code are executed? Then you should switch to the coverage guide (these two guides are very similar!)</p>

<p>We will start with a quick guide to profiling, with some brief comments. We will explain later how to do these things in greater depth!</p>

<p>Let's start with some code we want to profile. Here I am going to profile the function <code class="code">f</code> given below, and use a group from the <strong class="pkg">AtlasRep</strong> package.</p>


<div class="example"><pre>
LoadPackage("atlasrep");
a := AtlasGroup("U6(2)", NrMovedPoints, 12474);
b := a^(1,2,3);
f := function() Intersection(a,b); end;
</pre></div>

<p>Firstly, we will record a profile of the function <code class="code">f</code>:</p>


<div class="example"><pre>
# Code between ProfileLineByLine and UnprofileLineByLine is recorded
# to a file output.gz
ProfileLineByLine("output.gz"); f(); UnprofileLineByLine();
</pre></div>

<p>You should write this all on a single line in <strong class="pkg">GAP</strong>, as profiling records the real time spent executing code, so time spent typing commands will be counted.</p>

<p>This creates a file called <code class="file">output.gz</code>, which stores the result of running <code class="code">f</code>. Now we want to turn that into a nice output. This requires loading the <strong class="pkg">profiling</strong> package, like this:</p>


<div class="example"><pre>
LoadPackage("profiling");
OutputAnnotatedCodeCoverageFiles("output.gz", "outdir");
</pre></div>

<p>If loading the <strong class="pkg">profiling</strong> package produces errors, make sure you have compiled both the <strong class="pkg">profiling</strong> and <strong class="pkg">IO</strong> packages.</p>

<p><code class="func">OutputAnnotatedCodeCoverageFiles</code> (<a href="chap2_mj.html#X87AFADF581A7C1FD"><span class="RefLink">2.3-1</span></a>) reads the previously created <code class="file">output.gz</code> and produces HTML output into the directory <code class="file">outdir</code>.</p>

<p>You must view the result of your profiling in a web-browser outside of <strong class="pkg">GAP</strong>. Open <code class="file">index.html</code> from the <code class="file">outdir</code> directory in the web browser of your choice to see what happened.</p>

<p>At 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.</p>

<p>From this graph we can see that <code class="code">f</code> called <code class="func">Intersection</code> (<a href="../../../doc/ref/chap30_mj.html#X851069107CACF98E"><span class="RefLink">Reference: Intersection</span></a>), which called the function <code class="code">Intersection2 perm groups</code> near line 2950 in <code class="file">stbcbckt.gi</code>. This function spent most of its time in <code class="code">PartitionBacktrack</code>, and a little time in <code class="code">Stabilizer</code>.</p>

<p>Whenever you generate a profile which contains timing information, a flame graph link will be show on the first page of your generated profile!</p>

<p><a id="X7D806D77799DC543" name="X7D806D77799DC543"></a></p>

<h4>1.2 <span class="Heading">FAQ / Problems</span></h4>


<ul>
<li><p><code class="func">ProfileLineByLine</code> (<a href="../../../doc/ref/chap7_mj.html#X86557887796F66FA"><span class="RefLink">Reference: ProfileLineByLine</span></a>) records the wall time (also known as clock time) that occurs between <code class="func">ProfileLineByLine</code> (<a href="../../../doc/ref/chap7_mj.html#X86557887796F66FA"><span class="RefLink">Reference: ProfileLineByLine</span></a>) and the next <code class="func">UnprofileLineByLine</code> (<a href="../../../doc/ref/chap7_mj.html#X7C5DED9C7CC77504"><span class="RefLink">Reference: UnprofileLineByLine</span></a>). This is why we start profiling, run our code, and then stop profiling all on a single line.</p>

</li>
</ul>

<ul>
<li><p>If you want to profile how long everything in <strong class="pkg">GAP</strong> takes, including the startup, then you can do this by giving the command line option <code class="code">--prof filename</code> when starting <strong class="pkg">GAP</strong>. This is equivalent to <strong class="pkg">GAP</strong> calling <code class="code">ProfileLineByLine("filename");</code> before loading any of the standard library (obviously, give your own filename).</p>

</li>
</ul>

<ul>
<li><p>Giving your output file the <code class="code">gz</code> extension makes <strong class="pkg">GAP</strong> 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.</p>

</li>
</ul>

<ul>
<li><p><code class="func">ProfileLineByLine</code> (<a href="../../../doc/ref/chap7_mj.html#X86557887796F66FA"><span class="RefLink">Reference: ProfileLineByLine</span></a>) takes an optional second argument which is a record, which can set some configuration options. Here are some of the options:</p>

</li>
</ul>

<ul>
<li><p><code class="code">wallTime</code>: Boolean (defaults to <code class="keyw">true</code>). 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!</p>

</li>
</ul>

<ul>
<li><p><code class="code">resolution</code>: Integer (defaults to <code class="code">0</code>). By default <strong class="pkg">GAP</strong> will record a trace of all executed code. When non-zero, <strong class="pkg">GAP</strong> instead samples which piece of code is being executed every <code class="code">resolution</code> nanoseconds. Setting this to a non-zero value improves performance and produces smaller traces, at the cost of accuracy. <strong class="pkg">GAP</strong> will still accurately record which statements are executed at least once. This is mainly useful when you wish to consider very long-running code.</p>

</li>
</ul>
<p><a id="X7F70AFBB7C6ACE3C" name="X7F70AFBB7C6ACE3C"></a></p>

<h4>1.3 <span class="Heading">Function-based profiling</span></h4>

<p>Sometimes you will have code that just runs too long to easily profile line-by-line. You can profile this in <strong class="pkg">GAP</strong>'s older function-based profiler. You can read more about this profiler in <strong class="pkg">GAP</strong>'s documentation (<a href="../../../doc/ref/chap7_mj.html#X7FDF923D7D2937A1"><span class="RefLink">Reference: Profiling</span></a>), but here is a quick example to get you going!</p>


<div class="example"><pre>
ProfileGlobalFunctions(true);
ProfileOperationsAndMethods(true);
f();
ProfileGlobalFunctions(false);
ProfileOperationsAndMethods(false);
DisplayProfile();
</pre></div>


<div class="chlinkprevnextbot"> <a href="chap0_mj.html">[Top of Book]</a>   <a href="chap0_mj.html#contents">[Contents]</a>    <a href="chap0_mj.html">[Previous Chapter]</a>    <a href="chap2_mj.html">[Next Chapter]</a>   </div>


<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0_mj.html">Top</a>  <a href="chap1_mj.html">1</a>  <a href="chap2_mj.html">2</a>  <a href="chapInd_mj.html">Ind</a>  </div>

<hr />
<p class="foot">generated by <a href="https://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>