TARDIS Plasma Module

Plasma Structure

NetworkX - Plasma Graphs

The plasma is structured as a network of calculations. Each quantity (temperature, ionization, optical depth, etc.) is a “property.” Properties depend on one another, and TARDIS connects them into a graph so that when one value changes, only the downstream values get recalculated in the correct order.

The plasma lives in the class BasePlasma, defined in plasma/base.py.

There are two types of properties:

  • Input properties — values fed in from the model or config. They have outputs but no inputs, so they are the starting points of the graph.

  • Processing properties — values that get calculated. TARDIS reads the argument names of their calculate function to learn what inputs they need.

For example, PhiSahaLTE (defined in plasma/properties/ion_population.py) has the function:

calculate(g_electron, beta_rad, partition_function, ionization_data)

Its inputs are those four names and its output is phi. Connections are made by matching names — an output called phi automatically links to any calculation that has an argument called phi.

Building the Graph

TARDIS builds the graph inside _build_graph in three steps:

  1. Add one node for every property.

  2. Mark the input properties as starting points (they have no inputs).

  3. For each calculated property, find what it needs, locate the property that produces each name, and draw an arrow from producer to consumer. If a property needs something that nothing produces, TARDIS raises an error immediately, catching broken or incomplete setups.

When an input changes (for example, the temperature), TARDIS finds everything downstream of that change and recalculates in topological order, so each property is updated only after the values it depends on are fresh.

For a guide on how to display a plasma graph, see How to Generate the Plasma Graph.

Plasma Solver Factory

The PlasmaSolverFactory class, defined in plasma/assembly/base.py, initializes, configures, and assembles the plasma used in TARDIS runs. It has two key methods:

  • prepare_factory — accepts specific property collections, which are collections of classes that define plasma properties.

  • assemble — returns an instance of the BasePlasma class.

There is also an assemble_plasma function defined in two locations:

  • plasma/assembly/legacy_assembly.py

  • plasma/standard_plasmas.py

The active assemble_plasma function used by the TARDIS simulation class is the one defined in plasma/assembly/legacy_assembly.py. It returns an assembled plasma by:

  1. Defining a PlasmaSolverFactory instance.

  2. Calling the prepare_factory method.

  3. Calling the assemble method.

Plasma Properties

The plasma properties used throughout the plasma module are defined in legacy_property_collections.py. A separate property_collections.py file exists but is not imported by the main plasma solver factory and is therefore not active during standard TARDIS runs. The standard plasma solver imports its property collections from legacy_property_collections.py.

Property Categories

The following describes the property categories defined in legacy_property_collections.py. Properties that are inactive, uncovered, or not exercised by integration tests are noted inline.

Adiabatic Cooling Properties

  • AdiabaticCoolingRate

Basic Inputs

  • DilutePlanckianRadField

  • NumberDensity

  • TimeExplosion

  • AtomicData

  • JBlues

  • LinkTRadTElectron

  • HeliumTreatment

  • ContinuumInteractionSpecies — Not exercised by any current integration test. The associated continuum interaction properties are scoped to Type II supernova plasmas and are not activated in standard Type Ia simulation configs.

  • NLTEIonizationSpecies

  • NLTEExcitationSpecies

Basic Properties

  • BetaRadiation

  • DilutionFactor

  • ElectronTemperature

  • GElectron

  • IonizationData

  • Levels

  • Lines

  • LinesLowerLevelIndex

  • LinesUpperLevelIndex

  • PartitionFunction

  • SelectedAtoms

  • StimulatedEmission

  • TRadiative

  • TauSobolev

Continuum Interaction Inputs

  • PhotoIonRateCoeff

  • StimRecombRateFactor

  • BfHeatingRateCoeffEstimator

  • StimRecombCoolingRateCoeffEstimator

  • YgData — Tested directly in plasma/equilibrium/tests/test_collisional_transitions.py and plasma/tests/test_plasma_continuum.py, but not wired into the main plasma solver factory and therefore not built during standard TARDIS runs.

Continuum Interaction Properties

  • BoundFreeOpacity

  • CollDeexcRateCoeff — Defined in two files: plasma/equilibrium/rates/collision_strengths.py and plasma/properties/continuum_processes/rates.py. The active class is the one imported into the property collection from rates.py. The class in collision_strengths.py is not covered by the test suite.

  • CollExcRateCoeff — Same as above.

  • CollIonRateCoeffSeaton

  • CollRecombRateCoeff

  • ContinuumInteractionHandler

  • CorrPhotoIonRateCoeff

  • FreeBoundCoolingRate

  • FreeBoundEmissionCDF

  • FreeFreeCoolingRate

  • LevelIdxs2LineIdx

  • LevelIdxs2TransitionIdx

  • LevelNumberDensityLTE

  • MarkovChainIndex

  • MarkovChainTransProbs

  • MarkovChainTransProbsCollector

  • MonteCarloTransProbs

  • NonContinuumTransProbsMask

  • NonMarkovChainTransitionProbabilities

  • PhotoIonBoltzmannFactor

  • PhotoIonizationData — Registered in the plasma solver factory but not exercised by any current integration test configuration.

  • RawCollIonTransProbs

  • RawCollisionTransProbs

  • RawPhotoIonTransProbs

  • RawRadBoundBoundTransProbs

  • RawRecombTransProbs

  • SahaFactor

  • SpontRecombCoolingRateCoeff

  • SpontRecombRateCoeff — Defined in the property collection but not referenced by the main plasma solver factory. Developers extending continuum interaction support should note this class requires explicit wiring to become active.

  • StimRecombRateCoeff

  • ThermalGElectron

  • ThermalLTEPartitionFunction

  • ThermalLevelBoltzmannFactorLTE

  • ThermalPhiSahaLTE

  • YgInterpolator

