species.util package

Contents

species.util package#

Submodules#

species.util.box_util module#

Utility functions for boxes.

species.util.box_util.update_objectbox(objectbox: ObjectBox, model_param: Dict[str, float], model: str | None = None) ObjectBox[source]#

Function for updating the spectra and/or photometric fluxes in an ObjectBox, for example by applying a flux scaling and/or error inflation.

Parameters:
  • objectbox (species.core.box.ObjectBox) – Box with the object’s data, including the spectra and/or photometric fluxes.

  • model_param (dict) – Dictionary with the model parameters. Should contain the value(s) of the flux scaling and/or the error inflation.

  • model (str, None) – Name of the atmospheric model. Only required for inflating the errors of spectra. Otherwise, the argument can be set to None. Not required when model='petitradtrans' because the error inflation is implemented differently with AtmosphericRetrieval.

Returns:

The input box which includes the spectra with the scaled fluxes and/or inflated errors.

Return type:

species.core.box.ObjectBox

species.util.convert_util module#

Utility functions for converting quantities.

species.util.convert_util.absolute_to_apparent(abs_mag: Tuple[float, float | None] | Tuple[ndarray, ndarray | None], distance: Tuple[float, float | None] | Tuple[ndarray, ndarray | None]) Tuple[float, float | None] | Tuple[ndarray, ndarray | None][source]#

Function for converting an absolute magnitude into an apparent magnitude.

