petitRADTRANS.retrieval.retrieval_config#

Attributes#

`tfpd`
`_UNSET`

Classes#

RetrievalConfig

Contain all the data and model level information necessary to run a petitRADTRANS retrieval.

Module Contents#

petitRADTRANS.retrieval.retrieval_config.tfpd#

petitRADTRANS.retrieval.retrieval_config._UNSET#

class petitRADTRANS.retrieval.retrieval_config.RetrievalConfig(retrieval_name: str = 'retrieval_name', run_mode: str = 'retrieval', sampler_type: str = 'pymultinest', adaptive_mesh_refinement: bool = False, scattering_in_emission: bool = False, pressures: jax.typing.ArrayLike | None = None, feautrier_chunk_size: int | None = None, chunk_feautrier: bool = True, adaptive_feautrier_iterations: bool = False, amr=_UNSET)#

Contain all the data and model level information necessary to run a petitRADTRANS retrieval.

The name of the class will be used to name outputs. This class is passed to the Retrieval, which runs the actual pymultinest retrieval and produces the outputs.

The general usage of this class is to define it, add the parameters and their priors, add the opacity sources, the data together with a model for each dataset, and then configure a few plotting arguments.

Args:

retrieval_namestr: Name of this retrieval. Make it informative so that you can keep track of the outputs!
run_modestr: Can be either ‘retrieval’, which runs the retrieval normally using pymultinest, or ‘evaluate’, which produces plots from the best fit parameters stored in the output post_equal_weights file.
adaptive_mesh_refinementbool: Use an adaptive high resolution pressure grid around the location of cloud condensation. This will increase the size of the pressure grid by a constant factor that can be adjusted in the setup_pres function.
scattering_in_emissionbool: If using emission spectra, turn scattering on or off.
pressuresnumpy.array: A log-spaced array of pressures over which to retrieve. 100 points is standard, between 10^-6 and 10^3.
feautrier_chunk_sizeint, optional: Number of frequency bins solved per chunk of the Feautrier scattering solver used for emission spectra. Smaller values reduce the peak memory of the radiative transfer at the cost of a modest amount of extra scan overhead, which is useful on memory-constrained GPUs. If None (default), the value is taken from the PRT_FEAUTRIER_CHUNK_SIZE environment variable (falling back to a built-in default). This is forwarded to the ModelContext objects used to compute the radiative transfer.
chunk_feautrierbool: Whether the Feautrier scattering solver chunks the frequency axis (see feautrier_chunk_size). Only relevant when scattering_in_emission is True. Forwarded to the ModelContext objects.
adaptive_feautrier_iterationsbool: Whether the Feautrier scattering solver adaptively sets the number of iterations based on the photon destruction probability. Only relevant when scattering_in_emission is True. Forwarded to the ModelContext objects.

retrieval_name = 'retrieval_name'#

run_mode = 'retrieval'#

sampler_type = 'pymultinest'#

adaptive_mesh_refinement = False#

scaling = 1#

width = 1#

scattering_in_emission = False#

feautrier_chunk_size = None#

chunk_feautrier = True#

adaptive_feautrier_iterations = False#

parameters#

data#

instruments = ()#

line_species = ()#

cloud_species = ()#

rayleigh_species = ()#

continuum_opacities = ()#

_setup_pres(scaling: int = 10, width: int = 3) → jax.typing.ArrayLike#

add_parameter(name: str, is_free_parameter: bool, value: float | None = None, distribution: Any | None = None, plot_in_corner: bool = False, corner_ranges: tuple[float, float] | None = None, corner_transform: Callable | None = None, transform_prior_cube_coordinate: Callable | None = None, corner_label: str | None = None, units: Any | None = None, free=_UNSET) → None#

This function adds a Parameter (see parameter.py) to the dictionary of parameters. A Parameter has a name and a boolean parameter to set whether it is a free or fixed parameter during the retrieval. In addition, a value can be set, or a prior function can be given that transforms a random variable in [0,1] to the physical dimensions of the Parameter.

Args:

