GUIBRUSHR.Retrieval.ModelCalculation.ModelData module

ModelData Module

This module contains the core ModelData class for atmospheric retrieval calculations. It handles parameter management, model calculations, and likelihood evaluations for both high-resolution and low-resolution observations.

This is the CORE of the code - all logic and sequence of operations are preserved.

GUIBRUSHR.Retrieval.ModelCalculation.ModelData.get_param_array_initial_value(array, index, single_value=True)

Get initial parameter value from array at specified index.

Parameters:

• array – Parameter array

• index – Index to retrieve

• single_value – If True, return single value, else return array

Returns:

Initial parameter value or None if not found

class GUIBRUSHR.Retrieval.ModelCalculation.ModelData.ModelData(path_params=None, path_df=None, id_process=None, table_output_file=None, minwlen_lr=None, maxwlen_lr=None, minwlen_hr=None, maxwlen_hr=None, model_type='Retrieval', lbl_sampling_hr=None, lbl_sampling_lr=None, range_min=None, range_max=None, nlayers=None, manual_model_obj=None, load_new_opacities=True, path_default=None)

Bases: object

Core class for atmospheric retrieval model data and calculations.

This class manages all aspects of atmospheric modeling including: - Parameter initialization and management - Model calculations for both high and low resolution - Likelihood evaluations - MCMC chain operations

path_default

Default path for operations

params_list

List of all possible parameters

list_multiple_param

Parameters that can have multiple values

clight

Speed of light constant

model_type

Type of model (Retrieval, Model, etc.)

atmosphere

Atmosphere object for calculations

retrieval_data

Retrieval configuration data

bestpars_data

Best parameters data

random_obj

Random number generator object

__init__(path_params=None, path_df=None, id_process=None, table_output_file=None, minwlen_lr=None, maxwlen_lr=None, minwlen_hr=None, maxwlen_hr=None, model_type='Retrieval', lbl_sampling_hr=None, lbl_sampling_lr=None, range_min=None, range_max=None, nlayers=None, manual_model_obj=None, load_new_opacities=True, path_default=None)

Initialize ModelData object.

Parameters:

• path_params – Path to parameters file

• path_df – Path to dataframe file

• id_process – Process ID for parallel operations

• table_output_file – Output file for table data

• minwlen_lr – Minimum wavelength for low resolution

• maxwlen_lr – Maximum wavelength for low resolution

• minwlen_hr – Minimum wavelength for high resolution

• maxwlen_hr – Maximum wavelength for high resolution

• model_type – Type of model calculation

• lbl_sampling_hr – Line-by-line sampling parameter hr

• lbl_sampling_lr – Line-by-line sampling parameter lr

• range_min – Minimum pressure range

• range_max – Maximum pressure range

• nlayers – Number of atmospheric layers

• manual_model_obj – Manual model object for direct initialization

• load_new_opacities – Whether to load new opacity data

• path_default – Default working directory path

populate_from_manual_model(manual_model_obj, load_new_opacities, minwlen_lr, maxwlen_lr, minwlen_hr, maxwlen_hr, range_min_press=None, range_max_press=None, nlayers=None)

Populate model data from a manual model object.

This method initializes the model using parameters from a manual model object instead of reading from parameter files. It processes both parameter arrays and molecule lists to set up the atmospheric model.

Parameters:

• manual_model_obj – Manual model object containing parameters and molecules

• load_new_opacities – Whether to load new opacity data

• minwlen_lr – Minimum wavelength for low resolution

• maxwlen_lr – Maximum wavelength for low resolution

• minwlen_hr – Minimum wavelength for high resolution

• maxwlen_hr – Maximum wavelength for high resolution

• range_min_press – Minimum pressure range

• range_max_press – Maximum pressure range

• nlayers – Number of atmospheric layers

add_param_manual_model(name, value_during_retrieval, constant_VMR, mass_elem, molec_formula, name_for_list_molec, scale, rayleigh, rayleigh_species, line_species, line_species_isotope, line_species_complete_name_hr, line_species_complete_name_lr, list_bestpars, list_bestpars_initial_value, isotope, list_fixed, list_condensed_molecules)

Add a parameter from manual model to the parameter management system.

