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*MeV
    theta: 23*deg

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


gparticle

Unit convention

All kinematic values accept an explicit Geant4 unit attached with *, for example 4*GeV, 23*deg, 0.4*rad, -10*cm, 1.5*mm. This is the recommended form.

If a plain number without a unit is given, GEMC falls back to the field default and logs a warning:

Field group Default unit
Momentum (p, delta_p) MeV
Angles (theta, delta_theta, phi, delta_phi) deg
Vertex (vx, vy, vz, delta_vx, delta_vy, delta_vz) cm

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 with unit, e.g. 4*GeV or 4000*MeV
multiplicity 1 Number of copies generated per event; each copy is independently randomized
delta_p 0*MeV Momentum spread around p
randomMomentumModel uniform uniform: flat in [p - delta_p, p + delta_p]; gaussian: Gaussian with sigma delta_p
theta 0*deg Nominal polar angle (from the z-axis), e.g. 23*deg or 0.4*rad
delta_theta 0*deg Polar-angle spread around theta
randomThetaModel uniform uniform: flat in [theta - delta_theta, theta + delta_theta]; gaussian: Gaussian sigma delta_theta; cosine: cos(theta) uniform, with rejection sampling within the window (see note below)
phi 0*deg Nominal azimuthal angle
delta_phi 0*deg Azimuthal-angle spread. Always applied with the uniform model; there is no randomPhiModel
vx 0*cm Nominal vertex x
vy 0*cm Nominal vertex y
vz 0*cm Nominal vertex z
delta_vx 0*cm Vertex x spread
delta_vy 0*cm Vertex y spread
delta_vz 0*cm Vertex z spread
randomVertexModel uniform uniform: each component flat in [v - delta_v, v + delta_v]; gaussian: Gaussian sigma per component; sphere: uniform sampling within a spherical volume (see note below)

Note

cosine theta model: samples theta such that cos(theta) 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 deg].

Note

sphere vertex model: generates vertices uniformly within a spherical volume centered on the nominal vertex. Set delta_vx, delta_vy, and 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: 2.3*GeV
    theta: 23*deg
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:

gemc-analyzer generated_tracked.csv theta --kind csv --bins 50 --linear-y


Theta spread of 0.2 rad

gparticle:
  - name: e-
    p: 2.3*GeV
    theta: 0.4*rad
    delta_theta: 0.2*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:

gemc-analyzer generated_tracked.csv theta --kind csv --bins 50 --linear-y


10 protons per event, uniform in φ

gparticle:
  - name: proton
    multiplicity: 10
    p: 1200*MeV
    theta: 14*deg
    delta_phi: 180*deg
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:

gemc-analyzer generated_tracked.csv phi --kind csv --bins 50 --linear-y


Momentum spread — uniform

gparticle:
  - name: e-
    p: 2300*MeV
    delta_p: 100*MeV
    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:

gemc-analyzer generated_tracked.csv p --kind csv --bins 50 --linear-y


Momentum spread — Gaussian

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

Analyzer command:

gemc-analyzer generated_tracked.csv p --kind csv --bins 50 --linear-y


Cosine theta sampling

gparticle:
  - name: e-
    p: 2300*MeV
    theta: 23*deg
    delta_theta: 5*deg
    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:

gemc-analyzer generated_tracked.csv theta --kind csv --bins 50 --linear-y


Azimuthal-angle spread

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

Analyzer command:

gemc-analyzer generated_tracked.csv phi --kind csv --bins 50 --linear-y


Fixed vertex position

gparticle:
  - name: e-
    p: 2300*MeV
    vx: 0*cm
    vy: 0*cm
    vz: -10*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:

gemc-analyzer generated_tracked.csv vz --kind csv --bins 50 --linear-y


Vertex z spread — uniform

gparticle:
  - name: e-
    p: 2300*MeV
    vz: 0*cm
    delta_vz: 2*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:

gemc-analyzer generated_tracked.csv vz --kind csv --bins 50 --linear-y


Vertex spread — Gaussian

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

Analyzer command:

gemc-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*MeV
    theta: 23*deg
  - name: proton
    multiplicity: 2
    p: 1200*MeV
    theta: 14*deg
    delta_theta: 10*deg
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:

gemc-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.