# acsevillam/mdsim1 architecture

> Architecture diagram of the GitHub repository acsevillam/mdsim1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/acsevillam/mdsim1
- Repository: https://github.com/acsevillam/mdsim1

## Overview

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: [`include/geometry/base/DetectorRegistry.hh`](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/base/DetectorRegistry.hh) (Registry), [`include/MD1ActionInitialization.hh`](https://github.com/acsevillam/mdsim1/blob/main/include/MD1ActionInitialization.hh) (Action init), [`include/MD1DetectorConstruction.hh`](https://github.com/acsevillam/mdsim1/blob/main/include/MD1DetectorConstruction.hh) (Detector build), [`analysis/README.md`](https://github.com/acsevillam/mdsim1/blob/main/analysis/README.md) (Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["MultiDetector1<br/>Geant4 app<br/>[MultiDetector1.cc]"]
  node_control["Control<br/>[MD1Control.hh]"]
  node_actions["Action init<br/>lifecycle wiring"]
  node_run_action["Run action<br/>run output<br/>[MD1RunAction.hh]"]
  node_event_action["Event action<br/>event handling<br/>[MD1EventAction.hh]"]
  node_primary1["PHSP source<br/>primary generator"]
  node_primary2["GPS source<br/>primary generator"]
end

subgraph group_geometry["Geometry"]
  node_det_construction["Detector build<br/>geometry control"]
  node_registry[("Registry")]
  node_beamline["Beamline<br/>treatment head<br/>[ClinacTrueBeam.hh]"]
  node_phantoms["Water phantoms<br/>phantom geometry<br/>[PhantomWaterBox.hh]"]
  node_gdml["GDML<br/>import/export"]
end

subgraph group_detectors_basic["Basic detectors"]
  node_basic_core["Basic core<br/>shared dosimetry core"]
  node_cube["Cube<br/>basic dosimeter"]
  node_cylinder["Cylinder<br/>basic dosimeter"]
  node_sphere["Sphere<br/>basic dosimeter"]
end

subgraph group_detectors_scint["Scintillator detectors"]
  node_scintcube["ScintCube<br/>scintillator module"]
  node_model11["Model11<br/>imported detector"]
end

subgraph group_detectors_bb7["BB7"]
  node_bb7["BB7<br/>detector family"]
end

subgraph group_workflow["Workflow"]
  node_macros["Macros<br/>runtime config<br/>[init.mac]"]
  node_jobs["Jobs<br/>batch workflows<br/>[md1_job_helpers.sh]"]
  node_analysis["Analysis<br/>postprocessing<br/>[README.md]"]
end

node_app -->|"driven by"| node_control
node_app -->|"installs"| node_actions
node_actions -->|"creates"| node_run_action
node_actions -->|"creates"| node_event_action
node_actions -->|"creates"| node_primary1
node_actions -->|"creates"| node_primary2
node_app -->|"builds"| node_det_construction
node_det_construction -->|"delegates to"| node_registry
node_det_construction -->|"adds"| node_beamline
node_det_construction -->|"adds"| node_phantoms
node_registry -->|"hosts"| node_basic_core
node_registry -->|"enables"| node_cube
node_registry -->|"enables"| node_cylinder
node_registry -->|"enables"| node_sphere
node_registry -->|"enables"| node_scintcube
node_registry -->|"enables"| node_model11
node_registry -->|"enables"| node_bb7
node_cube -->|"reuses"| node_basic_core
node_cylinder -->|"reuses"| node_basic_core
node_sphere -->|"reuses"| node_basic_core
node_scintcube -->|"reports to"| node_analysis
node_model11 -->|"imports"| node_gdml
node_bb7 -->|"reports to"| node_analysis
node_macros -->|"configures"| node_control
node_jobs -->|"launches"| node_macros
node_analysis -->|"consumes"| node_run_action
node_primary1 -->|"feeds"| node_beamline
node_primary2 -->|"feeds"| node_beamline
node_run_action -->|"writes"| node_analysis
node_gdml -->|"supports"| node_registry

click node_app "https://github.com/acsevillam/mdsim1/blob/main/MultiDetector1.cc"
click node_control "https://github.com/acsevillam/mdsim1/blob/main/include/MD1Control.hh"
click node_actions "https://github.com/acsevillam/mdsim1/blob/main/include/MD1ActionInitialization.hh"
click node_run_action "https://github.com/acsevillam/mdsim1/blob/main/include/MD1RunAction.hh"
click node_event_action "https://github.com/acsevillam/mdsim1/blob/main/include/MD1EventAction.hh"
click node_primary1 "https://github.com/acsevillam/mdsim1/blob/main/include/MD1PrimaryGeneratorAction1.hh"
click node_primary2 "https://github.com/acsevillam/mdsim1/blob/main/include/MD1PrimaryGeneratorAction2.hh"
click node_det_construction "https://github.com/acsevillam/mdsim1/blob/main/include/MD1DetectorConstruction.hh"
click node_registry "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/base/DetectorRegistry.hh"
click node_beamline "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/beamline/ClinacTrueBeam.hh"
click node_phantoms "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/phantoms/PhantomWaterBox.hh"
click node_basic_core "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/basic/core/BasicDosimeterReadout.hh"
click node_cube "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/basic/cube/CubeDetectorModule.hh"
click node_cylinder "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/basic/cylinder/CylinderDetectorModule.hh"
click node_sphere "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/basic/sphere/SphereDetectorModule.hh"
click node_scintcube "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/scintCube/ScintCubeDetectorModule.hh"
click node_model11 "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/model11/Model11DetectorModule.hh"
click node_bb7 "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/BB7/BB7DetectorModule.hh"
click node_gdml "https://github.com/acsevillam/mdsim1/blob/main/include/geometry/gdml/MD1GeometryExport.hh"
click node_macros "https://github.com/acsevillam/mdsim1/blob/main/mac/init.mac"
click node_jobs "https://github.com/acsevillam/mdsim1/blob/main/jobs/lib/md1_job_helpers.sh"
click node_analysis "https://github.com/acsevillam/mdsim1/blob/main/analysis/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_control,node_actions,node_run_action,node_event_action,node_primary1,node_primary2 toneBlue
class node_det_construction,node_registry,node_beamline,node_phantoms,node_gdml toneAmber
class node_basic_core,node_cube,node_cylinder,node_sphere toneMint
class node_scintcube,node_model11 toneRose
class node_bb7 toneIndigo
class node_macros,node_jobs,node_analysis toneTeal
```

## Components

### Runtime

Executable and Geant4 lifecycle

- [MultiDetector1](https://github.com/acsevillam/mdsim1/blob/main/MultiDetector1.cc): Geant4 app · Main Monte Carlo executable · `MultiDetector1.cc`
- [Control](https://github.com/acsevillam/mdsim1/blob/main/include/MD1Control.hh): run control · Top-level runtime configuration and mode selection · `include/MD1Control.hh`
- [Action init](https://github.com/acsevillam/mdsim1/blob/main/include/MD1ActionInitialization.hh): lifecycle wiring · Registers run, event, and primary actions · `include/MD1ActionInitialization.hh`
- [Run action](https://github.com/acsevillam/mdsim1/blob/main/include/MD1RunAction.hh): run output · Aggregates scorers, uncertainties, and run summaries · `include/MD1RunAction.hh`
- [Event action](https://github.com/acsevillam/mdsim1/blob/main/include/MD1EventAction.hh): event handling · Per-event bookkeeping and simulation state · `include/MD1EventAction.hh`
- [PHSP source](https://github.com/acsevillam/mdsim1/blob/main/include/MD1PrimaryGeneratorAction1.hh): primary generator · IAEA phase-space based source selection · `include/MD1PrimaryGeneratorAction1.hh`
- [GPS source](https://github.com/acsevillam/mdsim1/blob/main/include/MD1PrimaryGeneratorAction2.hh): primary generator · Geant4 general particle source mode · `include/MD1PrimaryGeneratorAction2.hh`

### Geometry

Beamline, phantoms, and detector registry

- [Detector build](https://github.com/acsevillam/mdsim1/blob/main/include/MD1DetectorConstruction.hh): geometry control · Constructs world and delegates detector assembly · `include/MD1DetectorConstruction.hh`
- [Registry](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/base/DetectorRegistry.hh): module registry · Enables, discovers, and builds detector modules · `include/geometry/base/DetectorRegistry.hh`
- [Beamline](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/beamline/ClinacTrueBeam.hh): treatment head · Clinac beamline and collimation geometry · `include/geometry/beamline/ClinacTrueBeam.hh`
- [Water phantoms](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/phantoms/PhantomWaterBox.hh): phantom geometry · Water box and water tube study geometries · `include/geometry/phantoms/PhantomWaterBox.hh`
- [GDML](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/gdml/MD1GeometryExport.hh): import/export · Geometry import, assembly cache, and export support · `include/geometry/gdml/MD1GeometryExport.hh`

### Basic detectors

Shared dosimeter family

- [Basic core](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/basic/core/BasicDosimeterReadout.hh): shared dosimetry core · Common readout and calibration primitives · `include/geometry/detectors/basic/core/BasicDosimeterReadout.hh`
- [Cube](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/basic/cube/CubeDetectorModule.hh): basic dosimeter · Simple cubic detector module · `include/geometry/detectors/basic/cube/CubeDetectorModule.hh`
- [Cylinder](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/basic/cylinder/CylinderDetectorModule.hh): basic dosimeter · Simple cylindrical detector module · `include/geometry/detectors/basic/cylinder/CylinderDetectorModule.hh`
- [Sphere](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/basic/sphere/SphereDetectorModule.hh): basic dosimeter · Simple spherical detector module · `include/geometry/detectors/basic/sphere/SphereDetectorModule.hh`

### Scintillator detectors

Photosensor-based detector modules

- [ScintCube](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/scintCube/ScintCubeDetectorModule.hh): scintillator module · Scintillator cube with photosensor modeling · `include/geometry/detectors/scintCube/ScintCubeDetectorModule.hh`
- [Model11](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/model11/Model11DetectorModule.hh): imported detector · GDML-backed detector module with photosensor readout · `include/geometry/detectors/model11/Model11DetectorModule.hh`

### BB7

Separate detector family

- [BB7](https://github.com/acsevillam/mdsim1/blob/main/include/geometry/detectors/BB7/BB7DetectorModule.hh): detector family · Separate BB7 module with dual/single geometry variants · `include/geometry/detectors/BB7/BB7DetectorModule.hh`

### Workflow

Macros, jobs, and analysis

- [Macros](https://github.com/acsevillam/mdsim1/blob/main/mac/init.mac): runtime config · Canonical macro entry points for studies and tests · `mac/init.mac`
- [Jobs](https://github.com/acsevillam/mdsim1/blob/main/jobs/lib/md1_job_helpers.sh): batch workflows · Shell launchers for repeatable parameter sweeps · `jobs/lib/md1_job_helpers.sh`
- [Analysis](https://github.com/acsevillam/mdsim1/blob/main/analysis/README.md): postprocessing · Notebooks and derived calibration/validation artifacts · `analysis/README.md`

## Connections

- 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
