pygram11 0.5.0

Fast histogramming in python built on pybind11 and OpenMP.

pygram11

Simple and fast histogramming in Python via pybind11 and accelerated with OpenMP.

pygram11 provides fast functions for calculating histograms (and their sums-of-weights squared). The API is very simple, documentation found here (you'll also find some benchmarks there). I also wrote a blog post with some simple examples.

Installing

pygram11 requires NumPy and pybind11 (and therefore a C++ compiler with C++11 support).

From conda-forge

For a simple installation process via the conda package manager pygram11 is part of conda-forge. These builds include OpenMP acceleration.

conda install pygram11 -c conda-forge

From PyPI

Binary wheels are provided for Linux and macOS, they can be installed from PyPI via pip. These builds include OpenMP acceleration.

pip install pygram11

From Source

pip install git+https://github.com/douglasdavis/pygram11.git@master

Note: For releases older than v0.5, when building from source or PyPI, pybind11 was required to be explicitly installed before pygram11 (because setup.py used pybind11 to determine include directories). Starting with v0.5 pybind11 is bundled with the source for non-binary (conda-forge or wheel) installations.

In Action

A histogram (with fixed bin width) of weighted data in one dimension, accelerated with OpenMP:

>>> x = np.random.randn(10000)
>>> w = np.random.uniform(0.8, 1.2, 10000)
>>> h, staterr = pygram11.histogram(x, bins=40, range=(-4, 4), weights=w, omp=True)

A histogram with fixed bin width which saves the under and overflow in the first and last bins (using __ to catch the None returned due to the absence of weights):

>>> x = np.random.randn(1000000)
>>> h, __ = pygram11.histogram(x, bins=20, range=(-3, 3), flow=True, omp=True)

A histogram in two dimensions with variable width bins:

>>> x = np.random.randn(10000)
>>> y = np.random.randn(10000)
>>> xbins = [-2.0, -1.0, -0.5, 1.5, 2.0]
>>> ybins = [-3.0, -1.5, -0.1, 0.8, 2.0]
>>> h, __ = pygram11.histogram2d(x, y, bins=[xbins, ybins])

Other Libraries

• There is an effort to develop an object oriented histogramming library for Python called boost-histogram. This library will be feature complete w.r.t. everything a physicist needs with histograms.
• Simple and fast histogramming in Python using the NumPy C API: fast-histogram. No weights or overflow).
• If you want to calculate histograms on a GPU in Python, check out cupy.histogram. They only have 1D histograms (no weights over overflow).

---

If there is something you'd like to see in pygram11, please open an issue or pull request.