tardis.opacities.macro_atom.absorbing_markov_chain module

Calculate first-exit probabilities for reduced macro-atom chains.

This module eliminates internal transitions for selected blocks independently in each cell and computes the source-state probabilities for retained transitions.

Effectively this compresses the macro atom evaluation by internal reducing probability chains to equivalent single appropriate probability steps.

References

Absorbing Markov chain theory: https://en.wikipedia.org/wiki/Absorbing_Markov_chain

class tardis.opacities.macro_atom.absorbing_markov_chain.AbsorbingChainResult(matrix: ndarray[tuple[Any, ...], dtype[float64]], residual_probabilities: DataFrame, macro_level_to_reduced_idx: ndarray[tuple[Any, ...], dtype[int64]], reduced_to_macro_level_idx: ndarray[tuple[Any, ...], dtype[int64]])

Bases: NamedTuple

Carry processed reduced block exit probabilities and their global/compact index mapping.

Necessary for the monte-carlo step to enter and exit the reduced block.

Create new instance of AbsorbingChainResult(matrix, residual_probabilities, macro_level_to_reduced_idx, reduced_to_macro_level_idx)

macro_level_to_reduced_idx: ndarray[tuple[Any, ...], dtype[int64]]

Alias for field number 2

matrix: ndarray[tuple[Any, ...], dtype[float64]]

Alias for field number 0

reduced_to_macro_level_idx: ndarray[tuple[Any, ...], dtype[int64]]

Alias for field number 3

residual_probabilities: DataFrame

Alias for field number 1

tardis.opacities.macro_atom.absorbing_markov_chain.create_absorbing_probs(transition_probabilities: DataFrame, metadata: DataFrame, mode: str = 'full', elements: Sequence[str] = (), include_thermal_pool: bool = False, include_ionization_pool: bool = False, max_workers: int = 1) → AbsorbingChainResult

Calculate absorbing Markov chain probabilities and deactivation data.

Computes the absorption probability matrices for each cell and extracts deactivation probabilities by solving the absorbing Markov chain system for the requested block. Eliminates internal transition inside handled blocks.

Parameters:

transition_probabilitiespd.DataFrame

DataFrame with transition probabilities between states for each cell. Rows represent transitions, columns represent cells.

metadatapd.DataFrame

Metadata about transitions including source_level_idx, destination_level_idx, and transition_type. Values >= 0 for transition_type indicate internal transitions transitions that are not accompanied by reemission of the r-packet, and an end to the interaction handler chain. Negative values indicate deactivation, or reemitting from an absorbing state.

mode{‘full’, ‘partial’, ‘explicit’}

Full eliminates all internal jumps. Partial eliminates only jumps with both endpoints selected (e.g., internal transitions for a requested element), optionally including either shared pool. Explicit retains every original transition.

elementssequence of str

Element symbols, required only in partial mode. All represented ions and levels of each selected element are included.

include_thermal_poolbool, optional

Include the shared k state in partial reduction. Defaults to False.

include_ionization_poolbool, optional

Include the shared i state in partial reduction. Defaults to False.

max_workersint

Maximum number of cell-independent sparse LU workers.

Returns:

AbsorbingChainResult

Cell-by-activation-by-exit-source matrix, containing deactivation probabilities, and explicit global-to-reduced and reduced-to-global int64 maps.

Notes

The solve is (I-Q) B = diag(r), where r is the sum of actual remaining channels. Zero residual rows stay zero.

The matrix selects the source of the first retained transition, which can itself be internal. It is not necessarily a final emission state because only requested physical blocks are blocks are processed out of the matrix, and the not-requested blocks retain full internal transition probability tables. This means you can move freely back and forth between the absorbing-processed block.

tardis.opacities.macro_atom.absorbing_markov_chain.solve_cell_full(internal_matrix: spmatrix) → ndarray[tuple[Any, ...], dtype[float64]]

Solve one cell’s full reduction using the legacy exit calculation.

Parameters:

internal_matrixscipy.sparse.spmatrix

Square matrix Q of this cell’s internal transition coefficients, including all global states. Supply COO format to preserve the legacy row-summation order.

Returns:

numpy.ndarray

Activation-by-exit-source matrix for this cell. Exit coefficients are calculated as one minus each row sum of Q.

tardis.opacities.macro_atom.absorbing_markov_chain.solve_cell_partial(internal_matrix: spmatrix, exit_rates: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Solve one cell’s partial reduction from a specified subset of probabilities.

Parameters:

internal_matrixscipy.sparse.spmatrix

Square matrix Q of this cell’s eliminated internal coefficients, in compact selected-state order.

exit_ratesnumpy.ndarray

One-dimensional sums of this cell’s retained channel coefficients, in the same selected-state order.

Returns:

numpy.ndarray

Activation-by-exit-source matrix B satisfying (I-Q) B = diag(exit_rates) for this cell.