species.util package

Submodules

species.util.data_util module

Utility functions for data processing.

species.util.data_util.add_missing(model: str, parameters: List[str], database: h5py._hl.files.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.correlation_to_covariance(cor_matrix, spec_sigma)[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.ndarrays

species.util.data_util.retrieval_spectrum(indices: Dict[str, numpy.int64], chemistry: str, pt_profile: str, line_species: List[str], cloud_species: List[str], quenching: Optional[str], spec_res: float, distance: Optional[float], pt_smooth: Optional[float], read_rad: species.read.read_radtrans.ReadRadtrans, sample: numpy.ndarray) species.core.box.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) – 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).

  • read_rad (read_radtrans.ReadRadtrans) – Instance of ReadRadtrans.

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

Returns

Box with the petitRADTRANS spectrum.

Return type

box.ModelBox

species.util.data_util.sort_data(param_teff: numpy.ndarray, param_logg: Optional[numpy.ndarray], param_feh: Optional[numpy.ndarray], param_co: Optional[numpy.ndarray], param_fsed: Optional[numpy.ndarray], wavelength: numpy.ndarray, flux: numpy.ndarray) List[numpy.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 surface gravity (cgs) 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.

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

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

Returns

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.

Return type

list(np.ndarray, )

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: numpy.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], database: h5py._hl.files.File, data_sorted: List[numpy.ndarray]) None[source]

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

Parameters
  • model (str) – Atmosphere model.

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

  • database (h5py._hl.files.File) – 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: numpy.ndarray, flux: numpy.ndarray, v_band_ext: float, v_band_red: float) numpy.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

The database path from the configuration file.

Return type

str

