From EIC
Jump to navigation Jump to search

DpmjetHybrid is a generator built based on the framework of DPMJet with the target to do ep/eA simulations by employing PYTHIA to handle the elementary interaction as a replacement of PHOJET. The nuclear effect is included by linking PYTHIA PDF library to LHAPDF which enables us access EPS09 nuclear PDF routines and an afterburner effect from the parton fragmentation is also added to the program. Besides, as it is built in the framework of DPMJet, a nuclear geometry is provided through a Glauber assumption and the final state nuclear break up can be simulated by FLUKA.

Opening issue

This hybrid code is written in Fortran. It provides the feature to run PYTHIA as a parton level generator for the elementary interactions in ep/eA collisions. The major target of this generator is to build a general purpose eA generator fit into the target of simulation work at EIC energy scale.
As is known to all, we have very limited choice of eA Monte Carlo generator in the market up to now. DPMJet with the modification made by Nestor employing FLUKA to handle nucleus break up and intra-nuclear cascade process was thought to be the only available option at one moment. But after some more studies into this direction, we think that maybe DPMJet works fine to study photoproduction off a nuclei, but not a good choice for the DIS measurements at some higher Q like what we have at EIC for the following reasons:

  • First, as a generator mainly used for the photoproduction events, LODIS is not implemented in DPMJet. However, at the EIC energy, LODIS is a major process which accounts for a big fraction of the events.
  • In addition, the other higher order DIS process, Photon-Gluon Fusion (PGF) and QCD Compton (QCDC) process do not have the Q dependence in their hard matrix element and which is only valid in the low Q domain where the cross section of DIS events vanishes.

More details about the discussion of these issues can be found in this example the bug hunt in DPMJET.

In order to solve the above issues in a unified way, we have come up with the idea of using PYTHIA to replace the original parton level generator PHOJET. There are some advantages to use PYTHIA simulating parton level interactions:

  • As PYTHIA is a widely used code in ep simulations, a steady transition is allowed from the hadronic photon region based on Generalized Vector Dominance Model(GVDM) to the direct photon region with the major DIS process, we can achieve a good description for the whole Q range.
  • PYTHIA has a very flexible programming structure which can be used to interface with other packages, like the Salgado & Wiedemann energy loss module can be added as an after-burner effect to the quarks from hard interaction. Also, by linking to the LHAPDF routines we can access the EPS09 nuclear parton distribution function (PDF) at the initial state. With these modifications, we can have a comprehensive cold nuclear medium effect.

Programming Concept

The hybrid program is designed to be running in the framework of DPMJET, with PYTHIA being one of the modules to be called by the main subroutine of DPMJET, just like the other models (e.g. PHOJET) already implemented in this In order to figure this out, some subroutines to initialize and run PYTHIA in DPMJET are provided. Besides, since we need to use the nuclear PDF, PDF interfaces have been modified in PYTHIA to allow one use external PDFs provided by LHAPDF library. Reasonable isospin correction for a nuclear target has been taken into consideration when a nuclear PDF is called by this program. As an estimation to the final state hard parton energy loss, a cold nuclear medium energy loss model has been included as the afterburner before the fragmentation level in PYTHIA.
With a user defined routine, one can control the structure of output file, which can be translated to a root file for further analysis. In the EIC working group, the EIC root tree building code can be used to analyse and visualize the generated pseudodata.
One thing to be mentioned for the case to run PYTHIA in DPMJET is that only one nucleon in the nucleus will be picked as a target nucleon in the collision. This approximation is a very reasonable assumption because the e-Nucleon cross section is relatively small. The case of multiple interaction only happens for the hadronic component of photons, thus only makes up a small fraction of the total cross section, and doesn't affect the point like photon events at all.
A graphical demonstration of the program concept can be illustrated as follows:

generator concept.

How to run this code

the code can be found on the afs area for EIC at BNL


The main program in the file called user-eA3.0-5.f. A simple README is kept in the "Documents" directory, with a short description about what files are contained in the directory.

The compiling of this program needs to use the Makefile script, which has already been provided with this package. FLUKA and LHAPDF has to be preconfigured before compiling this program.

If running PHOJET model, the running process is exactly the same as what shown in DPMJet page. Otherwise if running PYTHIA model, the input file needs some modification. To run PYTHIA model, the 'MODEL' card value of ep.inp needs to be changed to 'PYTHIA'. At the meanwhile, another parameter read in file has to be provided in the same directory for initialization of PYTHIA modules. The name of this file can be specified by the 'PY-INPUT' card in the ep.inp input file.

The usage and explanations for the parameters in the input file and what kind of parameters do we need to give for PYTHIA can be found in the following file:


To run the program, assuming dpmjetHybrid is your compiled executable file. Then use the following command:

./dpmjetHybrid < ep.inp > ep.log

The event-wise output structure is exactly the same as DPMJet or PYTHIA when running in these specific mode. The track-wise output structure is following DPMJet conventions, thus exactly the same as what is shown in DPMJet page. A short summary about the output data file structure has been provided in:


