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:

charge

The (net) electric charge (in units of the elementary charge)

pdg

PDG code identifying the particle type

E

Total energy

px

Momentum x-component

py

Momentum y-component

pz

Momentum z-component

mass

Mass

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)