# sylvathle/flare architecture

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

- Interactive diagram: https://gitdiagram.com/sylvathle/flare
- Repository: https://github.com/sylvathle/flare

## Overview

1. **Overall architecture**
This repo is a pipeline for fluence-to-dose studies of the ICRP145 human phantom, optionally wrapped in an aluminum shell (“FLARE vest”). It has four main layers: geometry export, Geant4 simulation, post-processing of simulation CSVs, and spectrum/dose modeling in Python.

2. **Geant4 simulation core (`G4/`)**
`G4/` is the main runtime component. It builds a Geant4 executable (`sim`) from C++ sources in `src/` and public headers in `include/`. This layer owns the full physics simulation: geometry setup, materials, particle generation, scoring, event/run handling, and output writing.

3. **Geometry and phantom import**
The human phantom is not hardcoded as primitive solids; it is imported from external model data. `TETModelImport`, `TETParameterisation`, and related classes indicate a tetrahedral/mesh-based phantom representation. `geometry.cc` and `shieldmaterial.cc` likely assemble the phantom and optional aluminum shell into the simulation world.

4. **Custom scoring and outputs**
The `HitInfo`, `fluxInfo`, `TotalFlux`, `ISPSEnergyDeposit`, and `TETPSEnergyDeposit` classes define the experiment’s observables. The simulation records organ-level absorbed dose and dose equivalent, plus flux/energy-deposit information, and writes per-run CSV results into a structured results directory.

5. **Simulation control and macro interface**
`action.cc`, `event.cc`, `run.cc`, and `generator.cc` are the Geant4 action stack and primary generator control. The repo adds custom macro commands such as phantom selection, shell thickness, source radius, particle type, and energy range, so runs are configured from macro files rather than recompiling.

6. **Macro generation (`G4/macros/`)**
`genRunMacro.py` generates Geant4 macros for batch studies across scenario, thickness, particle type, and energy bounds. This is the orchestration layer that turns a parameter sweep into runnable `run_*.mac` files.

7. **Blender-to-Geant4 export (`ICRP145_BlenderToG4/`)**
This Python code is a separate preprocessing pipeline intended to run inside Blender. It exports the ICRP145 + vest model into the poly/scene format consumed by the Geant4 importer. Architecturally, this is the geometry-authoring boundary: Blender creates the mesh scene, Geant4 consumes it.

8. **Simulation data model and post-processing (`analysis/`)**
The analysis folder is the CSV aggregation layer. It takes the raw Geant4 outputs, combines them with organ metadata, and produces a consolidated dose table. The README indicates a `dose_data.csv` artifact with scenario, shell thickness, energy bin, organ identity, organ group, weighting factor, mass, simulated counts, absorbed dose, and dose equivalent plus uncertainties.

9. **Spectrum fitting and SEP source models (`SEP_spectra/`)**
This package extracts and fits solar energetic particle spectra from multiple literature/source models. Files such as `fit_goes.py`, `fit_sepem.py`, `fit_tylka_hu.py`, and `physics.py` show that it is a standalone scientific modeling layer used to parameterize input particle spectra for downstream dose calculations.

10. **Dose synthesis from spectra (`pyflare/`)**
`pyflare/` turns particle spectra into dose quantities using dose information and physics models. The modules suggest separate support for solar energetic particles, galactic cosmic rays, banded spectra, sunspot-driven inputs, and coefficient aggregation. Conceptually, it sits between spectral models and final dose estimates.

11. **End-to-end data flow**
The main flow is: phantom geometry is exported from Blender, imported into Geant4, simulated with a macro-defined particle beam, results are written as CSVs, then analysis consolidates organ/energy-bin dose tables. In parallel, `SEP_spectra` and `pyflare` provide the spectrum-to-dose modeling side used for broader fluence/dose studies.

12. **Key external dependencies and boundaries**
The core runtime depends on Geant4 and on external phantom data supplied via `PHANTOM_PATH` or the exported `scene/` folder. The repo is therefore split cleanly across three boundaries: geometry authoring in Blender, Monte Carlo transport in Geant4, and scientific post-processing/model fitting in Python.

