CRMC v1.6.0 Last modifications 2016/03/29

**********************************************************
                     The Program "crmc"
**********************************************************

The program "crmc" (Cosmic Ray Monte Carlo) is an interface giving
access to different cosmic ray and non cosmic ray event generators by
an easy-to-use command line interface. The output can be stored in
different formats, i.e. in a root TTree or HepMC event file
(http://lcgapp.cern.ch/project/simu/HepMC/).

**********************************************************
                         Authors
**********************************************************

C++ interface : Colin Baus (colin.baus@kit.edu)
                Ralf Ulrich (ralf.ulrich@kit.edu)
Fortran interface : Tanguy Pierog (tanguy.pierog@kit.edu)

"crmc" is loosely based on the first epos-root interface
by X. Garrido (2009)

**********************************************************
                         References
**********************************************************

-- CRMC :

Reference : C. Baus, T. Pierog and R. Ulrich. To be published (2016)
           (please ask colin.baus@alumni.kit.edu when needed)


-- Hadronic interaction models :

* Post LHC :

EPOS LHC (-m0) : T. Pierog et al.
                    Phys.Rev. C92 (2015) 034906

QGSJETII-04 (-m7) : S.Ostapchenko,
                    Phys.Rev. D83 (2011) 014018

SIBYLL2.3 (-m6) : R. Engel, T.K. Gaisser, F. Riehn and T. Stanev,
                  Proc. 34th Int. Cosmic Ray Conf., The Hague (Netherlands), 1 (2015) 1313
                 and
                  E.-J. Ahn, R. Engel, T.K. Gaisser, P. Lipari, and T. Stanev,
                  Phys.Rev. D80 (2009) 094003

* Pre LHC :

DPMJET 3.06 : 10.1103/PhysRevC.77.014904

EPOS 1.99 (-m1) : K. Werner, F.M. Liu and T. Pierog,
                  Phys.Rev. C74 (2006) 044902
                 and
                  T. Pierog and K. Werner,
                  Nucl.Phys.Proc.Suppl. 196 (2009) 102-105

QGSJET01 (-m2) : N.N. Kalmykov, S. Ostapchenko, and A.I. Pavlov,
                 Nucl.Phys. B (Proc. Suppl.) 52B (1997) 17

QGSJETII-03 (-m11) : S. Ostapchenko,
                     Nucl.Phys.Proc.Suppl. 151 (2006) 143

**********************************************************
                       Installation
**********************************************************

To install please get the latest version from the authors and
install the following pre-requisites: BOOST, HEPMC, CMAKE (*).
The next optional step is to modify the CMakeLists.txt file to
your needs of which models should be compiled. After you have
done so, you can compile the program:


mkdir -p installed
cd installed
cmake DIRECTORY_WHERE_YOUR_SOURCE_IS
make install #you can compile faster with option --jobs=8


To test the installation you can use
make test ARGS=-V
or
bin/crmc -T <your options>
if you want to test some specific set of options.






(*) On CERN lxplus HEPMC is preinstalled. Try setting
SET(HEPMC_PREFIX /afs/cern.ch/sw/lcg/external/HepMC/2.06.08/x86_64-slc6-gcc48-opt/)
in your CMakeLists.txt

**********************************************************
                       Troubleshoot
**********************************************************

Please first try in your build diretory to run:
make clean
rm CMakeCache.txt

Sometime it can happen that the CMake cache still contains
old options or set paths that should be updated. In this
case the issues can be resolved by doing that.

On MacOS, please switch to STATIC libraries in CMakeLists.txt.

**********************************************************
                            Run
**********************************************************

Run the program by executing

./bin/crmc -h

to get the following help:

Options of CRMC:
  -h [ --help ]                      description of options
  -v [ --version ]                   show version and exits
  -o [ --output ] arg                output mode: hepmc (default), hepmcgz,
                                     root, lhe, lhegz
  -s [ --seed ] arg                  random seed between 0 and 1e9 (default:
                                     random)
  -n [ --number ] arg                number of collisions
  -m [ --model ] arg                 model [0=EPOS_LHC, 1=EPOS_1.99,
                                     6=Sibyll_2.3, 7=QGSJETII-04]
  -p [ --projectile-momentum ] arg   momentum/(GeV/c)
  -P [ --target-momentum ] arg       momentum/(GeV/c)
  -S [ --sqrts ] arg                 sqrt(s/GeV**2)
  -i [ --projectile-id ] arg         PDG or Z*10000+A*10
  -I [ --target-id ] arg             PDG or Z*10000+A*10
  -c [ --config ] arg                config file
  -f [ --out ] arg                   output file name (auto if none provided)
  -t [ --produce-tables ] [=arg(=1)] create tables if none are found
  -T [ --test ] [=arg(=1)]           test mode
  -x [ --cross-section ] [=arg(=1)]  calculate and print cross section only

for projectile and target Id the following shortcuts are allowed :
 1    = PDG(2212)       = proton
-1    = PDG(-2212)      = anti-proton
 12   = PDG(1000060120) = Carbon
 120  = PDG(211)        = pion+ (not for -I)
-120  = PDG(-211)       = pion- (not for -I)
 130  = PDG(321)        = kaon+ (not for -I)
-130  = PDG(-321)       = kaon- (not for -I)
 208  = PDG(1000822080) = Lead
using these shortcuts with automatic output file name generation will create more human readable names.

The environment variable $CRMC_OUT can be set to define the path the path of the output files,
otherwise $PWD is used as default path.

**Example to generate 100 7 TeV pp collisions with EPOS LHC:
bin/crmc -o hepmc -S7000 -n100 -m0

**Example to generate 100 1.38 ATeV PbPb collisions with EPOS 1.99:
bin/crmc -o hepmc -p1380 -P-1380 -n100 -i208 -I208 -m1

**Example to generate 100 5.02 ATeV pPb collisions with QGSJetII-04:
bin/crmc -o hepmc -p4000 -P-1577 -n100 -m7 -i2212 -I822080

**Example to test Sibyll2.3
bin/crmc -T -m6

**********************************************************
                         Options
**********************************************************

The details of the run can be controlled by the file "crmc.param".

In this file the 3 first commented options are valid for EPOS 1.99 and EPOS LHC only.

- By defaults EPOS models use a simplified treatment of QGP in events where the energy density is high enough (including in pp). If you
uncomment the line "!switch fusion off" this will be disable and running time will be shorter (but data description will be worth since
the physics model will be incomplete). In that mode EPOS is comparable to PYTHIA model (no final state interaction).

- By default only the final particles are recorded in the output file like for other cosmic ray models.
Uncommenting "!set istmax 1" allows the user to have the full chain of mother/daughter from the beam to the final particles with EPOS models.
The outfile is at least 2 times larger but includes the decayed particles and some special intermediate particles between the beam and
the real particles which allow the user to know where the particles were generated. The ids of such particles are the following :

90 : sum of all spectators in case of nuclear beam. It is the mother particle of final nuclear fragments (nucleons and light nuclei).
91 : cluster which will produce particle statistically. Mother of particles coming from mini-(quark-gluon) plasma in EPOS.
92 : string. Mother of particles coming directly from string fragmentation of initial Pomerons (which do not participate to plasma formation).
93 : remnant. Mother of particles coming from the beam remnants.

Each primary particle has a mother with id 9x. For technical reasons all particles with the same id and same momentum are in fact the same
initial object (cluster, string or remnant) which was split in different local pieces to keep the correct production vertexes of the final
particles. If a set of particles with the same id (91 or 92) and the same momentum has 2 different mothers (one from the projectile and one
from the target) it means that the string was produced by the interaction of this pair of nucleons or for a cluster that it was the closest
pair of nucleon which participate at the formation of the cluster (a cluster is formed by string pieces of different pairs but hepmc format
allows only one mother in that case).

- By default the cross-section is calculated by a numerical method with is valid only for h-p or h-A
(h being pion, kaon or nucleon) but not AB (nucleus-nucleus). If you uncomment "!set isigma 2" the inelastic
cross-section will be always correct but it takes several minutes to compute it (see Note on simulating Heavy Ion events).

**********************************************************
           Note on Simulating Heavy Ion (HI) Events
******I****************************************************

QGSJET01 and SIBYLL2.3 are limited to hA collisions with A<64 (A<19) and h being a pion, a kaon or a nucleon.
Only EPOS (1.99 and LHC) and QGSJETII (03 and 04) models can run (h)AB collisions with A and B up to 208.
QGSJETII was never designed for HI collisions, so results should be interpreted with care (no final
state interactions).
EPOS 1.99 and LHC include a simplified treatment of final state interaction but doesn't include full hydro
simulations as already possible in EPOS 2. It gives a good overall description of HI data but it should not be
used to interpret QGP related observables (flow, jet quenching, etc ...) since the model is oversimplified in
this distribution.
* For detailed simulations of HI collisions within EPOS 2, please contact K. Werner (werner@subatech.in2p3.fr).*

Concerning the cross-section calculation in EPOS, to avoid unnecessary long time calculation needed
for HI interactions, the default type of cross-section calculation is fast and good for hA but not reliable for
AB collisions (OK for p-Pb, pi-C but not for C-C or Pb-Pb for instance). So if you really need to have
a correct cross-section for PbPb scattering for example, you should uncomment the line "set isigma 2" in the
crmc.param file but it will take several minutes to compute the cross-section each time you start CRMC.
The number of loops is hard-coded (20000 check models.F) and does not depend on "-n" option.

The HepMC (2.06) IO library has a default limitation of the number of produced particles of 10000.
Thus, events with more than that number of secondaries are either truncated or skipped. For heavy ion
collisions this easily can become a problem in crmc. Please consider changing thie limitation to a
higher value. We suggest 200000, which works for all models at LHC energies so far. We are happy for
feedback on this issue if problems are encountered.
The CRMC code automatically checks for the
limit in the HepMC library and uses this during compile time. In order to change the limit, you
need to re-compile HepMC package and change the value in the line
    #define HEPEVT_EntriesAllocation 199990
in the top of the file HepMC/HEPEVT_Wrapper.h
When you run into this limitation you will receive lots of warning messages.

**********************************************************
           Example For Analysing HepMC Files
******I****************************************************
In the directory ./ExampleAnalyser you can find code for a small
example that loops over the hepmc events and its particles.  To
install make sure you have boost, hepmc, and root setup as for the
normal installation of crmc then run

"make" and "bin/analyse"

to run the code.