POSEIDON.parameters

Functions related to the free parameters defining a POSEIDON model.

Functions

assign_free_params(param_species, bulk_species, ...)

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

unpack_surface_params(param_names, surface_in, ...)

Extract the surface property values

Module Contents

POSEIDON.parameters.assign_free_params(param_species, bulk_species, object_type, PT_profile, X_profile, cloud_model, cloud_type, gravity_setting, mass_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, sharp_EM_transition, reference_parameter, disable_atmosphere, aerosol_species, log_P_slope_arr, number_P_knots, PT_penalty, high_res_method, alpha_high_res_option, fix_alpha_high_res, fix_W_conv_high_res, fix_beta_high_res, fix_Delta_phi_high_res, lognormal_logwidth_free, surface_components, surface_model, surface_percentage_option, thermal, reflection)

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

  • bulk_species (list of str) – The chemical species (or two for H2+He) filling most of the atmosphere.

  • 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 / lever / dissociation / file_read).

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

  • cloud_type (str) –

    Cloud extinction type to consider (Options: deck / haze / deck_haze

    Mie Options: fuzzy_deck / uniform_X / slab / fuzzy_deck_plus_slab

    opaque_deck_plus_slab /opaque_deck_plus_uniform_X / one_slab / uniaxial_random_slab / uniaxial_slab / biaxial_random_slab / biaxial_slab

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

  • mass_setting (str) – Whether the planetary mass 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 / two_datasets / three_datasets).

  • error_inflation (str) – Error bar inflation treatment in a retrieval (Options: Line15 / Piette20 / Line15+Piette20).

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

  • sharp_EM_transition (bool) – For 2D / 3D models, sets evening-morning transition width (alpha) 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

  • aerosol_species (list of string) – Either ‘free’ or specific aerosol(s).

  • log_P_slope_array (np.array of float) – Log pressures where the temperature difference parameters are defined (Piette & Madhusudhan 2020 profile only).

  • number_P_knots (float) – Number of uniform knots in pressure space (only for the Pelletier 2021 P-T profile).

  • PT_penalty (bool) – If True, introduces the sigma_smooth parameter for retrievals (only for the Pelletier 2021 P-T profile).

  • high_res_method (list of str) – For high resolution retrievals, define which processing method will be used - only not None for high-res retrievals (Options: None, ‘pca’, ‘sysrem’).

  • alpha_high_res_option (str) – For high resolution retrievals, specify whether the retrieved model scaling parameter is in log space (default) or linear space (Options: ‘log’, ‘linear’).

  • fix_alpha_high_res (bool) – If True, the alpha (model scaling) parameter in high resolution retrievals will be fixed to 1 and not a retrieved parameter.

  • fix_W_conv_high_res (bool) – If True, the W_conv (broadening) parameter in high resolution retrievals will be fixed to 0 and not a retrieved parameter.

  • fix_beta_high_res (bool) – If True, the beta (error scaling) parameter in high resolution retrievals will be fixed to 1 and not a retrieved parameter.

  • fix_Delta_phi_high_res (bool) – If True, the Delta_phi (phase shift) parameter in high resolution retrievals will be fixed to 0 and not a retrieved parameter.

  • lognormal_logwidth_free (bool) – If True, has log_r_m_std_dev be a free parameter for aerosols. Only applicable for certain aerosols with precomputed grids.

  • surface_components (list of strings) – List of surface components (if surface_model = ‘Lab_data’)

  • surface_model (string) – Surface model definition (Options: gray, constant_albedo, lab_data)

  • surface_percentage_option (string) – Will make surface percentages log or linear (log is reccomended for CLR retrievals) (Options: linear, log)

  • thermal (bool) – If true, uses a emission model (scattering determines if one-stream or two-stream) Only used here for seeing if we need to set the T_surf parameter

  • reflection (bool) – If True, uses a two-stream multiple scattering reflection model. Only used here for seeing if we need to set the T_surf parameter

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.

high_res_params (np.array of str):

Parameters used for high resolution cross correlation models.

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.

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

Drawn values of the high-resolution retrieval parameters.

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

Drawn values of the surface 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)

POSEIDON.parameters.unpack_surface_params(param_names, surface_in, surface, surface_model, N_params_cumulative)

Extract the surface property values from the drawn surface parameters, according to the model specified by the user.

Parameters:

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

  • surface_in – Drawn values of the surface parameters.

Returns:

P_surf, T_surf, albedo_surf, surface_component_percentages