Internal Generator

The internal GEMC generator is configured with two cumulative options.

gparticle defines inline particle sources. Each entry adds one particle (or a group of identical copies) to every event. Multiple entries can be combined in the same list.

gparticlefile loads event records from a file. The built-in reader supports the LUND format.

When both options are present, every generated event receives all particles from gparticle plus all particles from the matching event record in each gparticlefile source.

Both options can be set from the YAML steering card or the command line:

# YAML steering card
gparticle:
  - name: e-
    p: 2300
    theta: 23.0

# equivalent command-line form
gemc -gparticle="[{name: e-, p: 2300, theta: 23.0}]"


gparticle

Fields

name and p are required. All other fields are optional.

Field Default Description
name required Geant4 particle name, e.g. e-, proton, gamma, pi+
p required Nominal momentum magnitude, interpreted with punit
multiplicity 1 Number of copies generated per event; each copy is independently randomized
punit MeV Unit for p and delta_p. Use MeV or GeV
delta_p 0 Momentum spread around p
randomMomentumModel uniform uniform: flat in [p − delta_p, p + delta_p]; gaussian: Gaussian with sigma delta_p
theta 0 Nominal polar angle (from the z-axis)
delta_theta 0 Polar-angle spread around theta
randomThetaModel uniform uniform: flat in [θ − Δθ, θ + Δθ]; gaussian: Gaussian sigma delta_theta; cosine: cos(θ) uniform, with rejection sampling within the window (see note below)
phi 0 Nominal azimuthal angle
delta_phi 0 Azimuthal-angle spread. Always applied with the uniform model — there is no randomPhiModel
aunit deg Unit for theta, delta_theta, phi, delta_phi. Use deg or rad
vx 0 Nominal vertex x
vy 0 Nominal vertex y
vz 0 Nominal vertex z
delta_vx 0 Vertex x spread
delta_vy 0 Vertex y spread
delta_vz 0 Vertex z spread
vunit cm Unit for vertex positions and spreads
randomVertexModel uniform uniform: each component flat in [v − δv, v + δv]; gaussian: Gaussian sigma per component; sphere: uniform sampling within a spherical volume (see note below)

Note

cosine theta model — samples θ such that cos(θ) is uniform using rejection sampling within [theta − delta_theta, theta + delta_theta]. For narrow windows the acceptance rate can be low. This model is most efficient when delta_theta covers a large fraction of the full range [0, 180°].

Note

sphere vertex model — generates vertices uniformly within a spherical volume centred on the nominal vertex. Set delta_vx, delta_vy, delta_vz all equal to the desired sphere radius. Using different values for the three components changes the effective sampling sphere size.


Examples

One 2.3 GeV electron at 23°

gparticle:
  - name: e-
    p: 2300
    theta: 23.0
theta distribution for one electron at 23 degrees
Polar angle (θ) of the generated-tracked bank in radians. The spike at θ ≈ 0.4 rad (≈ 23°) confirms a fixed-angle source.

Analyzer command:

python3 -m analyzer generated_tracked.csv theta --kind csv --bins 50 --linear-y


Explicit units with theta spread of 0.2 rad

gparticle:
  - name: e-
    p: 2.3
    punit: GeV
    theta: 0.4
    delta_theta: 0.2
    aunit: rad
theta distribution for radian spread example
Flat θ distribution in the window [0.2, 0.6] rad produced by uniform smearing with delta_theta = 0.2 rad.

Analyzer command:

python3 -m analyzer generated_tracked.csv theta --kind csv --bins 50 --linear-y


10 protons per event, uniform in φ

gparticle:
  - name: proton
    multiplicity: 10
    p: 1200
    theta: 14.0
    delta_phi: 180.0
phi distribution for ten protons with uniform phi
Flat φ distribution across the full 2π range. phi is always smeared uniformly; no model option is needed.

Analyzer command:

python3 -m analyzer generated_tracked.csv phi --kind csv --bins 50 --linear-y


Momentum spread — uniform

gparticle:
  - name: e-
    p: 2300
    delta_p: 100
    randomMomentumModel: uniform
