10.1. PrimaryGeneratorAction
Table of Contents
Purpose of the primary generator
In a Geant4 application, the primary generator is the component that tells the simulation which particles enter your geometry, where they come from, and how they move and with what energy. Geant4 itself does not decide this. Instead, you define a user class that inherits from G4VUserPrimaryGeneratorAction. This class is commonly called PrimaryGeneratorAction in example codes, and it is the central place where primary events are created.
The run manager calls the GeneratePrimaries(G4Event* event) method of your PrimaryGeneratorAction once for every event. Each call is responsible for filling that event with one or more primary vertices and primary particles. If you want one particle per event, you generate one primary. If you want a bunch of particles in the same event, you generate several primaries before returning from GeneratePrimaries.
Inside your PrimaryGeneratorAction you normally keep one or more particle source objects, such as a G4ParticleGun or a G4GeneralParticleSource (GPS). The primary generator does not transport particles or apply physics, it only creates the starting conditions. After that, Geant4 uses the physics list to transport and interact those particles in the geometry.
Your PrimaryGeneratorAction is registered with the run manager through the ActionInitialization class. During initialization, the master or worker run manager calls your ActionInitialization::Build() method, where you create an instance of PrimaryGeneratorAction and hand it to the run manager. From that point on, for each event, Geant4 will automatically call GeneratePrimaries.
It is important to keep all event specific particle configuration inside GeneratePrimaries, and leave construction, allocation, and basic configuration of the particle gun or GPS to the constructor of PrimaryGeneratorAction. This separation keeps your code efficient and easy to understand.
The only place where you must create primary particles for each event is GeneratePrimaries(G4Event*) in your class derived from G4VUserPrimaryGeneratorAction. Never try to create primaries in other user action classes.
Creating particles
To create particles, you first need a primary generator object, most simply a G4ParticleGun. In the constructor of your PrimaryGeneratorAction, you typically create the gun and set default properties that will apply to all events unless you change them later.
A minimal pattern looks like this in the header and source files.
In the header file:
// PrimaryGeneratorAction.hh
#ifndef PrimaryGeneratorAction_hh
#define PrimaryGeneratorAction_hh
#include "G4VUserPrimaryGeneratorAction.hh"
#include "G4ThreeVector.hh"
class G4ParticleGun;
class G4Event;
class PrimaryGeneratorAction : public G4VUserPrimaryGeneratorAction
{
public:
PrimaryGeneratorAction();
~PrimaryGeneratorAction() override;
void GeneratePrimaries(G4Event* event) override;
private:
G4ParticleGun* fParticleGun;
};
#endifIn the source file constructor you create and configure the gun.
// PrimaryGeneratorAction.cc
#include "PrimaryGeneratorAction.hh"
#include "G4ParticleGun.hh"
#include "G4ParticleTable.hh"
#include "G4ParticleDefinition.hh"
#include "G4SystemOfUnits.hh"
PrimaryGeneratorAction::PrimaryGeneratorAction()
: G4VUserPrimaryGeneratorAction(),
fParticleGun(nullptr)
{
// Create a particle gun that will shoot one particle per event
G4int nParticle = 1;
fParticleGun = new G4ParticleGun(nParticle);
// Choose the particle type
G4ParticleTable* particleTable = G4ParticleTable::GetParticleTable();
G4ParticleDefinition* gamma = particleTable->FindParticle("gamma");
fParticleGun->SetParticleDefinition(gamma);
// Set a default energy
fParticleGun->SetParticleEnergy(1.0 * MeV);
// Set a default starting position
fParticleGun->SetParticlePosition(G4ThreeVector(0., 0., -10.*cm));
// Set a default direction (along +z)
fParticleGun->SetParticleMomentumDirection(G4ThreeVector(0., 0., 1.));
}
PrimaryGeneratorAction::~PrimaryGeneratorAction()
{
delete fParticleGun;
}
In GeneratePrimaries, you use the configured gun to add the particle to the current event. You can also modify properties on an event by event basis before generating the primary.
void PrimaryGeneratorAction::GeneratePrimaries(G4Event* event)
{
// If needed, change energy, position, or direction here
// For example, a simple scan in energy:
// G4double eventID = event->GetEventID();
// G4double energy = (0.5 + 0.01*eventID) * MeV;
// fParticleGun->SetParticleEnergy(energy);
// Finally, generate the primary vertex in this event
fParticleGun->GeneratePrimaryVertex(event);
}
The G4ParticleTable is the standard way to obtain a G4ParticleDefinition for built in particles. You request a particle by name, such as "e-", "e+", "proton", "neutron", "gamma", and many others. The particle definition tells Geant4 the mass, charge, and other properties. The particle gun then uses this definition together with the energy, position, and direction to create the primary particle.
The most common particle properties you control are summarized here.
| Property | Setter in G4ParticleGun | Typical example |
|---|---|---|
| Type | SetParticleDefinition() | FindParticle("e-"), FindParticle("proton") |
| Kinetic energy | SetParticleEnergy(G4double) | 1.0 MeV, 100. keV |
| Position | SetParticlePosition(const G4ThreeVector&) | G4ThreeVector(0., 0., 0.) |
| Momentum direction | SetParticleMomentumDirection(const G4ThreeVector&) | G4ThreeVector(0., 0., 1.) |
| Number per event | Constructor argument of G4ParticleGun | new G4ParticleGun(1); |
Inside GeneratePrimaries, you can introduce randomness by using Geant4 random utilities. For example, to randomize the starting position within a circle you might write:
#include "Randomize.hh"
void PrimaryGeneratorAction::GeneratePrimaries(G4Event* event)
{
G4double r = 1.0 * cm;
G4double phi = 2.*CLHEP::pi * G4UniformRand();
G4double x = r * std::cos(phi);
G4double y = r * std::sin(phi);
G4double z = -10. * cm;
fParticleGun->SetParticlePosition(G4ThreeVector(x, y, z));
fParticleGun->GeneratePrimaryVertex(event);
}
For more complex sources, such as spatial, angular, or energy distributions defined in macro files, you typically replace or supplement the particle gun with a G4GeneralParticleSource. The overall role of PrimaryGeneratorAction stays the same: it owns the source object, configures it, and calls it in GeneratePrimaries to populate each event with primary particles.
Before calling GeneratePrimaryVertex(event), you must set a valid particle definition, position, and direction. If any of these are missing or invalid, the simulation can behave incorrectly or crash.
Views: 0
Where to Move
Move chapter:
- ☰ 1. Introduction to Geant4
- ☰ 1.1. What Is Geant4?
- ☰ 1.2. How Geant4 Works
- ☰ 1.3. Geant4 Simulation Structure
- ☰ 1.4. Geant4 and C++
-
- ☰ 2. Installing Geant4
- ☰ 2.1. Geant4 Requirements
- ☰ 2.2. Installing Geant4 on Linux
- ☰ 2.3. Installing Visualization Libraries
- ☰ 2.4. Verifying the Installation
- ☰ 2.5. Geant4 Example Applications
-
- ☰ 3. C++ Basics for Geant4
- ☰ 3.1. Classes and Objects
- ☰ 3.2. Inheritance
- ☰ 3.3. Pointers and References
- ☰ 3.4. Header and Source Files
- ☰ 3.5. Standard Library Containers
-
- ☰ 4. Creating Your First Geant4 Project
- ☰ 4.1. Project Structure
- ☰ 4.2. CMake Configuration
- ☰ 4.3. The Main Program
- ☰ 4.4. User Initialization Classes
- ☰ 4.5. Building and Running
-
- ☰ 5. Geant4 Units and Constants
- ☰ 5.1. Geant4 Unit System
- ☰ 5.2. Using Units in C++
- ☰ 5.3. Physical Constants
- ☰ 5.4. Printing Values with Units
-
- ☰ 6. Creating the Simulation World
- ☰ 6.1. DetectorConstruction
- ☰ 6.2. Solids
- ☰ 6.3. Logical Volumes
- ☰ 6.4. Physical Volumes
- ☰ 6.5. Creating the World Volume
-
- ☰ 7. Materials
- ☰ 7.1. Geant4 Materials
- ☰ 7.2. NIST Material Database
- ☰ 7.3. Common Materials
- ☰ 7.4. Creating Custom Materials
- ☰ 7.5. Detector Materials
-
- ☰ 8. Building Detector Geometry
- ☰ 8.1. Basic Geometrical Shapes
- ☰ 8.2. Boolean Solids
- ☰ 8.3. Positioning Volumes
- ☰ 8.4. Repeated Geometry
- ☰ 8.5. Detector Arrays
- ☰ 8.6. Geometry Overlap Checking
-
- ☰ 9. Geometry Visualization
- ☰ 9.1. Visualization in Geant4
- ☰ 9.2. Starting the Visualization System
- ☰ 9.3. Changing the View
- ☰ 9.4. Visualization Attributes
- ☰ 9.5. Displaying Particle Tracks
-
- ☰ 10. Primary Particle Generation
- ☰ 10.1. PrimaryGeneratorAction
- ☰ 10.2. Particle Gun
- ☰ 10.3. Particle Energy
- ☰ 10.4. Particle Position
- ☰ 10.5. Particle Direction
- ☰ 10.6. Common Particle Sources
-
- ☰ 11. General Particle Source
- ☰ 11.1. Introduction to GPS
- ☰ 11.2. Position Distributions
- ☰ 11.3. Angular Distributions
- ☰ 11.4. Energy Distributions
- ☰ 11.5. Configuring Sources with Macros
-
- ☰ 12. Physics Lists
- ☰ 12.1. What Is a Physics List?
- ☰ 12.2. Reference Physics Lists
- ☰ 12.3. Electromagnetic Physics
- ☰ 12.4. Gamma Interactions
- ☰ 12.5. Positron Physics
- ☰ 12.6. Hadronic Physics
- ☰ 12.7. Choosing a Physics List
-
- ☰ 13. Particle Tracking
- ☰ 13.1. Tracks
- ☰ 13.2. Steps
- ☰ 13.3. Energy Deposition
- ☰ 13.4. Track Status
- ☰ 13.5. Parent and Secondary Particles
-
- ☰ 14. User Actions
- ☰ 14.1. RunAction
- ☰ 14.2. EventAction
- ☰ 14.3. SteppingAction
- ☰ 14.4. TrackingAction
- ☰ 14.5. StackingAction
- ☰ 14.6. ActionInitialization
-
- ☰ 15. Sensitive Detectors
- ☰ 15.1. What Is a Sensitive Detector?
- ☰ 15.2. Creating a Sensitive Detector
- ☰ 15.3. Hits
- ☰ 15.4. Hit Collections
- ☰ 15.5. Assigning Sensitive Detectors
-
- ☰ 16. Recording Energy Deposition
- ☰ 16.1. Energy Deposition
- ☰ 16.2. Energy per Event
- ☰ 16.3. Energy per Detector
- ☰ 16.4. Energy Spectra
- ☰ 16.5. Detector Efficiency
-
- ☰ 17. Particle Position and Timing
- ☰ 17.1. Particle Position
- ☰ 17.2. Interaction Position
- ☰ 17.3. Global Time
- ☰ 17.4. Time of Flight
- ☰ 17.5. Detector Timing
-
- ☰ 18. Geant4 Analysis System
- ☰ 18.1. Introduction to G4AnalysisManager
- ☰ 18.2. Histograms
- ☰ 18.3. Ntuples
- ☰ 18.4. Filling Ntuples
- ☰ 18.5. Writing Output Files
- ☰ 18.6. Closing Analysis Files
-
- ☰ 19. Geant4 and ROOT
- ☰ 19.1. ROOT Output from Geant4
- ☰ 19.2. Reading Geant4 Output with ROOT
- ☰ 19.3. Plotting Energy Spectra
- ☰ 19.4. Event Analysis
- ☰ 19.5. Simulation-to-Analysis Workflow
-
- ☰ 20. Geant4 Macro Commands
- ☰ 20.1. Macro Files
- ☰ 20.2. Run Commands
- ☰ 20.3. Particle Source Commands
- ☰ 20.4. Visualization Commands
- ☰ 20.5. Controlling Simulations Without Recompiling
-
- ☰ 21. Random Numbers and Reproducibility
- ☰ 21.1. Monte Carlo Random Numbers
- ☰ 21.2. Setting Random Seeds
- ☰ 21.3. Running Independent Simulations
- ☰ 21.4. Reproducing an Event
-
- ☰ 22. Multithreading
- ☰ 22.1. Geant4 Multithreading
- ☰ 22.2. Running with Multiple Threads
- ☰ 22.3. Thread-Safe User Code
- ☰ 22.4. Analysis with Multithreading
- ☰ 22.5. Performance Considerations
-
- ☰ 23. Practical Example: Gamma-Ray Detector
- ☰ 23.1. Project Overview
- ☰ 23.2. Creating the World
- ☰ 23.3. Creating the Detector
- ☰ 23.4. Adding the Material
- ☰ 23.5. Creating a Gamma Source
- ☰ 23.6. Selecting Electromagnetic Physics
- ☰ 23.7. Recording Energy Deposition
- ☰ 23.8. Creating an Energy Spectrum
- ☰ 23.9. Simulating Detector Resolution
- ☰ 23.10. Analyzing the Spectrum with ROOT
-
- ☰ 24. Practical Example: Radiation Shielding
- ☰ 24.1. Project Overview
- ☰ 24.2. Creating the Source
- ☰ 24.3. Creating the Shield
- ☰ 24.4. Comparing Shielding Materials
- ☰ 24.5. Varying Shield Thickness
- ☰ 24.6. Recording Transmitted Particles
- ☰ 24.7. Calculating Transmission
- ☰ 24.8. Calculating Attenuation
- ☰ 24.9. Comparing Simulation Results
-
- ☰ 25. Practical Example: PET Scanner
- ☰ 25.1. Introduction to PET Simulation
- ☰ 25.2. Creating a PET Detector Ring
- ☰ 25.3. Creating Detector Crystals
- ☰ 25.4. Assigning Detector IDs
- ☰ 25.5. Creating a Positron Source
- ☰ 25.6. Simulating Positron Annihilation
- ☰ 25.7. Recording Detector Hits
- ☰ 25.8. Applying an Energy Window
- ☰ 25.9. Finding Coincidence Events
- ☰ 25.10. Recording Detector Positions
- ☰ 25.11. Creating Lines of Response
- ☰ 25.12. Saving PET Events to ROOT
- ☰ 25.13. Analyzing PET Data with ROOT
-
- ☰ 26. Practical Example: Proton Beam in Water
- ☰ 26.1. Project Overview
- ☰ 26.2. Creating the Water Phantom
- ☰ 26.3. Creating a Proton Beam
- ☰ 26.4. Selecting the Physics List
- ☰ 26.5. Recording Energy Deposition
- ☰ 26.6. Dividing the Phantom into Slices
- ☰ 26.7. Calculating Depth Dose
- ☰ 26.8. Observing the Bragg Peak
- ☰ 26.9. Plotting the Depth-Dose Curve
-
- ☰ 27. Detector Resolution and Smearing
- ☰ 27.1. Ideal vs Realistic Detector Response
- ☰ 27.2. Energy Resolution
- ☰ 27.3. Position Resolution
- ☰ 27.4. Time Resolution
- ☰ 27.5. Applying Detector Effects
- ☰ 27.6. Comparing Ideal and Smeared Results
-
- ☰ 28. Simulation Validation
- ☰ 28.1. Why Validate a Simulation?
- ☰ 28.2. Checking Geometry
- ☰ 28.3. Checking Energy Conservation
- ☰ 28.4. Comparing with Analytical Calculations
- ☰ 28.5. Comparing with Reference Data
- ☰ 28.6. Statistical Uncertainties
- ☰ 28.7. Number of Simulated Events
-
- ☰ 29. Improving Simulation Performance
- ☰ 29.1. Geometry Performance
- ☰ 29.2. Physics List Performance
- ☰ 29.3. Production Cuts
- ☰ 29.4. Reducing Unnecessary Output
- ☰ 29.5. Multithreading
- ☰ 29.6. Running Large Simulations
- ☰ 29.7. Parameter Scans
-
- ☰ 30. Debugging Geant4 Simulations
- ☰ 30.1. Compilation Errors
- ☰ 30.2. Geometry Errors
- ☰ 30.3. Overlapping Volumes
- ☰ 30.4. Missing Particles
- ☰ 30.5. Missing Energy Deposition
- ☰ 30.6. Physics List Problems
- ☰ 30.7. Sensitive Detector Problems
- ☰ 30.8. Empty Output Files
- ☰ 30.9. Segmentation Faults
- ☰ 30.10. Using Geant4 Verbose Output
-
- ☰ 31. Writing Better Geant4 Applications
- ☰ 31.1. Organizing Source Code
- ☰ 31.2. Separating Geometry and Analysis
- ☰ 31.3. Using Configuration Parameters
- ☰ 31.4. Avoiding Hard-Coded Values
- ☰ 31.5. Creating Reusable Detector Components
- ☰ 31.6. Naming Conventions
- ☰ 31.7. Documentation
- ☰ 31.8. Version Control with Git
-
- ☰ 32. Advanced Geometry
- ☰ 32.1. Parameterized Geometry
- ☰ 32.2. Replica Volumes
- ☰ 32.3. Nested Geometry
- ☰ 32.4. Complex Detector Arrays
- ☰ 32.5. Importing CAD Geometry
- ☰ 32.6. Exporting Geometry with GDML
-
- ☰ 33. Optical Photons
- ☰ 33.1. Introduction to Optical Physics
- ☰ 33.2. Optical Photons
- ☰ 33.3. Material Optical Properties
- ☰ 33.4. Scintillation Light
- ☰ 33.5. Optical Surfaces
- ☰ 33.6. Photodetectors
- ☰ 33.7. Counting Optical Photons
-
- ☰ 34. Medical Physics Applications
- ☰ 34.1. Geant4 in Medical Physics
- ☰ 34.2. Radiation Dose Simulation
- ☰ 34.3. PET Simulation
- ☰ 34.4. SPECT Simulation
- ☰ 34.5. Radiotherapy Simulation
- ☰ 34.6. Proton Therapy Simulation
- ☰ 34.7. Biological Tissue Materials
-
- ☰ 35. Final Project
- ☰ 35.1. Project Overview
- ☰ 35.2. Define the Simulation Goal
- ☰ 35.3. Create the Geometry
- ☰ 35.4. Define Materials
- ☰ 35.5. Configure the Particle Source
- ☰ 35.6. Select the Physics List
- ☰ 35.7. Implement Sensitive Detectors
- ☰ 35.8. Record Simulation Data
- ☰ 35.9. Run the Simulation
- ☰ 35.10. Analyze the Results with ROOT
- ☰ 35.11. Validate the Simulation
- ☰ 35.12. Create Scientific Figures
- ☰ 35.13. Document the Simulation
-
- ☰ 36. Appendices
- ☰ 36.1. Geant4 Class Cheat Sheet
- ☰ 36.2. Geant4 Units Cheat Sheet
- ☰ 36.3. Common Geant4 Macro Commands
- ☰ 36.4. Common Geometry Classes
- ☰ 36.5. Common Particle Definitions
- ☰ 36.6. Common Physics Lists
- ☰ 36.7. G4AnalysisManager Cheat Sheet
- ☰ 36.8. Common Visualization Commands
- ☰ 36.9. Common Geant4 Errors and Solutions
- ☰ 36.10. Recommended Geant4 Project Structure
- ☰ 36.11. Recommended Geant4 Simulation Workflow
-
Comments
Please login to add a comment.
Don't have an account? Register now!