How sylvathle/flare works
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: main.py Dose engine · run.cc Run output · geometry.cc Geometry setup · HitInfo.hh Scoring hits
Components 24
Geometry export
Blender-side authoring and export of the phantom mesh scene for Geant4 import.
- Blender export · Exports the ICRP145 + vest mesh scene into the format consumed by Geant4.
ICRP145_BlenderToG4/Exportation.py - Scene helpers · Support functions and object/organ naming used during export.
ICRP145_BlenderToG4/functions.py - Organ model · 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 · Entry point that builds and runs the Geant4 transport executable.
G4/sim.cc - Geometry setup · Constructs the simulation world, phantom placement, and shell geometry.
G4/src/geometry.cc - Import mesh · Loads the tetrahedral phantom and maps it into Geant4 geometry.
G4/src/TETModelImport.cc - Parameterisation · Defines tetrahedral parameterisation and mesh-to-volume representation.
G4/src/TETParameterisation.cc - Shield material · Builds the optional aluminum shell and related material definitions.
G4/src/shieldmaterial.cc - Primary generator · Configures particle type, energy, radius, and source distribution.
G4/src/generator.cc - Action stack · Coordinates Geant4 actions for initialization, event handling, and run lifecycle.
G4/src/action.cc - Scoring hits · Captures flux and energy-deposit observables for the simulation.
G4/include/HitInfo.hh - Energy deposit · Organ and tissue scoring implementations for absorbed dose observables.
G4/src/TETPSEnergyDeposit.cc - Flux tally · Flux and total-flux scoring components used by the transport run.
G4/src/TotalFlux.cc - Run output · Writes per-run results and organizes simulation output for downstream analysis.
G4/src/run.cc - Macro generator · 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 · 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 · Fits solar energetic particle spectra from GOES, SEPEM, and Tylka-Hu sources.
SEP_spectra/fit_tylka_hu.py - Physics models · Shared spectral and physics routines used by the SEP fitting modules.
SEP_spectra/physics.py - SEP resume · 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 · Combines spectra with dose information to estimate dose quantities.
pyflare/main.py - Dose info · Holds dose tables, organ data, and dose conversion metadata.
pyflare/DoseInfo.py - Band model · Represents banded spectral inputs and aggregation over energy intervals.
pyflare/band.py - GCR model · Galactic cosmic ray dose pathway and related spectral handling.
pyflare/gcr.py - SEP model · Solar energetic particle dose pathway and source-specific processing.
pyflare/sepem.py
Connections 24
- 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.