namestr: The name of the parameter. Must match the name used in the model function for the retrieval.
freebool: True if the parameter is a free parameter in the retrieval, false if it is fixed.
valuefloat: The value of the parameter in the units used by the model function.
transform_prior_cube_coordinatemethod: A function that transforms the unit interval to the physical units of the parameter. Typically given as a lambda function.
unitsastropy.units.UnitBase, optional: The physical units of the parameter value. Defaults to None (value already in the units expected by the model function). When set to an astropy unit, model functions can convert the value to the units required by the radiative transfer (e.g. cm, g). Currently used by planet_radius, system_distance, and planet_mass (and their aliases).

_add_uniform_free_parameter(name: str, lower: float, upper: float, corner_label: str = None) → None#

static _default_covariance_parameter_priors(data_object: petitRADTRANS.retrieval.data.Data) → dict[str, tuple[float, float]]#

_add_covariance_hyperparameters(data_object: petitRADTRANS.retrieval.data.Data, covariance_mode: str, n_local_covariance_kernels: int, covariance_parameter_priors: dict | None = None) → None#

static list_available_line_species() → set[str]#: List the currently installed opacity tables that are available for species that contribute to the line opacity.

static list_available_cloud_species() → set[str]#: List the currently installed opacity tables that are available for cloud species.

static list_available_cia_species() → set[str]#: List the currently installed opacity tables that are available for CIA species.

set_line_species(line_species: list[str] | tuple[str], use_equilibrium_chemistry: bool = False, free_mass_fraction_limits: tuple[float, float] = (-6.0, -0.5), plot_in_corner: bool = True, linelist=_UNSET, eq=_UNSET, abund_lim=_UNSET) → None#

Set RadTrans.line_species

This function adds a list of species to the pRT object that will define the line opacities of the model. The values in the list are strings, with the names matching the pRT opacity names, which vary between the c-k line opacities and the line-by-line opacities.

Args:

line_speciesList(str): The list of species to include in the retrieval
use_equilibrium_chemistrybool: If false, the retrieval should use free chemistry, and Parameters for the abundance of each species in the line_species will be added to the retrieval. Otherwise, equilibrium chemistry will be used. If you need fine control species, use the add_line_species and set up each species individually.
free_mass_fraction_limitsTuple(float,float): If free is True, this sets the boundaries of the uniform prior that will be applied for each species in line_species. The range of the prior goes from free_mass_fraction_limits[0] to free_mass_fraction_limits[1]. The abundance limits must be given in log10 units of the mass fraction.

set_rayleigh_species(rayleigh_species: list[str] = _UNSET, linelist=_UNSET) → None#

Set the list of species that contribute to the rayleigh scattering in the pRT object.

Args:

rayleigh_speciesList(str): A list of species that contribute to the rayleigh opacity.

set_continuum_opacities(continuum_opacities: list[str] = _UNSET, linelist=_UNSET) → None#

Set the list of species that contribute to the continuum opacity in the pRT object.

Args:

continuum_opacitiesList(str): A list of species that contribute to the continuum opacity.

add_line_species(species: str, use_equilibrium_chemistry: bool = False, free_mass_fraction_limits: tuple[float, float] = (-6.0, -0.5), fixed_mass_fraction_value: float | None = None, plot_in_corner: bool = True, corner_label: str | None = None, corner_ranges: tuple[float, float] | None = None, eq=_UNSET, abund_lim=_UNSET, fixed_abund=_UNSET) → None#

This function adds a single species to the pRT object that will define the line opacities of the model. The name must match the pRT opacity name, which vary between the c-k line opacities and the line-by-line opacities.

Args:

speciesstr: The species to include in the retrieval
use_equilibrium_chemistrybool: If False, the retrieval should use free chemistry, and Parameters for the abundance of the species will be added to the retrieval. Otherwise, (dis)equilibrium chemistry will be used.
free_mass_fraction_limitsTuple(float,float): If free is True, this sets the boundaries of the uniform prior that will be applied the species given. The range of the prior goes from free_mass_fraction_limits[0] to free_mass_fraction_limits[1] The abundance limits must be given in log10 units of the mass fraction.
fixed_mass_fraction_valuefloat: The log-mass fraction abundance of the species. Currently only supports vertically constant abundances. If this is set, then the species will not be a free parameter in the retrieval.

