Overview

The gparticle module implements a simple mechanism to define one or more primary particles from structured options and then shoot them into a G4Event using a G4ParticleGun.

The central class is Gparticle, which encapsulates:

The particle identity (name and PDG id resolution)
Multiplicity (how many primaries to shoot per event)
Momentum/angle/vertex parameters
Randomization models (uniform/gaussian/cosine/sphere) as provided by gutilities

Option parsing is performed via the functions in the gparticle namespace. Those functions translate structured option nodes, such as -gparticle=... and -gparticlefile=..., into inline particles, file-backed event particles, and output-bank records.

The scalar eventTimeWidth option belongs to this module because it describes the generated event timeline. Consecutive event IDs are assigned consecutive windows of this width. The value is exposed through gparticle::getEventTimeWidth for timing-aware consumers such as SRO; it is zero by default, so a consumer must opt into a continuous timeline explicitly.

Angular sampling

For uniform theta sampling, delta_theta is the half-width around the nominal theta value:

$\‍[ \theta_{sampled} \in [\theta - \Delta\theta,\; \theta + \Delta\theta] \‍]$

The full angular sector therefore spans $2\Delta\theta$ . The diagram uses theta=40*deg and delta_theta=12*deg, giving an interval from 28 to 52 degrees.

Theta and delta-theta acceptance sector

The interpretation of a delta depends on the selected randomization model:

uniform: flat sampling inside the center-plus-or-minus-delta interval.
gaussian: delta is one standard deviation and does not impose a hard boundary.
cosine: theta is sampled uniformly in $\cos(\theta)$ inside the requested interval.
sphere: vertex offsets are sampled inside a sphere whose radius is derived from delta_v.

Momentum, angle, and vertex sampling models

File-backed particles

The -gparticlefile option configures one or more generated-particle files:

-gparticlefile="[{format: lund, filename: events.lund}]"

Each file source has a format token and a filename. Built-in readers are registered statically, while external formats can be provided by dynamic plugins named gparticle_<format>_plugin that export GParticleReaderFactory.

Readers expose two related views of the same input:

GParticleEvents : event-indexed Gparticle objects that can be propagated in Geant4.
GParticleRecordEvents : event-indexed metadata records used for output banks. Records can represent particles that are not propagated in Geant4 and particles whose ids are not known to G4ParticleTable.

For Lund files, rows with type == 1 are propagated in Geant4. All parsed rows are preserved in the record view.

Generated-particle output banks

During event generation GEMC publishes two generated-particle banks:

generated : inline -gparticle definitions plus all particles parsed from -gparticlefile sources, including rows not propagated in Geant4.
generated_tracked : inline -gparticle definitions plus only the file-backed particles propagated in Geant4, normally rows with type == 1.

Both banks carry particle name, pid, source type, multiplicity, momentum, theta, phi, and vertex coordinates.

Verbosity

gparticle uses logging through GLogger. When the logger verbosity is:

0: only essential messages (errors and minimal status) are printed
1: adds high-level informational messages describing the selected configuration
2: adds detailed informational output, including printing the full particle configuration
debug: emits constructor/destructor and fine-grained tracing messages useful for development

Examples

gparticle_example_main : Minimal program that parses gparticle options, builds particles, and initializes a G4RunManager with a basic physics list.

Example snippet

The following excerpt shows how the example program builds the options and retrieves particles:

auto gopts = std::make_shared<GOptions>(argc, argv, gparticle::defineOptions());
auto log   = std::make_shared<GLogger>(gopts, FUNCTION_NAME, GPARTICLE_LOGGER);
auto particles = gparticle::getGParticles(gopts, log);

Table of Contents