36.11. Recommended Geant4 Simulation Workflow
Table of Contents
Overview
A clear workflow helps you build Geant4 simulations that are reproducible, maintainable, and easier to debug. This appendix gives a practical, step by step outline for how to go from a physics idea to a validated simulation, without prescribing one single “correct” way. Treat it as a checklist that you adapt to your own project.
Step 1: Define the Physics Question
Begin by writing down in plain language what you want to learn from the simulation. Specify:
What physical quantity are you trying to estimate or understand, such as dose, detection efficiency, energy spectrum, or shielding performance.
What energy range and which particles are involved.
What level of accuracy you need and what approximations are acceptable.
It helps to define a minimal working problem first, for example “simulate monoenergetic 1 MeV gamma rays in a simple water box” before you attempt a full detector model. This keeps early iterations fast and easy to debug.
Step 2: Collect Inputs and Reference Data
Before opening an editor, gather the information you need:
Geometry dimensions and layout, including tolerances if relevant.
Material compositions and densities, including whether you can use NIST materials or need custom mixtures.
Beam or source properties, such as spectra, angular distributions, and time structure.
Reference data for validation, such as analytical formulae, published measurements, or previous simulations.
Prepare a short document where you record the key numbers, formulas, and references. This will later help when you document assumptions and compare results.
Step 3: Plan the Simulation Structure
Map your physics question into the standard Geant4 application structure. Decide:
Which geometric components are essential and which can be simplified or omitted.
Which sensitive regions must record detailed information and which can be passive.
What outputs you actually need, such as histograms, ntuples, or simple counters.
Which Geant4 user classes you will implement initially, for example DetectorConstruction, PrimaryGeneratorAction, and a minimal set of user actions.
At this stage, also decide on a basic directory layout that you will keep consistent, with separate folders for sources, headers, build, and macros, and a place for output and logs.
Step 4: Set Up the Project Skeleton
Create a minimal but functional Geant4 application:
Write the main program that constructs the run manager, registers user initialization classes, and optionally starts an interactive session.
Add empty or minimal implementations of DetectorConstruction, PhysicsList or a reference physics list, and ActionInitialization.
Prepare a CMakeLists.txt that locates Geant4, defines your executable, and links the required libraries.
Create at least one macro file for initialization, for example to set the physics list, verbosity, and visualization driver.
At this stage, you should already be able to configure, compile, and run, even if the simulation does almost nothing. This step is crucial for catching build and environment issues early.
Step 5: Implement a Simple Geometry
Start with the simplest possible geometry that still resembles your problem:
Create a world volume with a reasonable size and a simple material, often air or vacuum.
Add one main detector or target volume, usually a single box or cylinder representing the active material.
Avoid complex Boolean operations or nested hierarchies in the first iteration.
Use NIST materials whenever possible to reduce the chance of mistakes in densities or compositions.
Verify this initial geometry visually using one of the visualization drivers. Use commands to draw volumes, adjust the view, and check sizes. Also run geometry overlap checks at this stage to catch obvious construction errors.
Step 6: Configure a Minimal Physics List
Choose a reference physics list that matches your problem domain, for example an electromagnetic list for photon and electron problems, or a standard hadronic list for neutrons and protons. In the early stages, avoid customizing the physics list unless you have a specific reason.
Write code to select the reference list and, if needed, enable or disable optional components such as optical physics or specialized processes. Record in your notes which physics list and version you selected, because this will matter for later validation and reproducibility.
Step 7: Define a Simple Primary Source
Implement PrimaryGeneratorAction with a basic source that lets you test geometry and physics:
Use a particle gun or the general particle source to emit a single particle type with fixed energy, position, and direction.
Place the source so that particles clearly traverse your main detector or target volume.
Use a small number of events at this stage so that tests run quickly.
Later, you can replace this test source with a more realistic spectrum or distribution, but keeping a simple test configuration is helpful for debugging.
Step 8: Add Sensitive Detectors and Hits
Once particles cross your detector volume, you need to record their interactions:
Create a sensitive detector class for each logical group of detector elements, and register it with the logical volumes where measurements occur.
Implement ProcessHits to collect information such as energy deposition, position, and time, and to create hit objects that are stored in hit collections.
Decide what each hit represents, for example one step, one energy deposit per track, or the sum over a detector element per event.
In parallel, define hit classes that store only the information you need at this stage. You can add more fields later.
Step 9: Set Up Basic Analysis Output
Introduce the Geant4 analysis manager early so that you can inspect results:
Create histograms for essential quantities, such as total energy deposit per event, or energy deposit per detector element.
Set up an ntuple if you need event by event or hit by hit information, including fields for energy, position, time, and IDs.
Enable writing of output files, for example in ROOT or CSV format, and make sure you close them cleanly at the end of each run.
Use clear naming conventions for histograms and ntuple columns. This will reduce confusion when you later analyze data in external tools.
Step 10: Test the Minimal Simulation
With geometry, physics, source, sensitive detectors, and analysis in place, run a first full loop:
Use a small number of events, such as a few hundred or a thousand, to keep turnaround time short.
Check that energy is deposited where expected. Verify that hits appear in the right detectors.
Look for obvious anomalies, such as zero energy deposition, unphysical energies, or hits outside your geometry.
Plot quick diagnostics from the output, such as an energy spectrum or spatial distribution, using your preferred analysis tool.
During this phase, use Geant4 verbose options for tracking and stepping to inspect individual events when needed.
Step 11: Incrementally Refine Geometry and Physics
After the minimal simulation works, gradually increase realism:
Add more volumes and refine shapes, always checking for overlaps and visual consistency.
Introduce additional materials and layers, such as shielding or support structures, in small steps.
Adjust the physics list choices if your energy range or particle types require it, and consider enabling higher precision electromagnetic models or specialized hadronic models if necessary.
At each refinement step, re run a small number of events to verify that the simulation still behaves as expected and that you did not introduce geometry or physics inconsistencies.
Step 12: Implement Realistic Sources and Conditions
Replace the test source with a realistic model of your experimental or clinical situation:
Configure spatial distributions, such as volume sources, beams with finite spot size, or distributed activity.
Implement energy spectra that match measured or expected distributions, using the general particle source or custom generators.
If timing is important, define time structures for the source or beam.
Keep macro commands for source configuration so you can easily scan over energies, positions, or other parameters without recompilation.
Step 13: Design and Run Production Simulations
When you are confident in the setup, plan your main production runs:
Decide on the number of events needed to reach the desired statistical precision for key observables.
Configure random seeds or random engine settings to ensure reproducibility and independence between runs.
Use multithreading if appropriate, while ensuring that user code and analysis are thread safe and that outputs from threads are correctly merged.
Organize runs in a structured way, with clear naming for output files, logs, and macro files so you can later trace exactly how each file was produced.
Step 14: Analyze and Validate Results
Connect your Geant4 outputs to your analysis workflow:
Inspect histograms and ntuples in ROOT or another analysis environment.
Compute derived quantities such as efficiencies, depth dose, transmission factors, or coincidence rates.
Compare your results with analytical calculations or published data, including uncertainties where available.
Pay attention to trends and discrepancies. Ask whether differences can be explained by physics approximations, geometry simplifications, or numerical issues.
Always validate key observables against independent references before drawing physical conclusions. Do not trust a visually “reasonable” result without quantitative checks.
Step 15: Check Systematic Effects and Uncertainties
Once basic validation is in place, explore how sensitive your results are to assumptions:
Vary geometry parameters within tolerances and see how results change.
Try alternative physics lists or model options, especially if you work at energies where multiple models are valid.
Change production cuts and step limits in reasonable ranges to quantify their impact.
If suitable, run simulations with different random seeds to confirm that statistical uncertainties behave as expected.
Document how these variations affect central values and uncertainties in your results.
Step 16: Optimize Performance and Clean Up
When simulations become heavy, focus on performance:
Simplify geometry where it does not significantly affect observables.
Restrict detailed outputs only to what is necessary and avoid verbose logging in production runs.
Use production cuts, region based cuts, and optimized physics lists to reduce unnecessary tracking.
Verify that multithreading and parallelism are used effectively and that memory usage stays within acceptable limits.
Also, remove outdated or experimental code paths that you no longer use, or clearly mark them as experimental so they do not confuse future work.
Step 17: Document the Complete Workflow
As a final step, make your simulation reproducible for yourself and others:
Write a brief description of the physics goal, geometry, materials, source, physics list, and main assumptions.
Keep the exact Geant4 version, compiler, and operating system recorded.
Store macro files, configuration files, and example commands that reproduce key results.
Add comments to your source code that explain design choices, not just obvious implementation details.
Use version control to track changes in geometry, physics configurations, and analysis scripts over time.
By following this structured workflow from question to validation and documentation, you create Geant4 simulations that are not only correct and efficient, but also understandable and reusable for future projects.
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!