Skip to content

Commit 113cd59

Browse files
AAAlvesJrAAAlvesJr
committed
Update README.md
1 parent f27cfe1 commit 113cd59

File tree

1 file changed

+98
-16
lines changed

1 file changed

+98
-16
lines changed

‎README.md‎

Lines changed: 98 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,72 @@ MCBooster
33

44
What is it?
55
-----------
6+
67
MCBooster is an header only library designed for the fast generation of
78
phase space events. The library makes use of Thrust and can deploy OpenMP
8-
threads, CUDA and Xeon Phi cores. It is focused on performance and precision.
9+
threads, CUDA and Xeon Phi cores. It is focused on performance and precision.
10+
11+
The libray core algorithm follow as close as it is possible the implementation of the class [TGenPhaseSpace](https://root.cern.ch/doc/master/TGenPhaseSpace_8cxx.html)
12+
from [ROOT framwork](https://root.cern.ch/),
13+
which is based on the [GENBOD function (W515 from CERNLIB)](http://cernlib.web.cern.ch/cernlib/mc/genbod.html)
14+
using the Raubold and Lynch method as described in
15+
16+
[_F. James, Monte Carlo Phase Space, CERN 68-15 (1968)_](https://cds.cern.ch/record/275743/files/CERN-68-15.pdf).
17+
18+
Main features
19+
-------------
20+
21+
Generates phase space Monte Carlo samples with up to nine particles in the final state, using very simple
22+
and intuitive interface. Example:
23+
```c++
24+
//generating 10M events of B0 -> J/psi K pi
25+
#include <mcbooster/GTypes.h>
26+
#include <mcbooster/Vector4R.h>
27+
#include <mcbooster/Generate.h>
28+
...
29+
//setting the mother particle
30+
Vector4R B0(5.2795, 0.0, 0.0, 0.0);
31+
32+
//setting the masses of the daughter particles
33+
vector<GReal_t> masses;
34+
masses.push_back(3.096916); // J/psi
35+
masses.push_back(0.493677); // K
36+
masses.push_back(0.13957018); // pi
37+
38+
//generator ctor for 10M events
39+
PhaseSpace phsp(B0.mass(), massesB0, 10000000);
40+
41+
//run the generator
42+
phsp.Generate(B0);
43+
44+
//Unweight the events flags the accepted and rejected events
45+
phsp.Unweight();
46+
47+
//export events to the host (in case it is necessary)
48+
Events *GenEvents = new Events(masses.size(), 10000000);
49+
phsp.Export(GenEvents);
50+
...
51+
```
52+
Other key features are:
53+
54+
1. Decays can be generated with mother particles are rest or with a definite four-vector.
55+
this feature allows the generation of sequential decays.
56+
57+
2. Generates weighted and "unweighted" samples simultaneously.
58+
59+
3. Allows the fast parallel evaluation of arbitrary functions taking as
60+
argument up to ten particles as input.
61+
62+
4. Allows the fast parallel evaluation of arrays of variables simultaneously.
63+
64+
MCBooster also provides a bunch of custom types, containers and an increasing number of algorithms
65+
to maximaze performance, avoid unecessary usage of memory and grant flexibility and protability between
66+
host and device calculations and deployment scenarios.
67+
68+
Just changing .cu to .cpp in any source code writen only using the provided cosntructs is enough
69+
to compile your application for OpenMP using GCC in a machine without a NVIDIA GPU installed.
70+
71+
Many other possibilities and functionaties, bounded only by the creativity of the users.
972
1073
The Latest Version
1174
------------------
@@ -26,30 +89,49 @@ Users can also browse the documentation by class, file or name using the followi
2689
2790
3.[names](http://multithreadcorner.github.io/MCBooster/namespacemembers.html)
2891
92+
Installation and requirements
93+
-----------------------------
94+
95+
MCBooster is a header only library, so no build process is necessary to install it.
96+
Just place the `mcbooter` folder and its contents where your system can find it.
97+
The library run on Linux systems and requires C++11 and the [Thrust library](https://thrust.github.io/).
98+
Some examples demonstrating the basic features of the library are included in the `src` folder.
99+
These code samples require [ROOT](https://root.cern.ch/) and [TCLAP](http://tclap.sourceforge.net/) library.
100+
CUDA based projects will require a local installation of [CUDA Tookit](https://developer.nvidia.com/cuda-toolkit) with version 6.5 or higher.
101+
Alternatively, projects the targeting [OpenMP](http://openmp.org/wp/) backend can be compiled with either nvcc or gcc.
102+
The CUDA runtime is not required to use OpemMP with gcc.
29103
30104
Examples
31105
--------
32106
33-
Some example code samples demonstrating the basic usage of the library are stored in the src directory.
107+
Some example code samples demonstrating the basic usage of the library are stored in the src directory, in the project source tree.
34108
These samples can be built using [CMAKE](https://cmake.org/) according the following instructions:
35109
36-
1. clone the git repository: __`git clone https://github.com/MultithreadCorner/MCBooster.git`__
37-
2. go to MCBooster directory: __`cd MCBooster`__
38-
3. create a build directory: __`mkdir build`__
39-
4. go to build directory: __`cd build`__
40-
4. __`cmake ../`__
41-
5. __`make`__
110+
1. clone the git repository: `git clone https://github.com/MultithreadCorner/MCBooster.git`
111+
2. go to MCBooster directory: `cd MCBooster`
112+
3. create a build directory: `mkdir build`
113+
4. go to build directory: `cd build`
114+
4. `cmake ../`
115+
5. `make`
42116
43-
Users with root privilegies can do `make install` and get the targets installed into system-install-dir/bin (usually /usr/local. __Notice that the project installation path is printed out in the setp 4__). Users without root privileges can point the installation path to a different location doing __`cmake -DCMAKE_INSTALL_PREFIX=<user-path>/ ../`__.
44-
To run an example do ./example-name
117+
Users with root privilegies can do `make install` and get the targets installed into system-install-dir/bin
118+
(usually /usr/local. __Notice the project installation path is printed out in the setp 4__). Users without root privileges can point the installation path to a different location cmake `-DCMAKE_INSTALL_PREFIX=<user-path>/ ../`.
45119
46-
Installation and requirements
47-
-----------------------------
120+
The examples are named according to the convention `MCBooster_Example_<BACKEND AND COMPILER>_<EXAMPLE NAME>`. To run an example do `./example-name`.
121+
The examples are described below:
48122
49-
MCBooster is a header only library, so no build process is necessary to install it.
50-
The library run on Linux systems and requires C++11 and the [Thrust library](https://thrust.github.io/). The code samples require [ROOT](https://root.cern.ch/) and [TCLAP](http://tclap.sourceforge.net/) library.
51-
CUDA based projects will require a local installation of [CUDA Tookit](https://developer.nvidia.com/cuda-toolkit) with version 6.5 or higher.
52-
Alternatively, projects the targeting [OpenMP](http://openmp.org/wp/) backend can be compiled with nvcc or gcc directly.
123+
1. __B2KPiJpsi__ : Generates a sample of B0 -> Jpsi K pi, with J/psi -> mu+ mu- and calculates in parallel, for each event, the variables:
124+
* M(K,pi), the Kpi invariant mass.
125+
* M(J/psi,pi), the J/psipi invariant mass.
126+
* cos theta(K), the helicity angle of the Kpi.
127+
* cos theta(mu), the helicity angle of the J/psi
128+
* phi, the angle between the decay planes
129+
130+
The program print some events and timing information to sdtout and plotsthe distributions of the above variables plus the B0 -> J/psiK pi Dalitz plot.
131+
132+
2. __GenerateSample__ : Takes arguments from the command line, generates a sample and save it into a ROOT TTree.
133+
134+
3. __PerformanceTest__: Meausure the time to generate and export samples in function of the number of events and number of particles.
53135
54136
Licensing
55137
---------

0 commit comments

Comments
 (0)