Hydra: A C++ repository from MultithreadCorner

What is it ?
Main features
Hydra and Thrust
Supported Parallel Backends
The Latest Version
Documentation
- Reference manual
- Users guide
Installation and requirements
Examples
Licensing
Contact the developers
Author
Acknowledgement

What is it?

Hydra is a C++17/20 compliant and header only framework designed to perform common data analysis tasks on massively parallel platforms. Hydra provides a collection of containers and algorithms commonly used in HEP data analysis, which can deploy transparently OpenMP, CUDA and TBB enabled devices, allowing the user to re-use the same code across a large range of available multi-core CPU and accelerators. The framework design is focused on performance and precision.

The core algorithms follow as close as possible the implementations widely used in frameworks like ROOT and libraries like GSL.

Main features

Currently Hydra implementation includes:

Generation of phase-space Monte Carlo samples with any number of particles in the final states. Sequential decays, calculation of integrals of models over the corresponding phase-space and production of weighted and unweighted samples, which can be flat or distributed following a model provided by the user.
Sampling of multidimensional pdfs.
Multidimensional maximum likelihood fits using binned and unbinned data sets.
Multi-layered simultaneous fit of different models, over different datasets, deploying different parallelization strategies for each submodel.
Calculation of S-Plots, a popular technique for statistical unfolding of populations contributing to a sample.
Evaluation of multidimensional functions over heterogeneous data sets.
Numerical integration of multidimensional functions using self-adaptive Monte Carlo and quadrature methods.
Multidimensional sparse and dense histogramming of large samples.
Object-based interface to FFTW and CuFFT for performing Fast Fourier Transform in CPU and GPU.
Fitting models containing FFT based one-dimensional convolution components with arbitrary signal and kernel shapes.
Booststrap and real cubic spline (1D, 2D, 3D and 4D)for datasets on CPU and GPU.
Sobol low discrepance sequences up to 3667 dimensions.
Seven fast and reliable counter based pseudo-random number generators.

Hydra also provides a bunch of custom types, optimized containers and a number of algorithms and constructs to maximize performance, avoiding unnecessary usage of memory and without losing the flexibility and portability to compile and run the same code across different platforms and deployment scenarios.

For example, just changing .cu to .cpp in any source code written only using the Hydra and standard C++14 is enough to compile your application for OpenMP or TBB compatible devices using GCC or other compiler in a machine without a NVIDIA GPU installed.

In summary, by using Hydra the user can transparently implement and dispatch typical bottle-neck calculations to a suitable parallel device and get speed-up factors ranging from dozens to hundreds.

Hydra and Thrust

Hydra is implemented on top of the Thrust library and relies strongly on Thrust's containers, algorithms and backend management systems. However, since the official version of Thrust supports tuples with maximum ten elements, in order to overcome this limitation, Hydra uses an maintain an unofficial version, initially forked from the original by Andrew Currigan and collaborators. This version implements variadic tuples and related classes, as well as provides some additional functionality, which are missing in the official Thrust and is necessary for Hydra, but too specific to "pull request".
In order to keep Hydra uptodated with the latest bug-fixes and architetural improvements in Thrust, at each Hydra release, the official Thrust library is patched with the Currigan's variadic tuple implementation. This Thrust version is accessible in hydra::thrust namespace and does not conflicts in anyway with the users system Cuda Tookit installation or its deployment in applications also using Hydra. Same logics applies to Eigen and Boost.Math, which are also distributed with Hydra and are accessible in hydra::Eigen and hydra::boost::math namespaces.

Supported Parallel Backends

Hydra uses the underlying Thrust's "backend systems" to control how the algorithms get mapped to and executed on the parallel processors and accelerators available to a given application. When necessary, the backends can be specified using the symbols hydra::device::sys_t, hydra::host::sys_t, hydra::omp::sys_t, hydra::tbb::sys_t, hydra::cuda::sys_t, hydra::cpp::sys_t. The backends hydra::device::sys_t and hydra::host::sys_t are selected in compile time using the macros HYDRA_HOST_SYSTEM and HYDRA_DEVICE_SYSTEM. The following possibilities are available:

host: CPP, OMP, TBB
device: CPP, OMP, TBB, CUDA

For example, this will compile my_program.cu using OpenMP as host backend and CUDA as device backend using the NVidia's compiler nvcc:

nvcc  -I/path/to/Hydra -Xcompiler -fopenmp -DHYDRA_HOST_SYSTEM=OMP -DHYDRA_DEVICE_SYSTEM=CUDA  my_program.cu ...

