Repository files navigation

hep-mc is a C++ library forMonte Carlo integration. The following integration algorithms areimplemented:

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

• Parallelization: For each integrator a function prefixed withmpi_ is available that usestheMessage Passing Interface (MPI) to run the integration inparallel. The parallel integration is designed so that the functions return the numerically sameresult as their non-parallel counterpart. This means that the result is independent from thenumber of processors and only dependend on the seed of the random number generator. The parallelintegrators divide the work equally among all processors and useMPI_Accumulate to exchangedata after each iteration.
• Distributions: Arbitrarily many differential distributions can be generated during theintegration (see below). This feature can also be used to integrate many integrands in the samerun.
• Intermediate results: Callback functions can be used to print intermediate results as soon asthey are available. After the integration is finished each intermediate result can be extractedseparately if the automatically weighted average does not suit the user.
• Checkpointing system: A checkpoint allows to convert the state of an integrator into a textualformat, which can, for example, be written into a file. The checkpoint contains the completeinformation neccessary to restart an integration seemlessly: The result of the restartedintegration 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 andone has to work around resource limitations of a computer cluster. In this case one can leveragethe maximum run time of the cluster and save a checkpoint, restart from the checkpoint and runagain for the maximum run time, and so on and so forth, until the integration yields satisfactoryresults.
• Random numbers: Random numbers are generated using the C++ standard libraryrandom. This library offers many random numbergenerators from which the user can choose. If no random number generator is explicitly requested aMersennne twister (MT19937) is used.
• Numeric Types: All functions are templates in order to support all floating point types ofC++, i.e.float,double, andlong double. Kahan summation is used to prevent loss ofnumerical accuracy in long-running integrations.

The following (LO) differential distribution was generated using the MULTI CHANNEL integrator fromhep-mc running with 200 processors on theNEMO clusterfor about 30 hours, for 50 iterations each calling the integrand 1'000'000'000 times. The plotitself was generated withmatplotlib.

The integrands are matrix elements fromOpenLoops describingthe scattering of W and Z bosons. The generated distribution describes the transverse momentum ofthe leading jet. For more plots seearXiv:1904.00882.

This library uses features from the ISO C++11 standard which must be enabled with your compiler. Forthe 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 MPIvariants of the integrators include

#include <hep/mc-mpi.hpp>

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

Documentation is available online athttp://cschwan.github.io/hep-mc and can be generated fromsources (seeInstallation). The examples can be viewed from within the documentation.

The easiest way to use this library is to just download it from thereleases page and point yourcompiler to theinclude directory - there is no library that needs to be compiled.

If you want to automatically compile the example programs, generate the documentation, and/orinstall the headers you have to usemeson to buildhep-mc. If mesonis installed type

meson buildcd build

to generate the build files in the directorybuild and to enter it. Before you build you canselect a few options:

1. To enable building the examples, type

   meson configure -Dexamples=true

   in the build directory.

2. To enable tests and more examples that depend on MPI, enter

   meson configure -Dmpi=true

3. TheDoxygen documentation can be enabled with

   meson configure -Ddoxygen=true

   which creates a documentation of all classes and functions in thedoc/html directory.

4. 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.

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

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

A few other libraries offering Monte Carlo integration routines are:

• BOOST
• CUBA
• DVEGAS
• GSL