Interpreting the output¶
This page provides a guide to the contents of the output files produced by the
marley executable. Following a brief description of the PDG codes used to
identify particle types in MARLEY, documentation for all four available output
formats is given below.
PDG codes¶
The Particle Data Group (PDG) has defined a standard numbering scheme for representing particle species in Monte Carlo event generators. Each kind of particle is assigned a unique positive integer as an identifier. The corresponding antiparticle is assigned a negative integer with the same absolute value. A full description of the numbering scheme is available here.
Like nearly all modern particle physics generators, MARLEY adopts the integer PDG codes for particle identification and uses them both internally and in output files. For convenience, a table of the PDG codes most relevant for MARLEY is given below.
| PDG code | Particle |
|---|---|
| 11 | e− |
| 12 | νe |
| 13 | μ− |
| 14 | νμ |
| 15 | τ− |
| 16 | ντ |
| 22 | γ |
| 2112 | n |
| 2212 | p |
| 1000010020 | d |
| 1000010030 | t |
| 1000020030 | h |
| 1000020040 | α |
In general, a PDG code of the form 100ZZZAAA0 represents a nuclide with proton number Z and mass number A. For example, 40Ar is represented by the PDG code 1000180400.
Output file formats¶
The neutrino scattering events generated by the marley executable may be
saved to disk in four distinct output formats. Descriptions of each of these
formats are given below.
ASCII¶
The ASCII format is MARLEY’s native text-based format for event input and
output. It is produced and parsed by applying the stream insertion (<<) and
extraction (>>) operators, respectively, to the marley::Event class in
the C++ source code.
An ASCII-format output file begins with the line
FluxAvgXSec
where FluxAvgXSec is the flux-averaged total cross section in natural units
(MeV −2 per atom). This quantity may be used together with the
events themselves to compute differential cross sections.
One or more event records appear in the remainder of the output file. Each event record begins with a header of the form
Ni Nf Ex twoJ P
where Ni (Nf) is the number of particles in the initial (final) state.
The three remaining fields in the event header report properties of the
final-state nucleus following the primary scattering reaction but before
de-excitations. The Ex field gives the nuclear excitation energy (MeV),
twoJ gives the nuclear spin multiplied by two (to allow half-integer spins
to be represented by a C++ int), and P is a single character
representing a positive (+) or negative (-) parity state.
On the lines following the event header, each of the particles belonging to the event is described by a single line of the form
PDG Etot Px Py Pz M Q
where PDG is the PDG code identifying the particle species and Etot,
Px, Py, and Pz are, respectively, the total energy and the x-, y-,
and z-components of the particle 3-momentum (MeV). The particle mass M
(MeV) and (net) electric charge Q (in units of the elementary charge)
appear at the end of each line. The first Ni lines following the event
header describe the initial-state particles. The remaining Nf lines
describe the final-state particles and complete the event record.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | 5.98368867447267264e-19
2 4 3.79748000000000019e+00 2 +
12 1.00000000000000000e+01 0.00000000000000000e+00 0.00000000000000000e+00 1.00000000000000000e+01 0.00000000000000000e+00 0
1000180400 3.72247225431518091e+04 0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00 3.72247225431518091e+04 0
11 5.20690886815266740e+00 -4.63535385338761508e+00 1.35706546730579314e+00 -1.87687187323011373e+00 5.10998927645907708e-01 -1
1000190400 3.72257175068044089e+04 4.98066184879143847e+00 -2.27058729207187593e+00 9.28456410767741858e+00 3.72257159465162476e+04 1
22 1.53694352434620662e+00 -1.11400145523226901e+00 9.50751758100756628e-01 4.66119350851738223e-01 0.00000000000000000e+00 0
22 2.26118395490673985e+00 7.68693459828445835e-01 -3.72299333346743089e-02 2.12618841470095354e+00 0.00000000000000000e+00 0
2 3 1.03964200000000009e+01 2 +
12 2.99304885549511290e+01 0.00000000000000000e+00 0.00000000000000000e+00 2.99304885549511290e+01 0.00000000000000000e+00 0
1000180400 3.72247225431518091e+04 0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00 3.72247225431518091e+04 0
11 1.85223477954320721e+01 -9.86795370224160173e+00 -1.55256312663347771e+01 -2.09630900945355991e+00 5.10998927645907708e-01 -1
1000190390 3.62940260743929030e+04 -1.74322423197586254e+01 -4.21863040207651636e+01 5.85225771236273147e+01 3.62939501877290750e+04 1
2112 9.42104609518426400e+02 2.73001960220002289e+01 5.77119352870999407e+01 -2.64957795592226226e+01 9.39565378653339735e+02 0
|
The listing above shows an example MARLEY output file in ASCII format. Line 1 gives the value of 5.984×10−19 MeV −2 = 2.330×10−40 cm2 for the flux-averaged total cross section per atom. Line 2 gives the header for the first event, which involves a transition to the 40K nuclear level with an excitation energy of 3.797 MeV above the ground state and spin-parity 1+. Lines 3–4 describe the initial state: a 10-MeV νe traveling in the +z direction toward a 40Ar atom at rest. Lines 5–8 describe the final-state particles: a 5.2 MeV electron, a 40K ion, and two de-excitation γ-rays with energies of 1.54 and 2.26 MeV. The second and final event in the file, which appears on lines 9–14, involves a νe-40Ar collision which produces an electron, a 39K ion, and a neutron.
HEPEVT¶
The legacy HEPEVT format is designed for interfacing event generators with each other and with other software. Compatibility with this event format is maintained in many modern high energy physics software libraries. The description presented here covers only those aspects of the HEPEVT format needed to interpret the output of MARLEY. Further details are available on pages 327–330 of this document.
A HEPEVT-format output file consists of one or more text-based event records. Each of these records begins with the header
NEVHEP NHEP
where NEVHEP is the event number (untracked by MARLEY and thus always set
to zero) and NHEP is the number of particles in the event. The header is
followed by NHEP lines, each representing a single particle. These have the
format
ISTHEP IDHEP JMOHEP1 JMOHEP2 JDAHEP1 JDAHEP2 PHEP1 PHEP2 PHEP3 PHEP4 PHEP5 VHEP1 VHEP2 VHEP3 VHEP4
where ISTHEP is an integer code identifying the particle status and
IDHEP is the particle’s PDG code. In agreement with the HEPEVT standard,
MARLEY uses status code 1 for the final-state particles and 3 for the
initial-state particles. The JMOHEP1, JMOHEP2, JDAHEP1, and
JDAHEP2 entries record the indices (between 1 and NHEP, inclusive) of
particles in the event record that correspond to the first mother, second
mother, first daughter, and last daughter of the current particle,
respectively. These indices are set to zero in cases where they do not apply
(e.g., a particle with no daughters will have JDAHEP1 = JDAHEP2 = 0).
Entries PHEP1 through PHEP3 record the x-, y-, and z-components of the
particle 3-momentum, while PHEP4 gives the total energy and PHEP5 gives
the particle mass (all in GeV). Entries VHEP1 through VHEP3 store the
x, y, and z positions of the particle production vertex (mm), and VHEP4
gives the production time (mm/c).
Because MARLEY currently treats all nuclear de-excitations as instantaneous and
does not perform any particle tracking, VHEP1 through VHEP4 are always
identically zero in HEPEVT output files. Intermediate de-excitation steps are
also not currently stored in the event record, so JMOHEP1, JMOHEP2,
JDAHEP1, and JDAHEP2 are also identically zero in most cases.
In addition to the initial- and final-state particles, MARLEY adds a dummy
particle with ISTHEP = 11 to each HEPEVT event record. All data fields are
zero for this particle except for (1) JMOHEP1, which contains the nuclear
spin multiplied by two, (2) JMOHEP2, which reports the parity of the
nucleus as an integer, (3) PHEP4, which gives the excitation energy of the
nucleus (MeV), and (4) PHEP5, which records the flux-averaged total cross
section in units of MeV −2 per atom. As is the case for the
ASCII format, the excitation energy, spin, and parity values refer to the
nuclear state that is formed after the primary scattering reaction but before
any de-excitations have occurred.
0 7
3 12 0 0 0 0 0.00000000000000000e+00 0.00000000000000000e+00 1.00000000000000002e-02 1.00000000000000002e-02 0.00000000000000000e+00 0. 0. 0. 0.
3 1000180400 0 0 0 0 0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00 3.72247225431518061e+01 3.72247225431518061e+01 0. 0. 0. 0.
11 0 2 1 0 0 0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00 3.79748000000000019e+00 5.98368867447267264e-19 0. 0. 0. 0.
1 11 0 0 0 0 -4.63535385338761496e-03 1.35706546730579320e-03 -1.87687187323011366e-03 5.20690886815266749e-03 5.10998927645907710e-04 0. 0. 0. 0.
1 1000190400 0 0 0 0 4.98066184879143812e-03 -2.27058729207187593e-03 9.28456410767741942e-03 3.72257175068044077e+01 3.72257159465162459e+01 0. 0. 0. 0.
1 22 0 0 0 0 -1.11400145523226908e-03 9.50751758100756655e-04 4.66119350851738206e-04 1.53694352434620668e-03 0.00000000000000000e+00 0. 0. 0. 0.
1 22 0 0 0 0 7.68693459828445808e-04 -3.72299333346743093e-05 2.12618841470095347e-03 2.26118395490674000e-03 0.00000000000000000e+00 0. 0. 0. 0.
0 6
3 12 0 0 0 0 0.00000000000000000e+00 0.00000000000000000e+00 2.99304885549511283e-02 2.99304885549511283e-02 0.00000000000000000e+00 0. 0. 0. 0.
3 1000180400 0 0 0 0 0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00 3.72247225431518061e+01 3.72247225431518061e+01 0. 0. 0. 0.
11 0 2 1 0 0 0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00 1.03964200000000009e+01 5.98368867447267264e-19 0. 0. 0. 0.
1 11 0 0 0 0 -9.86795370224160216e-03 -1.55256312663347770e-02 -2.09630900945356009e-03 1.85223477954320724e-02 5.10998927645907710e-04 0. 0. 0. 0.
1 1000190390 0 0 0 0 -1.74322423197586264e-02 -4.21863040207651613e-02 5.85225771236273160e-02 3.62940260743929031e+01 3.62939501877290738e+01 0. 0. 0. 0.
1 2112 0 0 0 0 2.73001960220002303e-02 5.77119352870999400e-02 -2.64957795592226236e-02 9.42104609518426450e-01 9.39565378653339778e-01 0. 0. 0. 0.
The listing above shows an example MARLEY output file in HEPEVT format. The same two events from the ASCII-format example file are used for easy comparison of the formats.
JSON¶
JSON (JavaScript Object Notation) is a
text-based data-interchange format used for a wide variety of applications. The
grammar of JSON is based on two data structures. A JSON object is an
unordered set of key-value pairs enclosed in curly braces ({}). A JSON
array is an ordered list of values enclosed in square brackets ([]). Each
key is an arbitrary string delimited by double quotes ("") and separated
from its corresponding value by a colon (:). Each value may be a string,
a number, an object, an array, or one of the words (without surrounding double
quotes) true, false, or null. Neighboring values within an array
and key-value pairs within an object are separated from each other by a comma
(,).
The JSON-format output files produced by MARLEY contain a single object with
two top-level keys. The events key is used to label an array of event
objects, while the gen_state key is associated with an object describing
the state of the generator at the moment that the file was created.
Each element of the events array is a JSON object containing five key-value
pairs. The first three of these, Ex, twoJ, and parity, provide the
excitation energy (MeV), two times the total spin, and the parity of the final
nucleus after the primary interaction but before any de-excitations have taken
place. The other two keys, initial_particles and final_particles, are
used store arrays of particles represented as JSON objects. Each particle
object defines the following keys:
chargeThe (net) electric charge (in units of the elementary charge)
pdgPDG code identifying the particle type
ETotal energy
pxMomentum x-component
pyMomentum y-component
pzMomentum z-component
massMass
The particle 4-momentum components and mass are all given in natural units (MeV).
The gen_state JSON object includes several key-value pairs. The config
key refers to a JSON object which reproduces the full contents (except for
comments) of the job configuration file used to generate the events. The
event_count, flux_avg_xsec, and seed keys label the total number of
events generated at the time the file was written, the flux-averaged total
cross section (MeV −2 per atom), and the integer random
number seed used to initialize the event generator. A final key,
generator_state_string, records a string representation of the internal
state of the std::mt19937_64 object used by
MARLEY to obtain pseudorandom numbers.
An example JSON output file is available here. It contains the same two events as the ASCII- and HEPEVT-format examples above.
ROOT¶
If MARLEY has been built against the appropriate shared libraries from the ROOT data analysis framework (see the description of MARLEY’s installation prerequisites here), then output files in ROOT’s compressed binary format may also be produced.
Within a ROOT-format output file, access to the generated events is managed by
an instance of the ROOT TTree
class, which provides a hierarchical data structure for storing many objects
belonging to the same C++ type. In general, a TTree may own one or more
branches (represented by the TBranch class), each of which owns one or more
leaves (represented by TLeaf).
The ROOT-format output files generated by MARLEY contain a single TTree
called MARLEY_event_tree. This TTree has a single branch called
event which stores one marley::Event object per tree entry. Example
ROOT macros that demonstrate the
recommended procedure for accessing and manipulating the events stored in this
format are provided in the folder examples/macros/ of the MARLEY source
code.
In order to properly interpret marley::Event objects, ROOT requires shared
libraries containing dictionaries for the MARLEY
classes to be loaded at runtime. Whenever MARLEY is successfully built against
ROOT, a helper script called mroot is installed in the build/ folder.
Running this script will start the interactive ROOT C++ interpreter after
automatically loading the needed class dictionaries.
Conventions used in the event objects¶
When analyzing marley::Event objects (or their alternative “flat”
representation discussed below), it is helpful to be
aware of MARLEY’s nomenclature for the particles involved in each event’s 2 → 2
primary interaction
𝑎 + 𝑏 → 𝑐 + 𝑑 .
Here the particles 𝑎, 𝑏, 𝑐, and 𝑑 are labeled as, respectively, the projectile, target, ejectile, and residue. Where a mass difference exists, MARLEY chooses the projectile (ejectile) to be the lighter of the two particles in the initial (final) state. Otherwise, the choice is arbitrary. All four-vector components stored in a MARLEY event record are expressed in the laboratory frame, i.e., the rest frame of the target. If simulation of nuclear de-excitations is enabled (as it is by default) and the residue is a nucleus, its 4-momentum and net charge are stored in the event record after it has reached the ground state.
Metadata¶
Four pieces of metadata are saved in a ROOT-format output file alongside the events themselves:
- MARLEY_config
A JSON-format string which stores the contents (except for comments) of the job configuration file used to generate the events
- MARLEY_state
A string giving the serialized internal state (obtained using the stream insertion operator
<<) of the std::mt19937_64 object used to generate random numbers when creating the events.- MARLEY_seed
A string representation of the integer random number seed used to initialize the simulation
- MARLEY_flux_avg_xsec
A TParameter<double> which stores the flux-averaged total cross section (MeV −2 per atom)
“Flat” ROOT files¶
An alternative “flat” form of the ROOT output format is also available which
may be analyzed without the need for the MARLEY class dictionaries. An output
file containing MARLEY events in any of the four standard formats may be
converted into a “flat” ROOT file using the marsum utility. After sourcing
the setup_marley.sh script, one may
convert the MARLEY output file OLD_EVENTS_FILE into a new “flat” ROOT file,
new_flat_file.root, via the command
marsum new_flat_file.root OLD_EVENTS_FILE
The new file will contain
a single ROOT TTree called mst
(for MARLEY summary tree) with the following branches:
- pdgv (int)
Projectile PDG code
- Ev (double)
Projectile total energy (MeV)
- KEv (double)
Projectile kinetic energy (MeV)
- pxv (double)
Projectile 3-momentum x-component (MeV)
- pyv (double)
Projectile 3-momentum y-component (MeV)
- pzv (double)
Projectile 3-momentum z-component (MeV)
- pdgt (int)
Target PDG code
- Mt (double)
Target mass (MeV)
- pdgl (int)
Ejectile PDG code
- El (double)
Ejectile total energy (MeV)
- KEl (double)
Ejectile kinetic energy (MeV)
- pxl (double)
Ejectile 3-momentum x-component (MeV)
- pyl (double)
Ejectile 3-momentum y-component (MeV)
- pzl (double)
Ejectile 3-momentum z-component (MeV)
- pdgr (int)
Residue PDG code
- Er (double)
Residue total energy (MeV)
- KEr (double)
Residue kinetic energy (MeV)
- pxr (double)
Residue 3-momentum x-component (MeV)
- pyr (double)
Residue 3-momentum y-component (MeV)
- pzr (double)
Residue 3-momentum z-component (MeV)
- Ex (double)
Initial residue excitation energy (MeV)
- twoJ (int)
Two times the initial residue spin
- parity (int)
Initial residue parity
- np (int)
Number of de-excitation products
- pdgp (int[np])
De-excitation product PDG codes
- Ep (double[np])
De-excitation product total energies (MeV)
- KEp (double[np])
De-excitation product kinetic energies (MeV)
- pxp (double[np])
De-excitation product 3-momentum x-components (MeV)
- pyp (double[np])
De-excitation product 3-momentum y-components (MeV)
- pzp (double[np])
De-excitation product 3-momentum z-components (MeV)
- xsec (double)
Flux-averaged total cross section (10−42 cm2 per atom)