Event generators¶

Todo

list of built-in generators and documentation
muon generators

We generate particles of interest using Geant4 macro commands (see link for some background).

This section of the user manual describes generation of the kinematics of events. However, for some generators this can also involve generation of positions of the primary particles (for example for muons). In most other cases the position is handled by the vertex confinement commands described in Vertex confinement.

You can check the list of all available generators in remage here under “candidates”. This section of the manual will cover the usage of:

General particle source (GPS) and Geant4 Gun (G4Gun)
Double-beta decay physics (BxDecay0)
Generic interface to externally generated kinematics (FromFile)
Cosmic muons (CosmicMuons), including support for MUSUN (MUSUNCosmicMuons)

Note

Adding generators with C++ code is possible using the RMGUserInit system:

auto user_init = RMGManager::Instance()->GetUserInit();
user_init->SetUserGenerator<MyCustomGenerator>(...);

The latter registers the user-defined generator new MyCustomGenerator(...), which must inherit from RMGVGenerator. You can then activate your generator at runtime with:

/RMG/Generator/Select UserDefined

General Particle Source¶

Most events can be generated using inbuilt Geant4 commands with the General Particle Source (G4GeneralParticleSource, GPS).

These commands allow to generate the position’s and kinematics of primary particles. In most cases we will use in-built remage commands for the positions (see Vertex confinement).

However, for the kinematics the GPS commands are often sufficient, for example to generate electrons with a fixed energy and isotropic direction we can use the macro commands (see docs):

/RMG/Generator/Select GPS
/gps/particle e-
/gps/ang/type iso

Note

These commands should be placed after /run/initialize

Many other macro commands are available for more complicated generators link! Similar commands can be used to generate other primary particles, for example gamma, alpha or mu-.

Note

remage supports G4ParticleGun too (/RMG/Generator/Select G4Gun), a more basic alternative to the GPS.

Generating nuclear decays¶

A special case of the GPS can be used to generate radioactive decays. This is done by producing an ion which Geant4 will then handle the decays of and the production of secondary particles.

The simplest case can be used to generate ions which only undergo a single decay (and have a stable daughter nuclei). For generate an ion with a given \(A\), \(Z\) with the command /gps/ion Z A (link).

For example we can generate decays of \(^{40}\)K with:

/RMG/Generator/Select GPS

/gps/particle ion
/gps/energy 0 eV
/gps/ion 19 40

Note

In some cases the lifetime of the nuclei is quite long, this would result in the times in the output files being large, possibly leading to numerical issues. remage will reset the times to be the time since the start of the decay by default unless the macro command /RMG/Processes/Stepping/ResetInitialDecayTime is set to False.

Nuclear decay chains¶

By default geant4 will propagate the decays of the nuclei until a stable daughter is reached, unless the time goes beyond the time threshold for radioactive decays, set at \(10^{27}\) ns (around \(3 \times 10^{10}\) yrs).

Warning

In some cases the lifetime of daughter nuclei can be very long, this can lead to numerical inaccuracy in the times saved to the output files. remage will warn you if a track has a global time large enough that the precision is less than 1\(\mu\)s. This will occur when times go beyond around 285 years.

In some cases, it may be required to simulate only a part of a decay chain. To do this we can use the /process/had/rdm/nucleusLimits [aMin] [aMax] [zMin] [zMax] macro command docs.

This will result in any nuclei having \(A\) outside of the range [aMin, aMax] or \(Z\) outside of [zMin, zMax] being killed (before having a chance to decay).

For example to generate decays of \(^{222}\)Rn until \(^{210}\)Pb we can use the commands:

/RMG/Generator/Select GPS

/gps/particle ion
/gps/energy 0 eV
/gps/ion 86 222
/process/had/rdm/nucleusLimits 214 222 82 86

This will allow the decays of \(^{222}\)Rn \((Z=86, A=222)\) and its daughters:

\(^{218}\)Po: (\(Z=84\), \(A=218\)),
\(^{214}\)Pb: (\(Z=82\), \(A=214\)),
\(^{214}\)Bi: (\(Z=83\), \(A=214\)),
\(^{214}\)Po: (\(Z=84\), \(A=214\)).

However, the decay of \(^{210}\)Pb would not be allowed due to the value of \(A=210\).

Note

This mechanism can be used to select arbitrary sections of decay chains!

Double-beta decay physics¶

To generate double beta decay physics we interface with the bxdecay0 package. This requires remage to be build with bxdecay0 support see Installation. The only documentation for this extension is available here.

The macro command:

/RMG/Generator/Select BxDecay0

can be used to select the Decay0 generators.

We can then use the bxdecay0 double beta decay generator macro commands to generate double beta decay physics. The macro command to generate double beta decay physics is:

/bxdecay0/generator/dbd ISOTOPE SEED MODE LEVEL

Where:

ISOTOPE (string): is the decaying nuclei,
SEED (int): is a random seed,
MODE (int): is an index the double beta decay mode labelling the decay type, a table of implemented decay modes can be found in link.
LEVEL (int): is a index of the energy level of the daughter nuclei, the list of available levels are documented here.

For example we can generate two-neutrino double beta decay to the \(0^+\) ground state of \(^{76}\)Ge with:

/RMG/Generator/Select BxDecay0
/bxdecay0/generator/dbd Ge76 1234 4 0

Tip

More information on the double beta decay commands can be obtained with /control/manual /bxdecay0/generator/dbd
The verbosity of bxdecay0 can be increased with /bxdecay0/generator/verbosity LEVEL where LEVEL is 0, 1, 2 and 3.

Cosmic muons¶

remage offers the possibility to simulate the interaction of cosmic muons through multiple third-party libraries.

EcoMug interface¶

EcoMug is a C++ library to simulate the kinematics of cosmic muons at the earth’s surface, optimized for muon tomography and radiography applications. It is capable of generating muons from different surfaces (plane, cylinder and half-sphere), while keeping the correct angular and momentum distribution of generated tracks.

/RMG/Generator/Select CosmicMuons

A macro command interface to the library is available below /RMG/Generator/CosmicMuons/. For further documentation, refer to the original publication.

MUSUN¶

MUSUN is a popular software to simulate cosmic muons at different underground sites (e.g. Laboratori Nazionali del Gran Sasso). Output files produced by MUSUN can be fed in directly to remage with the following commands:

/RMG/Generator/Select MUSUNCosmicMuons
/RMG/Generator/MUSUNCosmicMuons/MUSUNFile filename

Simulating event vertices and kinematics from external files¶

For more complicated or custom event generators remage supports the possibility to read in directly event kinematics (or positions) from input files.

The functionality for reading input files is described in Input event vertices and kinematics. For generating event kinematics we support reading LH5 files with the following format.

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

Here:

ekin (double) is the kinetic energy,
g4_pid (int) is the particle code (see link),
px, py, pz (double) are the x, y and z momenta.

Tip

It is supported to supply units for the energy with the LH5 attributes. It is then assumed the momenta have the same units!
The python package revertex docs contains functionality for generating input files in the correct format.

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.

Warning

This functionality is currently limited to events where a single primary particle is produced per event.