add_pressure_varying_line_species(species: str, mode: str = 'linear', pressure_spacing: str = 'relative', n_nodes: int = 3, free_mass_fraction_limits: tuple[float, float] = (-7.0, 0.0), log_pressure_range_prior: tuple[float, float] = (0, 9), fixed_pressure_node_species: str | None = None, abund_lim=_UNSET) → None#

This function adds a single species to the Radtrans object that will define the line opacities of the model. The name must match the pRT opacity name, which vary between the c-k line opacities and the line-by-line opacities. This species will have and abundance that varies with pressure, defined by the retrieved abundance at each of the provided abundance nodes.

This function adds a set of parameters to the retrieval to define the abundance profile of the species.

{species}_{mode}_abundance_profile defines which profile will be used (fixed parameter)
{species}_n_abundance_nodes sets the number of abundance nodes (fixed parameter)
{species}_n_pressure_nodes sets the number of pressure nodes (n_nodes - 2) (fixed parameter)
{species}_interpolation_mode sets the pressure spacing mode (fixed parameter)
{species}_pressure_node_{i} for i in 0 to n_nodes-2, the pressure at each node (free parameter)
{species}_abundance_node_{i} for i in 0 to n_nodes, the abundance at each node (free parameter)

Args:

species: str: The species to include in the retrieval
mode: str: One of ‘linear’, ‘cubic’, or ‘stepped’ - determines the interpolation method between abundance nodes.
pressure_spacing: str: One of ‘relative’, ‘absolute’, or ‘fixed’ - determines whether the pressure nodes are spaced relative to the top of the atmosphere pressure, retrieved in absolute log pressue, or fixed to the pressure nodes set by fixed_pressure_node_species.
n_nodes: int: The number of abundance nodes to use in the retrieval, including top and bottom nodes.
free_mass_fraction_limitsTuple(float,float): If free is True, this sets the boundaries of the uniform prior that will be applied the species given. The range of the prior goes from free_mass_fraction_limits[0] to free_mass_fraction_limits[1] The abundance limits must be given in log10 units of the mass fraction.
log_pressure_range_prior: Tuple(float,float): The prior range on the log pressure of the pressure nodes in log bar, only used if pressure_spacing is ‘absolute’ or ‘relative’.
fixed_pressure_node_species: str: If pressure_spacing is ‘fixed’, this species pressure nodes will be used as the pressure nodes. Note that this species must already have been added to the retrieval with add_pressure_varying_line_species.

remove_species_lines(species: str, free: bool = False) → None#

This function removes a species from the pRT line list, and if using a free chemistry retrieval, removes the associated Parameter of the species.

Args:

speciesstr: The species to remove from the retrieval
freebool: If true, the retrieval should use free chemistry, and Parameters for the abundance of the species will be removed to the retrieval

add_cloud_species(species: str, use_equilibrium_chemistry: bool = True, free_mass_fraction_limits: tuple[float, float] = (-3.5, 1.5), cloud_base_pressure_limits: tuple[float, float] | None = None, equilbrium_mass_fraction_scaling_factor: tuple[float, float] | None = None, fixed_mass_fraction_value: float | None = None, fixed_base_pressure_value: float | None = None, eq=_UNSET, abund_lim=_UNSET, p_base_lim=_UNSET, scaling_factor=_UNSET, fixed_abund=_UNSET, fixed_base=_UNSET) → None#

This function adds a single cloud species to the list of species. Optionally, it will add parameters to allow for a retrieval using an ackermann-marley model. If an equilibrium condensation model is used in th retrieval model function (use_equilibrium_chemistry=True), then a parameter is added that scales the equilibrium cloud abundance, as in Molliere (2020). If eq is false, two parameters are added, the cloud abundnace and the cloud base pressure. The limits set the prior ranges, both on a log scale.

NOTE: As of pRT version 2.4.9, the behaviour of this function has changed. In previous versions the abundance limits were set from free_mass_fraction_limits[0] to (free_mass_fraction_limits[0] + free_mass_fraction_limits[1]). This has been changed so that the limits of the prior range are from free_mass_fraction_limits[0] to free_mass_fraction_limits[1] (ie the actual boundaries). The same is true for PBase_lim.

Args:

