19.5 Simulation-to-Analysis Workflow

Table of Contents

Geant4 simulation

A practical workflow begins in Geant4 with a clear idea of what you want to measure. You define the detector geometry, choose materials, configure the particle source, and select an appropriate physics list in the C++ code and macros. For the workflow with ROOT in mind, you also need to design which quantities will be written to file and how they will be structured.

The central tool that connects the simulation to later analysis is G4AnalysisManager. It is usually created and configured in a user action class such as RunAction. Here you decide what histograms and ntuples you need. A histogram might store a one dimensional energy spectrum. An ntuple might store per event or per hit information such as event ID, detector ID, energy deposition, position, and time.

You typically follow these steps inside the Geant4 application:

In RunAction::BeginOfRunAction you create and configure histograms and ntuples with G4AnalysisManager. You also open the output file here.
In EventAction, SteppingAction, or in your sensitive detector classes you fill histograms and ntuples with values from the simulation. For instance, when a hit is created you accumulate deposited energy in a detector element and then record it.
In RunAction::EndOfRunAction you write all accumulated data to disk and close the output file.

The physics and geometry part of the simulation is independent of ROOT, but for an efficient workflow you should design them together. For example, if your analysis will later need to distinguish different detector elements, you must assign detector IDs and record them in the ntuple. If you need time of flight spectra, be sure you store global time or the time difference relevant to your detector.

It is useful to think about the data granularity during simulation design. You can record at different levels:

Level	Example data	Pros	Cons
Per event	Total deposited energy, number of hits	Small files, fast analysis	Less detail about individual hits
Per hit	Position, time, energy per hit	Detailed detector response	Larger files, more complex analysis
Per step	Step length, `dE`, process name	Very detailed debugging information	Very large files, usually not needed for ROOT

For production simulations you usually avoid step level output and focus on event and hit level data that map directly to physical observables.

Important rule: Decide what you need for analysis before you run large simulations. Changing the output structure usually requires recompiling and rerunning the simulation to regenerate data.

ROOT output

Geant4 writes analysis data through G4AnalysisManager into files, and one common format is ROOT. When you configure the analysis manager to use ROOT, it will internally create ROOT histograms and ntuples and serialize them into a .root file when you call Write() and CloseFile().

The basic structure looks like this in C++:

Choose the analysis backend and create the singleton G4AnalysisManager.
Set the output file name, for example "output.root".
Define histograms and ntuples at the beginning of the run.
Fill them during the event.
Write and close the file at the end of the run.

From the simulator perspective, you do not manipulate ROOT classes directly. Geant4 hides that through the analysis manager. The typical result after a run is a ROOT file that contains:

One or more histograms, for example h1 for an energy spectrum.
One or more ntuples, for example ntuple0 with columns such as Edep, x, y, z, t, detID.

ROOT files can hold several TTrees or histograms at once, which lets you organize data logically. For example, one TTree for event level summary and another TTree for hit level information. Since Geant4 writes standard ROOT objects, any ROOT installation can read them without extra plugins.

You should ensure that the file is properly closed at the end of the run. If a simulation is interrupted before Write() is called, some data may be lost. For long runs, you might decide to split output into several ROOT files by run number or by time to reduce the risk of corruption and to keep file sizes manageable.

Important rule: Always call the analysis manager Write() and CloseFile() methods at the end of the run. This guarantees that all histograms and ntuples are fully written and the ROOT file is consistent.

ROOT analysis

Once the Geant4 simulation has produced a ROOT file, the workflow moves to analysis. This step is usually done outside Geant4 using ROOT macros written in C++ or via PyROOT in Python. The ROOT file is opened, and the histograms and ntuples created during the simulation are examined, transformed, and visualized.

The standard pattern looks like this:

Start a ROOT session and open the file with TFile::Open("output.root").
Retrieve histograms or trees by name, for example TH1D hE = (TH1D)file->Get("hEdep") or TTree tree = (TTree)file->Get("Events").
Inspect the structure, especially for TTrees, to understand which branches correspond to which physical quantity.
Produce plots, cuts, and derived quantities and save them as images or new ROOT files.

For histograms, analysis can be as simple as plotting an energy spectrum, fitting a peak, or integrating counts over a given energy window. For ntuples, you typically work with TTrees. You may use TTree::Draw for quick projections, or attach branch addresses and process events in a loop for more complex logic such as event selection or reconstruction.

A common pattern in detector analysis is:

Select only events that satisfy some condition, for instance a minimum deposited energy.
Combine information from several branches, such as positions in different detectors, to reconstruct a physical observable.
Build new histograms or TTrees that store processed information like calibrated energy, coincidence times, or reconstructed vertices.

For a full workflow, you often chain several ROOT scripts. One script might perform basic cleaning and calibration and produce an intermediate ROOT file. Another script might use the cleaned data to create final physics plots, such as efficiency curves, attenuation coefficients, or energy resolution measurements.

Key workflow: Geant4 simulates and records raw detector-like data. ROOT then applies selection, reconstruction, and plotting to extract physics results. Design your Geant4 output so that ROOT has all the variables needed for this processing, but avoid storing unnecessary details that make analysis slow and files too large.

The final step is to export figures and tables for reports or publications. ROOT can save plots as images or vector graphics. You can also export numbers from histograms or TTrees to text or CSV for further processing with other tools. In a mature workflow, the Geant4 simulation and all ROOT analysis scripts are kept under version control, so that you can regenerate results in a reproducible way whenever the geometry, physics list, or analysis method changes.

19.5 Simulation-to-Analysis Workflow

Geant4 simulation

ROOT output

ROOT analysis

Comments

Where to Move