The available "host" and "device" backends can be freely combined. Two important features related to Hydra's design and the backend configuration:

If CUDA backend is not used or available, NVCC and the CUDA runtime are not necessary. The programs can be compiled with GCC, Clang or other host compiler compatible with C++17 support directly.
Programs written using only Hydra, Thrust, STL and standard c++ constructs, it means programs without any raw CUDA code or calls to the CUDA runtime API, can be compiled with NVCC, to run on CUDA backends, or a suitable host compiler to run on OpenMP , TBB and CPP backends. Just change the source file extension from .cu to .cpp, or something else the host compiler understands.

The Latest Version

The latest release can be downloaded here.

Documentation

Reference manual

The complete and updated Doxygen source code documentation in HTML format is available at the Reference documentation web-page. It is also possible to browse the documentation by class, file or name using the links:

1.classes

2.files

3.names

User's guide

The Hydra User's Guide is available in the following formats:

Installation and requirements

Hydra is a header only library, so no build process is necessary to install it. Just place the hydra folder and its contents where your system can find it. The framework runs on Linux systems and requires at least a host compiler supporting C++14. To use NVidia's GPUs, CUDA 9.2 or higher is required.
A suite of examples demonstrating the basic features of the framework is included in the examples folder. All the examples are organized in .inl files, which implements the main() function. These files are included by .cpp and .cu files, which are compiled according with the availability of backends. TBB and CUDA backends requires the installation of the corresponding libraries and runtimes. These code samples uses, but does not requires ROOT for graphics, and TCLAP library for process command line arguments. Some functionality in Hydra requires Eigen, GSL, CuFFT and FFTW.

Examples

The examples are built using CMAKE with the following instructions:

clone the git repository: git clone https://github.com/MultithreadCorner/Hydra.git
go to the Hydra repository: cd Hydra
create a build directory: mkdir build
go to build directory: cd build
cmake ..
make or make <target> (possible targets are: examples_cpp, examples_tbb, examples_omp, examples_cuda, tests)

The compiled examples will be placed in the build/examples folder. The sub-directories are named according to the functionalities they illustrate.

The examples are listed below:

async : async_mc
fit : basic_fit, multidimensional_fit, extended_logLL_fit, fractional_logLL_fit, phsp_unweighting_functor_and_fit, splot
histograming : dense_histogram, sparse_histogram
misc : multiarray_container, multivector_container, variant_types
numerical_integration : adaptive_gauss_kronrod, gauss_kronrod, plain_mc, vegas
phase_space : phsp_averaging_functor, phsp_evaluating_functor, phsp_reweighting, phsp_basic, phsp_unweighting, phsp_chain, phsp_unweighting_functor
phys : breit_wigner_plus_chebychev, breit_wigner_plus_polynomial, crystal_ball_plus_exponential, dalitz_plot, double_gaussian_plus_exponential, gaussian_plus_argus, ipatia_plus_argus, particle_mass, pseudo_experiment
random : basic_distributions, sample_distribution
root_macros : macros to run examples in ROOT

Each compiled example executable will have an postfix (ex.:_cpp, _cuda, _omp, _tbb) to indicate the deployed device backend.
All examples use CPP as host backend.

Recent publications citing Hydra and presentations at conferences and workshops

How to cite Hydra

[1]Alves Junior, A.A. - MultithreadCorner/Hydra, (2018). doi:10.5281/zenodo.1206261

bibtex:

@misc{hydra,
  
  author       = {Alves Junior, A A},
  title        = {MultithreadCorner/Hydra},
  month        = March,
  year         = 2018,
  doi          = {10.5281/zenodo.1206261},
  url          = {https://doi.org/10.5281/zenodo.1206261}
}

Licensing

Hydra is released under the GNU General Public License version 3. Please see the file called COPYING.

Contact the developers

Here’s what you should do if you need help or would like to contribute:

If you need help or would like to ask a general question, subscribe and use https://groups.google.com/forum/#!forum/hydra-library-users.
If you found a bug, use GitHub issues.
If you have an idea, suggestion or whatever, use GitHub issues.
If you want to contribute, submit a pull request https://github.com/MultithreadCorner/Hydra.

Author

Hydra was created and is maintained by Antonio Augusto Alves Jr.

Acknowledgement

Initial Hydra's development was supported by the National Science Foundation under the grant number PHY-1414736. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the developers and do not necessarily reflect the views of the National Science Foundation.

MultithreadCorner/Hydra

Table of Contents