CRMC v2.0.1 Last modifications 2021/08/26 Please cite as: Ralf Ulrich, Tanguy Pierog, Colin Baus. "The Cosmic Ray Monte Carlo Package, CRMC (v2.0.1)". Zenodo (2021). https://doi.org/10.5281/zenodo.4558705 ********************************************************** 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, HepMC3 event file, or Rivet output directly. Version with extended arrays for heavy ion collisions. ********************************************************** Authors ********************************************************** C++ interface : Colin Baus 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) Special thanks to Christian Holm Christensen for his contributions to migrate to HepCM3 as well as to directly write Rivet output. Great! ********************************************************** References ********************************************************** -- CRMC : Reference : C. Baus, T. Pierog and R. Ulrich. See also: https://doi.org/10.5281/zenodo.4558705 -- Hadronic interaction models : * Post LHC : EPOS LHC (-m 0) : T. Pierog et al. Phys.Rev. C92 (2015) 034906 QGSJETII-04 (-m 7) : S.Ostapchenko, Phys.Rev. D83 (2011) 014018 SIBYLL2.3d (-m 6) : F. Riehn, R. Engel, A. Fedynitch, T.K. Gaisser, and T. Stanev, hep-ph: 1912.03300 and E.-J. Ahn, R. Engel, T.K. Gaisser, P. Lipari, and T. Stanev, Phys.Rev. D80 (2009) 094003 DPMJETIII 2017-1 (-m 12) : Fedynitch at al. DPMJETIII 2019-1 (-m 12) : Fedynitch at al. * Pre LHC : DPMJET 3.06 (-m 12) : 10.1103/PhysRevC.77.014904 (not linked any more) EPOS 1.99 (-m 1) : 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 (-m 2) : N.N. Kalmykov, S. Ostapchenko, and A.I. Pavlov, Nucl.Phys. B (Proc. Suppl.) 52B (1997) 17 QGSJETII-03 (-m 11) : S. Ostapchenko, Nucl.Phys.Proc.Suppl. 151 (2006) 143 * Other models : PHOJET 1.12 (-m 8) : R. Engel, J. Ranft and S. Roesler, Phys. Rev. D52 (1995) 1459 and F. W. Bopp, R. Engel and J. Ranft arXiv:hep-ph/9803437. PYTHIA 6.4.28 (-m 4) : T. Sjostrand, S. Mrenna and P. Skands, JHEP 0605 (2006) 026 HIJING 1.38 (-m 5) : obsolete (please use a more modern version like HIJING++) GHEISHA (-m 3) : obsolete ********************************************************** Installation ********************************************************** To install please get the latest version from the authors and install the following pre-requisites: BOOST, HepMC3, CMAKE (*). Consider also the extensions provided by Rivet (>v3) and fastjet. We recommend to use a LTS Ubuntu version to avoid compatibility problems (latest tests done using 20.4). In order to compile with Fastjet, set the Fastjet_DIR environment variable to the location of your Fastjet installation. In order to compile with HepMC3, make sure that the 'HepMC3-config' tool is accessible via your PATH environment variable. In order to compile with Rivet, make sure that the 'rivet-config' tool is accessible via your PATH environment variable. Note, the only one model is compiled by default: EPOS-LHC. You can select many further models by passing "-DCRMC_SIBYLL" etc for all available models to cmake. Check 'CMakeLists.txt' for a list of models, or even better use the 'ccmake' tool for all configurations. After you have done so, you can compile the program: mkdir -p installed cd installed cmake [any futher config like -DCRMC_QGSJETII04] 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 if you want to test some specific set of options. (*) HepMC2 is not recommended any more. The support is deprecated and will disappear. Use HepMC3. ********************************************************** 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: hepmc3gz (default), hepmc3, hepmc, hepmcgz, rivet, 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 -a [ --analysis ] arg Rivet analysis to execute -r [ --rivet-include ] arg add to Rivet search path -L [ --preload ] arg add preloaded data to Rivet 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 -S 7000 -n 100 -m 0 **Example to generate 100 1.38 ATeV PbPb collisions with EPOS 1.99: bin/crmc -o hepmc -p 1380 -P -1380 -n 100 -i 208 -I 208 -m 1 **Example to generate 100 5.02 ATeV pPb collisions with QGSJetII-04: bin/crmc -o hepmc -p 4000 -P -1577 -n 100 -m 7 -i 2212 -I 822080 **Example to test Sibyll2.3d bin/crmc -T -m 6 ** On Rivet output if you select Rivet as output CRMC will produce a yoda file with analysis output for you. Of course, you have to specify suited Rivet analyses using the "-a" option (e.g. "-a CMS_2011_S9120041"). You may combined as many analyses as you wish in multiple "-a" options. You can also define specific Rivet search path and preloads using the -r and -L options. ********************************************************** 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 without color reconnection (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.3d 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 4. It gives a good overall description of HI data but it should not be used to interpret QGP related observables (correlation, flow, jet quenching, etc ...) since the model is oversimplified in this distribution. * For detailed simulations of HI collisions within EPOS 4, 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 this 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 HepMC3 Files ******I*************************************************** In the directory ./ExampleAnalyser you can find code for a small example that loops over the hepmc3 and hepmc3gz files and its particles. To install make sure you have boost, hepmc3, and root setup as for the normal installation of crmc then run "make" and "bin/analyse" to run the code.