Main entry points: [`pyflare/main.py`](https://github.com/sylvathle/flare/blob/main/pyflare/main.py) (Dose engine), [`G4/src/run.cc`](https://github.com/sylvathle/flare/blob/main/G4/src/run.cc) (Run output), [`G4/src/geometry.cc`](https://github.com/sylvathle/flare/blob/main/G4/src/geometry.cc) (Geometry setup), [`G4/include/HitInfo.hh`](https://github.com/sylvathle/flare/blob/main/G4/include/HitInfo.hh) (Scoring hits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Geometry export"]
  node_n1["Blender export<br/>python export<br/>[Exportation.py]"]
  node_n2["Scene helpers<br/>blender utils<br/>[functions.py]"]
  node_n3["Organ model<br/>mesh schema<br/>[organ.py]"]
end

subgraph group_g2["Geant4 runtime"]
  node_n4(("Geant4 app<br/>simulation exe<br/>[sim.cc]"))
  node_n5["Geometry setup<br/>world builder<br/>[geometry.cc]"]
  node_n6["Import mesh<br/>phantom import<br/>[TETModelImport.cc]"]
  node_n7["Parameterisation<br/>geometry mapping"]
  node_n8["Shield material<br/>materials<br/>[shieldmaterial.cc]"]
  node_n9["Primary generator<br/>beam source<br/>[generator.cc]"]
  node_n10["Action stack<br/>run control<br/>[action.cc]"]
  node_n11["Scoring hits<br/>dosimetry scoring<br/>[HitInfo.hh]"]
  node_n12["Energy deposit<br/>scorer"]
  node_n13["Flux tally<br/>scorer<br/>[TotalFlux.cc]"]
  node_n14["Run output<br/>csv writer<br/>[run.cc]"]
  node_n15["Macro generator<br/>batch config<br/>[genRunMacro.py]"]
end

subgraph group_g3["Post-processing"]
  node_n16["CSV aggregation<br/>postprocess<br/>[toCSV.py]"]
end

subgraph group_g4["Spectrum models"]
  node_n17["SEP fits<br/>spectrum fitting<br/>[fit_tylka_hu.py]"]
  node_n18["Physics models<br/>spectra physics<br/>[physics.py]"]
  node_n19["SEP resume<br/>source catalog<br/>[resume_sep.py]"]
end

subgraph group_g5["Dose synthesis"]
  node_n20["Dose engine<br/>dose model<br/>[main.py]"]
  node_n21["Dose info<br/>coefficients<br/>[DoseInfo.py]"]
  node_n22["Band model<br/>spectrum bins<br/>[band.py]"]
  node_n23["GCR model<br/>cosmic rays<br/>[gcr.py]"]
  node_n24["SEP model<br/>solar particles<br/>[sepem.py]"]
end

node_n1 -->|"exports mesh for"| node_n6
node_n2 -->|"supports"| node_n1
node_n3 -->|"organ layout"| node_n1
node_n4 -->|"builds"| node_n5
node_n5 -->|"imports"| node_n6
node_n6 -->|"uses"| node_n7
node_n5 -->|"adds"| node_n8
node_n9 -->|"drives"| node_n10
node_n10 -->|"collects"| node_n11
node_n11 -->|"records"| node_n12
node_n11 -->|"records"| node_n13
node_n12 -->|"writes"| node_n14
node_n13 -->|"writes"| node_n14
node_n15 -->|"configures"| node_n9
node_n14 -->|"aggregated by"| node_n16
node_n17 -->|"uses"| node_n18
node_n19 -->|"summarizes"| node_n17
node_n18 -->|"feeds"| node_n20
node_n21 -->|"provides"| node_n20
node_n22 -->|"parameterizes"| node_n20
node_n23 -->|"parameterizes"| node_n20
node_n24 -->|"parameterizes"| node_n20
node_n16 -->|"inputs"| node_n20
node_n4 -->|"produces"| node_n14

click node_n1 "https://github.com/sylvathle/flare/blob/main/ICRP145_BlenderToG4/Exportation.py"
click node_n2 "https://github.com/sylvathle/flare/blob/main/ICRP145_BlenderToG4/functions.py"
click node_n3 "https://github.com/sylvathle/flare/blob/main/ICRP145_BlenderToG4/organ.py"
click node_n4 "https://github.com/sylvathle/flare/blob/main/G4/sim.cc"
click node_n5 "https://github.com/sylvathle/flare/blob/main/G4/src/geometry.cc"
click node_n6 "https://github.com/sylvathle/flare/blob/main/G4/src/TETModelImport.cc"
click node_n7 "https://github.com/sylvathle/flare/blob/main/G4/src/TETParameterisation.cc"
click node_n8 "https://github.com/sylvathle/flare/blob/main/G4/src/shieldmaterial.cc"
click node_n9 "https://github.com/sylvathle/flare/blob/main/G4/src/generator.cc"
click node_n10 "https://github.com/sylvathle/flare/blob/main/G4/src/action.cc"
click node_n11 "https://github.com/sylvathle/flare/blob/main/G4/include/HitInfo.hh"
click node_n12 "https://github.com/sylvathle/flare/blob/main/G4/src/TETPSEnergyDeposit.cc"
click node_n13 "https://github.com/sylvathle/flare/blob/main/G4/src/TotalFlux.cc"
click node_n14 "https://github.com/sylvathle/flare/blob/main/G4/src/run.cc"
click node_n15 "https://github.com/sylvathle/flare/blob/main/G4/macros/genRunMacro.py"
click node_n16 "https://github.com/sylvathle/flare/blob/main/G4/analysis/toCSV.py"
click node_n17 "https://github.com/sylvathle/flare/blob/main/SEP_spectra/fit_tylka_hu.py"
click node_n18 "https://github.com/sylvathle/flare/blob/main/SEP_spectra/physics.py"
click node_n19 "https://github.com/sylvathle/flare/blob/main/SEP_spectra/resume_sep.py"
click node_n20 "https://github.com/sylvathle/flare/blob/main/pyflare/main.py"
click node_n21 "https://github.com/sylvathle/flare/blob/main/pyflare/DoseInfo.py"
click node_n22 "https://github.com/sylvathle/flare/blob/main/pyflare/band.py"
click node_n23 "https://github.com/sylvathle/flare/blob/main/pyflare/gcr.py"
click node_n24 "https://github.com/sylvathle/flare/blob/main/pyflare/sepem.py"

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_n1,node_n2,node_n3 toneBlue
class node_n4,node_n5,node_n6,node_n7,node_n8,node_n9,node_n10,node_n11,node_n12,node_n13,node_n14,node_n15 toneAmber
class node_n16 toneMint
class node_n17,node_n18,node_n19 toneRose
class node_n20,node_n21,node_n22,node_n23,node_n24 toneIndigo
```

## Components

### Geometry export

Blender-side authoring and export of the phantom mesh scene for Geant4 import.

- [Blender export](https://github.com/sylvathle/flare/blob/main/ICRP145_BlenderToG4/Exportation.py): python export · Exports the ICRP145 + vest mesh scene into the format consumed by Geant4. · `ICRP145_BlenderToG4/Exportation.py`
- [Scene helpers](https://github.com/sylvathle/flare/blob/main/ICRP145_BlenderToG4/functions.py): blender utils · Support functions and object/organ naming used during export. · `ICRP145_BlenderToG4/functions.py`
- [Organ model](https://github.com/sylvathle/flare/blob/main/ICRP145_BlenderToG4/organ.py): mesh schema · Organ metadata and scene organization for the exported phantom. · `ICRP145_BlenderToG4/organ.py`

### Geant4 runtime

Main Monte Carlo simulation executable, physics setup, and custom scoring.

- [Geant4 app](https://github.com/sylvathle/flare/blob/main/G4/sim.cc): simulation exe · Entry point that builds and runs the Geant4 transport executable. · `G4/sim.cc`
- [Geometry setup](https://github.com/sylvathle/flare/blob/main/G4/src/geometry.cc): world builder · Constructs the simulation world, phantom placement, and shell geometry. · `G4/src/geometry.cc`
- [Import mesh](https://github.com/sylvathle/flare/blob/main/G4/src/TETModelImport.cc): phantom import · Loads the tetrahedral phantom and maps it into Geant4 geometry. · `G4/src/TETModelImport.cc`
- [Parameterisation](https://github.com/sylvathle/flare/blob/main/G4/src/TETParameterisation.cc): geometry mapping · Defines tetrahedral parameterisation and mesh-to-volume representation. · `G4/src/TETParameterisation.cc`
- [Shield material](https://github.com/sylvathle/flare/blob/main/G4/src/shieldmaterial.cc): materials · Builds the optional aluminum shell and related material definitions. · `G4/src/shieldmaterial.cc`
- [Primary generator](https://github.com/sylvathle/flare/blob/main/G4/src/generator.cc): beam source · Configures particle type, energy, radius, and source distribution. · `G4/src/generator.cc`
- [Action stack](https://github.com/sylvathle/flare/blob/main/G4/src/action.cc): run control · Coordinates Geant4 actions for initialization, event handling, and run lifecycle. · `G4/src/action.cc`
- [Scoring hits](https://github.com/sylvathle/flare/blob/main/G4/include/HitInfo.hh): dosimetry scoring · Captures flux and energy-deposit observables for the simulation. · `G4/include/HitInfo.hh`
- [Energy deposit](https://github.com/sylvathle/flare/blob/main/G4/src/TETPSEnergyDeposit.cc): scorer · Organ and tissue scoring implementations for absorbed dose observables. · `G4/src/TETPSEnergyDeposit.cc`
- [Flux tally](https://github.com/sylvathle/flare/blob/main/G4/src/TotalFlux.cc): scorer · Flux and total-flux scoring components used by the transport run. · `G4/src/TotalFlux.cc`
- [Run output](https://github.com/sylvathle/flare/blob/main/G4/src/run.cc): csv writer · Writes per-run results and organizes simulation output for downstream analysis. · `G4/src/run.cc`
- [Macro generator](https://github.com/sylvathle/flare/blob/main/G4/macros/genRunMacro.py): batch config · Generates Geant4 macro files for parameter sweeps over scenario and beam settings. · `G4/macros/genRunMacro.py`

### Post-processing

Aggregation of raw Geant4 CSV outputs into organ- and energy-binned dose tables.

- [CSV aggregation](https://github.com/sylvathle/flare/blob/main/G4/analysis/toCSV.py): postprocess · Converts raw simulation outputs into consolidated dose tables. · `G4/analysis/toCSV.py`

### Spectrum models

Solar energetic particle spectrum fitting and source-model parameterization.

- [SEP fits](https://github.com/sylvathle/flare/blob/main/SEP_spectra/fit_tylka_hu.py): spectrum fitting · Fits solar energetic particle spectra from GOES, SEPEM, and Tylka-Hu sources. · `SEP_spectra/fit_tylka_hu.py`
- [Physics models](https://github.com/sylvathle/flare/blob/main/SEP_spectra/physics.py): spectra physics · Shared spectral and physics routines used by the SEP fitting modules. · `SEP_spectra/physics.py`
- [SEP resume](https://github.com/sylvathle/flare/blob/main/SEP_spectra/resume_sep.py): source catalog · Compiles and summarizes SEP model inputs and fit results. · `SEP_spectra/resume_sep.py`

### Dose synthesis

Python layer that turns spectra and dose coefficients into final dose estimates.

- [Dose engine](https://github.com/sylvathle/flare/blob/main/pyflare/main.py): dose model · Combines spectra with dose information to estimate dose quantities. · `pyflare/main.py`
- [Dose info](https://github.com/sylvathle/flare/blob/main/pyflare/DoseInfo.py): coefficients · Holds dose tables, organ data, and dose conversion metadata. · `pyflare/DoseInfo.py`
- [Band model](https://github.com/sylvathle/flare/blob/main/pyflare/band.py): spectrum bins · Represents banded spectral inputs and aggregation over energy intervals. · `pyflare/band.py`
- [GCR model](https://github.com/sylvathle/flare/blob/main/pyflare/gcr.py): cosmic rays · Galactic cosmic ray dose pathway and related spectral handling. · `pyflare/gcr.py`
- [SEP model](https://github.com/sylvathle/flare/blob/main/pyflare/sepem.py): solar particles · Solar energetic particle dose pathway and source-specific processing. · `pyflare/sepem.py`

## Connections

- Blender export → Import mesh: exports mesh for · Blender scene export produces geometry consumed by the Geant4 phantom importer.
- Scene helpers → Blender export: supports · Helper routines assist the export pipeline.
- Organ model → Blender export: organ layout · Organ definitions structure the exported phantom scene.
- Geant4 app → Geometry setup: builds · The executable assembles simulation geometry before transport begins.
- Geometry setup → Import mesh: imports · Geometry setup pulls in the tetrahedral phantom model.
- Import mesh → Parameterisation: uses · Imported tetrahedral geometry is parameterized for Geant4 volumes.
- Geometry setup → Shield material: adds · The world builder attaches the optional shield shell and materials.
- Primary generator → Action stack: drives · Primary particle generation is controlled through the Geant4 action stack.
- Action stack → Scoring hits: collects · Actions feed hit and scoring objects during the run.
- Scoring hits → Energy deposit: records · Hit information is accumulated into dose scorers.
- Scoring hits → Flux tally: records · Hit information is also accumulated into flux tallies.
- Energy deposit → Run output: writes · Scored dose is emitted as structured per-run output.
- Flux tally → Run output: writes · Flux results are written alongside dose outputs.
- Macro generator → Primary generator: configures · Generated macros parameterize the particle source and sweep settings.
- Run output → CSV aggregation: aggregated by · Raw CSV outputs are consolidated into analysis tables.
- SEP fits → Physics models: uses · Spectrum fitting relies on shared spectral physics utilities.
- SEP resume → SEP fits: summarizes · Resume scripts collect and summarize fitted SEP models.
- Physics models → Dose engine: feeds · Spectrum physics supports the dose synthesis engine.
- Dose info → Dose engine: provides · Dose tables and organ metadata are consumed by the synthesis layer.
- Band model → Dose engine: parameterizes · Banded spectra are one input form for dose calculations.
- GCR model → Dose engine: parameterizes · GCR source handling contributes to final dose estimates.
- SEP model → Dose engine: parameterizes · SEP source handling contributes to final dose estimates.
- CSV aggregation → Dose engine: inputs · Consolidated simulation dose tables inform downstream dose synthesis.
- Geant4 app → Run output: produces · The simulation runtime produces run-level output artifacts.
