Event 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 main documentation for this extension is available here.

The macro command:

/RMG/Generator/Select BxDecay0

can be used to select the BxDecay0 generator.

remage adds two macro commands to control the generator, which should cover all required use cases. While the original bxdecay0 double beta decay generator macro commands are still available to the user, the remage commands offer a simpler and more intuitive alternative.

The macro command to generate double beta decay physics /RMG/Generator/BxDecay0/DoubleBetaDecay expects the isotope name, the name of the process you want to simulate (like 2vbb or 0vbb) and an optional level for the daughter nucleus. All available isotopes and processes are listed here. The nuclear level defaults to ground state and can therefore be omitted in most cases.

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

/RMG/Generator/Select BxDecay0
/RMG/Generator/BxDecay0/DoubleBetaDecay Ge76 2vbb

The second macro command is used to generate other radioactive decay physics with bxdecay0. The command /RMG/Generator/BxDecay0/Background takes only a single string as parameter, which should be the name of the isotope. Again all isotope candidates are listed here. Using these we can for example simulate a \(^{60}\)Co background source:

/RMG/Generator/Select BxDecay0
/RMG/Generator/BxDecay0/Background Co60

The current seed of Geant4 will be forwarded to bxdecay0. This means that if any seed is specified using the /RMG/Manager/Randomization/ commands, that seed will be forwarded to bxdecay0.

Warning

bxdecay0 accepts only int seed values, while Geant4 accepts long values. In case a Geant4 seed happens to be above the numerical limit of int, the forwarded seed will be reduced to old_seed - std::numeric_limits<int>::max().

Tip

  • The verbosity of bxdecay0 can be increased with /bxdecay0/generator/verbosity LEVEL where LEVEL is 0, 1, 2 and 3. This should work in combination with the remage macro commands.

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
    └── 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 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.