cschwan/hep-mc

Project Description

hep-mc is a C++ library for Monte Carlo integration. The following integration algorithms are implemented:

PLAIN (naive Monte Carlo integration),
VEGAS [1] [2], and
MULTI CHANNEL with adaptive weight optimization [3].

Features

Parallelization: For each integrator a function prefixed with mpi_ is available that uses the Message Passing Interface (MPI) to run the integration in parallel. The parallel integration is designed so that the functions return the numerically same result as their non-parallel counterpart. This means that the result is independent from the number of processors and only dependend on the seed of the random number generator. The parallel integrators divide the work equally among all processors and use MPI_Accumulate to exchange data after each iteration.
Distributions: Arbitrarily many differential distributions can be generated during the integration (see below). This feature can also be used to integrate many integrands in the same run.
Intermediate results: Callback functions can be used to print intermediate results as soon as they are available. After the integration is finished each intermediate result can be extracted separately if the automatically weighted average does not suit the user.
Checkpointing system: A checkpoint allows to convert the state of an integrator into a textual format, which can, for example, be written into a file. The checkpoint contains the complete information neccessary to restart an integration seemlessly: The result of the restarted integration does not depend where the checkpoint was created, only on the integration parameters (iterations, calls, seed). This is useful, for example, when an integration takes very long and one has to work around resource limitations of a computer cluster. In this case one can leverage the maximum run time of the cluster and save a checkpoint, restart from the checkpoint and run again for the maximum run time, and so on and so forth, until the integration yields satisfactory results.
Random numbers: Random numbers are generated using the C++ standard library random. This library offers many random number generators from which the user can choose. If no random number generator is explicitly requested a Mersennne twister (MT19937) is used.
Numeric Types: All functions are templates in order to support all floating point types of C++, i.e. float, double, and long double. Kahan summation is used to prevent loss of numerical accuracy in long-running integrations.

Showcase

The following (LO) differential distribution was generated using the MULTI CHANNEL integrator from hep-mc running with 200 processors on the NEMO cluster for about 30 hours, for 50 iterations each calling the integrand 1'000'000'000 times. The plot itself was generated with matplotlib.

The integrands are matrix elements from OpenLoops describing the scattering of W and Z bosons. The generated distribution describes the transverse momentum of the leading jet. For more plots see arXiv:1904.00882.

Usage

This library uses features from the ISO C++11 standard which must be enabled with your compiler. For the GCC and clang compilers this can be done by passing an additional parameter to the compiler, for example

g++ -std=c++11 my_program.cpp

The inclusion of the main header,

#include <hep/mc.hpp>

is sufficient to use it; you do not need to link against a library. If you intend to use the MPI variants of the integrators include

#include <hep/mc-mpi.hpp>

instead. To see the library in action take a look at the example programs in the examples directory.

Documentation and Examples

Documentation is available online at http://cschwan.github.io/hep-mc and can be generated from sources (see Installation). The examples can be viewed from within the documentation.

Installation

The easiest way to use this library is to just download it from the releases page and point your compiler to the include directory - there is no library that needs to be compiled.

If you want to automatically compile the example programs, generate the documentation, and/or install the headers you have to use meson to build hep-mc. If meson is installed type

meson build
cd build

to generate the build files in the directory build and to enter it. Before you build you can select a few options:

To enable building the examples, type
```
meson configure -Dexamples=true
```
in the build directory.
To enable tests and more examples that depend on MPI, enter
```
meson configure -Dmpi=true
```
The Doxygen documentation can be enabled with
```
meson configure -Ddoxygen=true
```
which creates a documentation of all classes and functions in the doc/html directory.
More options are shown when entering
```
meson configure
```
which will display all options (including install paths) that can be changed by using the syntax -Doption-name=value as used above.

To finally build everything type

ninja

and/or

ninja install

to install the headers.

Support

If you spot a problem or a bug, or if you have a feature request, please use the Issues page to let me know. If you have any question concerning this library don't hesitate to write an email to me. If you prefix your subject line with a [hep-mc] you'll increase the chance of getting an answer quickly :).

Name

The hep in the project name stands for high-energy physics (see the showcase above), which is the area in which I use this library myself, but in fact it is completely general in terms of applications. Unfortunately, when I named this library, I wasn't aware of another project with a similar name: HepMC.

Similar Libraries

A few other libraries offering Monte Carlo integration routines are:

References

[1]	G. P. Lepage. "A New Algorithm for Adaptive Multidimensional Integration". J. of Comp. Phys. 27 (1978), pp. 192-203. DOI: 10.1016/0021-9991(78)90004-9.

[2]	G.P. Lepage. "VEGAS: An Adaptive Multi-dimensional Integration Program". Cornell preprint CLNS 80-447 (1980).

[3]	R. Kleiss, R. Pittau. "Weight optimization in multichannel Monte Carlo". Comp. Phys. Commun. 83 (1994), pp. 141-146. DOI: 10.1016/0010-4655(94)90043-4. arXiv: hep-ph/9405257.

cschwan / hep-mc