Phase Space Format

The allowed columns in the phase space data are defined in the __phase_space_config.py file, and are split into two categories:

1. Required columns are, as the name implies, required and present at all times. These are the core data used to represent the phase space; all other data can be derived from these. Each DataLoader must fill in these and only these columns to generate a valid import object.

2. Allowed columns can optionally be filled in using a fill method on a PhaseSpace object. For instance, to fill the allowed column Ek [MeV] you would use the fill_kinetic_E method. You are free to update the allowed_columns at any time, however in order for the code to pass testing you must:

3. Write an associated fill method

4. Update the test test_all_allowed_columns_can_be_filled inside test_ParticlePhaseSpace

5. Update the “Allowed Columns” documentation below

Required Columns

Column name	Description
x [units], y [units], z [units]	The position of each particle in mm
px [units], py [units], pz [units]	the relativistic momentum of each particle in MeV/c
particle type [pdg_code]	The particle type, encoded as an integer pdg code
weight	the statistical weight of each particle. This is used to calculate weighted statistics. In many cases this will be 1 for all particles
particle id	each particle in the phase space must have a unique integer particle ID
time [units]	the time the particle was recorded (in many cases this will be 0 for all particles)

Allowed Columns

Column Name	Description	fill method
Ek [units]	Kinetic energy	fill_kinetic_E
rest mass [units]	Particle rest mass	fill_rest_mass
p_abs	Total momentum	fill_absolute_momentum
relativistic mass [units]	Particle mass	fill_relativistic_mass
beta_x, beta_y, beta_z, beta_abs	x Beta factor of particle	fill_beta_and_gamma
gamma	Lorentz factor of particle	fill_beta_and_gamma
vx [units], vy [units], vz [units]	relativistic particle velocity in m/s	fill_velocity
Direction Cosine X, Direction Cosine Y, Direction Cosine Z	Direction Cosines of particle momentum	fill_direction_cosines

Units

This code can work with several different unit sets, and new unit sets can also be easily defined. Rather than attempt to document these here, see the ‘living documentation’ in notebook format here. This example shows the different unit sets available, how to use them, and how to add new unit sets if none of the existing ones are what you want.

Reading in momentum

Position-Momentum are the fundamental quantities read in by the DataLoaders. Position is (hopefully) trivial, but for momentum we make the following notes that may help in converting different properties into momentum:

If energy/ direction cosines are specified:

from math import sqrt
P = sqrt(E**2 + E_0**2)

where

E = E_k + E_0

E should be in units of MeV.

To calculate px, py, and pz from this, you must have something like the momentum cosines.

p_x = P*DirectionCosine_x

etc.

If beta/ gamma specified

For charged particles, data may be specified in terms of beta/gamma. In that case:

P = beta*gamma*rest_energy
p_x = beta_x*gamma*rest_energy

etc. rest_energy should be specified in MeV, e.g. for electrons the value is 0.511 MeV

If momentum is specified in SI units

We always use some form of eV/c for momentum. In the somewhat unusual situation that momentum is specified in the SI kg.m/s you can convert it as per below:

P_ev_c = P_SI * (c/q)
P_MeV_c = P_SI * (c/q) * 1e-6