How tardis-sn/tardis works
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: plasma Plasma · standard_tardis_workflow.py Standard WF · montecarlo Monte Carlo · configuration Configuration
Components 22
Input & model I/O
Configuration, model ingestion, atomic data, and external input boundaries.
- Configuration · Reads and validates simulation configuration, forming the main user input boundary.
tardis/io/configuration - Model I/O · Parses external ejecta descriptions such as CSVY, CMFGEN, ARTIS, STELLA, AREPO, and SNEC.
tardis/io/model - Atomic data · Loads, converts, and derives atomic data for line, macro atom, collision, and NLTE calculations.
tardis/io/atom_data - Radial model · 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 · Builds shell-by-shell thermodynamic and radiative plasma state from model, atomic data, and radiation-field estimates.
tardis/plasma - IIP plasma · Parallel plasma implementation for the IIP architecture path.
tardis/iip_plasma - Radiation field · Validates and represents radiation-field inputs and estimates passed into plasma and transport.
tardis/radiation_field - Opacities · 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 · Central radiative-transfer engine for packet creation, propagation, interactions, and iteration.
tardis/transport/montecarlo - Solver modes · Holds the classic and IIP transport paths, including mode-specific transport and propagation logic.
tardis/transport/montecarlo/modes - Estimators · Collects line, continuum, and bulk estimators that feed back into plasma updates.
tardis/transport/montecarlo/estimators - Convergence · Coordinates iterative coupling between transport, estimators, plasma, and opacity updates.
tardis/simulation/convergence.py
Outputs & analysis
Spectrum formation, visualization, analysis, and GUI tooling.
- Spectrum · Forms emergent spectra and luminosity products from transport output and last-interaction information.
tardis/spectrum - Formal integral · Post-processing path for spectrum synthesis, including accelerated CPU and CUDA implementations.
tardis/spectrum/formal_integral - Analysis · Provides convergence and diagnostic analysis helpers for simulation outputs.
tardis/analysis.py - Visualization · Plots packet, convergence, line-ID, and SDEC diagnostics.
tardis/visualization - GUI · 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 · Orchestrates the standard simulation pipeline from configuration through spectrum output.
tardis/workflows/standard_tardis_workflow.py - Simple WF · Lightweight workflow variant for simplified execution paths.
tardis/workflows/simple_tardis_workflow.py - Type IIP WF · 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 · Workflow for radioactive decay and gamma-ray energy deposition models.
tardis/workflows/high_energy/tardis_he_workflow.py - Energy input · Implements nuclear-decay energy sources, gamma-ray transport, and deposition handling.
tardis/energy_input
Connections 33
- 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.