Dilute LTE Excitation Properties

  • LevelBoltzmannFactorDiluteLTE

Helium LTE Properties

  • LevelNumberDensity

  • IonNumberDensity

Helium NLTE Properties

  • HeliumNLTE

  • RadiationFieldCorrection

  • ZetaData

  • BetaElectron

  • LevelNumberDensityHeNLTE

  • IonNumberDensityHeNLTE

Helium Numerical NLTE Properties

  • HeliumNumericalNLTE — Requires a specific numerical NLTE solver and a specific atomic dataset. Neither are distributed with TARDIS. This class is not activated in standard simulation runs.

LTE Excitation Properties

  • LevelBoltzmannFactorLTE

LTE Ionization Properties

  • PhiSahaLTE

Nebular Ionization Properties

  • PhiSahaNebular

  • ZetaData

  • BetaElectron

  • RadiationFieldCorrection

NLTE LU Solver Properties

  • NLTEIndexHelper

  • NLTEPopulationSolverLU — Tested in test_nlte_solver but not exercised in full integration tests. This solver is not activated in standard simulation configurations.

NLTE Properties

  • LevelBoltzmannFactorNLTE

  • NLTEData

  • PreviousElectronDensities

  • PreviousBetaSobolev

  • BetaSobolev

NLTE Root Solver Properties

  • NLTEIndexHelper

  • NLTEPopulationSolverRoot — Tested in test_nlte_solver but not exercised in full integration tests. This solver is not activated in standard simulation configurations.

Non NLTE Properties

  • LevelBoltzmannFactorNoNLTE

Two Photon Properties

  • RawTwoPhotonTransProbs

  • TwoPhotonData

  • TwoPhotonEmissionCDF

  • TwoPhotonFrequencySampler

Equilibrium

The tardis/plasma/equilibrium/rates/ folder contains an alternative plasma implementation based on RateSolver classes. This implementation is independent of the NetworkX-based plasma module used in standard TARDIS simulations and is not invoked during normal runs. The rate solver classes have dedicated unit tests and are retained for future development.

Developer Notes: Inactive and Partially Covered Modules

The following plasma module files are not invoked during standard TARDIS simulation runs. Developers modifying the plasma module should be aware of their status.

tardis/plasma/standard_plasmas.py

Not covered by the plasma test suite and not called during standard TARDIS runs. This module is used exclusively by grotrian_mockup.ipynb. The active plasma assembly entry point is assemble_plasma in plasma/assembly/legacy_assembly.py.

tardis/plasma/properties/property_collections.py

An alternative property collection used by standard_plasmas.py. Not imported by the main plasma solver factory and therefore inactive during normal simulation runs. Developers should use legacy_property_collections.py as the authoritative reference for active plasma properties.

tardis/plasma/properties/nlte_excitation_data.py

Defines NLTEExcitationData, which is not referenced elsewhere in the active codebase and is the existing implementation relevant to future NLTE excitation work.

tardis/plasma/properties/hydrogen_continuum.py

Not activated by any current simulation configuration and not covered by the plasma test suite.

tardis/plasma/properties/continuum_processes/fast_array_util.py

Provides two Numba-accelerated integration utilities:

  • numba_cumulative_trapezoid — Used by TwoPhotonEmissionCDF in tardis/plasma/properties/continuum_processes/rates.py.

  • cumulative_integrate_array_by_blocks — Used by the same class.

Both functions are not exercised by the plasma test suite, as TwoPhotonEmissionCDF is not activated in standard simulation configurations.

Developer Reference: Test Coverage and Plasma Graphs

Test Coverage

The plasma module test suite provides a practical way to identify which properties are exercised by standard plasma configurations. Running the plasma module tests with coverage enabled allows developers to verify which property calculate methods are exercised by the current set of simulation configurations.

Key architectural notes for developers:

  • plasma/standard_plasmas.py is not covered by the plasma test suite. The active assembly entry point is plasma/assembly/legacy_assembly.py.

  • Continuum interaction properties in PlasmaSolverFactory (plasma/assembly/base.py) are not activated by any current integration test configuration. Continuum interactions are not used in standard Type Ia supernova simulations.

  • hydrogen_continuum.py is not activated by any current simulation configuration and is not covered by the plasma test suite.

To determine whether a specific property class is active, inspect its calculate method under coverage. For example:

  • LinesLowerLevelIndex has full coverage, confirming it is calculated in every standard plasma configuration built by test_complete_plasmas.

  • SpontRecombRateCoeff, defined in continuum_interactions_properties, has no coverage in test_complete_plasmas, confirming it is not built by any current standard simulation configuration.

Coverage analysis of test_complete_plasmas can be used to:

  • Identify which property classes require additional unit tests.

  • Determine which features are scoped to Type II plasma and should not be assumed available in Type Ia runs.

  • Identify property classes that are candidates for removal or consolidation.

Plasma Graph Generation

TARDIS can generate diagrams of the plasma property graph, showing which properties depend on one another. Generating graphs across multiple simulation configurations is a practical method for identifying which plasma properties are relevant to standard simulation runs.

Useful resources: