Explicit positronium source modeling for Geant4 PET pipelines: controlled 2-gamma and 3-gamma generation and validation

An explicit positronium (Ps) source model was implemented in Geant4 to provide direct event-level control over annihilation channel selection, decay timing, and photon emission topology. The implementation supports direct annihilation, para-positronium (p-Ps), and ortho-positronium (o-Ps) branches with user-defined fractions, explicit routing of o-Ps events to two-photon (2-gamma) or three-photon (3-gamma) decay, exponential or fixed delay sampling, optional prompt-photon emission, and optional positron-range displacement. Event-level truth metadata were retained to support downstream validation and analysis. The implementation was evaluated in controlled Geant4 studies using native reference configurations, explicit branch-fraction sweeps, lifetime sweeps, timing benchmarks, and a frozen point-source downstream test harness. Observed 2-gamma and 3-gamma fractions followed the requested control parameters with the expected linear behavior, and measured mean delays reproduced the prescribed lifetime settings with near one-to-one agreement. Computational cost scaled linearly with event count, with modest overhead relative to native Geant4 operation. A minimal downstream validation framework was used to verify branch-consistent handling of pure and mixed datasets, including expected method-source compatibility and recovery of valid events under unified 2-gamma and 3-gamma routing. These results establish a practical and internally consistent code framework for explicit positronium modeling in Geant4 and provide a simple pathway for PET researchers to incorporate controlled Ps generation into existing simulation pipelines.