momentum distribution for uniform smearing
Flat momentum distribution in [2200, 2400] MeV produced by uniform smearing with delta_p = 100 MeV.

Analyzer command:

python3 -m analyzer generated_tracked.csv p --kind csv --bins 50 --linear-y


Momentum spread — Gaussian

gparticle:
  - name: e-
    p: 2300
    delta_p: 100
    randomMomentumModel: gaussian
momentum distribution for Gaussian smearing
Gaussian momentum distribution centred at 2300 MeV with sigma = 100 MeV.

Analyzer command:

python3 -m analyzer generated_tracked.csv p --kind csv --bins 50 --linear-y


Cosine theta sampling

gparticle:
  - name: e-
    p: 2300
    theta: 23.0
    delta_theta: 5.0
    randomThetaModel: cosine
theta distribution for cosine theta sampling
cos(θ)-uniform sampling within [18°, 28°]. The rising density toward larger θ is the sin(θ) weighting that makes solid angle uniform.

Analyzer command:

python3 -m analyzer generated_tracked.csv theta --kind csv --bins 50 --linear-y


Azimuthal-angle spread

gparticle:
  - name: e-
    p: 2300
    phi: 45.0
    delta_phi: 20.0
phi distribution for azimuthal angle smearing
Flat φ distribution in [25°, 65°] (≈ [0.44, 1.13] rad). phi is always spread uniformly.

Analyzer command:

python3 -m analyzer generated_tracked.csv phi --kind csv --bins 50 --linear-y


Fixed vertex position

gparticle:
  - name: e-
    p: 2300
    vx: 0.0
    vy: 0.0
    vz: -10.0
    vunit: cm
vertex-z distribution for a fixed source vertex
All events originate at vz = −100 mm (−10 cm). GEMC stores vertex positions in mm internally.

Analyzer command:

python3 -m analyzer generated_tracked.csv vz --kind csv --bins 50 --linear-y


Vertex z spread — uniform

gparticle:
  - name: e-
    p: 2300
    vz: 0.0
    delta_vz: 2.0
    vunit: cm
    randomVertexModel: uniform
vertex-z distribution for uniform z-vertex smearing
Flat vz distribution in [−20, +20] mm (±2 cm) produced by uniform vertex smearing.

Analyzer command:

python3 -m analyzer generated_tracked.csv vz --kind csv --bins 50 --linear-y


Vertex spread — Gaussian

gparticle:
  - name: e-
    p: 2300
    delta_vx: 1.0
    delta_vy: 1.0
    delta_vz: 5.0
    vunit: mm
    randomVertexModel: gaussian
vertex-z distribution for Gaussian vertex smearing
Gaussian vz distribution with sigma = 5 mm centred at z = 0.

Analyzer command:

python3 -m analyzer generated_tracked.csv vz --kind csv --bins 50 --linear-y


Multiple particle definitions

Each entry is an independent source; all contribute to every event. Here one electron (fixed angle) and two protons (smeared angle) are generated per event:

gparticle:
  - name: e-
    p: 2300
    theta: 23.0
  - name: proton
    multiplicity: 2
    p: 1200
    theta: 14.0
    delta_theta: 10.0
theta distribution for combined electron and proton sources
Two populations: a spike at θ ≈ 0.4 rad (one electron at 23°) and a broad flat band from two protons smeared around 14°.

Analyzer command:

python3 -m analyzer generated_tracked.csv theta --kind csv --bins 50 --linear-y


gparticlefile

gparticlefile loads particle definitions from a file. Each entry specifies a format and a filename:

Field Description
format File format reader name. The built-in reader is lund (case-insensitive).
filename Path to the input file containing event records. 
gparticlefile:
  - format: lund
    filename: events.lund

Event records are matched by index: file event 0 is used for GEMC event 0, file event 1 for GEMC event 1, and so on. In multi-threaded mode Geant4 distributes event IDs to worker threads; each file event is still assigned to exactly one GEMC event.

Multiple sources can be combined — events from all files are merged by index:

gparticlefile:
  - format: lund
    filename: beam_background.lund
  - format: lund
    filename: signal.lund

See the LUND format documentation for the file structure, column definitions, and unit conventions.