gparticle Module

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.

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

Table of contents

• gparticle
• Options and configuration
• Examples

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);