# luozf14/mdmsim architecture

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

- Interactive diagram: https://gitdiagram.com/luozf14/mdmsim
- Repository: https://github.com/luozf14/mdmsim

## Overview

MdmSim is a Geant4 ion-transport simulation: configuration and field maps initialize the detector and physics, events generate a beam and optionally react in a virtual target, then transport through the MDM fields to detector scoring and ROOT output. The README documents the detector stages, response models, and output branches; some wiring is inferred only where the supplied excerpts and explicit documentation support it.

Main entry points: [`src/EventAction.cc`](https://github.com/luozf14/mdmsim/blob/main/src/EventAction.cc) (Event aggregation), [`MdmSim.cc`](https://github.com/luozf14/mdmsim/blob/main/MdmSim.cc) (MdmSim entry point), [`src/DetectorConstruction.cc`](https://github.com/luozf14/mdmsim/blob/main/src/DetectorConstruction.cc) (Spectrometer geometry), [`src/ActionInitialization.cc`](https://github.com/luozf14/mdmsim/blob/main/src/ActionInitialization.cc) (Action initialization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Run setup"]
  node_config["Run configuration<br/>[config.json]"]
  node_main["MdmSim entry point<br/>[MdmSim.cc]"]
  node_actions["Action initialization"]
end

subgraph group_physics["Reaction and transport"]
  node_geometry["Spectrometer geometry"]
  node_primary["Beam generator"]
  node_reactionphysics["Reaction registration<br/>[ReactionPhysics.cc]"]
  node_reaction["Two-body reaction<br/>[ReactionProcess.cc]"]
  node_fieldwrapper["Geant4 field integration"]
  node_fieldmap["Map reader and interpolation<br/>[MdmFieldMap.cpp]"]
  node_fieldfiles["Magnet field maps"]
end

subgraph group_detectors["Detector scoring"]
  node_silicon["Silicon scoring<br/>[SiDetectorSD.cc]"]
  node_ppac["PPAC scoring<br/>[PpacSD.cc]"]
  node_tracking["Tracking-plane scoring<br/>[TrackingPlaneSD.cc]"]
end

subgraph group_results["Event results"]
  node_event["Event aggregation<br/>[EventAction.cc]"]
  node_raytrace["Legacy RAYTRACE<br/>[MdmTrace.cc]"]
  node_analysis["ROOT analysis<br/>[Analysis.cc]"]
  node_rootfile[("Simulation ROOT file")]
end

node_operator(("Simulation operator"))
node_geantrun["Geant4 run manager"]

node_operator -->|"starts run"| node_main
node_config -->|"configures"| node_main
node_main -->|"sets up geometry"| node_geometry
node_main -->|"installs actions"| node_actions
node_main -->|"installs physics"| node_reactionphysics
node_main -->|"starts run"| node_geantrun
node_actions -->|"registers"| node_primary
node_actions -->|"registers"| node_event
node_reactionphysics -->|"registers process"| node_reaction
node_primary -->|"generates ions"| node_geantrun
node_geantrun -->|"dispatches process"| node_reaction
node_geometry -->|"attaches fields"| node_fieldwrapper
node_fieldwrapper -->|"loads and samples"| node_fieldmap
node_fieldfiles -->|"map data"| node_fieldmap
node_geometry -->|"attaches scorer"| node_silicon
node_geometry -->|"attaches scorer"| node_ppac
node_geometry -->|"attaches scorer"| node_tracking
node_geantrun -->|"dispatches events"| node_event
node_event -->|"reads hit collections"| node_silicon
node_event -->|"reads hit collections"| node_ppac
node_event -->|"reads hit collections"| node_tracking
node_event -->|"traces slit hits"| node_raytrace
node_event -->|"sets event data"| node_analysis
node_analysis -->|"writes trees"| node_rootfile

click node_config "https://github.com/luozf14/mdmsim/blob/main/config/config.json"
click node_main "https://github.com/luozf14/mdmsim/blob/main/MdmSim.cc"
click node_actions "https://github.com/luozf14/mdmsim/blob/main/src/ActionInitialization.cc"
click node_geometry "https://github.com/luozf14/mdmsim/blob/main/src/DetectorConstruction.cc"
click node_primary "https://github.com/luozf14/mdmsim/blob/main/src/PrimaryGeneratorAction.cc"
click node_reactionphysics "https://github.com/luozf14/mdmsim/blob/main/src/ReactionPhysics.cc"
click node_reaction "https://github.com/luozf14/mdmsim/blob/main/src/ReactionProcess.cc"
click node_fieldwrapper "https://github.com/luozf14/mdmsim/blob/main/src/MdmFieldMapMagneticField.cc"
click node_fieldmap "https://github.com/luozf14/mdmsim/blob/main/src/MdmFieldMap.cpp"
click node_silicon "https://github.com/luozf14/mdmsim/blob/main/src/SiDetectorSD.cc"
click node_ppac "https://github.com/luozf14/mdmsim/blob/main/src/PpacSD.cc"
click node_tracking "https://github.com/luozf14/mdmsim/blob/main/src/TrackingPlaneSD.cc"
click node_event "https://github.com/luozf14/mdmsim/blob/main/src/EventAction.cc"
click node_raytrace "https://github.com/luozf14/mdmsim/blob/main/src/MdmTrace.cc"
click node_analysis "https://github.com/luozf14/mdmsim/blob/main/src/Analysis.cc"

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_config,node_main,node_actions toneBlue
class node_geometry,node_primary,node_reactionphysics,node_reaction,node_fieldwrapper,node_fieldmap,node_fieldfiles toneAmber
class node_silicon,node_ppac,node_tracking toneMint
class node_event,node_raytrace,node_analysis,node_rootfile toneRose
class node_operator,node_geantrun toneIndigo
```

## Components

### Run setup

- [Run configuration](https://github.com/luozf14/mdmsim/blob/main/config/config.json): `config/config.json`
- [MdmSim entry point](https://github.com/luozf14/mdmsim/blob/main/MdmSim.cc): `MdmSim.cc`
- [Action initialization](https://github.com/luozf14/mdmsim/blob/main/src/ActionInitialization.cc): `src/ActionInitialization.cc`

### Reaction and transport

- [Spectrometer geometry](https://github.com/luozf14/mdmsim/blob/main/src/DetectorConstruction.cc): `src/DetectorConstruction.cc`
- [Beam generator](https://github.com/luozf14/mdmsim/blob/main/src/PrimaryGeneratorAction.cc): `src/PrimaryGeneratorAction.cc`
- [Reaction registration](https://github.com/luozf14/mdmsim/blob/main/src/ReactionPhysics.cc): `src/ReactionPhysics.cc`
- [Two-body reaction](https://github.com/luozf14/mdmsim/blob/main/src/ReactionProcess.cc): `src/ReactionProcess.cc`
- [Geant4 field integration](https://github.com/luozf14/mdmsim/blob/main/src/MdmFieldMapMagneticField.cc): `src/MdmFieldMapMagneticField.cc`
- [Map reader and interpolation](https://github.com/luozf14/mdmsim/blob/main/src/MdmFieldMap.cpp): `src/MdmFieldMap.cpp`
- **Magnet field maps**

### Detector scoring

- [Silicon scoring](https://github.com/luozf14/mdmsim/blob/main/src/SiDetectorSD.cc): `src/SiDetectorSD.cc`
- [PPAC scoring](https://github.com/luozf14/mdmsim/blob/main/src/PpacSD.cc): `src/PpacSD.cc`
- [Tracking-plane scoring](https://github.com/luozf14/mdmsim/blob/main/src/TrackingPlaneSD.cc): `src/TrackingPlaneSD.cc`

### Event results

- [Event aggregation](https://github.com/luozf14/mdmsim/blob/main/src/EventAction.cc): `src/EventAction.cc`
- [Legacy RAYTRACE](https://github.com/luozf14/mdmsim/blob/main/src/MdmTrace.cc): `src/MdmTrace.cc`
- [ROOT analysis](https://github.com/luozf14/mdmsim/blob/main/src/Analysis.cc): `src/Analysis.cc`
- **Simulation ROOT file**

### Other components

- **Simulation operator**
- **Geant4 run manager**

## Connections

- Simulation operator → MdmSim entry point: starts run
- Run configuration → MdmSim entry point: configures
- MdmSim entry point → Spectrometer geometry: sets up geometry
- MdmSim entry point → Action initialization: installs actions
- MdmSim entry point → Reaction registration: installs physics
- MdmSim entry point → Geant4 run manager: starts run
- Action initialization → Beam generator: registers
- Action initialization → Event aggregation: registers
- Reaction registration → Two-body reaction: registers process
- Beam generator → Geant4 run manager: generates ions
- Geant4 run manager → Two-body reaction: dispatches process
- Spectrometer geometry → Geant4 field integration: attaches fields
- Geant4 field integration → Map reader and interpolation: loads and samples
- Magnet field maps → Map reader and interpolation: map data
- Spectrometer geometry → Silicon scoring: attaches scorer
- Spectrometer geometry → PPAC scoring: attaches scorer
- Spectrometer geometry → Tracking-plane scoring: attaches scorer
- Geant4 run manager → Event aggregation: dispatches events
- Event aggregation → Silicon scoring: reads hit collections
- Event aggregation → PPAC scoring: reads hit collections
- Event aggregation → Tracking-plane scoring: reads hit collections
- Event aggregation → Legacy RAYTRACE: traces slit hits
- Event aggregation → ROOT analysis: sets event data
- ROOT analysis → Simulation ROOT file: writes trees