POSEIDON.parameters =================== .. py:module:: POSEIDON.parameters .. autoapi-nested-parse:: Functions related to the free parameters defining a POSEIDON model. Functions --------- .. autoapisummary:: POSEIDON.parameters.assign_free_params POSEIDON.parameters.split_params POSEIDON.parameters.generate_state POSEIDON.parameters.unpack_cloud_params POSEIDON.parameters.unpack_geometry_params POSEIDON.parameters.unpack_stellar_params POSEIDON.parameters.unpack_surface_params Module Contents --------------- .. py:function:: 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. :param param_species: Chemical species with parametrised mixing ratios (trace species). :type param_species: list of str :param bulk_species: The chemical species (or two for H2+He) filling most of the atmosphere. :type bulk_species: list of str :param object_type: Type of planet / brown dwarf the user wishes to model (Options: transiting / directly_imaged). :type object_type: str :param PT_profile: Chosen P-T profile parametrisation (Options: isotherm / gradient / two-gradients / Madhu / slope / file_read). :type PT_profile: str :param X_profile: Chosen mixing ratio profile parametrisation (Options: isochem / gradient / two-gradients / lever / dissociation / file_read). :type X_profile: str :param cloud_model: Chosen cloud parametrisation (Options: cloud-free / MacMad17 / Iceberg / Mie). :type cloud_model: str :param cloud_type: 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 :type cloud_type: str :param gravity_setting: Whether log_g is fixed or a free parameter. (Options: fixed / free). :type gravity_setting: str :param mass_setting: Whether the planetary mass is fixed or a free parameter. (Options: fixed / free). :type mass_setting: str :param stellar_contam: Chosen prescription for modelling unocculted stellar contamination (Options: one_spot / one_spot_free_log_g / two_spots / two_spots_free_log_g). :type stellar_contam: str :param offsets_applied: Whether a relative offset should be applied to a dataset (Options: single_dataset / two_datasets / three_datasets). :type offsets_applied: str :param error_inflation: Error bar inflation treatment in a retrieval (Options: Line15 / Piette20 / Line15+Piette20). :type error_inflation: str :param PT_dim: 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). :type PT_dim: int :param X_dim: 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). :type X_dim: int :param cloud_dim: Dimensionality of the cloud model prescription (only the Iceberg cloud model supports 3D clouds) (Options: 1 / 2 / 3). :type cloud_dim: int :param TwoD_type: For 2D models, specifies whether the model considers day-night gradients or evening-morning gradients (Options: D-N / E-M). :type TwoD_type: str :param TwoD_param_scheme: For 2D models, specifies which quantities should be consider as free parameters (e.g. day & night vs. terminator & day-night diff.) (Options: absolute / difference). :type TwoD_param_scheme: str :param species_EM_gradient: List of chemical species with an evening-morning mixing ratio gradient. :type species_EM_gradient: list of str :param species_DN_gradient: List of chemical species with a day-night mixing ratio gradient. :type species_DN_gradient: list of str :param species_vert_gradient: List of chemical species with a vertical mixing ratio gradient. :type species_vert_gradient: list of str :param Atmosphere_dimension: The dimensionality of the model atmosphere (Options: 1 / 2 / 3). :type Atmosphere_dimension: int :param opaque_Iceberg: If using the Iceberg cloud model, True disables the kappa parameter. :type opaque_Iceberg: bool :param surface: If True, model a surface via an opaque cloud deck. :type surface: bool :param sharp_DN_transition: For 2D / 3D models, sets day-night transition width (beta) to 0. :type sharp_DN_transition: bool :param sharp_EM_transition: For 2D / 3D models, sets evening-morning transition width (alpha) to 0. :type sharp_EM_transition: bool :param reference_parameter: For retrievals, whether R_p_ref or P_ref will be a free parameter (Options: R_p_ref / P_ref). :type reference_parameter: str :param disable_atmosphere: If True, returns a flat planetary transmission spectrum @ (Rp/R*)^2 :type disable_atmosphere: bool :param aerosol_species: Either 'free' or specific aerosol(s). :type aerosol_species: list of string :param log_P_slope_array: Log pressures where the temperature difference parameters are defined (Piette & Madhusudhan 2020 profile only). :type log_P_slope_array: np.array of float :param number_P_knots: Number of uniform knots in pressure space (only for the Pelletier 2021 P-T profile). :type number_P_knots: float :param PT_penalty: If True, introduces the sigma_smooth parameter for retrievals (only for the Pelletier 2021 P-T profile). :type PT_penalty: bool :param high_res_method: For high resolution retrievals, define which processing method will be used - only not None for high-res retrievals (Options: None, 'pca', 'sysrem'). :type high_res_method: list of str :param alpha_high_res_option: For high resolution retrievals, specify whether the retrieved model scaling parameter is in log space (default) or linear space (Options: 'log', 'linear'). :type alpha_high_res_option: str :param fix_alpha_high_res: If True, the alpha (model scaling) parameter in high resolution retrievals will be fixed to 1 and not a retrieved parameter. :type fix_alpha_high_res: bool :param fix_W_conv_high_res: If True, the W_conv (broadening) parameter in high resolution retrievals will be fixed to 0 and not a retrieved parameter. :type fix_W_conv_high_res: bool :param fix_beta_high_res: If True, the beta (error scaling) parameter in high resolution retrievals will be fixed to 1 and not a retrieved parameter. :type fix_beta_high_res: bool :param fix_Delta_phi_high_res: If True, the Delta_phi (phase shift) parameter in high resolution retrievals will be fixed to 0 and not a retrieved parameter. :type fix_Delta_phi_high_res: bool :param lognormal_logwidth_free: If True, has log_r_m_std_dev be a free parameter for aerosols. Only applicable for certain aerosols with precomputed grids. :type lognormal_logwidth_free: bool :param surface_components: List of surface components (if surface_model = 'Lab_data') :type surface_components: list of strings :param surface_model: Surface model definition (Options: gray, constant_albedo, lab_data) :type surface_model: string :param surface_percentage_option: Will make surface percentages log or linear (log is reccomended for CLR retrievals) (Options: linear, log) :type surface_percentage_option: string :param thermal: 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 :type thermal: bool :param reflection: If True, uses a two-stream multiple scattering reflection model. Only used here for seeing if we need to set the T_surf parameter :type reflection: bool :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). :rtype: params (np.array of str) .. py:function:: 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. :param params_drawn: Values of the free parameters drawn from the prior distribution. :type params_drawn: list of float | np.array of float :param N_params_cumulative: Cumulative sum of number of parameters (used for indexing). :type N_params_cumulative: np.array of int :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 :rtype: physical_drawn (list of float | np.array of float) .. py:function:: 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. :param PT_in: Drawn values of the pressure-temperature profile parameters. :type PT_in: list of float | np.array of float :param log_X_in: Drawn values of the mixing ratio parameters. :type log_X_in: list of float | np.array of float :param param_species: Chemical species with parametrised mixing ratios (trace species). :type param_species: list of str :param PT_dim: 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). :type PT_dim: int :param X_dim: 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). :type X_dim: int :param PT_profile: Chosen P-T profile parametrisation (Options: isotherm / gradient / two-gradients / Madhu / slope / file_read). :type PT_profile: str :param X_profile: Chosen mixing ratio profile parametrisation (Options: isochem / gradient / two-gradients / file_read / chem_eq). :type X_profile: str :param TwoD_type: For 2D models, specifies whether the model considers day-night gradients or evening-morning gradients (Options: D-N / E-M). :type TwoD_type: str :param TwoD_param_scheme: For 2D models, specifies which quantities should be consider as free parameters (e.g. day & night vs. terminator & day-night diff.) (Options: absolute / difference). :type TwoD_param_scheme: str :param species_EM_gradient: List of chemical species with an evening-morning mixing ratio gradient. :type species_EM_gradient: list of str :param species_DN_gradient: List of chemical species with a day-night mixing ratio gradient. :type species_DN_gradient: list of str :param species_vert_gradient: List of chemical species with a vertical mixing ratio gradient. :type species_vert_gradient: list of str :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. :rtype: PT_state (np.array of float) .. py:function:: 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. :param param_names: Free parameters defining this POSEIDON model. :type param_names: np.array of str :param clouds_in: Drawn values of the aerosol parameters. :type clouds_in: list of float | np.array of float :param cloud_model: Chosen cloud parametrisation (Options: cloud-free / MacMad17 / Iceberg). :type cloud_model: str :param cloud_dim: Dimensionality of the cloud model prescription (only the Iceberg cloud model supports 3D clouds) (Options: 1 / 2 / 3). :type cloud_dim: int :param N_params_cumulative: Cumulative sum of number of parameters (used for indexing). :type N_params_cumulative: np.array of int :param TwoD_type: For 2D models, specifies whether the model considers day-night gradients or evening-morning gradients (Options: D-N / E-M). :type TwoD_type: str :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). :rtype: kappa_cloud_0 (float) .. py:function:: 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. :param param_names: Free parameters defining this POSEIDON model. :type param_names: np.array of str :param geometry_in: Drawn values of the multidimensional atmospheric geometry parameters. :type geometry_in: list of float | np.array of float :param N_params_cumulative: Cumulative sum of number of parameters (used for indexing). :type N_params_cumulative: np.array of int :returns: Terminator opening angle (degrees). beta (float): Day-night opening angle (degrees). :rtype: alpha (float) .. py:function:: 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. :param param_names: Free parameters defining this POSEIDON model. :type param_names: np.array of str :param star: Collection of stellar properties used by POSEIDON. :type star: dict :param stellar_in: Drawn values of the stellar parameters. :type stellar_in: list of float | np.array of float :param stellar_contam: Chosen prescription for modelling unocculted stellar contamination (Options: one_spot / one_spot_free_log_g / two_spots / two_spots_free_log_g). :type stellar_contam: str :param N_params_cumulative: Cumulative sum of number of parameters (used for indexing). :type N_params_cumulative: np.array of int :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)). :rtype: f_het (float) .. py:function:: 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. :param param_names: Free parameters defining this POSEIDON model. :type param_names: np.array of str :param surface_in: Drawn values of the surface parameters. :type surface_in: list of float | np.array of float surface (bool): If True, model a surface via an opaque cloud deck. surface_model (string): Surface model definition (Options: gray, constant, lab_data) N_params_cumulative (np.array of int): Cumulative sum of number of parameters (used for indexing). :returns: P_surf, T_surf, albedo_surf, surface_component_percentages