14.6. ActionInitialization
Table of Contents
Registering user actions
In a complete Geant4 application you usually define several user action classes, such as RunAction, EventAction, SteppingAction, TrackingAction, and StackingAction. The ActionInitialization class is the central place where all these actions are created and registered with the Geant4 kernel. Without this registration, your user actions will never be called, even if the classes compile correctly.
The base class for this mechanism is G4VUserActionInitialization. You create your own class that derives from it, then implement specific methods where you instantiate and attach your actions to the run manager. The run manager calls these methods at the appropriate time, both in sequential and multithreaded runs.
A minimal custom action initialization class looks conceptually like this:
// MyActionInitialization.hh
#include "G4VUserActionInitialization.hh"
class MyActionInitialization : public G4VUserActionInitialization
{
public:
MyActionInitialization();
~MyActionInitialization() override;
void Build() const override;
void BuildForMaster() const override;
};
// MyActionInitialization.cc
#include "MyActionInitialization.hh"
#include "MyPrimaryGeneratorAction.hh"
#include "MyRunAction.hh"
#include "MyEventAction.hh"
#include "MySteppingAction.hh"
MyActionInitialization::MyActionInitialization() {}
MyActionInitialization::~MyActionInitialization() {}
void MyActionInitialization::Build() const
{
// Called for each worker thread (or once in sequential mode)
auto primary = new MyPrimaryGeneratorAction();
SetUserAction(primary);
auto runAction = new MyRunAction();
SetUserAction(runAction);
auto eventAction = new MyEventAction(runAction);
SetUserAction(eventAction);
auto steppingAction = new MySteppingAction(eventAction);
SetUserAction(steppingAction);
}
void MyActionInitialization::BuildForMaster() const
{
// Called only in the master thread in multithreaded mode
auto runAction = new MyRunAction();
SetUserAction(runAction);
}
The exact implementation details of the user action classes belong to other chapters. Here the focus is on how you connect them to the simulation through ActionInitialization.
The Build() method is where you register all actions that need to be active in each worker thread. In sequential (single thread) mode, Build() is still called, so you always define at least this method. In multithreaded mode, Geant4 also calls BuildForMaster() once in the master thread, which is intended for actions that manage quantities across the whole run, such as summary statistics that do not depend on per-event data from a specific worker.
When you use the run manager in your main() function, you pass an instance of your action initialization class:
auto runManager = new G4RunManager();
runManager->SetUserInitialization(new MyDetectorConstruction());
runManager->SetUserInitialization(new MyPhysicsList());
runManager->SetUserInitialization(new MyActionInitialization());
After this, when you call /run/initialize (usually indirectly through the macro system), the run manager will invoke BuildForMaster() in the master thread, then Build() in each worker, and your actions will be in place.
The functions SetUserAction(...) are inherited from G4VUserActionInitialization and can accept different action pointer types, such as G4UserRunAction, G4UserEventAction, G4UserSteppingAction*, and so on. Each call tells the kernel, "use this object to handle the corresponding part of the simulation life cycle."
There are some important patterns to keep in mind when registering user actions.
Always create user action objects with new inside Build() or BuildForMaster() and pass the raw pointer to SetUserAction(). Do not create them as local variables that will go out of scope, and do not delete them yourself. Geant4 takes ownership and will delete them at the end of the run.
Frequently, user actions depend on each other. For example, a SteppingAction might need to access event-level accumulators defined in EventAction. In that case, you typically pass pointers between them when constructing:
auto runAction = new MyRunAction();
auto eventAction = new MyEventAction(runAction);
auto steppingAction = new MySteppingAction(eventAction);
SetUserAction(runAction);
SetUserAction(eventAction);
SetUserAction(steppingAction);
This pattern lets your actions share information without using global variables. The same idea applies for analysis classes or managers that your actions might use. These shared objects should be created and wired up inside Build() or BuildForMaster() so that each thread has its own copy when needed.
In multithreaded simulations, BuildForMaster() is often simpler and only sets up a RunAction. The master does not handle events directly, so it does not need EventAction or SteppingAction. In sequential runs, BuildForMaster() is not used, and only Build() is relevant.
The order in which you call SetUserAction() does not matter to Geant4, but for readability and maintenance it is helpful to keep a consistent order such as primary generator, run action, event action, stepping action, tracking action, stacking action. This makes it easier to see at a glance which actions are part of your application and how they are connected.
By keeping all user action registration inside a dedicated ActionInitialization class, your main program remains uncluttered, and you can later modify, enable, or disable specific user actions by editing a single source file instead of chasing references through main() or other parts of the code.
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!