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

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, selected_continuum_transitions: ndarray = array([], dtype=float64), line_interaction_type: str = 'macroatom')

Bases: BoundBoundMacroAtomSolver

Initialize the ContinuumMacroAtomSolver.

Parameters:

levelspd.DataFrame

DataFrame containing atomic level information.

linespd.DataFrame

DataFrame containing spectral line information.

photoionization_datapd.DataFrame

DataFrame containing photoionization cross-section information.

line_interaction_typestr, optional

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

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:

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.

selected_continuum_transitions: ndarray

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, electron_densities: DataFrame, level_number_density: DataFrame, delta_E_yg: DataFrame) → 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_wingpd.DataFrame

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_sobolevspd.DataFrame

Escape probabilities for the Sobolev approximation.

stimulated_emission_factorsnp.ndarray

Stimulated emission factors for the lines.

stim_recomb_corrected_photoionization_rate_coeffpd.DataFrame

Corrected photoionization rate coefficients for continuum transitions.

spontaneous_recombination_coeffpd.DataFrame

Spontaneous recombination coefficients for continuum 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.