36.10. Recommended Geant4 Project Structure
Table of Contents
Overview
A clear and consistent project structure makes Geant4 applications easier to write, debug, extend, and share. This appendix proposes a practical directory and file layout that you can adapt to most small and medium simulations. The focus is on separating responsibilities, keeping build files clean, and preparing your project for future growth without unnecessary complexity.
A well organized project is not optional. It is essential for:
- Avoiding subtle bugs when you change geometry, physics, or analysis.
- Reusing components across different simulations.
- Allowing others (and your future self) to understand and extend your code.
Basic Directory Layout
A typical Geant4 project can be organized into a small number of top-level directories. A good starting point is:
| Directory / File | Purpose |
|---|---|
CMakeLists.txt | Top-level build configuration. |
src/ | C++ source (.cc) files for your application. |
include/ | C++ header (.hh) files with class declarations. |
macro/ | Geant4 macro (.mac) files. |
data/ | Extra input data specific to your project. |
vis/ | Visualization macro files and styles. |
build/ | Out-of-source build directory (created by you). |
output/ | Simulation outputs (ROOT, CSV, logs, plots). |
docs/ | Notes, diagrams, and project documentation. |
scripts/ | Helper scripts for running and postprocessing. |
Only a few of these are strictly required for a minimal project. However, adopting this structure from the start avoids mixing very different kinds of files and keeps build products out of your source tree.
The build directory is usually not committed to version control. You create it manually and run CMake inside it. This keeps compiler outputs, temporary files, and generated makefiles separate from your source code.
Organizing Source and Header Files
The heart of your project lives in src/ and include/. Every user-defined class should have a header file in include/ and a matching source file in src/ with the same base name.
A simple, yet scalable convention is:
| Component | Header (in include/) | Source (in src/) |
|---|---|---|
| Main program | (none, typically) | main.cc |
| Detector construction | DetectorConstruction.hh | DetectorConstruction.cc |
| Physics list (if user defined) | PhysicsList.hh | PhysicsList.cc |
| Primary generator | PrimaryGeneratorAction.hh | PrimaryGeneratorAction.cc |
| Run action | RunAction.hh | RunAction.cc |
| Event action | EventAction.hh | EventAction.cc |
| Stepping action | SteppingAction.hh | SteppingAction.cc |
| Tracking action | TrackingAction.hh | TrackingAction.cc |
| Stacking action | StackingAction.hh | StackingAction.cc |
| Sensitive detector(s) | MyDetectorSD.hh | MyDetectorSD.cc |
| Hit class(es) | MyHit.hh | MyHit.cc |
| Analysis manager wrapper (optional) | MyAnalysis.hh | MyAnalysis.cc |
| Configuration / parameter class | Config.hh | Config.cc |
| Utility functions | Utils.hh | Utils.cc |
Within include/, you can group related headers into subdirectories once the project grows, for example:
include/geometry/DetectorConstruction.hhinclude/physics/PhysicsList.hhinclude/actions/RunAction.hh
If you choose this, mirror the same structure in src/ so that file locations remain predictable.
Always follow this rule:
One class = one header file and one source file (with the same base name), unless there is a very strong reason to group them.
This keeps compilation dependencies clear and reduces build times.
Mapping Geant4 Components to Files
Geant4 encourages a specific set of user classes. A clean structure reflects this directly in the file names and locations.
The main entry point usually lives in src/main.cc. It should be short and limited to:
- Creating the
G4RunManagerorG4MTRunManager. - Registering your user initialization classes (detector, physics, actions).
- Starting interactive or batch mode.
Your user initialization and actions are then separated:
| Responsibility | Recommended class name | File name |
|---|---|---|
| Detector geometry | DetectorConstruction | DetectorConstruction.cc / .hh |
| Physics configuration | PhysicsList or reference list | PhysicsList.cc / .hh (if custom) |
| Action initialization | ActionInitialization | ActionInitialization.cc / .hh |
| Primary particle source | PrimaryGeneratorAction | PrimaryGeneratorAction.cc / .hh |
| Run-level bookkeeping | RunAction | RunAction.cc / .hh |
| Event-level bookkeeping | EventAction | EventAction.cc / .hh |
| Step-level operations | SteppingAction | SteppingAction.cc / .hh |
| Optional tracking control | TrackingAction | TrackingAction.cc / .hh |
| Optional secondary management | StackingAction | StackingAction.cc / .hh |
| Sensitive detector for a subdetector | MyDetectorSD | MyDetectorSD.cc / .hh |
| Hit information for that detector | MyHit | MyHit.cc / .hh |
You can have multiple sensitive detectors and hit classes if your geometry has several subdetector types. Use descriptive names such as CalorimeterSD, TrackerSD, CalorimeterHit, and TrackerHit.
Macros, Visualization, and Configuration Files
It is tempting to scatter macro files and configuration text files inside the source directory, but this quickly becomes confusing. Instead, dedicate a few clear directories.
The macro/ directory contains run control macros. Typical files include:
init.macfor initialization commands such as/run/initializeand physics or geometry checks.run1.mac,run2.macfor different simulation scenarios.test_geometry.macfor overlap checks and visualization commands.
The vis/ directory can store visualization specific macros so that you do not mix them with physics and run settings:
vis.macfor opening a viewer and drawing volumes.vis_openGL.mac,vis_Qt.macfor viewer specific macros if needed.- Style macros for colors, line widths, and views.
The data/ directory supports any extra information that your code reads at runtime, such as material property tables, spectrum files, or parameter lists. Keep such files separate from Geant4 data libraries, which are handled globally by your installation.
A small but useful pattern is to have a single macro that includes others, for example in macro/master.mac:
/control/execute init.mac
/control/execute vis/vis.mac
/control/execute run1.macIn this way, you can tweak visual settings or run conditions without touching C++ code.
Never hard-code absolute file paths like C:/User/... or /home/you/... inside macros or C++ code.
Use relative paths from the project root, for example macro/run1.mac or data/materials.txt.
Output and Analysis Files
Keeping output separate from input and source code is critical for reproducibility and cleanliness. A simple approach is:
- Write simulation results into
output/. - Use subdirectories inside
output/if you have several categories of results, for exampleoutput/root/,output/csv/,output/logs/.
You can enforce this in your application by setting output file names clearly in one place, for example in a central analysis or configuration class. Use paths such as output/spectrum.root or output/dose_depth.csv.
If you generate many files, consider using date or run identifiers in names, but avoid encoding too much information in file names. Keep the mapping between macro parameters and output files documented in docs/ or in a simple README.md.
Scaling Up: Subdirectories for Geometry, Physics, and Actions
As your simulation becomes more complex, placing all .cc files in a flat src/ directory may become hard to navigate. A gentle refactor is to introduce subdirectories while preserving the basic idea of one class per file.
A good pattern is:
| Category | Example directory | Example contents |
|---|---|---|
| Geometry | src/geometry/ | DetectorConstruction.cc, Calorimeter.cc |
| Physics | src/physics/ | PhysicsList.cc, EMPhysics.cc |
| Actions | src/actions/ | RunAction.cc, EventAction.cc |
| Detectors | src/detectors/ | CalorimeterSD.cc, TrackerSD.cc |
| Hits | src/hits/ | CalorimeterHit.cc, TrackerHit.cc |
| Analysis | src/analysis/ | MyAnalysis.cc |
| Utils | src/utils/ | Config.cc, Utils.cc |
Mirror these directories in include/:
include/geometry/DetectorConstruction.hhinclude/actions/RunAction.hh- and so on.
This makes it obvious where to look for each part of the code and avoids huge source files that contain unrelated functionality.
CMake Integration and Targets
Your CMakeLists.txt should reflect the chosen structure but not hard-code every file name. You can either list each source file explicitly or use CMake commands to gather files from subdirectories.
A robust pattern is to define a single executable target for the application and link it against Geant4. For example, in the top-level CMakeLists.txt:
- Find Geant4 using its configuration.
- Collect your project sources.
- Define an executable and link it to Geant4 libraries.
- Optionally, define an installation or run script.
Try to keep build logic separate from simulation logic. Avoid including CMake-specific definitions or macros inside your C++ code.
Keep the build system simple and transparent:
- One main executable.
- One top-level
CMakeLists.txt. - Avoid complex CMake logic unless strictly necessary.
This reduces confusion and makes the project long-term maintainable.
Project Naming and File Naming Conventions
Consistent naming is a small effort that pays off when the project grows. A common convention is:
- Use
CamelCasefor C++ class names:DetectorConstruction,PrimaryGeneratorAction. - Use lowercase words separated by underscores for file and directory names, except where Geant4 suggests class-based filenames:
detector_construction_tests.cc, butDetectorConstruction.ccfor the main class. - Keep Geant4 user classes with their standard class names, to make it immediately clear what they represent.
Namespaces can help avoid name clashes in larger projects, but for small beginner projects you can usually work without them. If you do use a namespace, keep its name short and meaningful, such as myproj or pet_sim.
Multiple Examples in One Repository
If you plan to keep several different Geant4 applications in a single repository, it is better to separate them as independent subprojects rather than mixing everything into one build target. A simple structure is:
| Path | Purpose |
|---|---|
CMakeLists.txt | Top-level controlling file. |
examples/gamma/ | Gamma-ray detector project. |
examples/shielding/ | Radiation shielding project. |
examples/pet/ | PET scanner project. |
cmake/ | Shared CMake modules or scripts. |
Each example can follow the recommended structure inside its own directory:
examples/gamma/src/examples/gamma/include/examples/gamma/macro/examples/gamma/output/
The top-level CMakeLists.txt can then add each example as a subdirectory and build a separate executable for each.
Summary of Recommended Practices
To conclude, a good Geant4 project structure for beginners should:
- Separate source code, headers, macros, data, outputs, and documentation into their own directories.
- Follow a one-class-per-file rule with matching
.ccand.hhfile names. - Reflect Geant4 user classes directly in file names, such as
DetectorConstruction,PrimaryGeneratorAction, andRunAction. - Keep the build configuration simple and in one place, without mixing build logic into simulation code.
- Use relative paths and clear naming for macros, visualization files, and output data.
- Be ready to scale by introducing subdirectories for geometry, physics, actions, detectors, hits, analysis, and utilities.
If you adopt this layout from the beginning of your work with Geant4, most future projects will feel familiar and easier to manage, even as they become more sophisticated.
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!