Parameters:
  • abs_mag (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Tuple with the absolute magnitude and uncertainty (mag). The uncertainty on the returned apparent magnitude is simply adopted from the absolute magnitude. Providing the uncertainty is optional and can be set to None.

  • distance (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Tuple with the distance and uncertainty (pc). The uncertainty is optional and can be set to None. The distance uncertainty is currently not used by this function but included so it can be implemented at some point into the error budget.

Returns:

  • float, np.ndarray – Apparent magnitude (mag).

  • float, np.ndarray, None – Uncertainty (mag).

species.util.convert_util.apparent_to_absolute(app_mag: Tuple[float, float | None] | Tuple[ndarray, ndarray | None], distance: Tuple[float, float | None] | Tuple[ndarray, ndarray | None]) Tuple[float, float | None] | Tuple[ndarray, ndarray | None][source]#

Function for converting an apparent magnitude into an absolute magnitude. The uncertainty on the distance is propagated into the uncertainty on the absolute magnitude.

Parameters:
  • app_mag (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Apparent magnitude and uncertainty (mag). The returned error on the absolute magnitude is set to None if the error on the apparent magnitude is set to None, for example app_mag=(15., None).

  • distance (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Distance and uncertainty (pc). The error is not propagated into the error on the absolute magnitude if set to None, for example distance=(20., None).

Returns:

  • float, np.ndarray – Absolute magnitude (mag).

  • float, np.ndarray, None – Uncertainty (mag).

species.util.convert_util.logg_to_mass(logg: float | ndarray, radius: float | ndarray) float | ndarray[source]#

Function for converting \(\log(g)\) and a radius into a mass.

Parameters:
  • logg (float, np.ndarray) – Log10 of the surface gravity (cgs).

  • radius (float, np.ndarray) – Radius (Rjup).

Returns:

Mass (Mjup).

Return type:

float, np.ndarray

species.util.convert_util.logg_to_radius(logg: float | ndarray, mass: float | ndarray) float | ndarray[source]#

Function for converting \(\log(g)\) and a mass into a radius.

Parameters:
  • logg (float, np.ndarray) – Log10 of the surface gravity (cgs).

  • mass (float, np.ndarray) – Mass (Mjup).

Returns:

Radius (Rjup).

Return type:

float, np.ndarray

species.util.convert_util.luminosity_to_teff(luminosity: float | ndarray, radius: float | ndarray) float | ndarray[source]#

Function for converting a luminosity and radius into \(T_\mathrm{eff}\). :param luminosity: Bolometric luminosity ($L_odot$). :type luminosity: float, np.ndarray :param radius: Radius ($R_mathrm{J}$). :type radius: float, np.ndarray

Returns:

Effective temperature (K).

Return type:

float, np.ndarray

species.util.convert_util.mass_to_logg(mass: float | ndarray, radius: float | ndarray) float | ndarray[source]#

Function for converting a mass and radius into \(\log(g)\).

Parameters:
  • mass (float, np.ndarray) – Mass ($M_mathrm{J}$).

  • radius (float, np.ndarray) – Radius ($R_mathrm{J}$).

Returns:

Surface gravity \(\log(g)\).

Return type:

float, np.ndarray

species.util.convert_util.parallax_to_distance(parallax: Tuple[float, float | None] | Tuple[ndarray, ndarray | None]) Tuple[float, float | None] | Tuple[ndarray, ndarray | None][source]#

Function for converting from parallax to distance.

Parameters:

parallax (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Parallax and optional uncertainty (mas). The uncertainty is not used if set to None, for example, parallax=(2., None).

Returns:

  • float, np.ndarray – Distance (pc).

  • float, np.ndarray, None – Uncertainty (pc).

species.util.core_util module#

Module with utility functions for the species core.

species.util.core_util.print_section(sect_title: str, bound_char: str = '-', extra_line: bool = True) None[source]#

Function for printing a section title.

Parameters:
  • sect_title (str) – Section title.

  • bound_char (str) – Boundary character for around the section title.

  • extra_line (bool) – Extra new line at the beginning.

Returns:

None

Return type:

NoneType

species.util.data_util module#

Utility functions for data processing.

species.util.data_util.add_missing(model: str, parameters: List[str], database: File) None[source]#

Function for adding missing grid points with a linear interpolation.

Parameters:
  • model (str) – Atmosphere model.

  • parameters (list(str)) – Model parameters.

  • database (h5py._hl.files.File) – Database.

Returns:

None

Return type:

NoneType

species.util.data_util.convert_units(flux_in: ndarray, units_in: Tuple[str, str], convert_from: bool = True) ndarray[source]#

Function for converting the wavelength units to or from \(\mu\text{m}^{-1}\) and the flux units to or from \(\text{W} \text{m}^{-2} \mu\text{m}^{-1}\).

Parameters:
  • flux_in (np.ndarray) – Array with the input wavelengths and fluxes. The shape of the array should be (n_wavelengths, 3) or (n_wavelengths, 2) with the columns being the wavelengths, flux densities, and optionally the uncertainties. For photometric fluxes, the array should also be 2D but with a single row/wavelength.

  • units_in (tuple(str, str)) – Tuple with the units of the wavelength (“um”, “angstrom”, “nm”, “mm”, “cm”, “m”, “Hz”, “GHz”) and the units of the flux density (“W m-2 um-1”, “W m-2 m-1”, “W m-2 Hz-1”, “erg s-1 cm-2 angstrom-1” “erg s-1 cm-2 Hz-1”, “mJy”, “Jy”, “MJy”). One can use “um” or “µm” interchangeably, and similarly “AA”, “Å”, “A”, or “angstrom”.

  • convert_from (bool) – Convert from units_in to \(\mu\text{m}^{-1}\) and \(\text{W} \text{m}^{-2} \mu\text{m}^{-1}\) when set to True. Or, convert to units_in when set to False.

Returns:

Array with the output in the same shape as flux_in.

Return type:

np.ndarray

species.util.data_util.correlation_to_covariance(cor_matrix: ndarray, spec_sigma: ndarray) ndarray[source]#
Parameters:
  • cor_matrix (np.ndarray) – Correlation matrix of the spectrum.

  • spec_sigma (np.ndarray) – Uncertainties (W m-2 um-1).

Returns:

Covariance matrix of the spectrum.

Return type:

np.ndarray

species.util.data_util.extract_tarfile(data_file: str, data_folder: str, member_list: List[TarInfo] | None = None) None[source]#

Function for safely unpacking a TAR file (see details.

Parameters:
  • data_file (str) – Path of the TAR file.

  • data_folder (str) – Path of the data folder where the TAR file will be extracted.

  • member_list (list(tarfile.TarInfo), None) – List with filenames that should be extracted from the TAR file. All files are extracted if the argument is set to None.

Returns:

None

Return type:

NoneType

species.util.data_util.sort_data(param_teff: ndarray, param_logg: ndarray | None, param_feh: ndarray | None, param_co: ndarray | None, param_fsed: ndarray | None, param_logkzz: ndarray | None, param_adindex: ndarray | None, wavelength: ndarray, flux: ndarray) List[ndarray][source]#
Parameters:
  • param_teff (np.ndarray) – Array with the effective temperature (K) of each spectrum.

  • param_logg (np.ndarray, None) – Array with the log10 of the surface gravity (cm s-2) of each spectrum.

  • param_feh (np.ndarray, None) – Array with the metallicity of each spectrum. Not used if set to None.

  • param_co (np.ndarray, None) – Array with the carbon-to-oxygen ratio of each spectrum. Not used if set to None.

  • param_fsed (np.ndarray, None) – Array with the sedimentation parameter of each spectrum. Not used if set to None.

  • param_logkzz (np.ndarray, None) – Array with the log10 of the eddy diffusion coefficient (cm2 s-1) of each spectrum. Not used if set to None.

  • param_adindex (np.ndarray, None) – Array with the effective adiabatic index. Not used if set to None.

  • wavelength (np.ndarray) – Array with the wavelengths (um).

  • flux (np.ndarray) – Array with the spectra with dimensions (n_spectra, n_wavelengths).

Returns:

  • list(np.ndarray, ) – List with the unique values of the atmosphere parameters (each

  • in a separate array), an – array with the wavelengths, and a multidimensional array with the sorted spectra.

species.util.data_util.update_filter(filter_in)[source]#

Function to update a filter ID from the Vizier Photometry viewer VOTable to the filter ID from the SVO Filter Profile Service.

Parameters:

filter_in (str) – Filter ID in the format of the Vizier Photometry viewer.

Returns:

Filter ID in the format of the SVO Filter Profile Service.

Return type:

str

species.util.data_util.update_sptype(sptypes: ndarray) List[str][source]#

Function to update a list with spectral types to two characters (e.g., M8, L3, or T1). The spectral to is set to NaN in case the first character is not recognized or the second character is not a numerical value.

Parameters:

sptypes (np.ndarray) – Input spectral types.

Returns:

Output spectral types.

Return type:

list(str)

species.util.data_util.write_data(model: str, parameters: List[str], wavel_sampling: float, database: File, data_sorted: List[ndarray]) None[source]#

Function for writing the model spectra and parameters to the database.

Parameters:
  • model (str) – Atmosphere model.

  • parameters (list(str)) – Model parameters.

  • wavel_sampling (float) – Wavelength sampling \(\lambda/\Delta\lambda\).

  • database (h5py._hl.files.File) – HDF5 database.

  • data_sorted (list(np.ndarray)) – Sorted model data with the parameter values, wavelength points (um), and flux densities (W m-2 um-1).

Returns:

None

Return type:

NoneType

species.util.dust_util module#

Utility functions for dust cross sections and extinction.

species.util.dust_util.apply_ism_ext(wavelengths: ndarray, flux: ndarray, v_band_ext: float, v_band_red: float) ndarray[source]#

Function for applying ISM extinction to a spectrum.

wavelengthsnp.ndarray

Wavelengths (um) of the spectrum.

fluxnp.ndarray

Fluxes (W m-2 um-1) of the spectrum.

v_band_extfloat

Extinction (mag) in the $V$ band.

v_band_redfloat

Reddening in the $V$ band.

Returns:

Fluxes (W m-2 um-1) with the extinction applied.

Return type:

np.ndarray

species.util.dust_util.calc_reddening(filters_color: Tuple[str, str], extinction: Tuple[str, float], composition: str = 'MgSiO3', structure: str = 'crystalline', radius_g: float = 1.0) Tuple[float, float][source]#

Function for calculating the reddening of a color given the extinction for a given filter. A log-normal size distribution with a geometric standard deviation of 2 is used as parametrization for the grain sizes (Ackerman & Marley 2001).

Parameters:
  • filters_color (tuple(str, str)) – Filter names for which the extinction is calculated.

  • extinction (str) – Filter name and extinction (mag).

  • composition (str) – Dust composition (‘MgSiO3’ or ‘Fe’).

  • structure (str) – Grain structure (‘crystalline’ or ‘amorphous’).

  • radius_g (float) – Geometric radius of the grain size distribution (um).

Returns:

  • float – Extinction (mag) for filters_color[0].

  • float – Extinction (mag) for filters_color[1].

species.util.dust_util.check_dust_database() str[source]#

Function to check if the dust data is present in the database and add the data if needed.

Returns:

Path of the HDF5 database.

Return type:

str

species.util.dust_util.convert_to_av(filter_name: str, filter_ext: float, v_band_red: float = 3.1) float[source]#

Function for converting the extinction in any filter from the SVO Filter Profile Service to a visual extinction, \(A_V\). This is done by simply scaling the extinction so at the mean wavelength of the filter.

filter_namestr

Filter name for which the extinction will be converted to a visual extinction (i.e. \(A_V\)).

filter_extfloat

Extinction (mag) for the filter_name.

v_band_redfloat

Reddening in the $V$ band.

Returns:

Visual extinction (i.e. \(A_V\)) for which the extinction in the filter_name band is filter_ext.

Return type:

float

species.util.dust_util.dust_cross_section(dn_grains: ndarray, radii: ndarray, wavelength: float, n_index: float, k_index: float) float64[source]#

Function for calculating the extinction cross section for a size distribution of dust grains.

Parameters:
  • dn_grains (np.ndarray) – Number of grains in each radius bin, normalized to a total of 1 grain.

  • radii (np.ndarray) – Grain radii (um).

  • wavelength (float) – Wavelength (um).

  • n_index (float) – Real part of the refractive index.

  • k_index (float) – Imaginary part of the refractive index.

Returns:

Extinction cross section (um2)

Return type:

float

species.util.dust_util.interp_lognorm(inc_phot: List[str], inc_spec: List[str]) Tuple[Dict[str, RegularGridInterpolator | List[RegularGridInterpolator]], ndarray, ndarray][source]#

Function for interpolating the log-normal dust cross sections for each filter and spectrum.

Parameters:
  • inc_phot (list(str)) – List with filter names. Not used if the list is empty.

  • inc_spec (list(str)) – List with the spectrum names (as stored in the database with add_object()). Not used if the list is empty.

Returns:

  • dict – Dictionary with the extinction cross section for each filter and spectrum.

  • np.ndarray – Grid points of the geometric mean radius.

  • np.ndarray – Grid points of the geometric standard deviation.

species.util.dust_util.interp_powerlaw(inc_phot: List[str], inc_spec: List[str]) Tuple[Dict[str, RegularGridInterpolator | List[RegularGridInterpolator]], ndarray, ndarray][source]#

Function for interpolating the power-law dust cross sections for each filter and spectrum.

Parameters:
  • inc_phot (list(str)) – List with filter names. Not used if the list is empty.

  • inc_spec (list(str)) – List with the spectrum names (as stored in the database with add_object()). Not used if the list is empty.

Returns:

  • dict – Dictionary with the extinction cross section for each filter and spectrum.

  • np.ndarray – Grid points of the maximum radius.

  • np.ndarray – Grid points of the power-law exponent.

species.util.dust_util.ism_extinction(av_mag: float, rv_red: float, wavelengths: ndarray | List[float] | float) ndarray[source]#

Function for calculating the optical and IR extinction with the empirical relation from Cardelli et al. (1989).

Parameters:
  • av_mag (float) – Extinction (mag) in the $V$ band.

  • rv_red (float) – Reddening in the $V$ band, R_V = A_V / E(B-V).

  • wavelengths (np.ndarray, list(float), float) – Array or list with the wavelengths (um) for which the extinction is calculated. It is also possible to provide a single value as float.

Returns:

Extinction (mag) at wavelengths.

Return type:

np.ndarray

species.util.dust_util.log_normal_distribution(radius_g: float, sigma_g: float, n_bins: int) Tuple[ndarray, ndarray, ndarray][source]#

Function for returning a log-normal size distribution. See Eq. 9 in Ackerman & Marley (2001).

Parameters:
  • radius_g (float) – Mean geometric radius (um).

  • sigma_g (float) – Geometric standard deviation (dimensionless).

  • n_bins (int) – Number of logarithmically-spaced radius bins.

Returns:

  • np.ndarray – Number of grains in each radius bin, normalized to a total of 1 grain.

  • np.ndarray – Widths of the radius bins (um).

  • np.ndarray – Grain radii (um).

species.util.dust_util.power_law_distribution(exponent: float, radius_min: float, radius_max: float, n_bins: int) Tuple[ndarray, ndarray, ndarray][source]#

Function for returning a power-law size distribution.

Parameters:
  • exponent (float) – Exponent of the power-law size distribution, dn/dr = r**exponent.

  • radius_min (float) – Minimum grain radius (um).

  • radius_max (float) – Maximum grain radius (um).

  • n_bins (int) – Number of logarithmically-spaced radius bins.

Returns:

  • np.ndarray – Number of grains in each radius bin, normalized to a total of 1 grain.

  • np.ndarray – Widths of the radius bins (um).

  • np.ndarray – Grain radii (um).

species.util.fit_util module#

Utility functions for fit results.

species.util.fit_util.get_residuals(datatype: str, spectrum: str, parameters: Dict[str, float], objectbox: ObjectBox, inc_phot: bool | List[str] = True, inc_spec: bool | List[str] = True, radtrans: ReadRadtrans | None = None) ResidualsBox[source]#

Function for calculating the residuals from fitting model or calibration spectra to a set of spectra and/or photometry.

Parameters:
  • datatype (str) – Data type (‘model’ or ‘calibration’).

  • spectrum (str) – Name of the atmospheric model or calibration spectrum.

  • parameters (dict) – Parameters and values for the spectrum

  • objectbox (species.core.box.ObjectBox) – Box with the photometry and/or spectra of an object. A scaling and/or error inflation of the spectra should be applied with update_objectbox() beforehand.

  • inc_phot (bool, list(str)) – Include photometric data in the fit. If a boolean, either all (True) or none (False) of the data are selected. If a list, a subset of filter names (as stored in the database) can be provided.

  • inc_spec (bool, list(str)) – Include spectroscopic data in the fit. If a boolean, either all (True) or none (False) of the data are selected. If a list, a subset of spectrum names (as stored in the database with add_object()) can be provided.

  • radtrans (ReadRadtrans, None) – Instance of ReadRadtrans. Only required with spectrum='petitradtrans'. Make sure that the wavel_range of the ReadRadtrans instance is sufficiently broad to cover all the photometric and spectroscopic data of inc_phot and inc_spec. Not used if set to None.

Returns:

Box with the residuals.

Return type:

species.core.box.ResidualsBox

species.util.fit_util.multi_photometry(datatype: str, spectrum: str, filters: List[str], parameters: Dict[str, float], radtrans: ReadRadtrans | None = None) SynphotBox[source]#

Function for calculating synthetic photometry for a list of filters and a specified atmosphere model and related parameters. This function can for example be used for calculating the synthetic photometry from a best-fit model spectrum. It returns a SynphotBox that can be provided as input to plot_spectrum().

Parameters:
  • datatype (str) – Data type (‘model’ or ‘calibration’).

  • spectrum (str) – Spectrum name (e.g., ‘drift-phoenix’, ‘bt-settl-cifist’, planck’, ‘powerlaw’, ‘petitradtrans’).

  • filters (list(str)) – List with the filter names.

  • parameters (dict) – Dictionary with the model parameters.

  • radtrans (ReadRadtrans, None) – Instance of ReadRadtrans. Only required with spectrum='petitradtrans'`. Make sure that the ``wavel_range of the ReadRadtrans instance is sufficiently broad to cover all the filters. The argument can be set to None for any other model than petitRADTRANS.

Returns:

Box with synthetic photometry.

Return type:

species.core.box.SynphotBox

species.util.model_util module#

Utility functions for model spectra.

species.util.model_util.binary_to_single(param_dict: Dict[str, float], star_index: int) Dict[str, float][source]#

Function for converting a dictionary with atmospheric parameters of a binary system to a dictionary of parameters for one of the two stars.

Parameters:
  • param_dict (dict) – Dictionary with the atmospheric parameters of both stars. The keywords end either with _0 or _1 that correspond with star_index=0 or star_index=1.

  • star_index (int) – Star index (0 or 1) that is used for the parameters in param_dict.

Returns:

Dictionary with the parameters of the selected star.

Return type:

dict

species.util.model_util.convert_model_name(in_name: str) str[source]#

Function for updating a model name for use in plots.

Parameters:

in_name (str) – Model name as used by species.

Returns:

Updated model name for plots.

Return type:

str

species.util.model_util.gaussian_spectrum(wavel_range: Tuple[float, float] | Tuple[float32, float32], model_param: Dict[str, float], spec_res: float = 100.0, double_gaussian: bool = False) ModelBox[source]#

Function for calculating a Gaussian spectrum (i.e. for an emission line).

Parameters:
  • wavel_range (tuple(float, float)) – Tuple with the minimum and maximum wavelength (um).

  • model_param (dict) – Dictionary with the model parameters. Should contain 'gauss_amplitude', 'gauss_mean', 'gauss_sigma', and optionally 'gauss_offset'.

  • spec_res (float) – Spectral resolution (default: 100).

  • double_gaussian (bool) – Set to True for returning a double Gaussian function. In that case, model_param should also contain 'gauss_amplitude_2', 'gauss_mean_2', and 'gauss_sigma_2'.

Returns:

Box with the Gaussian spectrum.

Return type:

species.core.box.ModelBox

species.util.model_util.powerlaw_spectrum(wavel_range: Tuple[float, float] | Tuple[float32, float32], model_param: Dict[str, float], spec_res: float = 100.0) ModelBox[source]#

Function for calculating a power-law spectrum. The power-law function is calculated in log(wavelength)-log(flux) space but stored in the ModelBox in linear wavelength-flux space.

Parameters:
  • wavel_range (tuple(float, float)) – Tuple with the minimum and maximum wavelength (um).

  • model_param (dict) – Dictionary with the model parameters. Should contain ‘log_powerlaw_a’, ‘log_powerlaw_b’, and ‘log_powerlaw_c’.

  • spec_res (float) – Spectral resolution (default: 100).

Returns:

Box with the power-law spectrum.

Return type:

species.core.box.ModelBox

species.util.plot_util module#

Module with utility functions for plotting data.

species.util.plot_util.create_model_label(model_param: Dict[str, float], object_type: str, model_name: str, inc_model_name: bool, leg_param: List[str], param_fmt: Dict[str, str]) str[source]#

” Function for creating a label that includes the parameters of a model spectrum. The label is used in the legend of a SED plot.

Parameters:
  • model_param (dict) – Dictionary with model parameters.

  • model_name (str) – Name of the atmospheric model.

  • inc_model_name (bool) – Include the model name in the label.

  • object_type (str) – Object type (‘planet’ or ‘star’) that determines if Jupiter or solar units are used.

  • leg_param (list(str)) – List with the parameters to include. Apart from atmospheric parameters (e.g. ‘teff’, ‘logg’, ‘radius’) also parameters such as ‘mass’ and ‘luminosity’ can be included. The default atmospheric parameters are included in the legend if the argument is an empty list.

  • param_fmt (dict(str, str)) – Dictionary with formats that will be used for the model parameter. The parameters are included in the legend when plotting the model spectra. Default formats are used if the argument of param_fmt is set to None.

Returns:

Text label that includes the selected parameter names, the model values, and the parameter units.

Return type:

str

species.util.plot_util.field_bounds_ticks(field_range: Tuple[str, str], check_subclass: bool) Tuple[ndarray, ndarray, List[str]][source]#

Function for converting the specified field range into boundaries and labels for the discrete colorbar that is plotted with a color-magnitude or color-color diagram.

Parameters:
  • field_range (tuple(str, str)) – Range of the discrete colorbar for the field objects. The tuple should contain the lower and upper value (‘early M’, ‘late M’, ‘early L’, ‘late L’, ‘early T’, ‘late T’, ‘early Y). Also stellar spectral types can be specified.

  • check_subclass (bool) – Set to True if the discrete colorbar should distinguish early and late spectral types with different colors or set to False if subclasses should not be distinguished.

Returns:

  • np.ndarray – Array with the boundaries for the discrete colorbar.

  • np.ndarray – Array with the midpoints for the discrete colorbar.

  • list(str) – List with the tick labels for the discrete colorbar.

species.util.plot_util.quantity_unit(param: List[str], object_type: str) Tuple[List[str], List[str | None], List[str]][source]#

Function for creating lists with quantities, units, and labels for fitted parameter.

Parameters:
  • param (list) – List with parameter names.

  • object_type (str) – Object type ('planet' or 'star').

Returns:

  • list – List with the quantities.

  • list – List with the units.

  • list – List with the parameter labels for plots.

species.util.plot_util.remove_color_duplicates(object_names: List[str], empirical_names: ndarray) List[int][source]#

” Function for deselecting young/low-gravity objects that will already be plotted individually as directly imaged objects.

Parameters:
  • object_names (list(str)) – List with names of directly imaged planets and brown dwarfs.

  • empirical_names (np.ndarray) – Array with names of young/low-gravity objects.

Returns:

List with selected indices of the young/low-gravity objects.

Return type:

list

species.util.plot_util.sptype_to_index(field_range: Tuple[str, str], spec_types: ndarray, check_subclass: bool) ndarray[source]#

Function for mapping the spectral types of stellar and substellar objects to indices that corresponds with the discrete colorbar of a color-magnitude or color-color diagram.

Parameters:
  • field_range (tuple(str, str)) – Range of the discrete colorbar for the field objects. The tuple should contain the lower and upper value (‘early M’, ‘late M’, ‘early L’, ‘late L’, ‘early T’, ‘late T’, ‘early Y). Also stellar spectral types can be specified.

  • spec_types (np.ndarray) – Array with the spectral types.

  • check_subclass (bool) – Set to True if the discrete colorbar should distinguish early and late spectral types with different colors or set to False if subclasses should not be distinguished.

Returns:

Array with spectral types mapped to indices. Spectral types that are not within the range specified with field_range will be set to NaN.

Return type:

np.ndarray

species.util.plot_util.update_labels(param: List[str], object_type: str = 'planet') List[str][source]#

Function for formatting the model parameters to use them as labels in the posterior plot.

Parameters:
  • param (list) – List with names of the model parameters.

  • object_type (str) – Object type (‘planet’ or ‘star’). With ‘planet’, the radius and mass are expressed in Jupiter units. With ‘star’, the radius and mass are expressed in solar units.

Returns:

List with parameter labels for plots.

Return type:

list

species.util.query_util module#

Text

species.util.query_util.get_parallax(target)[source]#

Function for retrieving the parallax of an object.

Parameters:

target (str) – Target name.

Returns:

  • str – SIMBAD name.

  • tuple(float, float) – Parallax and uncertainty (mas).

species.util.query_util.get_simbad(name)[source]#

Function for getting the SIMBAD identifier of an object.

Parameters:

name (np.ndarray) –

Returns:

SIMBAD name.

Return type:

np.ndarray

species.util.radtrans_util module#

Utility functions for petitRADTRANS spectra.

species.util.radtrans_util.retrieval_spectrum(indices: Dict[str, int64], chemistry: str, pt_profile: str, line_species: List[str], cloud_species: List[str], quenching: str | None, spec_res: float, distance: float | None, pt_smooth: float | None, temp_nodes: integer | None, abund_nodes: integer | None, abund_smooth: float | None, read_rad: ReadRadtrans, sample: ndarray) ModelBox[source]#

Function for calculating a petitRADTRANS spectrum from a posterior sample.

Parameters:
  • indices (dict) – Dictionary with the parameter indices for sample.

  • chemistry (str) – Chemistry type ('equilibrium' or 'free').

  • pt_profile (str) – Pressure-temperature parametrization ('molliere', 'monotonic', or 'free').

  • line_species (list(str)) – List with the line species.

  • cloud_species (list(str)) – List with the cloud species.

  • quenching (str, None) – Quenching type for CO/CH4/H2O abundances. Either the quenching pressure (bar) is a free parameter (quenching='pressure') or the quenching pressure is calculated from the mixing and chemical timescales (quenching='diffusion'). The quenching is not applied if the argument is set to None.

  • spec_res (float) – Spectral resolution.

  • distance (float, None) – Distance (pc).

  • pt_smooth (float, None) – Standard deviation of the Gaussian kernel that is used for smoothing the sampled temperature nodes of the P-T profile. Only required with pt_profile=’free’ or pt_profile=’monotonic’. The argument should be given as log10(P/bar).

  • temp_nodes (int, None) – Number of free temperature nodes that are used when pt_profile='monotonic' or pt_profile='free'.

  • abund_nodes (int, None) – Number of free abundance nodes that are used when chemistry='free'.

  • abund_smooth (float, None) – Standard deviation of the Gaussian kernel that is used for smoothing the abundance profiles, after the abundance nodes have been interpolated to a higher pressure resolution. Only required with `chemistry='free'`. The argument should be given as \(\log10{P/\mathrm{bar}}\). No smoothing is applied if the argument if set to 0 or None.

  • read_rad (ReadRadtrans) – Instance of ReadRadtrans.

  • sample (np.ndarray) – Parameter values with their order given by the indices.

Returns:

Box with the petitRADTRANS spectrum.

Return type:

species.core.box.ModelBox

species.util.retrieval_util module#

Utility functions for atmospheric retrieval with petitRADTRANS. This module was put together many contributions by Paul Mollière (MPIA).

species.util.retrieval_util.atomic_masses() dict[source]#

Function which returns the atomic and molecular masses.

Returns:

Dictionary with the atomic and molecular masses.

Return type:

dict

species.util.retrieval_util.calc_metal_ratio(log_x_abund: Dict[str, float], line_species: List[str]) Tuple[float, float, float][source]#

Function for calculating [C/H], [O/H], and C/O for a given set of abundances.

Parameters:
  • log_x_abund (dict) – Dictionary with the log10 mass fractions.

  • line_species (list(str)) – List with the line species.

Returns:

  • float – Carbon-to-hydrogen ratio, relative to solar.

  • float – Oxygen-to-hydrogen ratio, relative to solar.

  • float – Carbon-to-oxygen ratio.

species.util.retrieval_util.calc_spectrum_clear(rt_object, pressure: ndarray, temperature: ndarray, log_g: float, c_o_ratio: float | None, metallicity: float | None, p_quench: float | None, log_x_abund: dict | None, chemistry: str, knot_press_abund: ndarray | None, abund_smooth: float | None, pressure_grid: str = 'smaller', contribution: bool = False) Tuple[ndarray, ndarray, ndarray | None][source]#

Function to simulate an emission spectrum of a clear atmosphere. The function supports both equilibrium chemistry (chemistry='equilibrium') and free abundances (chemistry='free').

rt_objectpetitRADTRANS.radtrans.Radtrans

Instance of Radtrans.

pressurenp.ndarray

Array with the pressure points (bar).

temperaturenp.ndarray

Array with the temperature points (K) corresponding to pressure.

log_gfloat

Log10 of the surface gravity (cm s-2).

c_o_ratiofloat, None

Carbon-to-oxygen ratio.

metallicityfloat, None

Metallicity.

p_quenchfloat, None

Quenching pressure (bar).

log_x_abunddict, None

Dictionary with the log10 of the abundances. Only required when chemistry='free'.

chemistrystr

Chemistry type (‘equilibrium’ or ‘free’).

knot_press_abundnp.ndarray, None

Pressure nodes at which the abundances are sampled. Only required when chemistry='free'.

abund_smoothfloat, None

Standard deviation of the Gaussian kernel that is used for smoothing the abundance profiles, after the abundance nodes have been interpolated to a higher pressure resolution. Only required with `chemistry='free'` and knot_press_abund is not set to None. The argument should be given as \(\log10{P/\mathrm{bar}}\). No smoothing is applied if the argument if set to 0 or None.

pressure_gridstr

The type of pressure grid that is used for the radiative transfer. Either ‘standard’, to use 180 layers both for the atmospheric structure (e.g. when interpolating the abundances) and 180 layers with the radiative transfer, or ‘smaller’ to use 60 (instead of 180) with the radiative transfer, or ‘clouds’ to start with 1440 layers but resample to ~100 layers (depending on the number of cloud species) with a refinement around the cloud decks. For cloudless atmospheres it is recommended to use ‘smaller’, which runs faster than ‘standard’ and provides sufficient accuracy. For cloudy atmosphere, one can test with ‘smaller’ but it is recommended to use ‘clouds’ for improved accuracy fluxes.

contributionbool

Calculate the emission contribution.

Returns:

  • np.ndarray – Wavelength (um).

  • np.ndarray – Flux (W m-2 um-1).

  • np.ndarray, None – Emission contribution.

species.util.retrieval_util.calc_spectrum_clouds(rt_object, pressure: ndarray, temperature: ndarray, c_o_ratio: float, metallicity: float, p_quench: float | None, log_x_abund: dict | None, log_x_base: dict | None, cloud_dict: Dict[str, float | None], log_g: float, chemistry: str, knot_press_abund: ndarray | None, abund_smooth: float | None, pressure_grid: str = 'smaller', plotting: bool = False, contribution: bool = False, tau_cloud: float | None = None, cloud_wavel: Tuple[float, float] | None = None) Tuple[ndarray | None, ndarray | None, ndarray | None, ndarray][source]#

Function to simulate an emission spectrum of a cloudy atmosphere.

Parameters:
  • rt_object (petitRADTRANS.radtrans.Radtrans) – Instance of Radtrans.

  • pressure (np.ndarray) – Array with the pressure points (bar).

  • temperature (np.ndarray) – Array with the temperature points (K) corresponding to pressure.

  • c_o_ratio (float) – Carbon-to-oxygen ratio.

  • metallicity (float) – Metallicity.

  • p_quench (float, None) – Quenching pressure (bar).

  • log_x_abund (dict, None) – Dictionary with the log10 of the abundances. Only required when chemistry='free'.

  • log_x_base (dict, None) – Dictionary with the log10 of the mass fractions at the cloud base. Only required when the cloud_dict contains fsed, log_kzz, and sigma_lnorm.

  • cloud_dict (dict) – Dictionary with the cloud parameters.

  • log_g (float) – Log10 of the surface gravity (cm s-2).

  • chemistry (str) – Chemistry type (‘equilibrium’ or ‘free’).

  • knot_press_abund (np.ndarray, None) – Pressure nodes at which the abundances are sampled. Only required when chemistry='free'.

  • abund_smooth (float, None) – Standard deviation of the Gaussian kernel that is used for smoothing the abundance profiles, after the abundance nodes have been interpolated to a higher pressure resolution. Only required with `chemistry='free'` and knot_press_abund is not set to None. The argument should be given as \(\log10{P/\mathrm{bar}}\). No smoothing is applied if the argument if set to 0 or None.

  • pressure_grid (str) – The type of pressure grid that is used for the radiative transfer. Either ‘standard’, to use 180 layers both for the atmospheric structure (e.g. when interpolating the abundances) and 180 layers with the radiative transfer, or ‘smaller’ to use 60 (instead of 180) with the radiative transfer, or ‘clouds’ to start with 1440 layers but resample to ~100 layers (depending on the number of cloud species) with a refinement around the cloud decks. For cloudless atmospheres it is recommended to use ‘smaller’, which runs faster than ‘standard’ and provides sufficient accuracy. For cloudy atmosphere, one can test with ‘smaller’ but it is recommended to use ‘clouds’ for improved accuracy fluxes.

  • plotting (bool) – Create plots.

  • contribution (bool) – Calculate the emission contribution.

  • tau_cloud (float, None) – Total cloud optical that will be used for scaling the cloud mass fractions. The mass fractions will not be scaled if the parameter is set to None.

  • cloud_wavel (tuple(float, float), None) – Tuple with the wavelength range (um) that is used for calculating the median optical depth of the clouds at the gas-only photosphere and then scaling the cloud optical depth to the value of log_tau_cloud. The range of cloud_wavel should be encompassed by the range of wavel_range. The full wavelength range (i.e. wavel_range) is used if the argument is set to None.

Returns:

  • np.ndarray, None – Wavelength (um).

  • np.ndarray, None – Flux (W m-2 um-1).

  • np.ndarray, None – Emission contribution.

  • np.ndarray – Array with mean molecular weight.

species.util.retrieval_util.cloud_mass_fraction(composition: str, metallicity: float, c_o_ratio: float) float[source]#

Function to calculate the mass fraction for a cloud species.

Parameters:
  • composition (str) – Cloud composition (‘Fe’, ‘MgSiO3’, ‘Mg2SiO4’, ‘Al2O3’, ‘Na2S’, or ‘KCL’).

  • metallicity (float) – Metallicity [Fe/H].

  • c_o_ratio (float) – Carbon-to-oxygen ratio.

Returns:

Mass fraction.

Return type:

float

species.util.retrieval_util.convective_flux(press: ndarray, temp: ndarray, mmw: ndarray, nabla_ad: ndarray, kappa_r: ndarray, density: ndarray, c_p: ndarray, gravity: float, f_bol: float, mix_length: float = 1.0) ndarray[source]#

Function for calculating the convective flux with mixing-length theory. This function has been adopted from petitCODE (Paul Mollière, MPIA) and was converted from Fortran to Python.

Parameters:
  • press (np.ndarray) – Array with the pressures (Pa).

  • temp (np.ndarray) – Array with the temperatures (K) at pressure.

  • mmw (np.ndarray) – Array with the mean molecular weights at pressure.

  • nabla_ad (np.ndarray) – Array with the adiabatic temperature gradient at pressure.

  • kappa_r (np.ndarray) – Array with the Rosseland mean opacity (m2 kg-1) at pressure.

  • density (np.ndarray) – Array with the density (kg m-3) at pressure.

  • c_p (np.ndarray) – Array with the specific heat capacity (J kg-1 K-1) at constant pressure, pressure.

  • gravity (float) – Surface gravity (m s-2).

  • f_bol (float) – Bolometric flux (W m-2) at the top of the atmosphere, calculated from the low-resolution spectrum.

  • mix_length (float) – Mixing length for the convection in units of the pressure scale height (default: 1.0).

Returns:

Convective flux (W m-2) at each pressure.

Return type:

np.ndarray

species.util.retrieval_util.convolve_spectrum(input_wavel: ndarray, input_flux: ndarray, spec_res: float) ndarray[source]#

Function to convolve a spectrum with a Gaussian filter.

Parameters:
  • input_wavel (np.ndarray) – Input wavelengths.

  • input_flux (np.ndarray) – Input flux

  • spec_res (float) – Spectral resolution of the Gaussian filter.

Returns:

Convolved spectrum.

Return type:

np.ndarray

species.util.retrieval_util.create_abund_dict(abund_in: Dict[str, ndarray], line_species: List[str], chemistry: str, pressure_grid: str = 'smaller', indices: ndarray | None = None) Dict[str, ndarray][source]#

Function to update the names in the abundance dictionary.

Parameters:
  • abund_in (dict) – Dictionary with the mass fractions.

  • line_species (list) – List with the line species.

  • chemistry (str) – Chemistry type (‘equilibrium’ or ‘free’).

  • pressure_grid (str) – The type of pressure grid that is used for the radiative transfer. Either ‘standard’, to use 180 layers both for the atmospheric structure (e.g. when interpolating the abundances) and 180 layers with the radiative transfer, or ‘smaller’ to use 60 (instead of 180) with the radiative transfer, or ‘clouds’ to start with 1440 layers but resample to ~100 layers (depending on the number of cloud species) with a refinement around the cloud decks. For cloudless atmospheres it is recommended to use ‘smaller’, which runs faster than ‘standard’ and provides sufficient accuracy. For cloudy atmosphere, one can test with ‘smaller’ but it is recommended to use ‘clouds’ for improved accuracy fluxes.

  • indices (np.ndarray, None) – Pressure indices from the adaptive refinement in a cloudy atmosphere. Only required with pressure_grid='clouds'. Otherwise, the argument can be set to None.

Returns:

Dictionary with the updated names of the abundances.

Return type:

dict

species.util.retrieval_util.create_pt_profile(cube, cube_index: Dict[str, float], pt_profile: str, pressure: ndarray, knot_press: ndarray | None, metallicity: float, c_o_ratio: float, pt_smooth: float | Dict[str, float] | None = 0.3) Tuple[ndarray | None, ndarray | None, float | None, float | None][source]#

Function for creating a pressure-temperature profile.

Parameters:
  • cube (LP_c_double) – Unit cube.

  • cube_index (dict) – Dictionary with the index of each parameter in the cube.

  • pt_profile (str) – The parametrization for the pressure-temperature profile (‘molliere’, ‘free’, ‘monotonic’, ‘eddington’, ‘gradient’).

  • pressure (np.ndarray) – Pressure points (bar) at which the temperatures is interpolated.

  • knot_press (np.ndarray, None) – Pressure knots (bar), which are required when the argument of pt_profile is either ‘free’ or ‘monotonic’.

  • metallicity (float) – Metallicity [Fe/H].

  • c_o_ratio (float, None) – Carbon-to-oxgen ratio.

  • pt_smooth (float, dict, None) – Standard deviation of the Gaussian kernel that is used for smoothing the P-T profile, after the temperature nodes have been interpolated to a higher pressure resolution. The argument should be given as \(\log10{P/\mathrm{bar}}\), with the default value set to 0.3 dex. No smoothing is applied if the argument is set to None.

Returns:

  • np.ndarray – Temperatures (K).

  • np.ndarray, None – Temperature at the knots (K). A None is returned if pt_profile is set to ‘molliere’ or ‘eddington’.

  • float, None – Pressure (bar) where the optical depth is 1.

  • float, None – Pressure (bar) at the radiative-convective boundary.

species.util.retrieval_util.cube_to_dict(cube, cube_index: Dict[str, float]) Dict[str, float][source]#

Function to convert the parameter cube into a dictionary.

Parameters:
  • cube (LP_c_double) – Cube with the parameters.

  • cube_index (dict) – Dictionary with the index of each parameter in the cube.

Returns:

Dictionary with the parameters.

Return type:

dict

species.util.retrieval_util.find_cloud_deck(composition: str, press: ndarray, temp: ndarray, metallicity: float, c_o_ratio: float, mmw: float = 2.33, plotting: bool = False) float[source]#

Function to find the base of the cloud deck by intersecting the P-T profile with the saturation vapor pressure.

Parameters:
  • composition (str) – Cloud composition (‘Fe’, ‘MgSiO3’, ‘Mg2SiO4’, ‘Al2O3’, ‘Na2S’, or ‘KCL’).

  • press (np.ndarray) – Pressures (bar).

  • temp (np.ndarray) – Temperatures (K).

  • metallicity (float) – Metallicity [Fe/H].

  • c_o_ratio (float) – Carbon-to-oxygen ratio.

  • mmw (float) – Mean molecular weight.

  • plotting (bool) – Create a plot.

Returns:

Pressure (bar) at the base of the cloud deck.

Return type:

float

species.util.retrieval_util.get_condensation_curve(composition: str, press: ndarray, metallicity: float, c_o_ratio: float, mmw: float = 2.33) ndarray[source]#

Function to find the base of the cloud deck by intersecting the P-T profile with the saturation vapor pressure.

Parameters:
  • composition (str) – Cloud composition (‘Fe’, ‘MgSiO3’, ‘Mg2SiO4’, ‘Al2O3’, ‘Na2S’, or ‘KCL’).

  • press (np.ndarray) – Pressures (bar).

  • metallicity (float) – Metallicity [Fe/H].

  • c_o_ratio (float) – Carbon-to-oxygen ratio.

  • mmw (float) – Mean molecular weight.

Returns:

Condensation temperatures (K) for the provided input pressures.

Return type:

np.array

species.util.retrieval_util.get_line_species() List[str][source]#

Function to get the list of the molecular and atomic line species. This function is not used anywhere so could be removed.

Returns:

List with the line species.

Return type:

list(str)

species.util.retrieval_util.list_to_dict(param_list: List[str], sample_val: ndarray) Dict[str, float][source]#

Function to convert the parameter cube into a dictionary.

Parameters:
  • param_list (list(str)) – List with the parameter labels.

  • sample_val (np.ndarray) – Array with the parameter values, in the same order as param_list.

Returns:

Dictionary with the parameters.

Return type:

dict

species.util.retrieval_util.log_x_cloud_base(c_o_ratio: float, metallicity: float, cloud_fractions: Dict[str, float]) Dict[str, float][source]#

Function for returning a dictionary with the log10 mass fractions at the cloud base.

Parameters:
  • c_o_ratio (float) – C/O ratio.

  • metallicity (float) – Metallicity, [Fe/H].

  • cloud_fractions (dict) – Dictionary with the log10 mass fractions at the cloud base, relative to the maximum values allowed from elemental abundances. The dictionary keys are the cloud species without the structure and shape index (e.g. Na2S(c) instead of Na2S(c)_cd).

Returns:

Dictionary with the log10 mass fractions at the cloud base. Compared to the keys of cloud_fractions, the keys in the returned dictionary are provided without (c) (e.g. Na2S instead of Na2S(c)).

Return type:

dict

species.util.retrieval_util.make_half_pressure_better(p_base: Dict[str, float], pressure: ndarray) Tuple[ndarray, ndarray][source]#

Function for reducing the number of pressure layers from 1440 to ~100 (depending on the number of cloud species) with a refinement around the cloud decks.

Parameters:
  • p_base (dict) – Dictionary with the base of the cloud deck for all cloud species. The keys in the dictionary are included for example as MgSiO3(c).

  • pressure (np.ndarray) – Pressures (bar) at high resolution (1440 points).

Returns:

  • np.ndarray – Pressures (bar) at lower resolution (60 points) but with a refinement around the position of the cloud decks.

  • np.ndarray, None – The indices of the pressures that have been selected from the input array pressure.

species.util.retrieval_util.mass_fractions(log_x_abund: Dict[str, float], line_species: List[str], abund_nodes: int | None = None) Dict[str, float][source]#

Function to return a dictionary with the mass fractions of all species, including molecular hydrogen and helium.

Parameters:
  • log_x_abund (dict) – Dictionary with the log10 of the mass fractions of metals.

  • line_species (list(str)) – List with the line species.

  • abund_nodes (int, None) – Number of abundance nodes. The argument can be set to None if abundances are constant with pressure.

Returns:

Dictionary with the mass fractions of all species.

Return type:

dict

species.util.retrieval_util.mean_molecular_weight(mass_frac: Dict[str, float]) float[source]#

Function to calculate the mean molecular weight from a dictionary with mass fractions.

Parameters:

mass_frac (dict) – Dictionary with the mass fraction of each species.

Returns:

Mean molecular weight in atomic mass units.

Return type:

float

species.util.retrieval_util.potassium_abundance(log_x_abund: Dict[str, float], line_species: List[str], abund_nodes: int | None = None) float | List[float][source]#

Function to calculate the mass fraction of potassium at a solar ratio of the sodium and potassium abundances.

Parameters:
  • log_x_abund (dict) – Dictionary with the log10 of the mass fractions.

  • line_species (list(str)) – List with the line species.

  • abund_nodes (int, None) – Number of abundance nodes. The argument can be set to None if abundances are constant with pressure.

Returns:

Log10 of the mass fraction of potassium or a list with the log10 mass fraction of potassium in case abund_nodes is not None. The length of the list is equal to the argument of abund_nodes in that case.

Return type:

float, list(float)

species.util.retrieval_util.pt_ret_model(temp_3: ndarray | None, delta: float, alpha: float, tint: float, press: ndarray, metallicity: float, c_o_ratio: float, conv: bool = True) Tuple[ndarray | None, float | None, float | None][source]#

Pressure-temperature profile for a self-luminous atmosphere (see Mollière et al. 2020).

Parameters:
  • temp_3 (np.ndarray, None) – Array with three temperature points that are added on top of the radiative Eddington structure (i.e. above tau = 0.1). The temperature nodes are connected with a spline interpolation and a prior is used such that t1 < t2 < t3 < t_connect. The three temperature points are not used if set to None.

  • delta (float) – Proportionality factor in tau = delta * press_cgs**alpha.

  • alpha (float) – Power law index in \(\tau = \delta * P_\mathrm{cgs}**\alpha\). For the tau model: use the proximity to the \(\kappa_\mathrm{rosseland}\) photosphere as prior.

  • tint (float) – Internal temperature for the Eddington model.

  • press (np.ndarray) – Pressure profile (bar).

  • metallicity (float) – Metallicity [Fe/H]. Required for the nabla_ad interpolation.

  • c_o_ratio (float) – Carbon-to-oxygen ratio. Required for the nabla_ad interpolation.

  • conv (bool) – Enforce a convective adiabat.

Returns:

  • np.ndarray – Temperature profile (K) for press.

  • float – Pressure (bar) where the optical depth is 1.

  • float, None – Pressure (bar) at the radiative-convective boundary.

species.util.retrieval_util.pt_spline_interp(knot_press: ndarray, knot_temp: ndarray, pressure: ndarray, pt_smooth: float | None = 0.3) ndarray[source]#

Function for interpolating the P-T nodes with a PCHIP 1-D monotonic cubic interpolation. The interpolated temperature is smoothed with a Gaussian kernel of width 0.3 dex in pressure (see Piette & Madhusudhan 2020).

Parameters:
  • knot_press (np.ndarray) – Pressure knots (bar).

  • knot_temp (np.ndarray) – Temperature knots (K).

  • pressure (np.ndarray) – Pressure points (bar) at which the temperatures is interpolated.

  • pt_smooth (float, dict, None) – Standard deviation of the Gaussian kernel that is used for smoothing the P-T profile, after the temperature nodes have been interpolated to a higher pressure resolution. The argument should be given as \(\log10{P/\mathrm{bar}}\), with the default value set to 0.3 dex. No smoothing is applied if the argument is set to None.

Returns:

Interpolated, smoothed temperature points (K).

Return type:

np.ndarray

species.util.retrieval_util.quench_pressure(pressure: ndarray, temperature: ndarray, metallicity: float, c_o_ratio: float, log_g: float, log_kzz: float) float | None[source]#

Function to determine the CO/CH$_4$ quenching pressure by intersecting the pressure-dependent timescales of the vertical mixing and the CO/CH$_4$ reaction rates.

Parameters:
  • pressure (np.ndarray) – Array with the pressures (bar).

  • temperature (np.ndarray) – Array with the temperatures (K) corresponding to pressure.

  • metallicity (float) – Metallicity [Fe/H].

  • c_o_ratio (float) – Carbon-to-oxygen ratio.

  • log_g (float) – Log10 of the surface gravity (cm s-2).

  • log_kzz (float) – Log10 of the eddy diffusion coefficient (cm2 s-1).

Returns:

Quenching pressure (bar).

Return type:

float, None

species.util.retrieval_util.return_T_cond_Al2O3(FeH: float) Tuple[ndarray, ndarray][source]#

Function for calculating the condensation temperature for Al2O3.

Parameters:
  • FeH (float) – Metallicity.

  • CO (float) – Carbon-to-oxygen ratio.

  • MMW (float) – Mean molecular weight.

Returns:

  • np.ndarray – Saturation pressure (bar).

  • np.ndarray – Temperature (K).

species.util.retrieval_util.return_T_cond_Fe(FeH: float, CO: float, MMW: float = 2.33) Tuple[ndarray, ndarray][source]#

Function for calculating the saturation pressure for solid Fe.

Parameters:
  • FeH (float) – Metallicity.

  • CO (float) – Carbon-to-oxygen ratio.

  • MMW (float) – Mean molecular weight.

Returns:

  • np.ndarray – Saturation pressure (bar).

  • np.ndarray – Temperature (K).

species.util.retrieval_util.return_T_cond_Fe_comb(FeH: float, CO: float, MMW: float = 2.33) Tuple[ndarray, ndarray][source]#

Function for calculating the saturation pressure for Fe.

Parameters:
  • FeH (float) – Metallicity.

  • CO (float) – Carbon-to-oxygen ratio.

  • MMW (float) – Mean molecular weight.

Returns:

  • np.ndarray – Saturation pressure (bar).

  • np.ndarray – Temperature (K).

species.util.retrieval_util.return_T_cond_Fe_l(FeH: float, CO: float, MMW: float = 2.33) Tuple[ndarray, ndarray][source]#

Function for calculating the saturation pressure for liquid Fe.

Parameters:
  • FeH (float) – Metallicity.

  • CO (float) – Carbon-to-oxygen ratio.

  • MMW (float) – Mean molecular weight.

Returns:

  • np.ndarray – Saturation pressure (bar).

  • np.ndarray – Temperature (K).

species.util.retrieval_util.return_T_cond_KCl(FeH: float, CO: float, MMW: float = 2.33) Tuple[ndarray, ndarray][source]#

Function for calculating the saturation pressure for KCl.

Parameters:
  • FeH (float) – Metallicity.

  • CO (float) – Carbon-to-oxygen ratio.

  • MMW (float) – Mean molecular weight.

Returns:

  • np.ndarray – Saturation pressure (bar).

  • np.ndarray – Temperature (K).

species.util.retrieval_util.return_T_cond_Mg2SiO4(FeH: float) Tuple[ndarray, ndarray][source]#

Function for calculating the saturation pressure for Mg2SiO4.

Parameters:

FeH (float) – Metallicity.

Returns:

  • np.ndarray – Saturation pressure (bar).

  • np.ndarray – Temperature (K).

species.util.retrieval_util.return_T_cond_MgSiO3(FeH: float, CO: float, MMW: float = 2.33) Tuple[ndarray, ndarray][source]#

Function for calculating the saturation pressure for MgSiO3.

Parameters:
  • FeH (float) – Metallicity.

  • CO (float) – Carbon-to-oxygen ratio.

  • MMW (float) – Mean molecular weight.

Returns:

  • np.ndarray – Saturation pressure (bar).

  • np.ndarray – Temperature (K).

species.util.retrieval_util.return_T_cond_Na2S(FeH: float, CO: float, MMW: float = 2.33) Tuple[ndarray, ndarray][source]#

Function for calculating the saturation pressure for Na2S.

Parameters:
  • FeH (float) – Metallicity.

  • CO (float) – Carbon-to-oxygen ratio.

  • MMW (float) – Mean molecular weight.

Returns:

  • np.ndarray – Saturation pressure (bar).

  • np.ndarray – Temperature (K).

species.util.retrieval_util.scale_cloud_abund(params: Dict[str, float], rt_object, pressure: ndarray, temperature: ndarray, mmw: ndarray, chemistry: str, abund_in: Dict[str, ndarray], composition: str, tau_cloud: float, pressure_grid: str) float[source]#

Function to scale the mass fraction of a cloud species to the requested optical depth.

Parameters:
  • params (dict) – Dictionary with the model parameters.

  • rt_object (petitRADTRANS.radtrans.Radtrans) – Instance of Radtrans.

  • pressure (np.ndarray) – Array with the pressure points (bar).

  • temperature (np.ndarray) – Array with the temperature points (K) corresponding to pressure.

  • mmw (np.ndarray) – Array with the mean molecular weights corresponding to pressure.

  • chemistry (str) – Chemistry type (only 'equilibrium' is supported).

  • abund_in (dict) – Dictionary with arrays that contain the pressure-dependent, equilibrium mass fractions of the line species.

  • composition (sr) – Cloud composition (‘Fe(c)’, ‘MgSiO3(c)’, ‘Mg2SiO4(c)’, ‘Al2O3(c)’, ‘Na2S(c)’, ‘KCl(c)’).

  • tau_cloud (float) – Optical depth of the clouds. The returned mass fraction is scaled such that the optical depth at the shortest wavelength is equal to tau_cloud.

  • pressure_grid (str) – The type of pressure grid that is used for the radiative transfer. Either ‘standard’, to use 180 layers both for the atmospheric structure (e.g. when interpolating the abundances) and 180 layers with the radiative transfer, or ‘smaller’ to use 60 (instead of 180) with the radiative transfer, or ‘clouds’ to start with 1440 layers but resample to ~100 layers (depending on the number of cloud species) with a refinement around the cloud decks. For cloudless atmospheres it is recommended to use ‘smaller’, which runs faster than ‘standard’ and provides sufficient accuracy. For cloudy atmosphere, one can test with ‘smaller’ but it is recommended to use ‘clouds’ for improved accuracy fluxes.

Returns:

Mass fraction relative to the maximum value allowed from elemental abundances. The value has been scaled to the requested optical depth tau_cloud (at the shortest wavelength).

Return type:

float

species.util.retrieval_util.solar_mixing_ratios() dict[source]#

Function which returns the volume mixing ratios for solar elemental abundances (i.e. [Fe/H] = 0); adopted from Asplund et al. (2009).

Returns:

Dictionary with the solar number fractions (i.e. volume mixing ratios).

Return type:

dict

species.util.spec_util module#

Utility functions for manipulating spectra.

species.util.spec_util.create_wavelengths(wavel_range: Tuple[float | float32, float | float32], wavel_sampling: float) ndarray[source]#

Function for creating logarithmically-spaced wavelengths, so with a constant \(\lambda/\Delta\lambda\).

Parameters:
  • wavel_range (tuple(float, float)) – Wavelength range (\(\mu\mathrm{m}\)). Tuple with the minimum and maximum wavelength.

  • wavel_sampling (float) – Wavelength sampling \(\lambda/\Delta\lambda\).

Returns:

Array with the wavelengths (\(\mu\mathrm{m}\)). Since the wavelength boundaries are fixed, the output sampling is slightly different from the value provided as argument of wavel_sampling.

Return type:

np.ndarray

species.util.spec_util.smooth_spectrum(wavelength: ndarray, flux: ndarray, spec_res: float, size: int = 11, force_smooth: bool = False) ndarray[source]#

Function for smoothing a spectrum with a Gaussian kernel to a fixed spectral resolution. The kernel size is set to 5 times the FWHM of the Gaussian. The FWHM of the Gaussian is equal to the ratio of the wavelength and the spectral resolution. If the kernel does not fit within the available wavelength grid (i.e. at the edge of the array) then the flux values are set to NaN.

Parameters:
  • wavelength (np.ndarray) – Wavelength points (um). Should be sampled with a uniform spectral resolution or a uniform wavelength spacing (slow).

  • flux (np.ndarray) – Flux (W m-2 um-1).

  • spec_res (float) – Spectral resolution.

  • size (int) – Kernel size (odd integer).

  • force_smooth (bool) – Force smoothing for constant spectral resolution

Returns:

Smoothed spectrum (W m-2 um-1).

Return type:

np.ndarray

species.util.test_util module#

Utility functions for running the unit tests.

species.util.test_util.create_config(test_path)[source]#

Function for creating a configuration file in the test folder.

Parameters:

test_path (str) – Folder where the unit tests are located.

Returns:

None

Return type:

NoneType

Module contents#