speciesstr: Name of the pRT cloud species, including the cloud shape tag.
use_equilibrium_chemistrybool: Does the retrieval model use an equilibrium cloud model. This restricts the available species!
free_mass_fraction_limitstuple(float,float): If use_equilibrium_chemistry is True, this sets the prior range on the log mass fraction of the cloud species relative to the equilibrium abundance, with a typical range being (-3.5, 1.5). If use_equilibrium_chemistry is False, this sets the prior range on the actual log mass fraction abundance of the cloud species, with a typical range being (-5.0, 0.0). The abundance limits must be given in log10 units of the mass fraction.
cloud_base_pressure_limitstuple(float,float): Only used if not using an equilibrium model. Sets the prior range on the log10 of the cloud base pressure in bar, e.g. (-3, 3). If None, no cloud base pressure parameter is added.
equilbrium_mass_fraction_scaling_factortuple(float,float): If provided, adds a free parameter eq_scaling_{cloud_name} that scales the equilibrium condensate mass fraction. The tuple defines the (lower, upper) bounds of the uniform prior on this scaling factor in log10 space, e.g. (-3.0, 1.0). Only used when use_equilibrium_chemistry is True. If None, no scaling parameter is added.
fixed_mass_fraction_valueOptional(float): A vertically constant log mass fraction abundance for the cloud species. If set, this will not be a free parameter in the retrieval. Only compatible with non-equilibrium clouds.
fixed_base_pressure_valueOptional(float): The log cloud base pressure. If set, fixes this parameter to a constant value, and it will not be a free parameter in the retrieval. Only compatible with non-equilibrium clouds. Not yet compatible with most built in pRT models.

add_data(name: str, model_generating_function: Callable[Ellipsis, tuple[jax.typing.ArrayLike, jax.typing.ArrayLike, jax.typing.ArrayLike]] | None = None, path_to_observations: str | None = None, wavelengths: jax.typing.ArrayLike | None = None, spectrum: jax.typing.ArrayLike | None = None, uncertainties: jax.typing.ArrayLike | None = None, covariance: jax.typing.ArrayLike | None = None, line_opacity_mode: str = 'c-k', data_resolution: float | None = None, model_resolution: float | None = None, scale_flux: bool = False, scale_uncertainties: bool = False, fit_flux_offset: bool = False, fit_covariance: bool = False, covariance_mode: str = 'none', global_covariance_kernel: str = 'squared_exponential', local_covariance_kernel: str = 'squared_exponential', n_local_covariance_kernels: int = 0, covariance_jitter: float = 0.0, covariance_parameter_priors: dict | None = None, fit_instrumental_resolution: bool = False, external_radtrans_reference: object | None = None, wavelength_boundaries: tuple[float, float] | None = None, wavelength_bin_widths: jax.typing.ArrayLike | None = None, subtract_continuum: bool = False, radtrans_grid: bool = False, radtrans_object: object = None, mask: jax.typing.ArrayLike | None = None, photometric_transformation_function: Callable[Ellipsis, tuple[jax.typing.ArrayLike, jax.typing.ArrayLike]] | None = None, photometric_bin_edges: jax.typing.ArrayLike | None = None, scale=_UNSET, scale_err=_UNSET, offset_bool=_UNSET, resample=_UNSET, concatenate_flux_epochs_variability=_UNSET, variability_atmospheric_column_model_flux_return_mode=_UNSET, atmospheric_column_flux_mixer=_UNSET, photometry=_UNSET) → None#

Create a Data object for the Retrieval class. Each dataset is associated with an instance of petitRadTrans and an atmospheric model. The pRT instance can be overwritten, and associated with an existing pRT instance with the external_pRT_reference parameter. This setup allows for joint or independent retrievals on multiple datasets.

Args:

namestr: Identifier for this data set.
model_generating_functionmethod: A function, typically defined in run_definition.py that returns the model wavelength and spectrum (emission or transmission). This is the function that contains the physics of the model, and calls pRT in order to compute the spectrum.
path_to_observationsstr: Path to observations file, including filename. This can be a txt or dat file containing the wavelength, flux, transit depth and error, or a fits file containing the wavelength, spectrum and covariance matrix. Alternatively, the data information can be directly given by the wavelengths, spectrum, uncertainties, and mask attributes.
wavelengths:: (um) Wavelengths of the data.
spectrum:: Spectrum of the data.
uncertainties:: Uncertainties of the data, in the same units as the spectrum.
covariance:: Covariance matrix of the data, in the same units as the spectrum squared.
line_opacity_modestr: Should the retrieval be run using correlated-k opacities (default, ‘c-k’), or line by line (‘lbl’) opacities? If ‘lbl’ is selected, it is HIGHLY recommended to set the model_resolution parameter. In general, ‘c-k’ mode is recommended for retrievals of everything other than high-resolution (R>40000) spectra.
data_resolutionfloat or jnp.ndarray: Spectral resolution of the instrument. Optional, allows convolution of model to instrumental line width. If the data_resolution is an array, the resolution can vary as as a function of wavelength. The array should have the same shape as the input wavelength array, and should specify the spectral resolution at each wavelength bin.
model_resolutionfloat: Will be None by default. The resolution of the c-k opacity tables in pRT. This will generate a new c-k table using exo-k. The default (and maximum) correlated k resolution in pRT is \(\\lambda/\\Delta \\lambda > 1000\) (R=500). Lowering the resolution will speed up the computation. If integer positive value, and if opacities == 'lbl' is True, then this will sample the high-resolution opacities at the specified resolution. This may be desired in the case where medium-resolution spectra are required with a \(\\lambda/\\Delta \\lambda > 1000\), but much smaller than \(10^6\), which is the resolution of the lbl mode. In this case it may make sense to carry out the calculations with line_by_line_opacity_sampling = 10e5, for example, and then re-binning to the final desired resolution: this may save time! The user should verify whether this leads to solutions which are identical to the re-binned results of the fiducial \(10^6\) resolution. If not, this parameter must not be used. Note the difference between this parameter and the line_by_line_opacity_sampling parameter in the RadTrans class - the actual desired resolution should be set here.
scale_fluxbool: Turn on or off scaling the data by a constant factor. Set to True if scaling the data during the retrieval.
scale_uncertainties:: Turn on or off scaling the uncertainties by a constant factor. Set to True if scaling the uncertainties during the retrieval.
fit_flux_offset:: Turn on or off fitting a flux offset. Set to True if fitting a flux offset during the retrieval.
fit_covariance:: If True, construct a fitted covariance matrix during retrieval using GP-like kernel terms. This is currently supported for 1D spectroscopic datasets only.
covariance_mode:: Covariance model to use. Supported values are 'none', 'local', 'global', and 'global_local'.
global_covariance_kernel:: Global kernel name used when covariance_mode includes a global term.
local_covariance_kernel:: Local kernel name used when covariance_mode includes local terms.
n_local_covariance_kernels:: Number of local covariance kernels to include when using 'global_local' mode.
covariance_jitter:: Small diagonal stabilization term added to the fitted covariance matrix.
external_radtrans_referenceobject: An existing RadTrans object. Leave as none unless you’re sure of what you’re doing.
wavelength_boundariestuple,list: Set the wavelength range of the pRT object. Defaults to a range +/-5% greater than that of the data. Must at least be equal to the range of the data.
wavelength_bin_widthsnumpy.ndarray: Set the wavelength bin width to bin the Radtrans object to the data. Defaults to the data bins.
radtrans_grid: bool: Set to true if data has been binned to a pRT c-k grid.
radtrans_object:: An instance of Radtrans object to be used to generate model spectra in retrievals.
mask:: Mask of the data.

add_time_series_data(name: str, observation_times: jax.typing.ArrayLike, model_generating_function: Callable, n_model_timesteps: int, time_varying_parameters: list[str] | None = None, sinusoidal_parameters: list[str] | None = None, *, path_to_observations: str | None = None, filename_list: list[str] | None = None, wavelengths: jax.typing.ArrayLike | None = None, spectrum: jax.typing.ArrayLike | None = None, uncertainties: jax.typing.ArrayLike | None = None, mask: jax.typing.ArrayLike | None = None, wavelength_bin_widths: jax.typing.ArrayLike | None = None, data_resolution: float | None = None, model_resolution: float | None = None, wavelength_boundaries: tuple | None = None, external_radtrans_reference: str | None = None, line_opacity_mode: str = 'c-k', scale_flux: bool = False, scale_uncertainties: bool = False, fit_flux_offset: bool = False, radtrans_object: object = None, covariance: jax.typing.ArrayLike | None = None, mean_divide: bool = False)#

