# tardis-sn/tardis architecture

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

- Interactive diagram: https://gitdiagram.com/tardis-sn/tardis
- Repository: https://github.com/tardis-sn/tardis

## Overview

1. **What the repository is**
   TARDIS is a Python scientific simulation package for supernova spectral synthesis. Its core purpose is to take a supernova ejecta model plus atomic data and produce synthetic observables, mainly spectra, using Monte Carlo radiative transfer.

2. **Top-level architecture**
   The code is organized as a pipeline with clear stages: configuration and model ingestion, plasma/physics state construction, opacity calculation, Monte Carlo transport, spectrum formation, and post-processing/visualization. Most of the repository follows this data flow rather than a generic app structure.

3. **Configuration and input boundary**
   The `tardis.io.configuration` package is the main entry point for reading YAML-based simulation configs and validating them against schemas. It feeds model, plasma, Monte Carlo, spectrum, and supernova settings into the rest of the system. This is the main boundary between user-facing input and internal simulation state.

4. **Model ingestion and geometry**
   `tardis.io.model` and `tardis.model` turn external ejecta descriptions into the internal 1D radial model used by the simulation. Supported sources include CSVY, CMFGEN, ARTIS, STELLA, AREPO, SNEC, and simple ASCII-style density/composition files. The `tardis.model.geometry.radial1d` module defines the shell-based geometry that the transport code uses.

5. **Atomic data and derived inputs**
   `tardis.io.atom_data` handles atomic datasets, including parsing, downloading, and transforming them into the forms needed by line opacities, macro atom transitions, collision data, and NLTE calculations. This subsystem is a key dependency for the plasma and opacity layers and is separate from the simulation logic itself.

6. **Plasma state calculation**
   The main plasma implementation lives in `tardis.plasma`, with a parallel/alternate implementation in `tardis.iip_plasma`. These packages build shell-by-shell thermodynamic and radiative state: ion populations, level populations, partition functions, NLTE rates, radiative properties, and continuum processes. The plasma layer consumes model geometry, atomic data, and radiation-field estimates, then produces the state used by opacities and transport.

7. **Opacity and interaction physics**
   `tardis.opacities` converts plasma state and model state into the interaction probabilities required by radiative transfer. It contains Sobolev line opacity logic, continuum opacity handling, macro atom transition machinery, and opacity-state solvers. This layer is the physics bridge between plasma computation and packet propagation.

8. **Monte Carlo transport core**
   `tardis.transport.montecarlo` is the central radiative-transfer engine. It defines packet types, packet sources, geometry-aware propagation, interaction event dispatch, macro atom handling, estimators, and the main transport loops. There are two transport modes under `modes`: `classic` and `iip`, reflecting different solver/architecture paths. This is where the simulation spends most of its runtime.

9. **Radiation-field estimation and convergence**
   The Monte Carlo layer produces estimators that feed back into plasma and opacity calculations. The `estimators` subpackage collects line, continuum, and bulk radiation-field quantities, while `tardis.simulation.convergence` manages iterative convergence of the coupled transport–plasma system. This feedback loop is the main coupled solver in the repository.

10. **Spectrum formation and observables**
   `tardis.spectrum` turns transport outputs into emergent spectra and luminosity products. It includes a formal-integral post-processing path, with CPU-optimized and CUDA variants, to compute final spectra from the simulated radiation field and last-interaction information. This is the main output boundary for scientific use.

11. **High-energy and decay-energy extension**
   `tardis.energy_input` and `tardis.workflows.high_energy` support gamma-ray and nuclear-decay energy deposition, including packet generation, gamma-ray transport, and interaction handling. This is a secondary but architecturally important pathway because it feeds energy into the plasma/transport system for radioactive supernova models.

12. **Analysis, visualization, and tooling**
   `tardis.analysis`, `tardis.visualization`, and `tardis.gui` provide downstream inspection tools: convergence plots, packet tracking plots, SDEC/LIV plots, line-identification widgets, shell and abundance widgets, and notebook-based exploration. These are not part of the solver core, but they are the primary layer for interpreting simulation results.

13. **Workflows and user entry points**
   `tardis.workflows` packages common simulation recipes such as standard, simple, Type IIP, and high-energy workflows, plus a v_inner solver workflow. These orchestrate the I/O, model, plasma, transport, and spectrum components into repeatable execution paths for notebooks, scripts, and tests.