This method processes a single parameter from a manual model object and adds it to the appropriate parameter lists based on its properties.

Parameters:

• name – Parameter name

• value_during_retrieval – Parameter value for retrieval

• constant_VMR – Whether VMR is constant

• mass_elem – Molecular mass

• molec_formula – Molecular formula

• name_for_list_molec – Name for molecule list

• scale – Scale factor list

• rayleigh – Whether Rayleigh scattering applies

• rayleigh_species – List of Rayleigh species

• line_species – List of line species

• line_species_isotope – List of isotopes

• line_species_complete_name_hr – List of complete species names HR

• line_species_complete_name_lr – List of complete species names LR

• list_bestpars – List of best parameters

• list_bestpars_initial_value – List of initial values

• isotope – Isotope information

• list_fixed – List of fixed parameters

• list_condensed_molecules – List of condensed molecules

Returns:

Tuple of updated parameter lists

read_df_parameters(path_df_parameters)

Read df_parameters.csv file containing the fitting parameters.

This method reads a CSV file containing parameter definitions and processes each parameter to build the complete parameter structure for the model.

Parameters:

path_df_parameters – Path to the parameters CSV file

Returns:

• mass_vector: List of molecular masses

• scale: Array of scale factors

• rayleigh_species: List of Rayleigh scattering species

• line_species: List of line species

• line_species_isotope: List of isotope information

• line_species_complete_name_hr: List of complete HR species names

• line_species_complete_name_lr: List of complete LR species names

• list_bestpars: List of best fit parameters

• list_bestpars_initial_value: List of initial parameter values

• list_fixed: List of fixed parameters

• list_condensed_molecules: List of condensed phase molecules

Return type:

Tuple containing all processed parameter information

parameter_management(name_for_retrieval, in_bestpars_param, scale_param, constant_vmr_param, range_min_param, range_max_param, molec_param, molec_formula_param, mass_param, name_for_list_molec, rayleigh_species_param, value_during_retrieval, sigma_prior_param, isotope, opacity_name_lr, scale, rayleigh_species, line_species, line_species_isotope, line_species_complete_name_hr, line_species_complete_name_lr, list_bestpars, list_bestpars_initial_value, list_fixed, list_condensed_molecules)

Manage parameter processing and categorization for the retrieval system.

This method handles the complex logic of processing individual parameters and categorizing them into appropriate lists based on their properties. It manages parameter creation, updates, and classification into different species types (Rayleigh, line species, condensed molecules).

Parameters:

• name_for_retrieval – Parameter name used in retrieval

• in_bestpars_param – Whether parameter is in best parameters list

• scale_param – Scale factor for parameter

• constant_vmr_param – Whether VMR is constant

• range_min_param – Minimum parameter range

• range_max_param – Maximum parameter range

• molec_param – Whether parameter is molecular

• molec_formula_param – Molecular formula

• mass_param – Molecular mass

• name_for_list_molec – Name for molecule list

• rayleigh_species_param – Whether parameter is Rayleigh species

• value_during_retrieval – Parameter value during retrieval

• sigma_prior_param – Sigma prior for parameter

• isotope – Isotope information

• opacity_name_lr – Opacity name for low resolution

• scale – Scale factors list

• rayleigh_species – Rayleigh species list

• line_species – Line species list

• line_species_isotope – Isotope list

• line_species_complete_name_hr – Complete species names list HR

• line_species_complete_name_lr – Complete species names list LR

• list_bestpars – Best parameters list

• list_bestpars_initial_value – Initial values list

• list_fixed – Fixed parameters list

• list_condensed_molecules – Condensed molecules list

Returns:

Tuple of updated parameter lists

read_df_information(path_df_information, df_parameters, id_process, table_output_file, minwlen_lr, maxwlen_lr, minwlen_hr, maxwlen_hr, range_min, range_max, nlayers)

Read and process general information from configuration CSV file.

This method reads the main configuration file containing instrument setup, atmospheric parameters, target properties, and retrieval settings. It initializes all core objects needed for the atmospheric retrieval including instruments, atmosphere, target, and retrieval configuration.

Parameters:

• path_df_information – Path to the general information CSV file

