POSEIDON.parameters

Functions related to the free parameters defining a POSEIDON model.

Module Contents

Functions

assign_free_params(param_species, object_type, ...)

From the user's chosen model settings, determine which free parameters

split_params(params_drawn, N_params_cumulative)

Split the array of drawn parameters from a retrieval (e.g. the MultiNest

generate_state(PT_in, log_X_in, param_species, PT_dim, ...)

Convert the P-T profile and mixing ratio parameters into the state array

unpack_cloud_params(param_names, clouds_in, ...)

Extract the aerosol property values (e.g cloud pressure and scattering

unpack_geometry_params(param_names, geometry_in, ...)

Extract the multidimensional geometry property values (i.e. terminator

unpack_stellar_params(param_names, star, stellar_in, ...)

Extract the stellar properties from the drawn stellar parameters, according
POSEIDON.parameters.assign_free_params(param_species, object_type, PT_profile, X_profile, cloud_model, cloud_type, gravity_setting, stellar_contam, offsets_applied, error_inflation, PT_dim, X_dim, cloud_dim, TwoD_type, TwoD_param_scheme, species_EM_gradient, species_DN_gradient, species_vert_gradient, Atmosphere_dimension, opaque_Iceberg, surface, sharp_DN_transition, reference_parameter, disable_atmosphere)

From the user’s chosen model settings, determine which free parameters define this POSEIDON model. The different types of free parameters are returned as separate arrays.

Parameters:

  • param_species (list of str) – Chemical species with parametrised mixing ratios (trace species).

  • object_type (str) – Type of planet / brown dwarf the user wishes to model (Options: transiting / directly_imaged).

  • PT_profile (str) –

    Chosen P-T profile parametrisation (Options: isotherm / gradient / two-gradients / Madhu / slope /

    file_read).

  • X_profile (str) – Chosen mixing ratio profile parametrisation (Options: isochem / gradient / two-gradients / file_read).

  • cloud_model (str) – Chosen cloud parametrisation (Options: cloud-free / MacMad17 / Iceberg).

  • cloud_type (str) – Cloud extinction type to consider (Options: deck / haze / deck_haze).

  • gravity_setting (str) – Whether log_g is fixed or a free parameter. (Options: fixed / free).

  • stellar_contam (str) –

    Chosen prescription for modelling unocculted stellar contamination (Options: one_spot / one_spot_free_log_g / two_spots /

    two_spots_free_log_g).

  • offsets_applied (str) – Whether a relative offset should be applied to a dataset (Options: single_dataset).

  • error_inflation (str) – Whether to consider inflation of error bars in a retrieval (Options: Line15).

  • PT_dim (int) – Dimensionality of the pressure-temperature field (uniform -> 1, a day-night or evening-morning gradient -> 2, both day-night and evening-morning gradients -> 3) (Options: 1 / 2 / 3).

  • X_dim (int) – Max dimensionality of the mixing ratio field (not all species need have gradients, this just specifies the highest dimensionality of chemical gradients – see the species_XX_gradient arguments) (Options: 1 / 2 / 3).

  • cloud_dim (int) – Dimensionality of the cloud model prescription (only the Iceberg cloud model supports 3D clouds) (Options: 1 / 2 / 3).

  • TwoD_type (str) – For 2D models, specifies whether the model considers day-night gradients or evening-morning gradients (Options: D-N / E-M).

  • TwoD_param_scheme (str) – For 2D models, specifies which quantities should be consider as free parameters (e.g. day & night vs. terminator & day-night diff.) (Options: absolute / difference).

  • species_EM_gradient (list of str) – List of chemical species with an evening-morning mixing ratio gradient.

  • species_DN_gradient (list of str) – List of chemical species with a day-night mixing ratio gradient.

  • species_vert_gradient (list of str) – List of chemical species with a vertical mixing ratio gradient.

  • Atmosphere_dimension (int) – The dimensionality of the model atmosphere (Options: 1 / 2 / 3).

  • opaque_Iceberg (bool) – If using the Iceberg cloud model, True disables the kappa parameter.

  • surface (bool) – If True, model a surface via an opaque cloud deck.

  • sharp_DN_transition (bool) – For 2D / 3D models, sets day-night transition width (beta) to 0.

  • reference_parameter (str) – For retrievals, whether R_p_ref or P_ref will be a free parameter (Options: R_p_ref / P_ref).

  • disable_atmosphere (bool) – If True, returns a flat planetary transmission spectrum @ (Rp/R*)^2

Returns:

Free parameters defining this POSEIDON model. physical_params (np.array of str):

Physical parameters of the planet.

PT_params (np.array of str):

Pressure-temperature profile parameters.

X_params (np.array of str):

Mixing ratio parameters.

cloud_params (np.array of str):

Aerosol parameters.

geometry_params (np.array of str):

Multidimensional atmospheric geometry parameters.

stellar_params (np.array of str):

Stellar heterogeneity parameters.

N_params_cumulative (np.array of int):

Cumulative sum of number of parameters (used for indexing).

Return type:

params (np.array of str)

POSEIDON.parameters.split_params(params_drawn, N_params_cumulative)

Split the array of drawn parameters from a retrieval (e.g. the MultiNest parameter cube) into the separate types of parameters used by POSEIDON.

Parameters:

  • params_drawn (list of float | np.array of float) – Values of the free parameters drawn from the prior distribution.

  • N_params_cumulative (np.array of int) – Cumulative sum of number of parameters (used for indexing).

Returns:

Drawn values of the physical parameters of the planet. PT_drawn (list of float | np.array of float):

Drawn values of the pressure-temperature profile parameters.

log_X_drawn (list of float | np.array of float):

Drawn values of the mixing ratio parameters.

clouds_drawn (list of float | np.array of float):

Drawn values of the aerosol parameters.

geometry_drawn (list of float | np.array of float):

Drawn values of the multidimensional atmospheric geometry parameters.

stellar_drawn (list of float | np.array of float):

Drawn values of the stellar heterogeneity parameters.

offsets_drawn (list of float | np.array of float):

Drawn values of the data offset parameters.

err_inflation_drawn (list of float | np.array of float):

Drawn values of the error inflation parameters.

Return type:

physical_drawn (list of float | np.array of float)

POSEIDON.parameters.generate_state(PT_in, log_X_in, param_species, PT_dim, X_dim, PT_profile, X_profile, TwoD_type, TwoD_param_scheme, species_EM_gradient, species_DN_gradient, species_vert_gradient, alpha, beta)

Convert the P-T profile and mixing ratio parameters into the state array format expected by the POSEIDON.atmosphere module. This function is called by ‘make_atmosphere’ in core.py.

Parameters:

  • PT_in (list of float | np.array of float) – Drawn values of the pressure-temperature profile parameters.

  • log_X_in (list of float | np.array of float) – Drawn values of the mixing ratio parameters.

  • param_species (list of str) – Chemical species with parametrised mixing ratios (trace species).

  • PT_dim (int) – Dimensionality of the pressure-temperature field (uniform -> 1, a day-night or evening-morning gradient -> 2, both day-night and evening-morning gradients -> 3) (Options: 1 / 2 / 3).

  • X_dim (int) – Max dimensionality of the mixing ratio field (not all species need have gradients, this just specifies the highest dimensionality of chemical gradients – see the species_XX_gradient arguments) (Options: 1 / 2 / 3).

  • PT_profile (str) – Chosen P-T profile parametrisation (Options: isotherm / gradient / two-gradients / Madhu / slope / file_read).

  • X_profile (str) – Chosen mixing ratio profile parametrisation (Options: isochem / gradient / two-gradients / file_read / chem_eq).

  • TwoD_type (str) – For 2D models, specifies whether the model considers day-night gradients or evening-morning gradients (Options: D-N / E-M).

  • TwoD_param_scheme (str) – For 2D models, specifies which quantities should be consider as free parameters (e.g. day & night vs. terminator & day-night diff.) (Options: absolute / difference).

  • species_EM_gradient (list of str) – List of chemical species with an evening-morning mixing ratio gradient.

  • species_DN_gradient (list of str) – List of chemical species with a day-night mixing ratio gradient.

  • species_vert_gradient (list of str) – List of chemical species with a vertical mixing ratio gradient.

Returns:

P-T profile state array for the POSEIDON.atmosphere module. log_X_state (2D np.array of float):

Mixing ratio state array for the POSEIDON.atmosphere module.

Return type:

PT_state (np.array of float)

POSEIDON.parameters.unpack_cloud_params(param_names, clouds_in, cloud_model, cloud_dim, N_params_cumulative, TwoD_type)

Extract the aerosol property values (e.g cloud pressure and scattering properties) from the drawn cloud parameters, according to the cloud model specified by the user.

Parameters:

  • param_names (np.array of str) – Free parameters defining this POSEIDON model.

  • clouds_in (list of float | np.array of float) – Drawn values of the aerosol parameters.

  • cloud_model (str) – Chosen cloud parametrisation (Options: cloud-free / MacMad17 / Iceberg).

  • cloud_dim (int) – Dimensionality of the cloud model prescription (only the Iceberg cloud model supports 3D clouds) (Options: 1 / 2 / 3).

  • N_params_cumulative (np.array of int) – Cumulative sum of number of parameters (used for indexing).

  • TwoD_type (str) – For 2D models, specifies whether the model considers day-night gradients or evening-morning gradients (Options: D-N / E-M).

Returns:

Grey cloud extinction coefficient (m^-1). P_cloud (float):

Cloud top pressure (bar).

f_cloud (float):

Terminator azimuthal cloud fraction for 2D/3D models.

phi_0 (float):

Azimuthal angle in terminator plane, measured clockwise from the North pole, where the patchy cloud begins for 2D/3D models (degrees).

theta_0 (float):

Zenith angle from the terminator plane, measured towards the nightside, where the patchy cloud begins for 2D/3D models (degrees).

a (float):

Haze ‘Rayleigh enhancement factor’, relative to H2 Rayleigh scattering, as defined in MacDonald & Madhusudhan (2017).

gamma (float):

Haze power law exponent, as defined in MacDonald & Madhusudhan (2017).

Return type:

kappa_cloud_0 (float)

POSEIDON.parameters.unpack_geometry_params(param_names, geometry_in, N_params_cumulative)

Extract the multidimensional geometry property values (i.e. terminator opening angles) from the drawn geometry parameters, according to the model dimensionality specified by the user.

Parameters:

  • param_names (np.array of str) – Free parameters defining this POSEIDON model.

  • geometry_in (list of float | np.array of float) – Drawn values of the multidimensional atmospheric geometry parameters.

  • N_params_cumulative (np.array of int) – Cumulative sum of number of parameters (used for indexing).

Returns:

Terminator opening angle (degrees). beta (float):

Day-night opening angle (degrees).

Return type:

alpha (float)

POSEIDON.parameters.unpack_stellar_params(param_names, star, stellar_in, stellar_contam, N_params_cumulative)

Extract the stellar properties from the drawn stellar parameters, according to the stellar contamination model specified by the user.

Parameters:

  • param_names (np.array of str) – Free parameters defining this POSEIDON model.

  • star (dict) – Collection of stellar properties used by POSEIDON.

  • stellar_in (list of float | np.array of float) – Drawn values of the stellar parameters.

  • stellar_contam (str) –

    Chosen prescription for modelling unocculted stellar contamination (Options: one_spot / one_spot_free_log_g / two_spots /

    two_spots_free_log_g).

  • N_params_cumulative (np.array of int) – Cumulative sum of number of parameters (used for indexing).

Returns:

For the ‘one_spot’ model, the fraction of stellar photosphere

covered by either spots or faculae.

f_spot (float):

For the ‘two_spots’ model, the fraction of stellar photosphere covered by spots.

f_fac (float):

For the ‘two_spots’ model, the fraction of stellar photosphere covered by faculae.

T_het (float):

For the ‘one_spot’ model, the temperature of the heterogeneity (K).

T_spot (float):

For the ‘two_spots’ model, the temperature of the spot (K).

T_fac (float):

For the ‘two_spots’ model, the temperature of the facula (K).

T_phot (float):

Stellar photosphere temperature (K).

log_g_het (float):

For the ‘one_spot’ model, the log g of the heterogeneity (log10(cm/s^2)).

log_g_spot (float):

For the ‘two_spots’ model, the log g of the spot (log10(cm/s^2)).

log_g_fac (float):

For the ‘two_spots’ model, the log g of the facula (log10(cm/s^2)).

log_g_phot (float):

Stellar photosphere log g (log10(cm/s^2)).

Return type:

f_het (float)