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_metadata

DataFrame containing macro atom transition metadata.

lines_level_upper

MultiIndex containing line upper level information.

Returns:

tuple[pd.Series, pd.Series]

Line to macro level upper mapping and unique source indices reference.

create_macro_block_references(macro_atom_transition_metadata: DataFrame) → Series

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_metadata

DataFrame containing metadata for macro atom transitions.

Returns:

pd.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: DataFrame) → None

Create 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, macro_atom_transition_metadata: DataFrame) → DataFrame

Normalize transition probabilities by their source levels.

Parameters:

probabilities_df

DataFrame containing transition probabilities.

macro_atom_transition_metadata:

Dataframe containing all metadata for the transitions. Needed to obtain sources to normalize by.

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

normalize_cooling_block_by_rate_fractions(probabilities: DataFrame, macro_atom_transition_metadata: DataFrame, coll_exc_cool_rate: ndarray, coll_exc_cool_arr: ndarray, coll_ion_cool_rate: ndarray, coll_ion_cool_arr: ndarray, fb_cool_rate: ndarray, fb_cool_probs_arr: ndarray, ff_cool_rate: ndarray) → tuple[DataFrame, DataFrame]

Create and normalize k-packet source block with cooling transitions.

This method handles cooling transitions (free-free, free-bound, collisional) which are not regular macroatom transitions. They must be added to and normalized separately because we cannot complete the normalization until all cooling pathways exist. The method incorporates cooling rates to establish the proper relative probabilities for deactivation pathways.

Parameters:

probabilities

DataFrame containing transition probabilities.

macro_atom_transition_metadata

DataFrame containing all metadata for the transitions.

coll_exc_cool_rate

Collisional excitation cooling rates per cell.

coll_exc_cool_arr

Array of collisional excitation cooling rates by transition.

coll_ion_cool_rate

Collisional ionization cooling rates per cell.

coll_ion_cool_arr

Array of collisional ionization cooling rates by transition.

fb_cool_rate

Free-bound cooling rates per cell.

fb_cool_probs_arr

Array of free-bound cooling probabilities by bound level.

ff_cool_rate

Free-free (bremsstrahlung) cooling rates per cell.

Returns:

probabilities

Probabilities with the cooling block normalized by rate, and free-free deactivation added if it did not exist yet.

macro_atom_transition_metadata

Updated metadata with cooling transitions appended if they did not exist.

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, coll_exc_cool_rate: Series, coll_exc_cool_arr: ndarray, coll_ion_cool_rate: Series, coll_ion_cool_arr: ndarray, fb_cool_rate: Series, fb_cool_probs_arr: ndarray, ff_cool_rate: 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.

coll_exc_cool_rate

Collisional excitation cooling rates per cell.

coll_exc_cool_arr

Array of collisional excitation cooling rates by transition.

coll_ion_cool_rate

Collisional ionization cooling rates per cell.

coll_ion_cool_arr

Array of collisional ionization cooling rates by transition.

fb_cool_rate

Free-bound cooling rates per cell.

fb_cool_probs_arr

Array of free-bound cooling probabilities by bound level.

ff_cool_rate

Free-free (bremsstrahlung) cooling rates per cell.

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.