mirror of
https://github.com/boostorg/histogram.git
synced 2026-01-30 20:02:13 +00:00
242 lines
13 KiB
HTML
242 lines
13 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
|
|
<title>Notes — histogram 1.0 documentation</title>
|
|
|
|
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT: './',
|
|
VERSION: '1.0',
|
|
COLLAPSE_INDEX: false,
|
|
FILE_SUFFIX: '.html',
|
|
HAS_SOURCE: false
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
|
<link rel="top" title="histogram 1.0 documentation" href="index.html" />
|
|
<link rel="next" title="Types" href="types.html" />
|
|
<link rel="prev" title="Tutorial" href="tutorial.html" />
|
|
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
|
|
|
|
</head>
|
|
<body role="document">
|
|
|
|
<div class="document">
|
|
<div class="documentwrapper">
|
|
<div class="bodywrapper">
|
|
<div class="body" role="main">
|
|
|
|
<div class="section" id="notes">
|
|
<h1>Notes<a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h1>
|
|
<div class="section" id="dependencies">
|
|
<h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2>
|
|
<ul class="simple">
|
|
<li><a class="reference external" href="http://www.boost.org">Boost</a></li>
|
|
<li><a class="reference external" href="https://cmake.org">CMake</a></li>
|
|
<li><strong>Optional dependencies</strong><ul>
|
|
<li><a class="reference external" href="http://www.python.org">Python</a> for Python bindings</li>
|
|
<li><a class="reference external" href="http://www.numpy.org">Numpy</a> for Numpy support</li>
|
|
<li><a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> to (re)build this documentation</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="how-to-build-and-install">
|
|
<h2>How to build and install<a class="headerlink" href="#how-to-build-and-install" title="Permalink to this headline">¶</a></h2>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">HDembinski</span><span class="o">/</span><span class="n">histogram</span><span class="o">.</span><span class="n">git</span>
|
|
<span class="n">mkdir</span> <span class="n">build</span> <span class="o">&&</span> <span class="n">cd</span> <span class="n">build</span>
|
|
<span class="n">cmake</span> <span class="o">../</span><span class="n">histogram</span><span class="o">/</span><span class="n">build</span>
|
|
<span class="n">make</span> <span class="n">install</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Do <code class="docutils literal"><span class="pre">make</span> <span class="pre">test</span></code> to run the tests, or <code class="docutils literal"><span class="pre">ctest</span> <span class="pre">-V</span></code> for more output.</p>
|
|
<p><strong>Caveat</strong>: I couldn’t figure out a proper way to install the Python module with CMake, so for the time being, CMake will print a message with manual instructions instead. The main problem is how to pick the right dist-packages path in a platform-independent way, and such that it respects the <code class="docutils literal"><span class="pre">CMAKE_INSTALL_PREFIX</span></code>.</p>
|
|
</div>
|
|
<div class="section" id="tests">
|
|
<h2>Tests<a class="headerlink" href="#tests" title="Permalink to this headline">¶</a></h2>
|
|
<p>Most of the C++ interface is implicitly tested in the tests of the Python interface, which in turn calls the C++ interface.</p>
|
|
</div>
|
|
<div class="section" id="checks">
|
|
<h2>Checks<a class="headerlink" href="#checks" title="Permalink to this headline">¶</a></h2>
|
|
<p>Some checks are included in <code class="docutils literal"><span class="pre">test/check</span></code>. These are not strictly tests, and not strictly examples, yet they provide useful information that belongs with the library code. They are not build by default, building can be activated with the CMake flag <code class="docutils literal"><span class="pre">BUILD_CHECKS</span></code>.</p>
|
|
</div>
|
|
<div class="section" id="consistency-of-c-and-python-interface">
|
|
<h2>Consistency of C++ and Python interface<a class="headerlink" href="#consistency-of-c-and-python-interface" title="Permalink to this headline">¶</a></h2>
|
|
<p>The Python and C++ interface are indentical - except when they are not. The exceptions concern cases where a more elegant and pythonic way of implementing things exists. In a few cases, the C++ classes have extra member functions for convenience, which are not needed on the Python side.</p>
|
|
<dl class="docutils">
|
|
<dt>Properties</dt>
|
|
<dd>Getter/setter-like functions are wrapped as properties.</dd>
|
|
<dt>Keyword-based parameters</dt>
|
|
<dd>C++ member functions <a class="reference internal" href="types.html#_CPPv2N9histogram4fillEdz" title="histogram::fill"><code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::fill()</span></code></a> and <a class="reference internal" href="types.html#_CPPv2N9histogram5wfillEjPKdd" title="histogram::wfill"><code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::wfill()</span></code></a> are wrapped by the single Python member function <code class="xref py py-func docutils literal"><span class="pre">histogram.fill()</span></code> with an optional keyword parameter <code class="xref py py-obj docutils literal"><span class="pre">w</span></code> to pass a weight.</dd>
|
|
<dt>C++ convenience</dt>
|
|
<dd>C++ member function <a class="reference internal" href="types.html#_CPPv2NK9histogram4binsEj" title="histogram::bins"><code class="xref cpp cpp-func docutils literal"><span class="pre">histogram::bins()</span></code></a> is omitted on the Python side, since it is very easy to just query this directly from the axis object in Python. On the C++ side, this would require a extra type cast or applying a visitor.</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="section" id="benchmarks">
|
|
<h2>Benchmarks<a class="headerlink" href="#benchmarks" title="Permalink to this headline">¶</a></h2>
|
|
<p>One design goal of this project is to be fast. The act of filling the histogram with a number should be insignificant compared to the CPU cycles spend to retrieve/generate that number. Naturally, we also want to beat the competition.</p>
|
|
<p>The following table shows results of a simple benchmark against</p>
|
|
<ul class="simple">
|
|
<li><code class="xref cpp cpp-type docutils literal"><span class="pre">TH1I</span></code>, <code class="xref cpp cpp-type docutils literal"><span class="pre">TH3I</span></code> and <code class="xref cpp cpp-type docutils literal"><span class="pre">THnI</span></code> of the <a class="reference external" href="https://root.cern.ch">ROOT framework</a></li>
|
|
<li><a class="reference internal" href="types.html#module-histogram" title="histogram"><code class="xref py py-func docutils literal"><span class="pre">histogram()</span></code></a> and <code class="xref py py-func docutils literal"><span class="pre">histogramdd()</span></code> from the Python module <code class="xref py py-mod docutils literal"><span class="pre">numpy</span></code></li>
|
|
</ul>
|
|
<p>The benchmark against ROOT is implemented in C++, the benchmark against numpy in Python.</p>
|
|
<p>Remarks:</p>
|
|
<ul class="simple">
|
|
<li>The comparison with ROOT puts ROOT at the advantage, since <code class="xref cpp cpp-type docutils literal"><span class="pre">TH1I</span></code> and <code class="xref cpp cpp-type docutils literal"><span class="pre">TH3I</span></code> are specialized classes for 1 dimension and 3 dimensions, not a general class for N-dimensions like <code class="xref cpp cpp-class docutils literal"><span class="pre">boost::histogram</span></code>. ROOT histograms also lack a comparably flexible system to define different binning schemes for each axis.</li>
|
|
<li>Large vectors are pre-allocated and with random numbers drawn from a uniform or normal distribution for all tests. In the timed part, these numbers are read from the vector and put into the histograms. This reduces the overhead merely to memory access.</li>
|
|
<li>The test with uniform random numbers never fills the overflow and underflow bins, while the test with random numbers from a normal distribution does. This explains some of the differences between the two distributions.</li>
|
|
<li>All tests are repeated 10 times, the minimum is shown.</li>
|
|
</ul>
|
|
<p>Test system: Intel Core i7-4500U CPU clocked at 1.8 GHz, 8 GB of DDR3 RAM</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="29%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><th class="head">distribution</th>
|
|
<th class="head" colspan="3">uniform</th>
|
|
<th class="head" colspan="3">normal</th>
|
|
</tr>
|
|
<tr class="row-even"><th class="head">dimension</th>
|
|
<th class="head">1D</th>
|
|
<th class="head">3D</th>
|
|
<th class="head">6D</th>
|
|
<th class="head">1D</th>
|
|
<th class="head">3D</th>
|
|
<th class="head">6D</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr class="row-odd"><td>No. of fills</td>
|
|
<td>12M</td>
|
|
<td>4M</td>
|
|
<td>2M</td>
|
|
<td>12M</td>
|
|
<td>4M</td>
|
|
<td>2M</td>
|
|
</tr>
|
|
<tr class="row-even"><td>C++: ROOT [t/s]</td>
|
|
<td>0.127</td>
|
|
<td>0.199</td>
|
|
<td>0.185</td>
|
|
<td>0.168</td>
|
|
<td>0.143</td>
|
|
<td>0.179</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>C++: boost [t/s]</td>
|
|
<td>0.172</td>
|
|
<td>0.177</td>
|
|
<td>0.155</td>
|
|
<td>0.172</td>
|
|
<td>0.171</td>
|
|
<td>0.150</td>
|
|
</tr>
|
|
<tr class="row-even"><td>Py: numpy [t/s]</td>
|
|
<td>0.825</td>
|
|
<td>0.727</td>
|
|
<td>0.436</td>
|
|
<td>0.824</td>
|
|
<td>0.426</td>
|
|
<td>0.401</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>Py: boost [t/s]</td>
|
|
<td>0.209</td>
|
|
<td>0.229</td>
|
|
<td>0.192</td>
|
|
<td>0.207</td>
|
|
<td>0.194</td>
|
|
<td>0.168</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><code class="xref cpp cpp-class docutils literal"><span class="pre">boost::histogram</span></code> shows consistent performance comparable to the specialized ROOT histograms. It is faster than ROOT’s implementation of a N-dimensional histogram <code class="xref cpp cpp-type docutils literal"><span class="pre">THnI</span></code>. The performance of <code class="xref cpp cpp-class docutils literal"><span class="pre">boost::histogram</span></code> is similar in C++ and Python, showing only a small overhead in Python. It is consistently faster than numpy’s histogram functions.</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|
<div class="sphinxsidebarwrapper">
|
|
<h1 class="logo"><a href="index.html">histogram</a></h1>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<iframe src="https://ghbtns.com/github-btn.html?user=HDembinski&repo=histogram&type=watch&count=true&size=large"
|
|
allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<h3>Navigation</h3>
|
|
<ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="motivation.html">Motivation</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="intro.html">Introduction</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
|
|
<li class="toctree-l1 current"><a class="current reference internal" href="#">Notes</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#how-to-build-and-install">How to build and install</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#tests">Tests</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#checks">Checks</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#consistency-of-c-and-python-interface">Consistency of C++ and Python interface</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#benchmarks">Benchmarks</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="types.html">Types</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="rationale.html">Rationale</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="references.html">References</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="changelog.html">CHANGELOG</a></li>
|
|
</ul>
|
|
|
|
<div class="relations">
|
|
<h3>Related Topics</h3>
|
|
<ul>
|
|
<li><a href="index.html">Documentation overview</a><ul>
|
|
<li>Previous: <a href="tutorial.html" title="previous chapter">Tutorial</a></li>
|
|
<li>Next: <a href="types.html" title="next chapter">Types</a></li>
|
|
</ul></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="clearer"></div>
|
|
</div>
|
|
<div class="footer">
|
|
©2016, Hans Dembinski.
|
|
|
|
|
|
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.4.1</a>
|
|
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.7</a>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
</body>
|
|
</html> |