KAHIBARO
22.4. Analysis with Multithreading
Table of Contents
Merging output
In multithreaded Geant4, each worker thread runs its own copy of the user actions and its own instance of G4AnalysisManager. This is essential for thread safety, because it avoids concurrent writes to the same data structures and files. However, it also means that the results must be combined at the end of the run.
For beginners it is useful to think of the workflow as two stages. First, each worker thread fills its own in memory histograms and ntuples during the run. Second, when the run ends, these thread local results are merged by the master thread and written to disk as a single output file.
Geant4 handles most of this merging for you if you use the built in analysis system correctly. You normally create and configure your histograms and ntuples only once, typically in the master thread, for example in RunAction::BeginOfRunAction when IsMaster() returns true. The same definitions are then automatically cloned for each worker thread. During the event loop, each worker fills its own copy, without any explicit synchronization in your code.
When the run finishes, Geant4 merges all worker copies into the master copy. The merged master contains the accumulated contents from all threads. Finally, when you call G4AnalysisManager::Write() and G4AnalysisManager::CloseFile() in the master thread at the end of the run, only the merged data are written to disk.
Always call OpenFile(), Write(), and CloseFile() exactly once per run, in the master thread only. Use if (IsMaster()) checks in RunAction to avoid multiple workers trying to write to the same file.
If you try to open a different file in each worker thread, or write from worker threads, you lose the built in merging and risk corrupted or inconsistent output. For a single combined result, keep one output file per run and let the Geant4 analysis manager handle the internal thread separation and merging.
The same principle applies if you split your analysis over several histograms or ntuples. All of them are defined in the master, automatically created in each worker, and then merged back into the master at the end of the run. As long as you do not manually store global static data for analysis, you do not need to write any special multithreading code just to merge the results.
Histogram handling
Histograms are central objects in Geant4 analysis, and they are fully supported in multithreaded runs. From the user perspective, histogram handling in multithreading looks almost identical to the single thread case. The important differences are where you define histograms, and where you open and close the output file.
You usually create histograms in RunAction::BeginOfRunAction. When the run manager is multithreaded, this method is called once in the master and once in every worker. To avoid defining histograms multiple times, you check the master flag and only define them when IsMaster() is true. The worker threads will automatically receive thread local copies that match the master definitions.
During the event processing, you fill histograms in any user action that has access to the analysis manager, for example in EventAction or SteppingAction. In multithreaded mode, each call to FillH1, FillH2, or FillH3 updates only the histogram copy that belongs to the current worker thread. No locking is needed, so there is no performance penalty from using histograms in multithreaded simulations.
At the end of the run, the contents of all per thread histograms are merged into the master copy. Geant4 uses a simple rule: bin contents from each thread are summed into the corresponding bins of the master histogram. Underflow and overflow bins are treated the same way. For beginners, this means that if you define a histogram with $N$ bins, the final merged histogram will look exactly as if you had run a single threaded simulation with all events combined.
Define each histogram and its binning only once in the master thread, and never change histogram definitions after events start. Changing the number of bins or ranges during a run breaks the merging and leads to undefined behavior.
The following table summarizes typical operations with histograms in multithreading and where they should be done:
| Operation | Where it happens | Thread context |
|---|---|---|
| Define histograms | BeginOfRunAction when IsMaster() == true | Master only |
| Open output file | BeginOfRunAction when IsMaster() == true | Master only |
| Fill histograms | EventAction, SteppingAction, etc. | Worker threads only |
| Merge histograms | End of run (automatic) | Internal to Geant4 |
| Write and close file | EndOfRunAction when IsMaster() == true | Master only |
With this pattern, histogram handling remains simple even as you increase the number of threads. You write the same filling code you would use in a single thread, and Geant4 ensures that the final histograms contain the combined statistics from all threads without race conditions or duplicate output.
Views: 9