• df_parameters – Processed parameter data from read_df_parameters

• id_process – Process ID for parallel operations

• table_output_file – Output file for logging

• minwlen_lr – Minimum wavelength for low resolution

• maxwlen_lr – Maximum wavelength for low resolution

• minwlen_hr – Minimum wavelength for high resolution

• maxwlen_hr – Maximum wavelength for high resolution

• range_min – Minimum pressure range override (overrides CSV value if provided)

• range_max – Maximum pressure range override (overrides CSV value if provided)

• nlayers – Number of atmospheric layers for retrieval

night_data_extraction()

Extract and process night observation data for each instrument.

This method handles the extraction and organization of night observation data, including path setup, file archiving (for retrieval mode), and creation of Night objects for each observation date. The method handles different processing modes (Model, Manual, Retrieval) with appropriate file handling.

get_value(params, name, single_value=True)

Extract value of named parameter from params array.

Parameters:

• params – Array of parameter objects

• name – Parameter name to extract

• single_value – If True, return single value, else return array

Returns:

Parameter value(s) or None if parameter not found

get_index(param_name)

Find index of parameter with given name in the parameters list.

This method handles both exact parameter names and parameter names with numeric suffixes (e.g., ‘jitter1’, ‘jitter2’ -> ‘jitter’).

Parameters:

param_name – Name of parameter to find

Returns:

Index of parameter in params_list

calculate_mass_fraction(temperature, metallicity, c_o_ratio, si_o_ratio_final, vmr_peak_arr, pressure_peak_arr, width_peak_arr)

Compute mass mixing ratios for atmospheric species.

This method calculates mass mixing ratios based on the selected chemistry model (equilibrium, free chemistry, or hybrid). It handles volume mixing ratio calculations, mean molecular weight computation, and species abundance adjustments for dissociation effects.

Parameters:

• temperature – 1D temperature profile array

• metallicity – log(metallicity) enhancement factor for equilibrium chemistry

• c_o_ratio – Carbon-to-oxygen ratio for equilibrium chemistry

• si_o_ratio_final – Si-to-oxygen ratio for equilibrium chemistry

• vmr_peak_arr – VMR peak values for variable abundance profiles

• pressure_peak_arr – Pressure peak positions for variable profiles

• width_peak_arr – Width parameters for variable abundance profiles

Returns:

• mass_fraction: Dictionary of mass mixing ratio profiles {species name: 1D profile} for each species

• MMW: 1D mean molecular weight profile array

• vmr: 2D volume mixing ratio array of shape [nlayers, nmol]

• mean_VMR_and_MF_string: String containing mean VMR and mass fractions per species

• mean_VMR_and_MF_dict: Dictionary mapping species to their mean VMR, MF, and linelist name

Return type:

Tuple containing

calculate_det(params)

Calculate the determinant for prior probability evaluation.

This method computes the determinant term used in Bayesian parameter estimation, incorporating Gaussian priors for parameters that have sigma_prior values defined.

Parameters:

params – Array of parameter objects

Returns:

Determinant value for prior probability calculation

Return type:

det

high_resolution_lhood(temperature, mass_fraction, vmr, MMW, dict_calc_model)

Compute high-resolution likelihood with advanced spectral processing.

This method performs the most complex spectral processing in the atmospheric retrieval system. It handles: 1. Full-resolution atmospheric model calculation 2. Instrumental resolution convolution 3. Stellar rotation broadening (solid body rotation) 4. Orbital dynamics and Doppler shifts 5. Telluric removal via Principal Component Analysis (PCA) 6. Chi-square likelihood evaluation against observations

The method preserves exact mathematical operations critical for high-precision atmospheric spectroscopy and exoplanet detection.

Parameters:

• temperature – Atmospheric temperature profile

• mass_fraction – Mass fraction profiles for all species

• vmr – Volume mixing ratios for all species

• MMW – Mean molecular weight profile

• dict_calc_model – Dictionary containing all model parameters

Returns:

• status: True if successful, False if errors occurred

• lhood: Log-likelihood value

• wl_full_resolution_HR: Full resolution wavelength array

• depth_full_resolution_HR: Full resolution spectrum