14. **Engineering and runtime characteristics**
   The repository is Python-based and heavily test-driven, with a large `tests` footprint under nearly every subsystem. Performance-sensitive paths use NumPy/Numba, and some spectrum and opacity routines have specialized accelerated implementations; CUDA appears only in the formal-integral path. The repo also has substantial docs, notebooks, CI workflows, benchmark tooling, and release automation, which indicate a mature scientific codebase with strong reproducibility and validation concerns.

Main entry points: [`tardis/plasma`](https://github.com/tardis-sn/tardis/tree/master/tardis/plasma) (Plasma), [`tardis/workflows/standard_tardis_workflow.py`](https://github.com/tardis-sn/tardis/blob/master/tardis/workflows/standard_tardis_workflow.py) (Standard WF), [`tardis/transport/montecarlo`](https://github.com/tardis-sn/tardis/tree/master/tardis/transport/montecarlo) (Monte Carlo), [`tardis/io/configuration`](https://github.com/tardis-sn/tardis/tree/master/tardis/io/configuration) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_io["Input & model I/O"]
  node_n_config["Configuration<br/>YAML config"]
  node_n_model_io["Model I/O<br/>ejecta readers"]
  node_n_atom_data[("Atomic data")]
  node_n_radial1d["Radial model<br/>1D geometry<br/>[radial1d.py]"]
end

subgraph group_group_physics["Physics state"]
  node_n_plasma["Plasma<br/>state solver"]
  node_n_iip_plasma["IIP plasma<br/>alt plasma"]
  node_n_rfield["Radiation field<br/>field state"]
  node_n_opacities["Opacities<br/>interaction physics"]
end

subgraph group_group_transport["Transport core"]
  node_n_mc_core["Monte Carlo<br/>transport engine"]
  node_n_mc_modes["Solver modes<br/>classic/iip"]
  node_n_estimators["Estimators<br/>radfield metrics"]
  node_n_convergence["Convergence<br/>coupled iteration<br/>[convergence.py]"]
end

subgraph group_group_output["Outputs & analysis"]
  node_n_spectrum["Spectrum<br/>observables"]
  node_n_formal_integral["Formal integral<br/>postprocess"]
  node_n_analysis["Analysis<br/>inspection tools<br/>[analysis.py]"]
  node_n_visualization["Visualization<br/>plotting"]
  node_n_gui["GUI<br/>widgets"]
end

subgraph group_group_workflows["Workflows"]
  node_n_standard_wf["Standard WF<br/>workflow"]
  node_n_simple_wf["Simple WF<br/>workflow"]
  node_n_iip_wf["Type IIP WF<br/>workflow"]
end

subgraph group_group_ext["Extensions"]
  node_n_he_wf["High-energy WF<br/>workflow"]
  node_n_energy_input["Energy input<br/>decay/gamma"]
end

node_n_config -->|"model settings"| node_n_model_io
node_n_config -->|"atomic settings"| node_n_atom_data
node_n_config -->|"plasma settings"| node_n_plasma
node_n_config -->|"transport settings"| node_n_mc_core
node_n_model_io -->|"internal model"| node_n_radial1d
node_n_model_io -->|"model state"| node_n_plasma
node_n_atom_data -->|"atomic input"| node_n_plasma
node_n_atom_data -->|"line data"| node_n_opacities
node_n_radial1d -->|"shell geometry"| node_n_opacities
node_n_rfield -->|"field estimate"| node_n_plasma
node_n_plasma -->|"state update"| node_n_opacities
node_n_opacities -->|"interaction probs"| node_n_mc_core
node_n_mc_core -->|"collect estimators"| node_n_estimators
node_n_estimators -->|"feedback"| node_n_convergence
node_n_convergence -->|"iterate plasma"| node_n_plasma
node_n_mc_core -->|"transport output"| node_n_spectrum
node_n_spectrum -->|"formal integral"| node_n_formal_integral
node_n_formal_integral -->|"derived products"| node_n_analysis
node_n_analysis -->|"plots"| node_n_visualization
node_n_visualization -->|"interactive views"| node_n_gui
node_n_standard_wf -->|"orchestrates"| node_n_config
node_n_standard_wf -->|"orchestrates"| node_n_model_io
node_n_standard_wf -->|"orchestrates"| node_n_plasma
node_n_standard_wf -->|"orchestrates"| node_n_mc_core
node_n_standard_wf -->|"orchestrates"| node_n_spectrum
node_n_simple_wf -.->|"variant of"| node_n_standard_wf
node_n_iip_wf -->|"uses"| node_n_iip_plasma
node_n_iip_wf -->|"uses"| node_n_mc_modes
node_n_mc_core -->|"mode dispatch"| node_n_mc_modes
node_n_energy_input -->|"packet source"| node_n_mc_core
node_n_energy_input -->|"deposition"| node_n_plasma
node_n_he_wf -->|"orchestrates"| node_n_energy_input
node_n_he_wf -.->|"extends"| node_n_standard_wf

click node_n_config "https://github.com/tardis-sn/tardis/tree/master/tardis/io/configuration"
click node_n_model_io "https://github.com/tardis-sn/tardis/tree/master/tardis/io/model"
click node_n_atom_data "https://github.com/tardis-sn/tardis/tree/master/tardis/io/atom_data"
click node_n_radial1d "https://github.com/tardis-sn/tardis/blob/master/tardis/model/geometry/radial1d.py"
click node_n_plasma "https://github.com/tardis-sn/tardis/tree/master/tardis/plasma"
click node_n_iip_plasma "https://github.com/tardis-sn/tardis/tree/master/tardis/iip_plasma"
click node_n_rfield "https://github.com/tardis-sn/tardis/tree/master/tardis/radiation_field"
click node_n_opacities "https://github.com/tardis-sn/tardis/tree/master/tardis/opacities"
click node_n_mc_core "https://github.com/tardis-sn/tardis/tree/master/tardis/transport/montecarlo"
click node_n_mc_modes "https://github.com/tardis-sn/tardis/tree/master/tardis/transport/montecarlo/modes"
click node_n_estimators "https://github.com/tardis-sn/tardis/tree/master/tardis/transport/montecarlo/estimators"
click node_n_convergence "https://github.com/tardis-sn/tardis/blob/master/tardis/simulation/convergence.py"
click node_n_spectrum "https://github.com/tardis-sn/tardis/tree/master/tardis/spectrum"
click node_n_formal_integral "https://github.com/tardis-sn/tardis/tree/master/tardis/spectrum/formal_integral"
click node_n_analysis "https://github.com/tardis-sn/tardis/blob/master/tardis/analysis.py"
click node_n_visualization "https://github.com/tardis-sn/tardis/tree/master/tardis/visualization"
click node_n_gui "https://github.com/tardis-sn/tardis/tree/master/tardis/gui"
click node_n_standard_wf "https://github.com/tardis-sn/tardis/blob/master/tardis/workflows/standard_tardis_workflow.py"
click node_n_simple_wf "https://github.com/tardis-sn/tardis/blob/master/tardis/workflows/simple_tardis_workflow.py"
click node_n_iip_wf "https://github.com/tardis-sn/tardis/blob/master/tardis/workflows/type_iip_workflow.py"
click node_n_he_wf "https://github.com/tardis-sn/tardis/blob/master/tardis/workflows/high_energy/tardis_he_workflow.py"
click node_n_energy_input "https://github.com/tardis-sn/tardis/tree/master/tardis/energy_input"

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_n_config,node_n_model_io,node_n_atom_data,node_n_radial1d toneBlue
class node_n_plasma,node_n_iip_plasma,node_n_rfield,node_n_opacities toneAmber
class node_n_mc_core,node_n_mc_modes,node_n_estimators,node_n_convergence toneMint
class node_n_spectrum,node_n_formal_integral,node_n_analysis,node_n_visualization,node_n_gui toneRose
class node_n_standard_wf,node_n_simple_wf,node_n_iip_wf toneIndigo
class node_n_he_wf,node_n_energy_input toneTeal
```

## Components

### Input & model I/O

Configuration, model ingestion, atomic data, and external input boundaries.

- [Configuration](https://github.com/tardis-sn/tardis/tree/master/tardis/io/configuration): YAML config · Reads and validates simulation configuration, forming the main user input boundary. · `tardis/io/configuration`
- [Model I/O](https://github.com/tardis-sn/tardis/tree/master/tardis/io/model): ejecta readers · Parses external ejecta descriptions such as CSVY, CMFGEN, ARTIS, STELLA, AREPO, and SNEC. · `tardis/io/model`
- [Atomic data](https://github.com/tardis-sn/tardis/tree/master/tardis/io/atom_data): atomic datasets · Loads, converts, and derives atomic data for line, macro atom, collision, and NLTE calculations. · `tardis/io/atom_data`
- [Radial model](https://github.com/tardis-sn/tardis/blob/master/tardis/model/geometry/radial1d.py): 1D geometry · Defines the shell-based radial geometry and internal model representation used throughout the solver. · `tardis/model/geometry/radial1d.py`

### Physics state

Plasma, opacities, and radiation-field state construction used by transport.

- [Plasma](https://github.com/tardis-sn/tardis/tree/master/tardis/plasma): state solver · Builds shell-by-shell thermodynamic and radiative plasma state from model, atomic data, and radiation-field estimates. · `tardis/plasma`
- [IIP plasma](https://github.com/tardis-sn/tardis/tree/master/tardis/iip_plasma): alt plasma · Parallel plasma implementation for the IIP architecture path. · `tardis/iip_plasma`
- [Radiation field](https://github.com/tardis-sn/tardis/tree/master/tardis/radiation_field): field state · Validates and represents radiation-field inputs and estimates passed into plasma and transport. · `tardis/radiation_field`
- [Opacities](https://github.com/tardis-sn/tardis/tree/master/tardis/opacities): interaction physics · Turns plasma state into line, continuum, and macro atom interaction probabilities. · `tardis/opacities`

### Transport core

Monte Carlo packet propagation, estimators, and solver modes.

- [Monte Carlo](https://github.com/tardis-sn/tardis/tree/master/tardis/transport/montecarlo): transport engine · Central radiative-transfer engine for packet creation, propagation, interactions, and iteration. · `tardis/transport/montecarlo`
- [Solver modes](https://github.com/tardis-sn/tardis/tree/master/tardis/transport/montecarlo/modes): classic/iip · Holds the classic and IIP transport paths, including mode-specific transport and propagation logic. · `tardis/transport/montecarlo/modes`
- [Estimators](https://github.com/tardis-sn/tardis/tree/master/tardis/transport/montecarlo/estimators): radfield metrics · Collects line, continuum, and bulk estimators that feed back into plasma updates. · `tardis/transport/montecarlo/estimators`
- [Convergence](https://github.com/tardis-sn/tardis/blob/master/tardis/simulation/convergence.py): coupled iteration · Coordinates iterative coupling between transport, estimators, plasma, and opacity updates. · `tardis/simulation/convergence.py`

### Outputs & analysis

Spectrum formation, visualization, analysis, and GUI tooling.

- [Spectrum](https://github.com/tardis-sn/tardis/tree/master/tardis/spectrum): observables · Forms emergent spectra and luminosity products from transport output and last-interaction information. · `tardis/spectrum`
- [Formal integral](https://github.com/tardis-sn/tardis/tree/master/tardis/spectrum/formal_integral): postprocess · Post-processing path for spectrum synthesis, including accelerated CPU and CUDA implementations. · `tardis/spectrum/formal_integral`
- [Analysis](https://github.com/tardis-sn/tardis/blob/master/tardis/analysis.py): inspection tools · Provides convergence and diagnostic analysis helpers for simulation outputs. · `tardis/analysis.py`
- [Visualization](https://github.com/tardis-sn/tardis/tree/master/tardis/visualization): plotting · Plots packet, convergence, line-ID, and SDEC diagnostics. · `tardis/visualization`
- [GUI](https://github.com/tardis-sn/tardis/tree/master/tardis/gui): widgets · Notebook-oriented widgets and interfaces for interactive inspection of runs and model state. · `tardis/gui`

### Workflows

User-facing orchestration layers that combine the pipeline stages.

- [Standard WF](https://github.com/tardis-sn/tardis/blob/master/tardis/workflows/standard_tardis_workflow.py): workflow · Orchestrates the standard simulation pipeline from configuration through spectrum output. · `tardis/workflows/standard_tardis_workflow.py`
- [Simple WF](https://github.com/tardis-sn/tardis/blob/master/tardis/workflows/simple_tardis_workflow.py): workflow · Lightweight workflow variant for simplified execution paths. · `tardis/workflows/simple_tardis_workflow.py`
- [Type IIP WF](https://github.com/tardis-sn/tardis/blob/master/tardis/workflows/type_iip_workflow.py): workflow · Workflow specialized for Type IIP simulation setups and plasma handling. · `tardis/workflows/type_iip_workflow.py`

### Extensions

High-energy deposition and decay-energy support.

- [High-energy WF](https://github.com/tardis-sn/tardis/blob/master/tardis/workflows/high_energy/tardis_he_workflow.py): workflow · Workflow for radioactive decay and gamma-ray energy deposition models. · `tardis/workflows/high_energy/tardis_he_workflow.py`
- [Energy input](https://github.com/tardis-sn/tardis/tree/master/tardis/energy_input): decay/gamma · Implements nuclear-decay energy sources, gamma-ray transport, and deposition handling. · `tardis/energy_input`

## Connections

- Configuration → Model I/O: model settings · Configuration determines which external model reader and geometry are used.
- Configuration → Atomic data: atomic settings · Configuration selects and validates atomic-data inputs.
- Configuration → Plasma: plasma settings · Configuration feeds plasma solver choices and closures.
- Configuration → Monte Carlo: transport settings · Configuration provides Monte Carlo solver controls and packet parameters.
- Model I/O → Radial model: internal model · External model descriptions are converted into the internal radial shell geometry.
- Model I/O → Plasma: model state · Model densities and compositions become plasma inputs.
- Atomic data → Plasma: atomic input · Atomic datasets supply levels, transitions, collisions, and NLTE data.
- Atomic data → Opacities: line data · Opacity calculations depend on atomic transitions and collision information.
- Radial model → Opacities: shell geometry · Opacity and interaction calculations use the radial shell structure.
- Radiation field → Plasma: field estimate · Radiation-field estimates are consumed by plasma state solvers.
- Plasma → Opacities: state update · Plasma state drives opacity and interaction probabilities.
- Opacities → Monte Carlo: interaction probs · Interaction physics is used by packet transport.
- Monte Carlo → Estimators: collect estimators · Transport produces estimators for radiation-field and bulk quantities.
- Estimators → Convergence: feedback · Estimator output drives iteration and convergence checks.
- Convergence → Plasma: iterate plasma · Coupled solver updates the plasma until convergence.
- Monte Carlo → Spectrum: transport output · Transport output is the basis for emergent observables.
- Spectrum → Formal integral: formal integral · Spectrum formation uses formal-integral post-processing.
- Formal integral → Analysis: derived products · Post-processed spectra and luminosities are analyzed and compared.
- Analysis → Visualization: plots · Analysis outputs are rendered through visualization tools.
- Visualization → GUI: interactive views · Visualization components back notebook and widget interfaces.
- Standard WF → Configuration: orchestrates · Standard workflow starts from configuration parsing.
- Standard WF → Model I/O: orchestrates · Standard workflow loads the ejecta model.
- Standard WF → Plasma: orchestrates · Standard workflow builds plasma state.
- Standard WF → Monte Carlo: orchestrates · Standard workflow runs Monte Carlo transport.
- Standard WF → Spectrum: orchestrates · Standard workflow produces spectra.
- Simple WF → Standard WF: variant of · Simple workflow is a lighter orchestration path built from the main workflow pattern.
- Type IIP WF → IIP plasma: uses · Type IIP workflow targets the alternate plasma implementation.
- Type IIP WF → Solver modes: uses · Type IIP workflow relies on the IIP transport mode.
- Monte Carlo → Solver modes: mode dispatch · The transport engine dispatches to classic or IIP mode implementations.
- Energy input → Monte Carlo: packet source · Decay and gamma-ray energy feeds the transport system as packet sources.
- Energy input → Plasma: deposition · Deposited decay energy contributes to plasma state evolution.
- High-energy WF → Energy input: orchestrates · High-energy workflow coordinates decay-energy and gamma-ray handling.
- High-energy WF → Standard WF: extends · High-energy workflow builds on the standard simulation pipeline.
