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”.

create_line2macro_level_upper_and_reference_idx(macro_atom_transition_metadata: DataFrame, lines_level_upper: MultiIndex) → tuple[Series, 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

pd.Series

Series with unique source levels as index and their assigned indices as values

create_macro_block_references(macro_atom_transition_metadata)

Create macro block references from the macro atom transition metadata. This method creates a mapping from unique source levels to their first occurrence index in the metadata.

Parameters:

macro_atom_transition_metadatapandas.DataFrame

DataFrame containing metadata for macro atom transitions.

Returns:

pandas.Series

Series with unique source levels as index and their first occurrence index in the metadata as values.

create_source_and_destination_idx_columns(macro_atom_transition_metadata)

This function creates numerical indices for source and destination levels by mapping unique source levels to sequential integers. The destination indices use -99 for destinations that are not sources (emission-only levels).

Parameters:

macro_atom_transition_metadatapd.DataFrame

DataFrame containing macro atom transition metadata with ‘source’ and ‘destination’ columns.

levels: DataFrame

lines: DataFrame

static 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).

reindex_sort_and_clean_probabilities_and_metadata(probabilities: DataFrame, macro_atom_transition_metadata: DataFrame) → tuple[DataFrame, DataFrame]

Reindex and sort macro atom transition probabilities and metadata. Also creates the unique metadata ID.

Parameters:

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.

solve(mean_intensities_blue_wing: DataFrame, beta_sobolevs: DataFrame, stimulated_emission_factors: ndarray) → 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_factorsnp.ndarray

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.ContinuumMacroAtomSolver(levels: DataFrame, lines: DataFrame, photoionization_data: DataFrame, ionization_energies: Series, selected_continuum_transitions: ndarray = array([], dtype=float64), line_interaction_type: str = 'macroatom')

Bases: BoundBoundMacroAtomSolver

Initialize the ContinuumMacroAtomSolver.

Parameters:

levels

DataFrame containing atomic level energy information.

lines

DataFrame containing spectral line information.

photoionization_data

DataFrame containing photoionization cross-section information.

ionization_energies

Series containing ionization energies for each level.

selected_continuum_transitions

Array of selected continuum transitions (atomic_number, ion_number) pairs. If empty, all photoionization transitions are included.

line_interaction_type

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

ionization_energies: Series

levels: DataFrame

line_interaction_type: str

lines: DataFrame

photoionization_data: DataFrame

reindex_sort_and_clean_probabilities_and_metadata(probabilities: DataFrame, macro_atom_transition_metadata: DataFrame) → tuple[DataFrame, DataFrame]

Adapted for continuum macroatom, where continuum transitions do not have the same dataframe indices. Reindex and sort macro atom transition probabilities and metadata. Also creates the unique metadata ID.

Parameters:

probabilities

DataFrame containing normalized transition probabilities.

macro_atom_transition_metadata

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.

selected_continuum_transitions: ndarray

set_static_properties(delta_E_yg: Series, coll_ion_coeff: DataFrame, coll_exc_coeff: DataFrame) → None

Set static properties that are computed from plasma data.

This method stores energy differences and collision coefficient-derived properties that are needed for the solve iterations but cannot be computed in __init__ because they depend on plasma properties.

Parameters:

delta_E_yg

Energy differences for collisional transitions.

coll_ion_coeff

Collisional ionization coefficients.

coll_exc_coeff

Collisional excitation coefficients.

solve(mean_intensities_blue_wing: DataFrame, beta_sobolevs: DataFrame, stimulated_emission_factors: ndarray, stim_recomb_corrected_photoionization_rate_coeff: DataFrame, spontaneous_recombination_coeff: DataFrame, coll_deexc_coeff: DataFrame, coll_exc_coeff: DataFrame, coll_ion_coeff: DataFrame, coll_recomb_coeff: DataFrame, electron_densities: Series, delta_E_yg: Series) → MacroAtomState

Solve the Macro Atom State including continuum transitions.

This method calculates transition probabilities for both bound-bound (line) and continuum transitions 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_wing

Mean intensity of the radiation field of each line in the blue wing for each shell. Referenced as ‘J^b_{lu}’ internally, or ‘J^b_{ji}’ in the original paper.

beta_sobolevs

Escape probabilities for the Sobolev approximation.

stimulated_emission_factors

Stimulated emission factors for the lines.

stim_recomb_corrected_photoionization_rate_coeff

Corrected photoionization rate coefficients for continuum transitions.

spontaneous_recombination_coeff

Spontaneous recombination coefficients for continuum transitions.

coll_deexc_coeff

Collisional de-excitation coefficients.

coll_exc_coeff

Collisional excitation coefficients.

coll_ion_coeff

Collisional ionization coefficients.

coll_recomb_coeff

Collisional recombination coefficients.

electron_densities

Electron number densities for each cell.

delta_E_yg

Energy differences for transitions.

Returns:

MacroAtomState

State of the macro atom including continuum transitions, ready to be placed into the OpacityState.

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.