species.util.dust_util.dust_cross_section(dn_grains: numpy.ndarray, radii: numpy.ndarray, wavelength: float, n_index: float, k_index: float) numpy.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], spec_data: Optional[Dict[str, Tuple[numpy.ndarray, Optional[numpy.ndarray], Optional[numpy.ndarray], float]]]) Tuple[Dict[str, Union[scipy.interpolate.interpolate.interp2d, List[scipy.interpolate.interpolate.interp2d]]], numpy.ndarray, numpy.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.

  • spec_data (dict, None) – Dictionary with the spectrum data. Only required in combination with inc_spec, otherwise the argument needs to be set to None,.

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], spec_data: Optional[Dict[str, Tuple[numpy.ndarray, Optional[numpy.ndarray], Optional[numpy.ndarray], float]]]) Tuple[Dict[str, Union[scipy.interpolate.interpolate.interp2d, List[scipy.interpolate.interpolate.interp2d]]], numpy.ndarray, numpy.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.

  • spec_data (dict, None) – Dictionary with the spectrum data. Only required in combination with inc_spec, otherwise the argument needs to be set to None,.

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: Union[numpy.ndarray, List[float], float]) numpy.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[numpy.ndarray, numpy.ndarray, numpy.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[numpy.ndarray, numpy.ndarray, numpy.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.phot_util module

Utility functions for photometry.

species.util.phot_util.absolute_to_apparent(abs_mag: Union[Tuple[float, Optional[float]], Tuple[numpy.ndarray, Optional[numpy.ndarray]]], distance: Union[Tuple[float, float], Tuple[numpy.ndarray, numpy.ndarray]]) Union[Tuple[float, Optional[float]], Tuple[numpy.ndarray, Optional[numpy.ndarray]]][source]

Function for converting an absolute magnitude into an apparent magnitude.

Parameters
  • abs_mag (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Absolute magnitude and uncertainty (mag). The same uncertainty is used for the apparent magnitude.

  • distance (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Distance and uncertainty (pc).

Returns

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

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

species.util.phot_util.apparent_to_absolute(app_mag: Union[Tuple[float, Optional[float]], Tuple[numpy.ndarray, Optional[numpy.ndarray]]], distance: Union[Tuple[float, Optional[float]], Tuple[numpy.ndarray, Optional[numpy.ndarray]]]) Union[Tuple[float, Optional[float]], Tuple[numpy.ndarray, Optional[numpy.ndarray]]][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.phot_util.get_residuals(datatype: str, spectrum: str, parameters: Dict[str, float], objectbox: species.core.box.ObjectBox, inc_phot: Union[bool, List[str]] = True, inc_spec: Union[bool, List[str]] = True, radtrans: Optional[species.read.read_radtrans.ReadRadtrans] = None) species.core.box.ResidualsBox[source]
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_spectra() 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 (read_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.phot_util.multi_photometry(datatype: str, spectrum: str, filters: List[str], parameters: Dict[str, float], radtrans: Optional[species.read.read_radtrans.ReadRadtrans] = None) species.core.box.SynphotBox[source]
Parameters
  • datatype (str) – Data type (‘model’ or ‘calibration’).

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

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

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

  • radtrans (read_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. Not used if set to None.

Returns

Box with synthetic photometry.

Return type

species.core.box.SynphotBox

species.util.plot_util module

Utility functions for plotting data.

species.util.plot_util.field_bounds_ticks(field_range)[source]
Parameters

field_range (tuple(str, str), None) – Range of the discrete colorbar for the field dwarfs. The tuple should contain the lower and upper value (‘early M’, ‘late M’, ‘early L’, ‘late L’, ‘early T’, ‘late T’, ‘early Y). The full range is used if set to None.

Returns

  • np.ndarray

  • np.ndarray

  • list(str, )

species.util.plot_util.model_name(key: str) str[source]

Function for updating a model name for use in plots.

Parameters

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

Returns

Updated model name for plots.

Return type

str

species.util.plot_util.quantity_unit(param: List[str], object_type: str) Tuple[List[str], List[Optional[str]], 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: numpy.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_stellar(sptype: numpy.ndarray, shape: Tuple[int]) numpy.ndarray[source]

Function for mapping all spectral types (O through Y) to numbers.

Parameters
  • sptype (np.ndarray) – Array with spectral types.

  • shape (tuple(int)) – Shape (1D) of the output array

Returns

Array with spectral types mapped to numbers.

Return type

np.ndarray

species.util.plot_util.sptype_substellar(sptype: numpy.ndarray, shape: Tuple[int]) numpy.ndarray[source]

Function for mapping the spectral types of substellar objects (M, L, T, and Y) to numbers.

Parameters
  • sptype (np.ndarray) – Array with spectral types.

  • shape (tuple(int)) – Shape (1D) of the output array

Returns

Array with spectral types mapped to numbers.

Return type

np.ndarray

species.util.plot_util.update_labels(param: List[str]) 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.

Returns

List with parameter labels for plots.

Return type

list

species.util.query_util module

Text

class species.util.query_util.NoStdStreams(stdout=None, stderr=None)[source]

Bases: object

Text

species.util.query_util.get_distance(target)[source]
Parameters

target (str) – Target name.

Returns

  • str – SIMBAD name.

  • tuple(float, float) – Distance and uncertainty (pc).

species.util.query_util.get_parallax()[source]
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.read_util module

Utility functions for reading data.

species.util.read_util.add_luminosity(modelbox)[source]

Function to add the luminosity of a model spectrum to the parameter dictionary of the box.

Parameters

modelbox (species.core.box.ModelBox) – Box with the model spectrum. Should also contain the dictionary with the model parameters, the radius in particular.

Returns

The input box with the luminosity added in the parameter dictionary.

Return type

species.core.box.ModelBox

species.util.read_util.create_wavelengths(wavel_range: Tuple[Union[float, numpy.float32], Union[float, numpy.float32]], spec_res: float) numpy.ndarray[source]

Function for creating logarithmically-spaced wavelengths at a constant spectral resolution.

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

  • spec_res (float) – Spectral resolution at which the wavelengths are sampled.

Returns

Array with the wavelength points and a fixed spectral resolution. Since the wavelength boundaries are fixed, the output spectral resolution is slightly different from the spec_res value.

Return type

np.ndarray

species.util.read_util.gaussian_spectrum(wavel_range: Union[Tuple[float, float], Tuple[numpy.float32, numpy.float32]], model_param: Dict[str, float], spec_res: float = 100.0, double_gaussian: bool = False) species.core.box.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.read_util.get_mass(logg: Union[float, numpy.ndarray], radius: Union[float, numpy.ndarray]) Union[float, numpy.ndarray][source]

Function for converting a \(\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.read_util.get_radius(logg: Union[float, numpy.ndarray], mass: Union[float, numpy.ndarray]) Union[float, numpy.ndarray][source]

Function for converting a \(\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.read_util.powerlaw_spectrum(wavel_range: Union[Tuple[float, float], Tuple[numpy.float32, numpy.float32]], model_param: Dict[str, float], spec_res: float = 100.0) species.core.box.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.read_util.smooth_spectrum(wavelength: numpy.ndarray, flux: numpy.ndarray, spec_res: float, size: int = 11, force_smooth: bool = False) numpy.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.read_util.update_spectra(objectbox: species.core.box.ObjectBox, model_param: Dict[str, float], model: Optional[str] = None) species.core.box.ObjectBox[source]

Function for applying a flux scaling and/or error inflation to the spectra of an ObjectBox.

Parameters
  • objectbox (species.core.box.ObjectBox) – Box with the object’s data, including the spectra.

  • 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. Otherwise, the argument can be set to None. Not required when model='petitradtrans' because the error inflation is differently implemented 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.retrieval_util module

Utility functions for atmospheric retrieval with petitRADTRANS. This module was put together with 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]) 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.

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: numpy.ndarray, temperature: numpy.ndarray, log_g: float, c_o_ratio: Optional[float], metallicity: Optional[float], p_quench: Optional[float], log_x_abund: Optional[dict], chemistry: str, pressure_grid: str = 'smaller', contribution: bool = False) Tuple[numpy.ndarray, numpy.ndarray, Optional[numpy.ndarray]][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').

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: numpy.ndarray, temperature: numpy.ndarray, c_o_ratio: float, metallicity: float, p_quench: Optional[float], log_x_abund: Optional[dict], log_x_base: Optional[dict], cloud_dict: Dict[str, Optional[float]], log_g: float, chemistry: str, pressure_grid: str = 'smaller', plotting: bool = False, contribution: bool = False, tau_cloud: Optional[float] = None, cloud_wavel: Optional[Tuple[float, float]] = None) Tuple[Optional[numpy.ndarray], Optional[numpy.ndarray], Optional[numpy.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. A parameter value is set to None if the parameter is not in use.

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

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

  • 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.

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’, ‘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.convolve(input_wavel: numpy.ndarray, input_flux: numpy.ndarray, spec_res: float) numpy.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, line_species: list, chemistry: str, pressure_grid: str = 'smaller', indices: Optional[numpy.array] = None) dict[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: numpy.ndarray, knot_press: Optional[numpy.ndarray], metallicity: float, c_o_ratio: float, pt_smooth: float = 0.3) Tuple[numpy.ndarray, Optional[numpy.ndarray], float, Optional[float]][source]

Function for creating the P-T 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’, or ‘monotonic’).

  • 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) – Carbon-to-oxgen ratio.

  • pt_smooth (float) – Standard deviation of the Gaussian kernel that is used for smoothing the sampled temperature nodes of the P-T profile. The argument should be given as log10(P/bar) with the default value in run_multinest() set to 0.3 dex.

Returns

  • np.ndarray – Temperatures (K).

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

  • float – 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: numpy.ndarray, temp: numpy.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’, ‘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_line_species() list[source]

Function to get the list of the molecular and atomic line species.

Returns

List with the line species.

Return type

list

species.util.retrieval_util.list_to_dict(param_list: List[str], sample_val: numpy.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) dict[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: numpy.ndarray) Tuple[numpy.ndarray, numpy.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) dict[source]

Function to return a dictionary with the mass fractions of all species.

Parameters

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

Returns

Dictionary with the mass fractions of all species.

Return type

dict

species.util.retrieval_util.mean_molecular_weight(abundances: dict) float[source]

Function to calculate the mean molecular weight from the abundances.

Parameters

abundances (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) 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.

Returns

Log10 of the mass fraction of potassium.

Return type

float

species.util.retrieval_util.pt_ret_model(temp_3: Optional[numpy.ndarray], delta: float, alpha: float, tint: float, press: numpy.ndarray, metallicity: float, c_o_ratio: float, conv: bool = True) Tuple[numpy.ndarray, float, Optional[float]][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 * press_cgs**alpha. For the tau model: use the proximity to the kappa_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: numpy.ndarray, knot_temp: numpy.ndarray, pressure: numpy.ndarray, pt_smooth: float = 0.3) numpy.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) – Standard deviation of the Gaussian kernel that is used for smoothing the sampled temperature nodes of the P-T profile. The argument should be given as log10(P/bar) with the default value in run_multinest() set to 0.3 dex.

Returns

Interpolated, smoothed temperature points (K).

Return type

np.ndarray

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

Function to determine the CO/CH4 quenching pressure by intersecting the pressure-dependent timescales of the vertical mixing and the CO/CH4 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, CO: float, MMW: float = 2.33) Tuple[numpy.ndarray, numpy.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[numpy.ndarray, numpy.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[numpy.ndarray, numpy.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[numpy.ndarray, numpy.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[numpy.ndarray, numpy.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_MgSiO3(FeH: float, CO: float, MMW: float = 2.33) Tuple[numpy.ndarray, numpy.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[numpy.ndarray, numpy.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: numpy.ndarray, temperature: numpy.ndarray, mmw: numpy.ndarray, chemistry: str, abund_in: Dict[str, numpy.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)’, ‘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.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