Input event vertices and kinematics

Tip

The python package revertex contains functionality for generating input files in the correct format.

If you generate the input files on your own without revertex, you have to ensure that all data types and units are as defined here. The input reader does not support dynamic type conversions, as you would expect for example for python (i.e. float32 to float64)!

Warning

We strongly recommend the LH5 format documented below. Input files are read through the Geant4 analysis reader, so the other formats it understands (HDF5, ROOT, CSV, XML) are also accepted, but with caveats: they carry no unit metadata, so all columns are silently assumed to be in the default units (meters for positions, MeV for energies, nanoseconds for times), and only HDF5 (in the Geant4 ntuple layout, as produced by remage-from-lh5) is covered by the test suite.

Vertex input

If the internal vertex confinement options in remage are not sufficient, the user can instruct remage to load the event vertices from a file written by an external event generator.

By design, each event can only have a single vertex, that might be shared between the particles produced in the event.

The input file can be selected with the macro command /RMG/Generator/Confinement/FromFile/FileName:

/RMG/Generator/Confine FromFile
/RMG/Generator/Confinement/FromFile/FileName {FILE}

The vertex input file should be an LH5 table with the following columns:

/
└── vtx
    └── pos · table{xloc,yloc,zloc}
        ├── xloc · array<1>{real} ── {'units': 'm'}
        ├── yloc · array<1>{real} ── {'units': 'm'}
        └── zloc · array<1>{real} ── {'units': 'm'}

  • xloc, yloc, zloc (double, with units): the global position of the particle emission

Kinematics input

remage can also read the initial particle information from a file writtem by an external event generator.

For generating event kinematics we support reading LH5 files with the following format.

/
└── vtx
    └── kin · table{ekin,g4_pid,n_part,px,py,pz,time}
        ├── ekin · array<1>{real} ── {'units': 'keV'}
        ├── g4_pid · array<1>{real}
        ├── px · array<1>{real}
        ├── py · array<1>{real}
        ├── pz · array<1>{real}
        ├── time · array<1>{real} ── {'units': 'ns'}
        └── n_part · array<1>{real}

Here:

  • g4_pid (int) is the PDG code of the particle (see link),

  • ekin (double) is the kinetic energy,

  • px, py, pz (double) are the momentum direction components (unit vector),

  • time (double, with units) is global time of the particle emission,

  • n_part (int) is the number of particles emitted in this event or zero.

Each event starts with a row with n_part > 0. This specifies the count of rows that will be read in for this event. The following rows for this event are then required to set n_part to zero.

Once this input file is created it can be read into remage as an event generator using the macro command /RMG/Generator/FromFile/FileName:

/RMG/Generator/Select FromFile
/RMG/Generator/FromFile/FileName {FILE_PATH}

Where {FILE_PATH} is the path to the input LH5 file.

Tip

When you want to simulate kinematics from a file at a specific point instead of confined to volume, you cannot use /gps/position to set the position. You can however use

/RMG/Vertex/Select FromPoint
/RMG/Vertex/FromPoint/Position {x} {y} {z}

to set a constant position for all events.

Combining vertex and kinematics input

Combining vertex and kinematics input loaded from two tables is possible, even from the same file. However, by design, each event can only have a single vertex, that will be shared between all particles for an event from the kinematics file.

However, in a multithreaded run, the consistent iteration between vertex and kinematics input files is not guaranteed. The events from the files might be mixed up in the simulation, i.e., it is not possible to simulate particle properties statistically dependent on their location.

You can also load a combined position/kinematics table with the following structure; enable /RMG/Generator/FromFile/IncludePosition to use it. Consistent iteration in the multithreaded case is guaranteed in this case. This format also allows to generate multiple particles different vertex positions.

/
└── vtx
    └── kin · table{ekin,g4_pid,n_part,px,py,pz,time,xloc,yloc,zloc}
        ├── ekin · array<1>{real} ── {'units': 'keV'}
        ├── g4_pid · array<1>{real}
        ├── px · array<1>{real}
        ├── py · array<1>{real}
        ├── pz · array<1>{real}
        ├── time · array<1>{real} ── {'units': 'ns'}
        ├── n_part · array<1>{real}
        ├── xloc · array<1>{real} ── {'units': 'm'}
        ├── yloc · array<1>{real} ── {'units': 'm'}
        └── zloc · array<1>{real} ── {'units': 'm'}

Behavior in parallel runs

In both parallel modes every entry of the input file is consumed exactly once, but the two modes differ in how entries are distributed over the events:

  • With --threads, the worker threads share a single file cursor and consume entries in a non-deterministic order. The event identifier in the output does not correspond to the row index in the input, and the assignment is not reproducible from run to run, even with a fixed seed of the random number generator. Vertex and kinematics tables are read independently and may be paired inconsistently, as mentioned above.

  • With --procs, each process reads its own contiguous block of the file, which preserves the correspondence between input row and output event identifier. Since every process simulates the number of events requested in the macro, the file must hold enough entries for all of them.

If the input file is exhausted before the end of the run, an error is logged (a depleted vertex file additionally aborts the run).

Refer to RMGVertexFromFile and RMGGeneratorFromFile in the API documentation for the details.