Create a TimeSeriesData object for time-variable retrievals.

This method creates the data object and registers the fixed N_time parameter. The caller is still responsible for adding the per-timestep or sinusoidal free parameters with appropriate priors via add_parameter().

Args:

namestr: Identifier for this data set.
observation_timesArrayLike: 1-D array of observation times in seconds (absolute or relative to the first observation).
model_generating_functionCallable: A runtime-native model function (e.g. time_series_gradient_emission).
n_model_timestepsint: Number of model spectra computed at regular intervals spanning the observation window. Spectra at the actual observation times are interpolated from these.
time_varying_parameterslist[str], optional: Parameter names that are freely varied at each model timestep. For each name P the retrieval must contain free parameters {P}_t_0 through {P}_t_{n_model_timesteps - 1}.
sinusoidal_parameterslist[str], optional: Parameter names whose time variation is described by a sinusoid. For each name P the retrieval must contain free parameters {P}_amplitude, {P}_period, {P}_phase, and {P}_offset.
path_to_observationsstr, optional: Path to a directory containing individual epoch files when using filename_list.
filename_listlist[str], optional: Per-epoch filenames inside path_to_observations. If given, data will be loaded via TimeSeriesData.load_single_spectrum_txt().
wavelengthsArrayLike, optional: 1-D wavelength grid (micron) shared by all epochs.
spectrumArrayLike, optional: 2-D flux array of shape (N_obs, N_wavelength).
uncertaintiesArrayLike, optional: 2-D uncertainty array matching spectrum.
maskArrayLike, optional: 2-D boolean mask matching spectrum.
wavelength_bin_widthsArrayLike, optional: 1-D or 2-D bin widths.

data_resolution, model_resolution, wavelength_boundaries, external_radtrans_reference, line_opacity_mode, scale_flux, scale_uncertainties, fit_flux_offset, radtrans_object, covariance

Same semantics as add_data().

mean_dividebool: Fit in mean-divided (relative-variability) space: the stored data become F(lambda, t) / <F(lambda)>_t with uncertainties sigma(lambda, t) / <F(lambda)>_t (the time mean is taken over valid epochs per wavelength), and at scoring time the projected model is likewise divided by its own time mean (M(lambda, t) / <M(lambda)>_t). Static (time-constant) model/calibration deficiencies cancel in this ratio while the time-variability signal is preserved against the measured uncertainties – no error inflation is involved. Requires inline spectrum and uncertainties arrays.

add_photometry(path: str, model_generating_function: Callable, model_resolution: float = 10.0, scale_flux: bool = False, wlen_range_micron: tuple[float, float] = None, photometric_transformation_function: Callable = None, external_prt_reference: object = None, opacity_mode: str = 'c-k') → None#

Create a Data class object for each photometric point in a photometry file. The photometry file must be a csv file and have the following structure: name, lower wavelength bound [um], upper wavelength boundary[um], flux [W/m2/micron], flux error [W/m2/micron]

Photometric data requires a transformation function to convert a spectrum into synthetic photometry. You must provide this function yourself, or have the species package installed. If using species, the name in the data file must be of the format instrument/filter.

Args:

model_generating_functionstr: Identifier for this data set.
pathstr: Path to observations file, including filename.
model_resolutionfloat: Spectral resolution of the model, allowing for low resolution correlated k tables from exo-k.
scale_fluxbool: Turn on or off scaling the data by a constant factor. Currently only set up to scale all photometric data in a given file.
wlen_range_micronTuple: A pair of wavelengths in units of micron that determine the lower and upper boundaries of the model computation.
external_prt_referencestr: The name of an existing Data object. This object’s prt_object will be used to calculate the chi squared of the new Data object. This is useful when two datasets overlap, as only one model computation is required to compute the log likelihood of both datasets.
photometric_transformation_functionmethod: A function that will transform a spectrum into an average synthetic photometric point, typically accounting for filter transmission.
opacity_mode: str: Opacity mode.