How acsevillam/mdsim1 works
1. What this repository is
- MultiDetector1 is a Geant4 Monte Carlo application for radiotherapy detector studies.
- It simulates a linac beamline, a water phantom, and several detector families, then converts energy deposition into physical readouts and calibrated dosimetry outputs.
2. Top-level runtime shape
- The executable is MultiDetector1, built from CMake and linked against Geant4.
- Runtime is driven primarily by Geant4 macro files under mac/ and input/, not by a server or UI application.
- The app can run interactively or in batch; batch mode is the main path for sweeps and reproducible studies.
3. Core orchestration layer
- MD1Control, MD1ActionInitialization, MD1RunAction, and MD1EventAction define the Geant4 application lifecycle.
- MD1DetectorConstruction builds the world and delegates actual detector/phantom assembly to registered modules.
- Primary generation is split between MD1PrimaryGeneratorAction1 for IAEA phase-space sources and MD1PrimaryGeneratorAction2 for GPS sources.
4. Geometry and detector registry boundary
- The architectural center is geometry/base/DetectorRegistry.
- The registry knows which detector modules exist, which ones are enabled, and how to construct them into the current geometry.
- This gives the project a plug-in style boundary: detector-specific code stays in its own module, while the global app only talks to the registry.
5. Three geometry domains
- geometry/beamline/ models the treatment head and collimation system, especially ClinacTrueBeam and MLC80.
- geometry/phantoms/ contains water phantom variants: WaterBox and WaterTube.
- geometry/detectors/ contains the actual detector families, each with its own geometry, readout, calibration, and messenger code.
6. Detector module pattern
- Each detector is organized as a self-contained module with:
- geometry
- messenger commands
- sensitive detector
- hit and digit types
- digitizer
- calibration
- This pattern appears in cube, cylinder, sphere, scintCube, model11, and BB7.
- The “basic” detectors share a common core in geometry/detectors/basic/core/, which reduces duplication for simple dosimeters.
7. Two detector families with different readout philosophies
- cube, cylinder, and sphere are geometrically simple dosimeters. They share calibration/readout logic and differ mainly in shape and table data.
- scintCube and model11 are scintillator-based pipelines with photosensor modeling.
- BB7 is its own detector family with a separate readout/calibration split, but still follows the same module boundary.
8. Data flow from event to result
- Geant4 tracks particles through the beamline, phantom, and detector geometry.
- Sensitive detectors collect hits, digitizers convert them into detector-specific digits, and calibration classes convert physical readout into dose estimates.
- MD1RunAction also manages Geant4 scorers and writes mesh-based analysis outputs under analysis/.
- The repository clearly separates raw simulation observables from calibrated dosimetric quantities.
9. Beam and source subsystem
- The beamline consumes either IAEA phase-space files from beam/ or GPS-defined sources.
- MD1PhspSourceConfig and G4IAEAphspReader/Writer handle phase-space configuration and file IO.
- In MT runs, each worker has its own lazy-created reader, and event-to-source selection is deterministic by event ID.
- This means source selection is stable across runs while worker file consumption is partitioned.
10. Calibration and uncertainty model
- Calibration tables for some detectors are stored as .dat files near the implementation, especially for the basic shapes.
- The runtime distinguishes Monte Carlo statistical error from MU scaling error and detector calibration error.
- This separation matters architecturally because report generation combines uncertainties in RunAction, rather than inside detector hits or digits.
11. GDML import/export subsystem
- The project supports GDML-based geometry import and export in geometry/gdml/.
- model11 is the main consumer of imported GDML, and the repo includes GDML fixtures and expected outputs for CI.
- There is also a geometry export path, which makes this repo not just a simulator but also a geometry conversion/inspection tool.
12. Macros, jobs, and reproducibility
- input/ contains canonical macros and templates for detector studies, dosimetry, and benchmark cases.
- jobs/ wraps those macros into repeatable batch launchers for parameter sweeps and replication studies.
- The architecture here is workflow-oriented: macros configure the simulation, jobs orchestrate many runs, and analysis/ stores postprocessing artifacts.
13. Validation and test boundary
- cmake/tests/ and mac/tests/ form a regression suite for geometry lifecycle, PHSP handling, detector signals, and GDML import behavior.
- Tests are important because the code supports dynamic geometry changes in Idle, PHSP source selection, and split-at-interface behavior.
- The tests protect the contract between macro commands, detector modules, and runtime state transitions.
14. External and file-based dependencies that affect the architecture
- Geant4 is the primary runtime framework and event engine.
- ROOT is used through the project’s build/tooling and is relevant to analysis and data handling.
- Large runtime inputs are file-based: IAEA phase-space data, GDML detector models, and calibration tables.
- The system is therefore a simulation pipeline with significant dependence on external data assets rather than network services.
15. How to draw the architecture diagram
- Put MultiDetector1 at the center, with three major inbound configuration paths: macros/jobs, phase-space or GPS sources, and GDML/imported detector models.
- Show MD1DetectorConstruction and DetectorRegistry as the geometry control plane.
- Show separate detector module boxes for cube/cylinder/sphere, scintCube, model11, and BB7, each feeding hit/digit/calibration outputs.
- Show RunAction writing scorer meshes to analysis/ and detector summaries to run outputs.
- Show jobs/ and analysis/ as workflow/postprocessing layers around the simulation core, not inside it.
Main entry points: DetectorRegistry.hh Registry · MD1ActionInitialization.hh Action init · MD1DetectorConstruction.hh Detector build · README.md Analysis
Components 22
Runtime
Executable and Geant4 lifecycle
- MultiDetector1 · Main Monte Carlo executable
MultiDetector1.cc - Control · Top-level runtime configuration and mode selection
include/MD1Control.hh - Action init · Registers run, event, and primary actions
include/MD1ActionInitialization.hh - Run action · Aggregates scorers, uncertainties, and run summaries
include/MD1RunAction.hh - Event action · Per-event bookkeeping and simulation state
include/MD1EventAction.hh - PHSP source · IAEA phase-space based source selection
include/MD1PrimaryGeneratorAction1.hh - GPS source · Geant4 general particle source mode
include/MD1PrimaryGeneratorAction2.hh
Geometry
Beamline, phantoms, and detector registry
- Detector build · Constructs world and delegates detector assembly
include/MD1DetectorConstruction.hh - Registry · Enables, discovers, and builds detector modules
include/geometry/base/DetectorRegistry.hh - Beamline · Clinac beamline and collimation geometry
include/geometry/beamline/ClinacTrueBeam.hh - Water phantoms · Water box and water tube study geometries
include/geometry/phantoms/PhantomWaterBox.hh - GDML · Geometry import, assembly cache, and export support
include/geometry/gdml/MD1GeometryExport.hh
Basic detectors
Shared dosimeter family
- Basic core · Common readout and calibration primitives
include/geometry/detectors/basic/core/BasicDosimeterReadout.hh - Cube · Simple cubic detector module
include/geometry/detectors/basic/cube/CubeDetectorModule.hh - Cylinder · Simple cylindrical detector module
include/geometry/detectors/basic/cylinder/CylinderDetectorModule.hh - Sphere · Simple spherical detector module
include/geometry/detectors/basic/sphere/SphereDetectorModule.hh
Scintillator detectors
Photosensor-based detector modules
BB7
Separate detector family
- BB7 · Separate BB7 module with dual/single geometry variants
include/geometry/detectors/BB7/BB7DetectorModule.hh
Connections 30
- MultiDetector1 → Control: driven by · Executable delegates mode and runtime setup to control layer
- MultiDetector1 → Action init: installs · Application wires Geant4 action stack
- Action init → Run action: creates · Registers run-level accumulation and output
- Action init → Event action: creates · Registers event bookkeeping
- Action init → PHSP source: creates · Registers phase-space primary generator
- Action init → GPS source: creates · Registers GPS primary generator
- MultiDetector1 → Detector build: builds · Geometry construction is part of application initialization
- Detector build → Registry: delegates to · Detector assembly is controlled through the registry
- Detector build → Beamline: adds · World includes treatment head and collimation geometry
- Detector build → Water phantoms: adds · World includes water phantom variants
- Registry → Basic core: hosts · Shared dosimetry primitives reused by basic detectors
- Registry → Cube: enables · Module is selectable at runtime
- Registry → Cylinder: enables · Module is selectable at runtime
- Registry → Sphere: enables · Module is selectable at runtime
- Registry → ScintCube: enables · Module is selectable at runtime
- Registry → Model11: enables · Module is selectable at runtime
- Registry → BB7: enables · Module is selectable at runtime
- Cube → Basic core: reuses · Shares readout and calibration foundation
- Cylinder → Basic core: reuses · Shares readout and calibration foundation
- Sphere → Basic core: reuses · Shares readout and calibration foundation
- ScintCube → Analysis: reports to · Calibration and validation outputs are postprocessed here
- Model11 → GDML: imports · Primary consumer of imported GDML detector geometry
- BB7 → Analysis: reports to · Calibration studies and readout outputs are analyzed here
- Macros → Control: configures · Macros drive interactive and batch runtime behavior
- Jobs → Macros: launches · Batch scripts wrap canonical macros for sweeps
- Analysis → Run action: consumes · Uses run outputs and scorer summaries for notebooks
- PHSP source → Beamline: feeds · Phase-space or source particles enter simulation geometry
- GPS source → Beamline: feeds · GPS particles enter simulation geometry
- Run action → Analysis: writes · Stores scorer meshes and run summaries for later study
- GDML → Registry: supports · Imported/exported detector geometry integrates through registry