An efficient hadron sampler based on the Cooper-Frye formula. This also provides a command-line interface for JAM cascades useful for event-by-event calculations of heavy-ion collisions.
- The Monte-Carlo sampling by the combination of the inversion method & rejection method. Isotropic components are sampled by the inversion method based on the pre-calculated interpolation table of one-dimentional integrations. Anisotropy is taken into account by the rejection sampling.
- The isotropic part is reduced to one-dimensional integration by considering the symmery in the local rest frame. High-precision interpolation of integral tables by the combination of the Lagrange interpolation of the Chebyshef nodes and the cubic splines.
- Baryon density and diffusion are currently not considered.
This package requires the library libjam from JAM version 1.8 or before.
The source code archives of JAM version 1 can be obtained from the following
URL:
In the JAM package, the parameter mxv defined in src/jam1.inc
should be rewritten to 200000 before the compile of JAM.
For illustration, the JAM library can be installed by the following commands.
$ wget https://github.com/ynara305/jam1past/raw/refs/heads/main/jam-1.822.tar.xz
$ wget https://github.com/ynara305/jam1past/raw/refs/heads/main/jam-1.823-fix-print-format.patch
$ tar xf jam-1.822.tar.bz2
$ cd jam-1.822
$ patch -p 1 < ../jam-1.823-fix-print-format.patch
$ export F77=gfortran
$ ./configure --prefix="$HOME"/.opt/jam/1.823
$ make -j
$ make installOptionally, one may also link libjam2 from JAM version 2. To build JAM 2,
one first needs to compile the corresponding version of Pythia 8. As of
2025-08-04, the verseion corresponding to the main branch of jam2 is Pythia
8.315. You can download, compile, install with the following commands:
$ wget https://pythia.org/download/pythia83/pythia8315.tar.bz2
$ tar xf pythia8315.tar.bz2
$ cd pythia8315
$ ./configure --prefix="$HOME"/.opt/pythia/8.315
$ make -j
$ make installAfter the installation of the Pythia 8.315 library, one may proceed to installing JAM 2. The latest development version of JAM 2 can be obtained from GitLab:
$ git clone https://gitlab.com/transportmodel/jam2.git
$ cd jam2
$ autoreconf -i
$ ./configure PYTHIA8=~/.opt/pythia/8.315 --prefix="$HOME"/.opt/jam2/main
$ make -j
$ make installrunjam.exe can be compiled with the following commands:
$ git clone https://github.com/idthic/runjam.git
$ cd runjam
$ ./configure --prefix="$HOME"/.opt/idt --with-jam1="$HOME"/.opt/jam/1.823
$ make
$ make installTo enable libjam2, please use the following ./configure command:
$ ./configure --prefix="$HOME"/.opt/idt --with-jam1="$HOME"/.opt/jam/1.823 --with-jam2="$HOME"/.opt/jam2/mainThis programs is provided under GPL-2.0-or-later.
runjam (idt) - Sample hadrons by Cooper-Frye formula / Run JAM cascade.
Copyright (C) 2011-2025, Koichi Murase <myoga.murase at gmail.com>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
$ runjam.exe --help
usage: runjam [SUBCOMMAND] [OPTIONS|VAR=VALUE]
SUBCOMMAND
cascade (default)
decay
sample
OPTIONS and VARIABLES
Variables can be specified by the environment variables or the command-line
argument of the form `VAR=VALUE'. In command-line arguments, the prefix
`runjam_' can be omitted.
runjam_mode=SUBCOMMAND
-n, runjam_nevent=INT [1] number of events to process
-s, runjam_seed=INT [18371] seed for random numbers in runjam
runjam_jamseed=INT [runjam_seed] seed for random numbers in JAM
-t, runjam_oversampling_factor=NUM [1] number of test particles
-w, runjam_switch_weak_decay=BOOL [false] enable weak decays
runjam_phi_decays=BOOL [true]
-1, runjam_jam_version=1 use JAM1 for cascade/decay
-2, runjam_jam_version=2 (default) use JAM2 for cascade/decay
Output options
-o, runjam_output_directory=DIR [out] directory of output files
--fphase, runjam_fname_phdat=FILE [] output filename
--fphase0, runjam_fname_phdat0=FILE [] output filename
runjam_output_phdat=BOOL [true] output phasespace data
runjam_output_phdat0=BOOL [true] output phasespace0 data
runjam_output_phbin=BOOL [false] output binary phasespace
runjam_output_phbin0=BOOL [false] output binary phasespace0
runjam_output_phdat_indexed=BOOL [false]
runjam_output_phdat0_indexed=BOOL [false]
runjam_output_index_start=INT [0]
-d INT
0 Disable all output format
1 Enable only 'phdat' and 'phdat0'
2 Enable only 'phbin' and 'phbin0'
3 Enable only 'phdat_indexed' and 'phdat0_indexed'
Initialization options
-i ICSPEC specify initial condition
c0lrf:FILE sample particles from the hypersurface data from
rfh c0lrf format "hypersurface_v1.txt"
hydrojet:DIR sample particles using the hypersurface data from
hydrojet (DIR/freezeout.dat, DIR/position.dat)
phase:FILE load particle lists from the text format "phasespace.dat".
phase1:FILE load a particle list from FILE. This performs an additional
check to require that FILE contains only a single event.
phbin:FILE load particle lists from the binary format "ph000k.bin".
psample:FILE read a particle list from the file in the format of
runjam "particlesample_pos.dat"
Resonance list
-r, --resodata, runjam_resodata=FILE resonance data
-p, runjam_eospce=INT [6] eospce
-k, runjam_kintmp=INT [5] freezeout temperature type
Options for viscous sampler
--switching-temperature, runjam_switching_temperature=TEMP [155]
an advice to switching temperature in MeV
runjam_turnsOffViscousEffect=INT
Options for hydrojet hypersurface
--hydrojet-bfree, hydrojet_baryonfree=INT [1] baryonfree
--hydrojet-dir, hydrojet_directory=DIR [test] directory of freezeout.dat
--hydrojet-dt, hydrojet_deltat=NUM [0.3] delta tau
--hydrojet-dx, hydrojet_deltax=NUM [0.3] delta x
--hydrojet-dy, hydrojet_deltay=NUM [0.3] delta y
--hydrojet-dh, hydrojet_deltah=NUM [0.3] delta eta
hydrojet_reverse_particles=BOOL [false] (debug) perform z-reflection
hydrojet_shuffle_particles=BOOL [false] (debug) shuffle particles
hydrojet_rotate_freezeout=BOOL [false] (debug) rotate freezeout data
Other options
--help show this help
--version show version information
EXAMPLE
$ ./runjam cascade -s 12345 -o jam -i c0lrf:hypersurface_v1.txt
$ ./runjam decay -s 12345 -o jam -i phase:phasespace0.in
$ ./runjam sample -s 12345 -o jam -i c0lrf:hypersurface_v1.txt -n 1000 -d 2This contains the sequence of event data in text format.
Each event data starts with a line containing two fields. The first field
contains the number of particles in the event. When this number is -999, it
means that this is the end of the file and that no more events are available.
The second column contains the oversampling factor, i.e., the factor for the
number of particles in the test-particle method for the Boltzmann equation.
This is normally 1 which corresponds to using the real number of hadrons.
Then, as many lines as the number of the particles are followed. Each line carries one particle information with the following format:
ks kf px py pz m x y z t
ks is 1 for stable qparticle and 2 for unstable particle. kf is PDG
Monte-Carlo code. px py pz m are the momentum and the mass in the unit
[GeV]. x y z t are the spacetime point of the last interaction vertex or the
formation vertex.
This is the binary format. This contains the sequence of event frames. Each event frame starts with an eight-byte header followed by a sequence of particle entries. The structure is summarized in the following pseudo-code.
struct PARTICLE {
// 1: stable, 2: unstable particle
UINT32 ks;
// PDG Monte-Carlo code
UINT32 kf;
// Momentum and mass in [GeV]
SINGLE px, py, pz, m;
// The formation point or the last interaction point in [fm]
SINGLE x, y, z, t;
};
struct PHBIN_EVENT_FRAME {
FOURCC magic; // 4-bytes. Fixed to be a string "EvPh"
UINT32 numberOfParticles;
PARTICLE data[numberOfParticles];
};
struct PHBIN {
PHBIN_EVENT_FRAME fileContents[numberOfEvents];
};This is the binary format only with the particle species and momentum. The structure is summarized in the following pseudo-code.
struct PARTICLE4 {
// PDG Monte-Carlo Code
UINT32 kf;
// Momentum in [GeV]
SINGLE px, py, pz;
};
struct PHBIN4_EVENT_FRAME {
FOURCC magic; // 4-bytes. Fixed to be a string "EvPp"
UINT32 numberOfParticles;
PARTICLE4 data[numberOfParticles];
};
struct PHBIN4 {
PHBIN4_EVENT_FRAME fileContents[numberOfEvents];
};This data format contains just a sequence of particle information without any header information. Each particle is represented in a line of the following format:
px py pz e m ireso tau x y eta
e is the energy in the unit [GeV]. ireso is the particle ID in the
resonance list described below. tau and eta are spacetime coordinates
specified by the Bjorken proper time and the spacetime rapidity.
The first line contains two fields. The first field indicating the file format
is always c0lrf. The second field indicates the grid coordinates used in the
hydrodynamic calculation. This needs to be taueta or taueta-tilde.
taueta is the natural tensor basis defined by the differentiation with
respect to the coordinate variables. taueta-tilde corresponds to the
orthonormalized tensor basis, i.e., Galilei frame comoving with the fixed
spatial coodinates. The subsequent lines are the information of hypersurface
elements. Each line corresponds to a hypersurface element of the following
format:
dir ds0 ds1 ds2 ds3 x0 x1 x2 x3 dx0 dx1 dx2 dx3 T u0 u1 u2 u3 e p pi11 pi12 pi13 pi22 pi23 pi33
In this format, the Lorentz indices (0, 1, 2, 3) correspond to (tau, eta, x,
y), respectively. dir is the direction of the hypersurface. ds0 ds1 ds2 ds3 contains the hypersurface element dσμ (direction and
size). x0 x1 x2 x3 contains the center position of the hypersurface
element. dx0 dx1 dx2 dx3 contains the extent of the hypersurface element
along the grid coordinates. T e p are temperature, energy density, and
pressure, respectively. u0 u1 u2 u3 is the flow velocity at the point in the
grid coordinates. pi11 pi12 pi13 pi22 pi23 pi33 are the shear stress tensor
in the local rest frame (singly boosted from the grid cordinates).
The hypersurface data from hydrojet is saved in two separate files
freezeout.dat and position.dat. Both files contain the same numbers of the
lines and are just a sequence of lines each corresponding to a hypersurface
element. The line in freezeout.dat has the following format:
isbulk ds dx dy T eta mu vxp vyp yvp
ds dx dy contain ds0 dx dy, respectively if isbulk is 1, or otherwise
contain ds1 dx dy, respectively. All the tensor basis are in taueta-tilde
coodinates. T mu are temperature and chemical potential, respectively. Only
mu = 0.0 is supported by runjam. eta is the spacetime rapidity of the
position of the hypersurface element. vxp and vyp are the flow velocity
(dx/dt, dy/dt). yvp is the rapidity of the flow velocity in the z direction.
The line in position.dat has the following format:
tau x y eta
tau x y eta is the position of the hypersurface element. Note that these
fields in both files actually do not have to form a line for each hypersurface
element, i.e., each field can be placed in an independent line as in the output
of the original hydrojet.
The resonance list can be specified by the option -r, --resodata, runjam_resodata=FILE.
This option selects the file that contains the information of particle species to be sampled.
The default resonance list file is data/ResonanceJam.dat or data/ResonanceJam2.dat depending on the version of the underlying JAM.
For the cascade calculations, the default particle list for the cascade model should be used.
Here the file format of the resonance list file is described. Empty
lines and lines starting with # are ignored. Each line contains the
information of a particle species with the following format:
- Column 1: Mass
- Column 2: Degeneracy
- Column 3: Effective degeneracy (average number of pions after decays)
- Column 4: Chemical potential
- Column 5: Statistics (1: boson, 2: fermion)
- Column 6: Is antiparticle
- Column 7: KEY. The name used to determine the filename for the resonance.
- Column 8: Description
- Column 9+: corresponding PDG Monte-Carlo codes. Note that there can be multiple codes corresponding to the isospin degenracy.
When this option is not specified, the resonance list file is determined
based on the other options --hydrojet-pce, hydrojet_eospce=INT and --hydrojet-ftemp, hydrojet_kintmp=INT.
The default is eospce=6 and kintmp=5 so that ResonanceJam.dat is used.
eospce=0:ResonancePCE.datwill be used as the list of particles. 21 resonances are contained.eospce=1The same aseospce=0but with the chemical potentials (PCE)kintmp=1:ResonancePCE.T080.dat. Freezeout temperature 80 MeVkintmp=2:ResonancePCE.T100.dat. Freezeout temperature 100 MeVkintmp=3:ResonancePCE.T120.dat. Freezeout temperature 120 MeVkintmp=4:ResonancePCE.T140.dat. Freezeout temperature 140 MeVkintmp=5:ResonancePCE.T160.dat. Freezeout temperature 160 MeV
eospce=4:ResonanceEosqJam.dat. EOS-Qeospce=5:ResonancePCE.New.dat.eospce=1with updated masseseospce=10:ResonanceCharged.Massless.dat.eospce=11:ResonanceCharged.dat.eospce=12The same aseospce=11but with the chemical potentials (PCE)kintmp=1:ResonanceCharged.T080.dat. Freezeout temperature 80 MeVkintmp=2:ResonanceCharged.T100.dat. Freezeout temperature 100 MeVkintmp=3:ResonanceCharged.T120.dat. Freezeout temperature 120 MeVkintmp=4:ResonanceCharged.T140.dat. Freezeout temperature 140 MeVkintmp=5:ResonanceCharged.T160.dat. Freezeout temperature 160 MeV
eospce=13:ResonancePhi.dat. phi and J/psi mesonseospce=14:ResonancePhi.T100.dat. phi and J/psi mesons with PCE T = 100 MeV.- Otherwise:
ResonanceJam.dat
Calculate the feeddown factors of each hadrons based on the JAM decay. The
result is saved in feeddown.txt. This file is used to fill column DEGEFF
in the resonance list.
# Use the default resonance list
./runjam.exe resolist-feeddown-factor
# Specify the resonance list
./runjam.exe resolist-feeddown-factor -r data/ResonanceJam2.dat
# Specify the JAM version
./runjam.exe resolist-feeddown-factor -1 -r data/ResonanceJam.datThe full procedure to update data/ResonanceJam2.dat is as follows:
$ echo 'ParticleData:listAll = 1' > jam.inp
$ /path/to/jam2/jam > listAll.txt
$ ./mktool.sh jam2-generate-resodata-full listAll.txt
Note: This updates the particle list in data/ResonanceJam2.dat, but column
DEGEFF is filled with 0.
$ ./runjam.exe resolist-feeddown-factor -2 -r data/ResonanceJam2.dat
Note: This creates a file "feeddown.txt"
$ ./mktool.sh jam2-generate-resodata-full listAll.txt
Note: The second call of the above command will generate data/ResonanceJam2.dat
with column DEGEFF filled with the data extracted from "feeddown.txt".