3.4. Header and Source Files
Table of Contents
`.hh` files
In a Geant4 application you will see many files ending in .hh. These are C++ header files. A header file describes the interface of your classes and functions. It tells the compiler what exists, without providing all the implementation details.
In a typical Geant4 class, the header file contains the class declaration. This includes the class name, its base class, its member variables, and the declarations of its member functions. Constructors, destructors, and important methods such as Construct() for detector geometry or BeginOfRunAction() for a run action are all declared here.
For example, a simple header for a detector construction class might look like:
#ifndef MyDetectorConstruction_hh
#define MyDetectorConstruction_hh
#include "G4VUserDetectorConstruction.hh"
#include "globals.hh"
class G4VPhysicalVolume;
class MyDetectorConstruction : public G4VUserDetectorConstruction
{
public:
MyDetectorConstruction();
virtual ~MyDetectorConstruction();
virtual G4VPhysicalVolume* Construct();
private:
// Member variables go here
};
#endif
The header uses only what is needed to describe the class. Implementations of methods are not written here, except sometimes short one line functions that you may mark inline. In Geant4 examples, you will often see inline getters or simple utility methods defined directly in the .hh file for performance and simplicity, but all nontrivial code usually goes to the .cc file.
For a beginner, it is useful to think of .hh files as the place that other parts of the program read in order to know how to use your class. Your main() function and other user classes will include these headers with #include "MyDetectorConstruction.hh" and then create objects or call methods that are declared there.
Because Geant4 is a large object oriented framework, you will create many header files: one for your detector construction, one for your primary generator, one for your physics list or physics configuration, and one for each user action class. Keeping the interface of each class in a separate .hh file helps keep your code organized and makes it easier to reuse classes across different applications.
You should avoid putting executable code or global variables in header files. If you put real code (for example, full function bodies) in a header and include that header from several .cc files, you can easily create multiple definition problems during linking. Instead, keep your logic in .cc files and use headers only for declarations and very short inline definitions that you intentionally want to share.
`.cc` files
Files ending in .cc are the C++ source files that hold the implementations of the classes and functions declared in your headers. In Geant4 examples, .cc is used instead of .cpp, but they mean the same thing for the compiler.
At the top of a .cc file, you include the corresponding header file, then write the method definitions. For the detector construction example above, the source file could look like:
#include "MyDetectorConstruction.hh"
#include "G4Box.hh"
#include "G4LogicalVolume.hh"
#include "G4PVPlacement.hh"
#include "G4NistManager.hh"
#include "G4SystemOfUnits.hh"
MyDetectorConstruction::MyDetectorConstruction()
: G4VUserDetectorConstruction()
{
}
MyDetectorConstruction::~MyDetectorConstruction()
{
}
G4VPhysicalVolume* MyDetectorConstruction::Construct()
{
G4NistManager* nist = G4NistManager::Instance();
G4Material* worldMat = nist->FindOrBuildMaterial("G4_AIR");
G4double worldSize = 1.0*m;
G4Box* solidWorld =
new G4Box("World", 0.5*worldSize, 0.5*worldSize, 0.5*worldSize);
G4LogicalVolume* logicWorld =
new G4LogicalVolume(solidWorld, worldMat, "World");
G4VPhysicalVolume* physWorld =
new G4PVPlacement(0,
G4ThreeVector(),
logicWorld,
"World",
0,
false,
0,
true);
return physWorld;
}In this file, you write the actual algorithms and logic: building geometry, configuring materials, defining actions, filling histograms, and so on. The compiler uses the header to check that your definitions match the declarations, and then compiles the source file into an object file that is later linked into the executable.
A few practical points are important for Geant4 work. First, always include the corresponding header as the first include in the .cc file. This helps ensure your header is self-contained and has all includes it needs. Second, keep one main class per pair of .hh and .cc files, especially in a teaching or small project context. For example, PrimaryGeneratorAction.hh and PrimaryGeneratorAction.cc should only define and implement PrimaryGeneratorAction. This makes it easier to map code files to the Geant4 user initialization hooks and to the CMake build.
Your main() function is also normally placed in a .cc file, often called example.cc, main.cc, or something similar. That file will include the user headers such as DetectorConstruction.hh and ActionInitialization.hh, create the run manager, register your classes, and start the simulation. Because main() must see the full class declarations, it includes the .hh files, not the .cc files.
In CMake configuration, only .cc files are added to the executable or library sources. Header files are discovered automatically through #include. Understanding this separation between interface in .hh and implementation in .cc is essential for building and extending Geant4 applications.
Include guards
Header files are often included from several different source files, and sometimes headers include other headers. This can easily lead to the same header being processed multiple times by the compiler. If the compiler sees the same class definition more than once in one translation unit, it will report an error about redefinition.
Include guards solve this problem. An include guard is a simple preprocessor pattern that makes sure the contents of a header file are only included once per compilation unit. You saw an example already:
#ifndef MyDetectorConstruction_hh
#define MyDetectorConstruction_hh
// header contents
#endif
The idea is that MyDetectorConstruction_hh is a unique macro name. During the first inclusion, it is not defined, so the preprocessor defines it and includes all the header contents. If another file includes the header again, the macro is already defined, so the whole block is skipped.
Always protect every header file with a unique include guard macro, or use #pragma once if and only if your compiler and project policy allow it. Missing include guards in Geant4 headers will almost always lead to compile time errors due to multiple class definitions.
Choosing a good macro name is important. It must be unique across the whole project. A common convention is to base it on the file path and convert it to uppercase, for example MYPROJECT_DETECTORCONSTRUCTION_HH. In Geant4 examples, you will see names like B1DetectorConstruction_hh or similar, where the example name appears in the macro.
Some compilers support the shorter directive
#pragma onceat the top of a header file. This has the same purpose as an include guard, but it is not part of the C++ standard, even though it is widely supported. For maximum portability and for consistency with Geant4 coding style, traditional include guards are a safe default, especially in educational projects.
From a practical point of view in Geant4, include guards make it safe to have complex include chains. For example, ActionInitialization.hh might include RunAction.hh, which itself includes AnalysisManager.hh. Your main.cc can include both ActionInitialization.hh and RunAction.hh directly without worrying about duplicate definitions, as long as each header has proper guards.
Whenever you create a new user class header, make setting up the include guard the first step. Many code editors and IDEs can insert the pattern automatically. Doing this consistently avoids subtle and confusing compilation problems later in your Geant4 development.
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!