tardis.opacities.macro_atom.macroatom_solver module

class tardis.opacities.macro_atom.macroatom_solver.BoundBoundMacroAtomSolver(levels: DataFrame, lines: DataFrame, line_interaction_type: str = 'macroatom')

Bases: object

Initialize the BoundBoundMacroAtomSolver.

Parameters:

levelspd.DataFrame

DataFrame containing atomic level information.

linespd.DataFrame

DataFrame containing spectral line information.

line_interaction_typestr, optional

Type of line interaction to use. Default is “macroatom”.

levels: DataFrame

lines: DataFrame

solve(mean_intensities_blue_wing: DataFrame, beta_sobolevs: DataFrame, stimulated_emission_factors: DataFrame) → MacroAtomState

Solve the transition probabilities for the macroatom.

This method calculates transition probabilities and returns a MacroAtomState object with the probabilities and macro atom transition metadata. Referenced as $p_i$ in Lucy 2003, https://doi.org/10.1051/0004-6361:20030357

Parameters:

mean_intensities_blue_wingpd.DataFrame

Mean intensity of the radiation field of each line in the blue wing for each shell. For more detail see Lucy 2003, https://doi.org/10.1051/0004-6361:20030357 Referenced as ‘J^b_{lu}’ internally, or ‘J^b_{ji}’ in the original paper.

beta_sobolevspd.DataFrame

Escape probabilities for the Sobolev approximation.

stimulated_emission_factorspd.DataFrame

Stimulated emission factors for the lines.

Returns:

MacroAtomState

A MacroAtomState object containing the transition probabilities, transition metadata, and a mapping from line IDs to macro atom level upper indices.

class tardis.opacities.macro_atom.macroatom_solver.LegacyMacroAtomSolver(initialize: bool = True, normalize: bool = True)

Bases: object

Initialize the LegacyMacroAtomSolver.

Parameters:

initializebool, optional

Whether or not to initialize the transition probability coefficients and block references when solving the first time. Default is True.

normalizebool, optional

Whether or not to normalize the transition probabilities to unity. Default is True.

initialize: bool = True

initialize_transition_probabilities(atomic_data: AtomData) → None

Initialize the transition probability coefficients and block references.

This method should be called when solving for the first time to set up the necessary coefficients and block references.

Parameters:

atomic_dataAtomData

Atomic data containing the necessary information for initialization.

normalize: bool = True

solve(mean_intensities_lines_blue_wing: DataFrame, atomic_data: AtomData, tau_sobolev: DataFrame, stimulated_emission_factor: DataFrame, beta_sobolev: DataFrame | None = None) → LegacyMacroAtomState

Solve the Macro Atom State.

Parameters:

mean_intensities_lines_blue_wingpd.DataFrame

Mean intensity of the radiation field of each line in the blue wing for each shell.

atomic_dataAtomData

Atomic data containing macro atom information.

tau_sobolevpd.DataFrame

Expansion optical depths.

stimulated_emission_factorpd.DataFrame

Stimulated emission factors.

beta_sobolevpd.DataFrame | None, optional

Modified expansion optical depths. Default is None.

Returns:

LegacyMacroAtomState

State of the macro atom ready to be placed into the OpacityState.

solve_transition_probabilities(atomic_data: AtomData, mean_intensities_lines_blue_wing: DataFrame, tau_sobolev: DataFrame, beta_sobolev: DataFrame | None, stimulated_emission_factor: DataFrame | ndarray) → DataFrame | None

Solve the basic transition probabilities for the macroatom.

Parameters:

atomic_dataAtomData

Atomic data containing macro atom information.

mean_intensities_lines_blue_wingpd.DataFrame

Mean intensity of the radiation field of each line in the blue wing for each shell. For more detail see Lucy 2003, https://doi.org/10.1051/0004-6361:20030357

tau_sobolevpd.DataFrame

Expansion optical depths.

beta_sobolevpd.DataFrame | None

Modified expansion optical depths.

stimulated_emission_factorpd.DataFrame | np.ndarray

Stimulated emission factors.

Returns:

pd.DataFrame | None

Transition probabilities. Returns None if mean_intensities_lines_blue_wing is empty.

tardis.opacities.macro_atom.macroatom_solver.create_line2macro_level_upper(macro_atom_transition_metadata: DataFrame, lines_level_upper: MultiIndex) → Series

Create a mapping from line transitions to macro atom level indices for upper levels. This method creates a mapping that connects line transition upper levels to their corresponding macro atom level indices. It first extracts unique source levels from the macro atom transition metadata and assigns sequential indices to them, then maps the line upper levels to these indices.

Parameters:

macro_atom_transition_metadatapd.DataFrame

DataFrame containing macro atom transition metadata

lines_level_upperpd.MultiIndex

MultiIndex containing line upper level information

Returns:

pd.Series

Series mapping line transitions to macro atom level indices

tardis.opacities.macro_atom.macroatom_solver.normalize_transition_probabilities(probabilities_df: DataFrame) → DataFrame

Normalize transition probabilities by their source levels.

Parameters:

probabilities_dfpd.DataFrame

DataFrame containing transition probabilities with a ‘source’ column for grouping.

Returns:

pd.DataFrame

Normalized probabilities where each source group sums to 1.0. NaN values are replaced with 0.0 for cases where all transition probabilities are zero (typically ground levels in macroatom).

tardis.opacities.macro_atom.macroatom_solver.reindex_sort_and_clean_probabilities_and_metadata(normalized_probabilities: DataFrame, macro_atom_transition_metadata: DataFrame) → tuple[DataFrame, DataFrame]

Reindex and sort macro atom transition probabilities and metadata.

Parameters:

normalized_probabilitiespd.DataFrame

DataFrame containing normalized transition probabilities.

macro_atom_transition_metadatapd.DataFrame

DataFrame containing metadata for macro atom transitions.

Returns:

tuple[pd.DataFrame, pd.DataFrame]

Reindexed normalized probabilities and cleaned metadata sorted by atomic number, ion number, and source level.