# christy62/detector-foundation-model architecture

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

- Interactive diagram: https://gitdiagram.com/christy62/detector-foundation-model
- Repository: https://github.com/christy62/detector-foundation-model

## Overview

This repository combines a Geant4 aerogel Cherenkov simulation with a PyTorch model trained to reproduce its photon-hit patterns. The documented workflow simulates pion events, records optical-photon hits with event conditions, prepares tokenized events, and trains a conditional Transformer/MoE generator; README results compare simulated and generated ring and radial observables. Source excerpts show the hit-recording and ML training components, but not how simulation output is converted into the HDF5 input consumed by the dataset, nor the full simulation application wiring.

Main entry points: [`src/DetectorConstruction.cc`](https://github.com/christy62/detector-foundation-model/blob/main/src/DetectorConstruction.cc) (Aerogel detector), [`src/ActionInitialization.cc`](https://github.com/christy62/detector-foundation-model/blob/main/src/ActionInitialization.cc) (Action setup), [`src/EventAction.cc`](https://github.com/christy62/detector-foundation-model/blob/main/src/EventAction.cc) (Event hit record), [`train.py`](https://github.com/christy62/detector-foundation-model/blob/main/train.py) (Training loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sim["Geant4 simulation"]
  node_detector["Aerogel detector"]
  node_physics["Optical physics<br/>[PhysicsList.cc]"]
  node_primary["Pion source"]
  node_actions["Action setup"]
  node_sensitive["Photon capture"]
  node_event["Event hit record<br/>[EventAction.cc]"]
  node_csv["hits.csv"]
end

subgraph group_ml["Model training"]
  node_dataset["Event tokenization<br/>[dataset.py]"]
  node_trainer["Training loop<br/>[train.py]"]
  node_generator["Conditional MoE model<br/>[model.py]"]
end

subgraph group_results["Response analysis"]
  node_comparisons["Response comparisons"]
end

node_operator(("Simulation user"))
node_hdf5["HDF5 event data"]

node_detector -->|"attaches"| node_sensitive
node_sensitive -->|"records hits"| node_event
node_event -->|"appends events"| node_csv
node_actions -->|"sets up"| node_primary
node_actions -->|"sets up"| node_event
node_operator -.->|"runs simulation"| node_detector
node_operator -.->|"runs simulation"| node_physics
node_operator -.->|"runs simulation"| node_actions
node_csv -.->|"converted to"| node_hdf5
node_hdf5 -->|"loads events"| node_dataset
node_trainer -->|"batches events"| node_dataset
node_trainer -->|"trains"| node_generator
node_generator -->|"compared with simulation"| node_comparisons
node_detector -->|"response studied"| node_comparisons

click node_detector "https://github.com/christy62/detector-foundation-model/blob/main/src/DetectorConstruction.cc"
click node_physics "https://github.com/christy62/detector-foundation-model/blob/main/src/PhysicsList.cc"
click node_primary "https://github.com/christy62/detector-foundation-model/blob/main/src/PrimaryGeneratorAction.cc"
click node_actions "https://github.com/christy62/detector-foundation-model/blob/main/src/ActionInitialization.cc"
click node_sensitive "https://github.com/christy62/detector-foundation-model/blob/main/src/PhotonSensitiveDetector.cc"
click node_event "https://github.com/christy62/detector-foundation-model/blob/main/src/EventAction.cc"
click node_dataset "https://github.com/christy62/detector-foundation-model/blob/main/dataset.py"
click node_trainer "https://github.com/christy62/detector-foundation-model/blob/main/train.py"
click node_generator "https://github.com/christy62/detector-foundation-model/blob/main/model.py"
click node_comparisons "https://github.com/christy62/detector-foundation-model/tree/main/plots"

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_detector,node_physics,node_primary,node_actions,node_sensitive,node_event,node_csv,node_operator toneBlue
class node_dataset,node_trainer,node_generator toneAmber
class node_comparisons toneMint
class node_hdf5 toneIndigo
```

## Components

### Geant4 simulation

- [Aerogel detector](https://github.com/christy62/detector-foundation-model/blob/main/src/DetectorConstruction.cc): `src/DetectorConstruction.cc`
- [Optical physics](https://github.com/christy62/detector-foundation-model/blob/main/src/PhysicsList.cc): `src/PhysicsList.cc`
- [Pion source](https://github.com/christy62/detector-foundation-model/blob/main/src/PrimaryGeneratorAction.cc): `src/PrimaryGeneratorAction.cc`
- [Action setup](https://github.com/christy62/detector-foundation-model/blob/main/src/ActionInitialization.cc): `src/ActionInitialization.cc`
- [Photon capture](https://github.com/christy62/detector-foundation-model/blob/main/src/PhotonSensitiveDetector.cc): `src/PhotonSensitiveDetector.cc`
- [Event hit record](https://github.com/christy62/detector-foundation-model/blob/main/src/EventAction.cc): `src/EventAction.cc`
- **hits.csv**

### Model training

- [Event tokenization](https://github.com/christy62/detector-foundation-model/blob/main/dataset.py): `dataset.py`
- [Training loop](https://github.com/christy62/detector-foundation-model/blob/main/train.py): `train.py`
- [Conditional MoE model](https://github.com/christy62/detector-foundation-model/blob/main/model.py): `model.py`

### Response analysis

- [Response comparisons](https://github.com/christy62/detector-foundation-model/tree/main/plots): `plots`

### Other components

- **Simulation user**
- **HDF5 event data**

## Connections

- Aerogel detector → Photon capture: attaches (evidence: `src/DetectorConstruction.cc`)
- Photon capture → Event hit record: records hits (evidence: `src/PhotonSensitiveDetector.cc`)
- Event hit record → hits.csv: appends events (evidence: `src/EventAction.cc`)
- Action setup → Pion source: sets up (evidence: `src/ActionInitialization.cc`)
- Action setup → Event hit record: sets up (evidence: `src/ActionInitialization.cc`)
- Simulation user → Aerogel detector: runs simulation
- Simulation user → Optical physics: runs simulation
- Simulation user → Action setup: runs simulation
- hits.csv → HDF5 event data: converted to
- HDF5 event data → Event tokenization: loads events (evidence: `dataset.py`)
- Training loop → Event tokenization: batches events (evidence: `train.py`)
- Training loop → Conditional MoE model: trains (evidence: `train.py`)
- Conditional MoE model → Response comparisons: compared with simulation (evidence: `README.md`)
- Aerogel detector → Response comparisons: response studied (evidence: `README.md`)