• opacity_contribution_HR: Opacity contributions (for plotting)

• lh_high_resolution: Dictionary of per-instrument per-night likelihood details

Return type:

Tuple containing

low_resolution_lhood(temperature, mass_fraction, vmr, MMW, dict_calc_model, rp)

Compute likelihood for low-resolution observations.

This method calculates the likelihood by comparing the binned theoretical spectrum with low-resolution observational data. It handles spectral binning, offset corrections, and chi-square calculation for each instrument.

Parameters:

• temperature – Temperature profile

• mass_fraction – Mass fraction profiles for species

• vmr – Volume mixing ratios

• MMW – Mean molecular weight profile

• dict_calc_model – Dictionary containing model calculation parameters

• rp – Planet radius in cm

Returns:

• lhood: Log-likelihood value

• wl_full_resolution_LR: Full resolution wavelength array

• depth_full_resolution_LR: Full resolution spectrum

• wl_binned_LR_complete: Binned wavelength arrays for all instruments

• spectrum_binned_LR_complete: Binned spectra for all instruments

• opacity_contribution_LR: Opacity contributions (if model plotting)

• lh_low_resolution: Dictionary of per-instrument likelihood details

Return type:

Tuple containing

lh_function_gib(params)

Evaluate the core likelihood function for atmospheric retrieval.

This is the HEART of the atmospheric retrieval system. It takes input parameters, performs boundary checks, extracts all parameter values, calculates temperature profiles, computes mass fractions, and evaluates both high-resolution and low-resolution likelihoods.

The function preserves the exact sequence of operations critical for atmospheric modeling and MCMC retrieval.

Parameters:

params – List of ParamForModel objects containing all retrieval parameters

Returns:

• lhood: Log-likelihood value (float)

• det: Determinant value for Bayesian priors (float)

• not_retrieval_obj: NotRetrieval object with model results (or None)

Return type:

Tuple containing

parallel_chain(index_core, j, return_dict, oldpars, oldchi2, olddet, pars_r1, pars_r2)

Execute parallel MCMC chain step for differential evolution.

This method implements one step of the differential evolution MCMC algorithm in parallel. It calculates new parameter values using the DE formula and evaluates the likelihood to decide whether to accept or reject the step.

Parameters:

• index_core – Index of the core.

• j – Chain index

• return_dict – Shared dictionary for returning results

• oldpars – Current parameter values for this chain

• oldchi2 – Current chi-square value for this chain

• olddet – Current determinant value for this chain

• pars_r1 – Parameter values from random chain 1

• pars_r2 – Parameter values from random chain 2

run_multiple_processes_manager_version(old_pars, old_chi, old_det)

Run MCMC chain steps in parallel using multiprocessing Manager.

This method distributes chain steps across multiple processes using differential evolution MCMC, with a shared Manager dictionary for collecting results.

Parameters:

• old_pars – Current parameter values for all chains, shape (nfit, nchains)

• old_chi – Current chi-square values for all chains, shape (nchains,)

• old_det – Current determinant values for all chains, shape (nchains,)

Returns:

Manager dictionary mapping core index to array of

StructReturnExofast results

Return type:

return_dict

run_multiple_processes(old_pars, old_chi, old_det, use_pool=False)

Run MCMC chain steps in parallel using the Manager-based approach.

Parameters:

• old_pars – Current parameter values for all chains, shape (nfit, nchains)

• old_chi – Current chi-square values for all chains, shape (nchains,)

• old_det – Current determinant values for all chains, shape (nchains,)

• use_pool – Currently unused; Manager approach is always used

Returns:

Dictionary containing results from all processes

Return type:

return_dict

create_param_full(newpars_chain)

Create full parameter array from chain parameter values.

This method reconstructs the complete parameter array from the reduced set of parameters used in the MCMC chain. It handles both single-value parameters and multi-value parameters (like jitter, f_rot arrays).

The logic preserves the exact sequence of operations: 1. Single parameters get assigned directly 2. Multi-value parameters (jitter, f_rot, etc.) get collected into arrays

Parameters:

newpars_chain – Array of parameter values from MCMC chain

Returns:

Complete parameter array with all values assigned

Return type:

param_full