To find the final state particles, just use the following selection rules:

ISTHKK(i)=1 or -1 or 1001

which selects all the particles from hard interaction, nuclear evaporation and heavy nuclear fragments.

Output Data Format

The output structure of this program is similar, but not identical, to the conventions of DPMJet or PYTHIA. The standard eic-smear doesn't work and one needs to use a special version written by Liang.

The output file text format has the following structure:

  • 1st line: "PYTHIA EVENT FILE"
  • 2nd line: "============================================"
  • 3rd line: Information on event wise variables stored in the file
I: 0 (line index)
ievent: eventnumber running from 1 to XXX
genevent: trials to generate this event
subprocess: pythia subprocess (MSTI(1)), for details see table above
nucleon: hadron beam type (MSTI(12))
targetparton: parton hit in the target (MSTI(16))
xtargparton: x of target parton (PARI(34))
beamparton: in case of resolved photon processes and soft VMD the virtual photon has a hadronic structure. This gives the info which parton interacted with the target parton (MSTI(15))
xbeamparton: x of beam parton (PARI(33))
thetabeamparton: theta of beam parton (PARI(53))
truey, trueQ2, truex, trueW2, trueNu: are the kinematic variables of the event.
If radiative corrections are turned on they are different from what is calculated from the scattered lepton.
If radiative corrections are turned off they are the same as what is calculated from the scattered lepton
leptonphi: phi of the lepton (VINT(313))
s_hat: s-hat of the process (PARI(14))
t_hat: Mandelstam t (PARI(15))
u_hat: Mandelstam u (PARI(16))
pt2_hat: pthat^2 of the hard scattering (PARI(18))
Q2_hat: Q2hat of the hard scattering (PARI(22)),
F2, F1, R, sigma_rad, SigRadCor: information used and needed in the radiative correction code
EBrems: energy of the radiative photon in the nuclear rest frame
photonflux: flux factor from PYTHIA (VINT(319))
nrTracks: four less than the number of tracks in this event, includes also virtual particles
  • 4th line: "============================================"

  • 5th line: Information on track wise variables stored in the file
I: line index, runs from 1 to nrTracks+4 (as 1st 4 tracks are informational)
ISTHKK(I): status code KS (-1,1 & 1001 are stable final state particles, see details below)
IDHKK(I): particle KF code (211: pion, 2112:n, ....). Code 80000 refers to a nucleus, specified in more detail by A=IDRES(I), Z=IDXRES(I)
JMOHKK(2,I): line number of second mother particle
JMOHKK(1,I): line number of first mother 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 (GeV/c)
PHKK(2,I): py of particle (GeV/c)
PHKK(3,I): pz of particle (GeV/c)
PHKK(4,I): Energy of particle (GeV)
PHKK(5,I): mass of particle (GeV/c^2)
VHKK(1,I): x vertex information (mm)
VHKK(2,I): y vertex information (mm)
VHKK(3,I): z vertex information (mm)
IDRES(I): For a nucleus (IDHKK(I)=80000), this is A, else 0.
IDXRES(I): For a nucleus (IDHKK(I)=80000), this is Z, else 0.
NOBAM(I): Flag describing the particle creation 0=the intranuclear cascade and the scattered electron. 2=created in the target (Pythia, extra nucleon interacting due to shadowing, or evaporation/nuclear breakup)
  • 6th line: "============================================"
  • 7th line: event information for first event. Format descriptor:


  • 8th line: "============================================"
  • 9th to X-1 line: trackwise info for first event. Format descriptor:


  • 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.

The 4-momentum for particle I, PHKK(mu,I) is reported in the lab frame for all stable final state particles. It is also reported in the lab frame for most intermediate/document particles with the following exceptions: Particle 5 is a copy of the gamma* with 4-momentum reported as zero. Particles 6 through A+5 are the incoming original nucleons from the A, in the target rest frame with gamma* momentum along +z. The momentum corresponds to the Fermi momentum of the nucleon in question.

The impact parameter, defined as the transverse position of the virtual photon with respect to the nucleus center in a frame with z along gamma*, is given by bx=VHKK(1,5) and by=VHKK(2,5) in mm.

The status codes ISTHKK(I) have the following meaning. Note that final state particles have status -1, 1, or 1001. All other statuses refer to intermediate particles or informational lines.

-1: final state particle from excited nucleus evaporation and breakup
1: stable final state particle from collision or intranuclear cascade
2: unstable intermediate particle
3: Documentation line describing the collision
11: Projectile (gamma*) documentation line
12: Incoming wounded nucleon from nucleus
14: Incoming spectator nucleon from nucleus
16: Intermediate baryon involved in the intranuclear cascade
18: Spectator nucleon (wrt hard collision) involved in the intranuclear cascade
19: Intermediated meson involved in the intranuclear cascade
21: documentation line describing the collision
1000: excited nucleus, which will evaporate and breakup
1001: residual nucleus