gMLQMC - A Generic Library for Multilevel (Quasi-)Monte Carlo

Introduction

This software framework, available here, is designed to aid in applying various single- and multilevel Monte Carlo (MC) and quasi-Monte Carlo (QMC) methods in a high-performance setting, for which such methods are naturally suited. We give various tools to ease implementation of multilevel methods, with arbitrary samplers.

See the publication outlining this library for an introduction to these methods and some example applications. A Doxygen documentation can be built by executing doxygen in the gMLQMC/doc folder.

User Guide

Compiling with CMake

The examples and tests accompanying the header-only library rely on the CMake build system. The code has been tested with recent versions of the Clang and GNU C++ compilers. Tests have been conducted on various systems, see the documentation in the cluster/ folder for system-specific details. To compile and execute the unit tests, run the following in the root of the repository:

mkdir build
cd build
cmake ..
make serial_testrun
make parallel_testrun

The examples can be compiled and listed with:

make examples
ls examples/

Using gMLQMC in your program

gMLQMC is a header-only library, thus you do not need to compile and install any library files. To use gMLQMC, you must only specify the path to the gMLQMC/include folder to the compiler. In CMake, this can be achieved by passing the full path to the include_directories command. Then, you can simply include the gMLQMC/gMLQMC.hpp header.

A good starting point may be one of the included example programs, located in the gMLQMC/examples folder. Some include:

IPL.cpp, containing an example of a single-level computation with IPL rules
nested.cpp, containing an example of a parallel integrand and “nested” simulation
parametric_convergence.cpp, for testing the convergence of discretizations of the parametric integration example mentioned in the paper
parametric_MLQMC.cpp, which applies multilevel methods to the parametric integrand, and can be used to reproduce the results from the paper
strategy_full.cpp, a minimal example of using the full parallelization strategy
strategy_serial.cpp, a minimal example of using the serial parallelization strategy

We briefly describe other headers included in the library:

gMLQMC/IPL/ contains code related to interlaced polynomial lattice rules, including routines to load them (cache.hpp), some helper classes and a sampler (sampler.hpp) for use in the single or multilevel methods.
gMLQMC/samplers/ contains various samplers, including uniform and standard normal random samplers, a Halton QMC sampler and a symlink to the IPL sampler (see the point above).
gMLQMC/strategy/ contains parallelization strategies. Currently, a serial and full parallel strategy (full.hpp) are available.
gMLQMC/tools/ contains various tools, among them standard_Ml.hpp which contains a routine for determining the optimal number of samples M_l, and vector_ops.hpp, which implements vector space operations for std::vector<T>.

Dependencies

Boost::Serialization allows generic serialization of objects, which is used by boost::mpi for communication operations.
Boost::MPI provides a C++ wrapper for the MPI interface, and simplifies many of the required operations. This library must be consistent with the version of MPI used. The user-specified functions may use any MPI commands, and are not required to use Boost::MPI.
An implementation of MPI must be available. gMLQMC has been tested with openMPI and mpich.
If IPL rules are to be used, the NTL (Number Theory Library) as well as GMP must be available. For CMake to find the libraries, set the environment variables NTL_DIR=/path/to/ntl and GMP_DIR=/path/to/gmp.

The following two dependencies are included in the code archive:

For testing, we use the header-only library Catch.
The jsoncons library is used for reading and writing json-formatted files, including the provided generating vector files. It is also header-only.

Serial Execution

In the case that you want to apply the methods from the library in serial, you can simply #define GMLQMC_SERIAL_FLAG before including any gMLQMC include files. This will avoid including Boost libraries (MPI and serialization), as well as other MPI includes.

Miscellaneous

License

Citation

The following bibtex entry can be used to cite this library, see also here.

@inproceedings{gMLQMC,
    author = {Gantner, Robert N.},
    title = {A Generic C++ Library for Multilevel Quasi-Monte Carlo},
    booktitle = {Proceedings of the Platform for Advanced Scientific Computing Conference},
    series = {PASC '16},
    year = {2016},
    isbn = {978-1-4503-4126-4},
    location = {Lausanne, Switzerland},
    pages = {11:1--11:12},
    articleno = {11},
    numpages = {12},
    url = {http://doi.acm.org/10.1145/2929908.2929915},
    doi = {10.1145/2929908.2929915},
    acmid = {2929915},
    publisher = {ACM},
    address = {New York, NY, USA},
}

Concept VectorSpace

The goal of this concept is to provide minimal requirements for classes representing elements of a vector space. The two basic requirements are an addition operation and a multiplication with a scalar; in C++ we assume these to be given by operator+ and operator*, respectively.

The type V satisfies VectorSpace if

the type satisfies CopyConstructible

and, given

v,w, two instances of V,
a, an instance of a scalar type (convertible to double),

the following expressions must be valid and have their specified effects.

Expression	Postcondition
`V u = v+w`	`u` contains the sum of `v` and `w`
`V u = a*w`	`u` contains the product of `a` and `v`

Note that only multiplication by a scalar from the left is assumed in the expressions above; the reverse argument ordering (i.e. w*a) is not required.

Higher-Order Quasi-Monte Carlo