36.7. G4AnalysisManager Cheat Sheet
Table of Contents
Overview
The G4AnalysisManager class provides a simple, uniform interface to create histograms and ntuples, fill them during the simulation, and write them to file. It hides the details of specific backends such as ROOT, CSV, or XML and is designed to be used in user action classes, especially RunAction.
This cheat sheet summarizes the typical usage pattern and the most common methods you need in basic Geant4 applications.
Getting the Analysis Manager
G4AnalysisManager is a singleton. You never construct it directly with new. Instead you obtain the instance through the static Instance() method.
In a source file (for example RunAction.cc), include the header and get the instance:
#include "g4analysis.hh" // or "G4AnalysisManager.hh" depending on version
G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
You normally acquire the pointer inside the constructor or in the BeginOfRunAction and EndOfRunAction methods of your RunAction class. The same singleton instance can be accessed in other user action classes such as EventAction or SteppingAction, always through Instance().
If you use multithreading, keep in mind that G4AnalysisManager is a per-thread object, not shared, so each worker thread has its own instance.
Configuring Output and Verbosity
Before creating histograms or ntuples, you should configure the analysis manager. This is usually done in the constructor of your RunAction or in BeginOfRunAction.
Typical configuration includes setting the output file name, choosing output type, and adjusting verbosity.
Basic configuration looks like this:
G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
// Set default file type, for example "root", "csv", or "hbook" depending on build
analysisManager->SetDefaultFileType("root");
// Set the base file name (extension is added automatically by the backend)
analysisManager->SetFileName("myOutput");
// Set verbosity level (0 = silent, larger = more messages)
analysisManager->SetVerboseLevel(1);
// Optionally, enable or disable ntuple merging in multithreaded runs
analysisManager->SetNtupleMerging(true);
You can also control automatic file opening and closing. In most simple applications, you explicitly call OpenFile at the start of the run and Write followed by CloseFile at the end of the run.
Important rule
Always ensure that you call OpenFile() before filling any histograms or ntuples, and call Write() and CloseFile() at the end of the run. Otherwise, your data will not be saved.
Creating Histograms
You normally create histograms once per job, typically in the RunAction constructor or in BeginOfRunAction. Histograms are identified by an integer ID and optionally by a string name.
The most frequently used method creates one-dimensional histograms:
G4int id = analysisManager->CreateH1(
"Edep", // name (optional identifier string)
"Energy dep.", // title (for plots)
100, // number of bins
0.*keV, // lower edge
10.*MeV // upper edge
);You can also create 2D histograms for distributions in two variables, for example position:
analysisManager->CreateH2(
"XY", // name
"Hit position", // title
100, -5.*cm, 5.*cm, // x bins, x min, x max
100, -5.*cm, 5.*cm // y bins, y min, y max
);The return value is the numeric ID assigned to the histogram. It usually starts from 0 and increases with each call. You can either store this ID in a variable or rely on the order of creation and remember that the first histogram has ID 0, the second ID 1, and so on.
Important rule
Histogram IDs are integers assigned in the order of creation. Use consistent IDs when filling histograms. If you change the order of creation, you must also update all fill calls that use numeric IDs.
Filling Histograms
You fill histograms during the simulation, usually from EventAction, SteppingAction, or SensitiveDetector code, after you have accumulated some quantity such as energy deposition or position.
To fill a one-dimensional histogram run:
auto analysisManager = G4AnalysisManager::Instance();
G4double edep = ...; // some energy value in MeV, for example
analysisManager->FillH1(0, edep); // 0 is the histogram IDFor 2D histograms:
G4double x = ...;
G4double y = ...;
analysisManager->FillH2(1, x, y); // 1 is the 2D histogram ID
You can call FillH1 or FillH2 as many times as needed during an event. Geant4 increments the bin content corresponding to the given value.
If your values are not in the same units as the histogram range, convert them using Geant4 units before filling. This ensures consistent interpretation of the axes.
Creating Ntuples
Ntuples store per-event or per-hit data row by row. You define an ntuple and its columns once, then fill rows during the simulation.
You typically create ntuples and columns in the RunAction constructor or in BeginOfRunAction:
auto analysisManager = G4AnalysisManager::Instance();
// Create ntuple with ID 0 and name "Event"
analysisManager->CreateNtuple("Event", "Event data");
// Add columns with names and types
analysisManager->CreateNtupleIColumn("eventID"); // integer
analysisManager->CreateNtupleDColumn("Edep"); // double (energy)
analysisManager->CreateNtupleDColumn("x"); // position x
analysisManager->CreateNtupleDColumn("y");
analysisManager->CreateNtupleDColumn("z");
// Finish the ntuple definition
analysisManager->FinishNtuple();Common column-creation methods include:
| Method | Description |
|---|---|
CreateNtupleIColumn(name) | Integer column |
CreateNtupleFColumn(name) | Float column |
CreateNtupleDColumn(name) | Double column |
CreateNtupleSColumn(name) | String column |
There are also overloaded methods that attach columns to user-provided arrays or vectors, but for simple beginners applications the basic versions are usually enough.
If you need more than one ntuple, you can call CreateNtuple again and then define a separate set of columns, followed by FinishNtuple. Each ntuple has a numeric ID, starting from 0.
Important rule
Call FinishNtuple() after defining all columns for a given ntuple. Without this, the ntuple definition is incomplete and cannot be written correctly.
Filling Ntuples
You typically fill an ntuple row once per event in EndOfEventAction, or once per hit in the ProcessHits method of a sensitive detector.
The typical sequence is to set column values, then call AddNtupleRow:
auto analysisManager = G4AnalysisManager::Instance();
G4int eventID = ...;
G4double edep = ...;
G4double x = ...;
G4double y = ...;
G4double z = ...;
// ntuple ID 0, column IDs follow creation order
analysisManager->FillNtupleIColumn(0, eventID);
analysisManager->FillNtupleDColumn(1, edep);
analysisManager->FillNtupleDColumn(2, x);
analysisManager->FillNtupleDColumn(3, y);
analysisManager->FillNtupleDColumn(4, z);
// Finalize this row
analysisManager->AddNtupleRow();
The first argument to FillNtuple...Column is the column ID, which corresponds to the order in which you created the columns, starting at 0. For multiple ntuples, some versions of the interface provide overloaded methods that take ntuple ID and column ID separately. Consult the version of g4analysis.hh that you are using for the exact signatures.
You can fill only a subset of columns for a row if desired, but typically you fill all defined columns. Each call to AddNtupleRow() writes the current row into memory and resets any internal buffers for the next row.
Important rule
Always call AddNtupleRow() after filling columns for a row. Without this, the values set by FillNtuple...Column() will not be stored.
Opening, Writing, and Closing Files
The life cycle of the analysis file is usually controlled in BeginOfRunAction and EndOfRunAction. The usual pattern is:
In BeginOfRunAction:
auto analysisManager = G4AnalysisManager::Instance();
// The file name and type should already be set
analysisManager->OpenFile();
In EndOfRunAction:
auto analysisManager = G4AnalysisManager::Instance();
// Write all histograms and ntuples to the file
analysisManager->Write();
// Close the file properly
analysisManager->CloseFile();
You can also pass a file name to OpenFile directly:
analysisManager->OpenFile("run1");This overrides the default file name for that run.
If you perform several runs in the same session and want separate output files, you can change the file name before each call to OpenFile, for example by appending the run ID.
Important rule
Call Write() before CloseFile() to ensure that all buffered data are flushed to disk. Forgetting Write() may result in empty or incomplete output files.
Common Usage Pattern in RunAction
The following compact example shows a typical way to integrate G4AnalysisManager in a simple application. The example omits error checks and focuses on key calls.
In the RunAction.hh:
#include "G4UserRunAction.hh"
class RunAction : public G4UserRunAction {
public:
RunAction();
~RunAction() override;
void BeginOfRunAction(const G4Run*) override;
void EndOfRunAction(const G4Run*) override;
};
In RunAction.cc:
#include "RunAction.hh"
#include "g4analysis.hh"
RunAction::RunAction() : G4UserRunAction() {
auto analysisManager = G4AnalysisManager::Instance();
analysisManager->SetVerboseLevel(1);
analysisManager->SetFileName("output");
// Create histograms
analysisManager->CreateH1("Edep", "Energy deposition", 100, 0., 10.*MeV);
// Create ntuple
analysisManager->CreateNtuple("Event", "Event data");
analysisManager->CreateNtupleIColumn("eventID");
analysisManager->CreateNtupleDColumn("Edep");
analysisManager->FinishNtuple();
}
RunAction::~RunAction() {
delete G4AnalysisManager::Instance();
}
void RunAction::BeginOfRunAction(const G4Run*) {
auto analysisManager = G4AnalysisManager::Instance();
analysisManager->OpenFile();
}
void RunAction::EndOfRunAction(const G4Run*) {
auto analysisManager = G4AnalysisManager::Instance();
analysisManager->Write();
analysisManager->CloseFile();
}
In EventAction or SteppingAction, you then call FillH1, FillNtuple...Column, and AddNtupleRow as needed, always via G4AnalysisManager::Instance().
Selecting and Building Analysis Backends
G4AnalysisManager supports several output formats. Which ones are available depends on how Geant4 was configured when built. Common backends include:
| Backend | File type string | Typical file extension |
|---|---|---|
| ROOT | "root" | .root |
| CSV | "csv" | .csv |
| XML | "xml" | .xml |
You select the default type with:
analysisManager->SetDefaultFileType("root");
To enable a specific backend, Geant4 must be compiled with the corresponding option. For example, for ROOT output you usually configure CMake with -DGEANT4_USE_G4ROOT=ON. For CSV, use -DGEANT4_USE_G4CSV=ON. If a backend is not built, trying to use it will either fail at compile time or give a runtime error.
In many beginner setups, the examples are already configured for ROOT output if ROOT is available. Check the Geant4 build configuration or example documentation for your installation.
Useful Additional Methods
Beyond the basic creation, filling, and writing operations, G4AnalysisManager provides several utility methods that can be helpful in more involved applications.
You can adjust histogram activation status to enable or disable certain histograms at runtime:
analysisManager->SetActivation(true); // enable activation control
analysisManager->SetH1Activation(0, true); // activate histogram with ID 0
analysisManager->SetH1Activation(1, false); // deactivate histogram with ID 1You can get the number of histograms and ntuples that have been created:
G4int nH1 = analysisManager->GetNofH1s();
G4int nNtp = analysisManager->GetNofNtuples();In multithreaded applications, some versions allow you to enable ntuple merging:
analysisManager->SetNtupleMerging(true);This lets the master thread automatically merge per-thread ntuples at the end of the run.
Finally, you can change the base file name or type at runtime if you want to separate output by run:
G4int runID = run->GetRunID();
std::ostringstream fname;
fname << "output_run" << runID;
analysisManager->SetFileName(fname.str());
analysisManager->OpenFile();
This cheat sheet focuses on the most common patterns for beginners. For more advanced features such as profile histograms, weighted filling, or vector-linked columns, refer to the Geant4 Application Developers Guide and the example codes in the examples/extended/analysis directory.
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!