DPMJet is a multipurpose generator Based on the Dual Parton Model (DPM), developed by Stefan Roesler, Ralph Engel and Johannes Ranft. It is capable of simulating hadron-hadron, hadron-nucleus, nucleus-nucleus, photon-hadron, photon-photon and photon-nucleus interactions from a few GeV up to the highest cosmic ray energies. Our current version installed on EIC machines is modified by Nestor Armesto, which takes the nuclear fission effect into consideration through FLUKA, thus can be used in both ep and eA simulation.
The DPMJet code is written in FORTRAN. It unifies all the features of the event generators DPMJET-II and DTUNUC-2 which include intra-nuclear cascading, while the individual collisions are simulated based on the PHOJET1.12 code. JETSET takes care of the fragmentation part using string model. The extension to nuclei is done through Glauber-Gribov theory. Furthermore, the model employs FLUKA to simulate nuclear evaporation, breakup and photonic de-excitation.
Documentation on DPMJet
(1) An introduction to DPMJET3
(2) An input card manual for our dpmjet code
(3) Manual for the phojet1.12
(4) Data common description same as version 2.5
Some modifications and the applicability of this code
Since Phojet, the code responsible for the elementary interaction generation, only describes the interaction involving photons at very low Q2, or real photons in another word, this DPMJET code allows basically the simulation of photoproduction off nuclei.
Besides, a modification in the photon flux of dpmjet is implemented based on the photon flux used in EIC pythia code to debug a boundary effect in the DPMJET code. Some more detailed information could be found in the following slides.
the bug hunt in DPMJET
DPMJET subprocesses in ep/eA
|1||non-diffractive inelastic scattering|
|2||purely elastic scattering|
|4||central diffraction (double-pomeron scattering)|
|5||single diffractive dissociation of particle 1|
|6||single diffractive dissociation of particle 2|
|7||double diffractive dissociattion|
|8||hard direct interactions|
hard process id for all the channels in ep/eA
|1||g g → g g|
|2||q qbar → g g|
|3||g q → g q|
|4||g g → q qbar|
|5||q qbar → q qbar|
|6||q qbar → q' qbar'|
|7||q q → q q|
|8||q q' → q q'|
|10||γ q → g q|
|11||γ g → q qbar|
More detailed information about the process could be found in the phojet manual(3).
How to run this code
the code can be found on the afs directory for EIC at BNL
The main program is in this directory and called user-eA3.0-5.f. The code system is consisted of dpmjet3.0-5F.f ( the version of DPMJET with interface to FLUKA modified by Nestor ), phojet1.12-35c4.f, and pythia6115dpm3v1.f ( contains the code of JETSET ). A simple README is kept in this directory to explain all the code and necessary data files for the initialization. You have to use this code with FLUKA, thus a variable FLUPRO pointing to the FLUKA directory is necessary, and you also need to link libflukahp.a when creating DPMJET-executable.
For ep collision
dpmjet < ep.inp > XXX.log
ep.inp is one the steer file example in the directory to run DPMJET with settings for ep collision. You can set the output unit by the input card OUTPUT to generate your data sample with a name of fort.xxx. Generally, this xxx is set to some value between 20 to 99, since some of the numbers less than 20 are used for other purposes. If you don't give a output unit number, the default output file will be named as fort.89. The target is set to proton in the input card TARPAR. Collision energy has to be given according to the conventions in the ENERGY card, first comes the electron energy in nucleon rest frame, then a 0, and the last one is energy of proton beam in lab frame. Kinematics cut can be made by the L-TAG card, you can also switch on only the processes you want in the card of PROCESS. In the end, you have to specify the number of events by the number following START. More detailed information about the input cards can be found in the input card manual(2).
For eA collision
dpmjet < eAu.inp > XXX.log
eAu.inp is the steer file example to run e+Au collisions. This file could be found in the directory of DPMJET package. You can do similar stuff as that in ep. Just remember to specify the type of nuclear target in TARPAR.
When you are adding the input card, remember to stick to the format A10,6E10.0,A8 when you input those numbers. There is some issue about the size of your output file. For some unknown reason, your every single output file cannot be too huge. So if you wanna generate a big number of events, you had better generate them separately and combine them together when you are analyzing them. But make sure you have given different random number seed to the generator by FSEED when you want to combine several files to make one event sample.
Output file structure
The output file of DPMJET is a text format which has the following structure.
- 1st line: DPMJET EVENT FILE
- 2nd line: "============================================"
- 3rd line: Information on event wise variables stored in this file
|I:||0 (line index)|
|ievent:||eventnumber running from 1 to XXX|
|process1：||process id for the subprocess|
|process2:||process id for the hard process ( 0 is assigned to the soft process )|
|IP:||particle combination ( from 1 to 4 )|
|y, Q2, x, W2, Nu:||are the kinematic variables of the event as calculated from the scattered lepton.|
|theta_e:||theta of the scattered electron|
|photonFlux:||photonFlux spectrum on the electron side|
|targetparton, projectileparton:||flavors of incoming parton in hard interaction|
|xtargetparton, xprojectileparton:||momentum fraction of incoming parton in hard interaction|
|nucleon:||PDG number of the mother particle for the parton involved in hard scattering on hadron beam side|
|nTrack:||number of tracks in every event|
- 4th line: "============================================"
- 5th line: Information on track wise variables stored in the file
|I:||line index, runs from 1 to nrTracks|
|ISTHKK(I):||status code KS (1: stable particles, 2: particles which might decay ...)|
|IDTHKK(I):||particle KF code (211: pion, 2112:n, ....)|
|JMOHKK(1,I):||line number of parent particle|
|JDAHKK(1,I):||normally the line number of the first daughter.|
|JDAHKK(2,I):||normally the line number of the last daughter.|
|PHKK(1,I):||px of particle|
|PHKK(2,I):||py of particle|
|PHKK(3,I):||pz of particle|
|PHKK(4,I):||Energy of particle|
|PHKK(5,I):||mass of particle|
|VHKK(1,I):||x vertex information|
|VHKK(2,I):||y vertex information|
|VHKK(3,I):||z vertex information|
- 6th line: "============================================"
- 7th line: event information for first event
- 8th line: "============================================"
- 9th to X-1 line: trackwise info of 1st event
- Xth line "=============== Event finished ==============="
the information from line 7 to X repeats for each event.
Something to be mentioned here is the first 4 tracks in every event which deliver the information of beam parameter are added externally in order to get some handy variables like z, ptVsGamma... So the mother daughter relationship of these four tracks can not be taken too seriously. But the orig number and daughter number of the tracks after those 4 tracks are consistent and can be used for further purposes.
How to analyze events
- create a root tree
there are root macros available to convert the output txt-files into root trees.
Details how to run the macros can be found [here]
Maybe some of the variables stored in the root tree are meaningless to our analysis， but all the variables listed above are included in this root file.
To normalize your counts to cross section you need to know the total number of events and total integrated cross section.
- the total number of events is the number of events you requested in the input card START
- the total integrated cross section can be found in the logfile/screen if DPMJet finishes at the line:
Sigma used for normalization xxx mb
Cross section = counts / Luminosity
The unit of this cross section is milibarn (10^-3). And Luminosity = Total integrated cross section / total number of events.
The frame choice
in the original dpmjet setup, there is no available choice for the output in the Lab frame when beam energies are
asymmetric, which is a general case for the DIS collisions. To achieve that, we changed the 'MOMENTUM' card in the code and let the output
particles in the event list to be transformed to the lab frame as specified by the beam energy configuration.
The status numbering scheme
we list the meaning of the status number used in the event list for the output
KS=21, beam momentum information added by hand to follow the eicsmear convention used to calculate the event kinematic variables
KS=11/12, projectile/target participant
KS=13/14, noninteracting projectile/target spectators
KS=15/16, nucleons from secondary interaction can not escape from nuclear potential
KS=17/18, nucleons wounded by the formation zone intranuclear cascade
KS=19, negative particles with too low energy to escape the potential that are forced to be absorbed within the nucleus. KS=1, stable final state particles
KS=-1/1001, stable final state particles generated during the evaporation process
To collect all the final state particles, use KS==1,-1,1001. Excited nuclear remnants are consisted of KS=13/14 and KS=15/16 nucleons. KS=11/12 or KS=17/18 are nucleons knocked out of the remnant.