POSEIDON.contributions

Attributes

cp

comm

rank

block

thread

Functions

wl_grid_constant_R(wl_min, wl_max, R)

Create a wavelength array with constant spectral resolution (R = wl/dwl).

check_atmosphere_physical(atmosphere, opac)

Checks that a specific model atmosphere is physical.

extinction_spectral_contribution(chemical_species, ...)

Main function to evaluate extinction coefficients for molecules / atoms,

spectral_contribution(planet, star, model, atmosphere, ...)

Calculate extinction coefficients, then solve the radiative transfer

plot_spectral_contribution(planet, wl, spectrum, ...)

Plot the spectral contributions directly from the spectral_contribution() outputs

extinction_pressure_contribution(chemical_species, ...)

Main function to evaluate extinction coefficients for molecules / atoms,

pressure_contribution_compute_spectrum(planet, star, ...)

Calculate extinction coefficients, then solve the radiative transfer

pressure_contribution(planet, star, model, atmosphere, ...)

Computes the pressure contribution function by looping over each layer in the Pressure array

plot_pressure_contribution(wl, P, planet, ...[, R, ...])

Plot the pressure contributions directly from the pressure_contribution() outputs

photometric_contribution_function(wl, P, Contribution, ...)

Computes the photometric contribution directly from the pressure_contribution() outputs

plot_photometric_contribution(P, planet, ...[, bins, ...])

Plots the photometric contributions directly from outputs of photometric_contribution_function()

Module Contents

POSEIDON.contributions.cp
POSEIDON.contributions.comm
POSEIDON.contributions.rank
POSEIDON.contributions.block
POSEIDON.contributions.thread
POSEIDON.contributions.wl_grid_constant_R(wl_min, wl_max, R)

Create a wavelength array with constant spectral resolution (R = wl/dwl).

Parameters:

  • wl_min (float) – Minimum wavelength of grid (μm).

  • wl_max (float) – Maximum wavelength of grid (μm).

  • R (int or float) – Spectral resolution of desired wavelength grid.

Returns:

Model wavelength grid (μm).

Return type:

wl (np.array of float)

POSEIDON.contributions.check_atmosphere_physical(atmosphere, opac)

Checks that a specific model atmosphere is physical.

Parameters:

  • atmosphere (dict) – Collection of atmospheric properties.

  • opac (dict) – Collection of cross sections and other opacity sources.

Returns:

True if atmosphere physical, otherwise False.

Return type:

Bool

POSEIDON.contributions.extinction_spectral_contribution(chemical_species, active_species, cia_pairs, ff_pairs, bf_species, aerosol_species, n, T, P, wl, X, X_active, X_cia, X_ff, X_bf, a, gamma, P_cloud, kappa_cloud_0, sigma_stored, cia_stored, Rayleigh_stored, ff_stored, bf_stored, enable_haze, enable_deck, enable_surface, N_sectors, N_zones, T_fine, log_P_fine, P_surf, enable_Mie, n_aerosol_array, sigma_Mie_array, P_deep=1000.0, contribution_species='', bulk_species=False, cloud_contribution=False, cloud_species='', cloud_total_contribution=False)

Main function to evaluate extinction coefficients for molecules / atoms, Rayleigh scattering, hazes, and clouds for parameter combination chosen in retrieval step.

Takes in cross sections pre-interpolated to ‘fine’ P and T grids before retrieval run (so no interpolation is required at each step). Instead, for each atmospheric layer the extinction coefficient is simply kappa = n * sigma[log_P_nearest, T_nearest, wl], where the ‘nearest’ values are the closest P_fine, T_fine points to the actual P, T values in each layer. This results in a large speed gain.

The output extinction coefficient arrays are given as a function of layer number (indexed from low to high altitude), terminator sector, and wavelength.

In the spectral contribution plots, each extinction coefficient is turned off except for the one being analysed.

POSEIDON.contributions.spectral_contribution(planet, star, model, atmosphere, opac, wl, spectrum_type='transmission', save_spectrum=False, disable_continuum=False, suppress_print=False, Gauss_quad=2, use_photosphere_radius=True, device='cpu', y_p=np.array([0.0]), contribution_species_list=[], bulk_species=True, cloud_contribution=False, cloud_species_list=[], cloud_total_contribution=False)

Calculate extinction coefficients, then solve the radiative transfer equation to compute the spectrum of the model atmosphere in order to get the spectral contribution of each species.

Parameters:

  • planet (dict) – Collection of planetary properties used by POSEIDON.

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

  • model (dict) – A specific description of a given POSEIDON model.

  • atmosphere (dict) – Collection of atmospheric properties.

  • opac (dict) – Collection of cross sections and other opacity sources.

  • wl (np.array of float) – Model wavelength grid (μm).

  • spectrum_type (str) –

    The type of spectrum for POSEIDON to compute (Options: transmission / emission / direct_emission /

    transmission_time_average).

  • save_spectrum (bool) – If True, writes the spectrum to ‘./POSEIDON_output/PLANET/spectra/’.

  • disable_continuum (bool) – If True, turns off CIA and Rayleigh scattering opacities.

  • suppress_print (bool) – if True, turn off opacity print statements (in line-by-line mode).

  • Gauss_quad (int) – Gaussian quadrature order for integration over emitting surface * Only for emission spectra * (Options: 2 / 3).

  • use_photosphere_radius (bool) – If True, use R_p at tau = 2/3 for emission spectra prefactor.

  • device (str) – Experimental: use CPU or GPU (only for emission spectra) (Options: cpu / gpu)

  • y_p (np.array of float) – Coordinate of planet centre along orbit at the time the spectrum is computed (y_p = 0, the default, corresponds to mid-transit). For non-grazing transits of uniform stellar disks, the spectrum is identical at all times due to translational symmetry, so y_p = 0 is good for all times post second contact and pre third contact. Units are in m, not in stellar radii.

  • contribution_species_list (np.array of string) – List of gas species to analyze the spectral contribution of

  • bulk_species (bool) – If true, will compute the spectral contribution of the bulk species

  • cloud_contribution (bool) – If true, will compute the spectral contribution of clouds (either parameterized or aerosols)

  • cloud_species_list (np.array of string) – List of aerosols to analyze the spectral contribution of. Cloud_contribution must be True

  • cloud_total_contribution (bool) – If true, will compute spectral contribution of combined clouds If using parameterized clouds, this bool will need to be true (to show deck + haze, for example) If using aerosols, will compute combined aerosol spectral contribution

Returns:

The spectrum of the atmosphere (transmission or emission). spectrum_contribution_list_names (np.array of string):

Array used for plotting (contains names and order of spectral contribution spectra)

spectrum_contribution_list (np.array of float):

Array of spectra, each corresponding to the spectral contribution of a species in the list_names array.

Return type:

spectrum (np.array of float)

POSEIDON.contributions.plot_spectral_contribution(planet, wl, spectrum, spectrum_contribution_list_names, spectrum_contribution_list, full_spectrum_first=True, y_unit='transit_depth', brightness_temperature=False, star=None, y_min=None, y_max=None, figure_shape='wide', save_fig=False, line_width_list=[], colour_list=[], return_fig=False, ax=None, file_label=None, fill_between=[], fill_between_alpha=0.5, fill_to_spectrum=[], data=None, spectra_labels=[], dark_mode=False, **kwargs)

Plot the spectral contributions directly from the spectral_contribution() outputs

Parameters:

  • planet (dict) – Collection of planetary properties used by POSEIDON.

  • wl (np.array of float) – Model wavelength grid (μm).

  • spectrum (np.array of float) – The spectrum of the atmosphere (transmission or emission).

  • spectrum_contribution_list_names (np.array of string) – Array used for plotting (contains names and order of spectral contribution spectra)

  • spectrum_contribution_list (np.array of float) – Array of spectra, each corresponding to the spectral contribution of a species in the list_names array.

  • full_spectrum_first (bool) – If True, the full spectrum will be plotted first (behind all other spectra)

  • y_unit (str, optional) – The unit of the y-axis (Options: ‘transit_depth’, ‘eclipse_depth’, ‘(Rp/Rs)^2’, ‘(Rp/R*)^2’, ‘Fp/Fs’, ‘Fp/F*’, ‘Fp’).

  • brightness_temperature (bool, optional) – If True, will convert spectrum and spectrum_contribution_list_names to brightness temperature

  • star (dict, optional) – Collection of stellar properties used by POSEIDON. For converting secondary eclipse spectra into brightness temperature

  • y_min (float, optional) – The minimum value for the y-axis.

  • y_max (float, optional) – The maximum value for the y-axis.

  • figure_shape (str, optional) – The shape of the figure (‘default’ or ‘wide’ - the latter is 16:9).

  • save_fig (bool, optional) – If True, saves a PDF in the POSEIDON output folder.

  • line_width_list (array of floats, optional) – Optional line widths. We recommend the full spectra be larger than the contributing ones

  • colour_list (list, optional) – A list of colours for the model spectra

  • return_fig (bool, optional) – Returns the fig object, in case you want it in the notebook to manipulate

  • ax (matplotlib axis object, optional) – Matplotlib axis provided externally.

  • file_label (str, optional) – Optional label to append to end of the output file name.

  • dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

POSEIDON.contributions.extinction_pressure_contribution(chemical_species, active_species, cia_pairs, ff_pairs, bf_species, aerosol_species, n, T, P, wl, X, X_active, X_cia, X_ff, X_bf, a, gamma, P_cloud, kappa_cloud_0, sigma_stored, cia_stored, Rayleigh_stored, ff_stored, bf_stored, enable_haze, enable_deck, enable_surface, N_sectors, N_zones, T_fine, log_P_fine, P_surf, enable_Mie, n_aerosol_array, sigma_Mie_array, P_deep=1000.0, contribution_species='', bulk_species=False, cloud_contribution=False, cloud_species='', cloud_total_contribution=False, layer_to_ignore=0, total_pressure_contribution=False)

Main function to evaluate extinction coefficients for molecules / atoms, Rayleigh scattering, hazes, and clouds for parameter combination chosen in retrieval step.

Takes in cross sections pre-interpolated to ‘fine’ P and T grids before retrieval run (so no interpolation is required at each step). Instead, for each atmospheric layer the extinction coefficient is simply kappa = n * sigma[log_P_nearest, T_nearest, wl], where the ‘nearest’ values are the closest P_fine, T_fine points to the actual P, T values in each layer. This results in a large speed gain.

The output extinction coefficient arrays are given as a function of layer number (indexed from low to high altitude), terminator sector, and wavelength.

For pressure contribution, it goes row by row And removes the opacity (either total or individual species) from that row

POSEIDON.contributions.pressure_contribution_compute_spectrum(planet, star, model, atmosphere, opac, wl, spectrum_type='transmission', save_spectrum=False, disable_continuum=False, suppress_print=False, Gauss_quad=2, use_photosphere_radius=True, device='cpu', y_p=np.array([0.0]), contribution_species_list=[], bulk_species=True, cloud_contribution=False, cloud_species_list=[], cloud_total_contribution=False, total_pressure_contribution=False, layer_to_ignore=0)

Calculate extinction coefficients, then solve the radiative transfer equation to compute the spectrum of the model atmosphere.

In the pressure contribution plots, the extinction coefficient in one pressure layer (either total or individual species) is turned off and the spectrum is recomputed

Note that this function is called by pressure_contribution, which loops over all pressure layers Though it can be called by a user, to calculate the contribution for a single pressure layer

Parameters:

  • planet (dict) – Collection of planetary properties used by POSEIDON.

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

  • model (dict) – A specific description of a given POSEIDON model.

  • atmosphere (dict) – Collection of atmospheric properties.

  • opac (dict) – Collection of cross sections and other opacity sources.

  • wl (np.array of float) – Model wavelength grid (μm).

  • spectrum_type (str) –

    The type of spectrum for POSEIDON to compute (Options: transmission / emission / direct_emission /

    transmission_time_average).

  • save_spectrum (bool) – If True, writes the spectrum to ‘./POSEIDON_output/PLANET/spectra/’.

  • disable_continuum (bool) – If True, turns off CIA and Rayleigh scattering opacities.

  • suppress_print (bool) – if True, turn off opacity print statements (in line-by-line mode).

  • Gauss_quad (int) – Gaussian quadrature order for integration over emitting surface * Only for emission spectra * (Options: 2 / 3).

  • use_photosphere_radius (bool) – If True, use R_p at tau = 2/3 for emission spectra prefactor.

  • device (str) – Experimental: use CPU or GPU (only for emission spectra) (Options: cpu / gpu)

  • y_p (np.array of float) – Coordinate of planet centre along orbit at the time the spectrum is computed (y_p = 0, the default, corresponds to mid-transit). For non-grazing transits of uniform stellar disks, the spectrum is identical at all times due to translational symmetry, so y_p = 0 is good for all times post second contact and pre third contact. Units are in m, not in stellar radii.

  • contribution_species_list (np.array of string) – List of gas species to analyze the pressure contribution of

  • bulk_species (bool) – If true, will compute the pressure contribution of the bulk species

  • cloud_contribution (bool) – If true, will compute the pressure contribution of clouds (either parameterized or aerosols)

  • cloud_species_list (np.array of string) – List of aerosols to analyze the pressure contribution of. Cloud_contribution must be True

  • cloud_total_contribution (bool) – If true, will compute pressure contribution of combined clouds If using parameterized clouds, this bool will need to be true (to show deck + haze, for example) If using aerosols, will compute combined aerosol pressure contribution

  • total_pressure_contribution (bool) – If true, will compute the pressure contribution by removing all opacity from each layer

  • layer_to_ignore (int) – The pressure layer whose opacity will be turned off. Looped over in pressure_contribution()

Returns:

The spectrum of the atmosphere (transmission or emission). spectrum_contribution_list_names (np.array of string):

Array used for plotting (contains names and order of pressure contribution spectra)

spectrum_contribution_list (np.array of float):

Array of spectra, each corresponding to the pressure contribution of a species in the list_names array.

Return type:

spectrum (np.array of float)

POSEIDON.contributions.pressure_contribution(planet, star, model, atmosphere, opac, wl, spectrum_type='transmission', save_spectrum=False, disable_continuum=False, suppress_print=False, Gauss_quad=2, use_photosphere_radius=True, device='cpu', y_p=np.array([0.0]), contribution_species_list=[], bulk_species=True, cloud_contribution=False, cloud_species_list=[], cloud_total_contribution=False, total_pressure_contribution=False, verbose=False)

Computes the pressure contribution function by looping over each layer in the Pressure array

Parameters:

  • planet (dict) – Collection of planetary properties used by POSEIDON.

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

  • model (dict) – A specific description of a given POSEIDON model.

  • atmosphere (dict) – Collection of atmospheric properties.

  • opac (dict) – Collection of cross sections and other opacity sources.

  • wl (np.array of float) – Model wavelength grid (μm).

  • spectrum_type (str) –

    The type of spectrum for POSEIDON to compute (Options: transmission / emission / direct_emission /

    transmission_time_average).

  • save_spectrum (bool) – If True, writes the spectrum to ‘./POSEIDON_output/PLANET/spectra/’.

  • disable_continuum (bool) – If True, turns off CIA and Rayleigh scattering opacities.

  • suppress_print (bool) – if True, turn off opacity print statements (in line-by-line mode).

  • Gauss_quad (int) – Gaussian quadrature order for integration over emitting surface * Only for emission spectra * (Options: 2 / 3).

  • use_photosphere_radius (bool) – If True, use R_p at tau = 2/3 for emission spectra prefactor.

  • device (str) – Experimental: use CPU or GPU (only for emission spectra) (Options: cpu / gpu)

  • y_p (np.array of float) – Coordinate of planet centre along orbit at the time the spectrum is computed (y_p = 0, the default, corresponds to mid-transit). For non-grazing transits of uniform stellar disks, the spectrum is identical at all times due to translational symmetry, so y_p = 0 is good for all times post second contact and pre third contact. Units are in m, not in stellar radii.

  • contribution_species_list (np.array of string) – List of gas species to analyze the pressure contribution of

  • bulk_species (bool) – If true, will compute the pressure contribution of the bulk species

  • cloud_contribution (bool) – If true, will compute the pressure contribution of clouds (either parameterized or aerosols)

  • cloud_species_list (np.array of string) – List of aerosols to analyze the pressure contribution of. Cloud_contribution must be True

  • cloud_total_contribution (bool) – If true, will compute pressure contribution of combined clouds If using parameterized clouds, this bool will need to be true (to show deck + haze, for example) If using aerosols, will compute combined aerosol pressure contribution

  • total_pressure_contribution (bool) – If true, will compute the pressure contribution by removing all opacity from each layer

Returns:

Contribution (np.array)

Array. [i,j,k] i = molecule number (or total if total = True), j = Pressure layer, k = Wavelength

norm (np.array)

Array [i,j] where i = molecule number and j = wavelength. If user wants to normalize them (not used in our code)

spectrum_contribution_list_names (np.array of string):

Array used for plotting (contains names and order of spectral contribution spectra)

POSEIDON.contributions.plot_pressure_contribution(wl, P, planet, Contribution, spectrum_contribution_list_names, R=100, return_fig=False, save_fig=False, show_log_plot=False, file_label=None, dark_mode=False)

Plot the pressure contributions directly from the pressure_contribution() outputs

Parameters:

  • wl (np.array of float) – Model wavelength grid (μm).

  • P (np.array of float) – Model pressure grid (bar). (From atmosphere[‘P’])

  • Contribution (np.array) – Array. [i,j,k] i = molecule number (or total if total = True), j = Pressure layer, k = Wavelength

  • spectrum_contribution_list_names (np.array of string) – Array used for plotting (contains names and order of spectral contribution spectra)

  • R (int, optional) – Spectral resolution (R = wl/dwl) to bin the model spectra to.

  • return_fig (bool, optional) – Returns the fig object, in case you want it in the notebook to manipulate

  • save_fig (bool, optional) – If True, saves a PDF in the POSEIDON output folder.

  • show_log_plot (bool, optional) – If True, will also show the log plot of the contribution function.

  • file_label (str, optional) – Optional label to append to end of the output file name.

  • dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

POSEIDON.contributions.photometric_contribution_function(wl, P, Contribution, spectrum_contribution_list_names, binsize=1, treat_wlmin_as_zero=False)

Computes the photometric contribution directly from the pressure_contribution() outputs (a photometric contribution is just the integral average over wavelengths, i.e. the mean)

Parameters:

  • wl (np.array of float) – Model wavelength grid (μm).

  • P (np.array of float) – Model pressure grid (bar). (From atmosphere[‘P’])

  • Contribution (np.array) – Array. [i,j,k] i = molecule number (or total if total = True), j = Pressure layer, k = Wavelength

  • spectrum_contribution_list_names (np.array of string) – Array used for plotting (contains names and order of spectral contribution spectra)

  • binsize (float) – The size of the wavelength bin

  • treat_wlmin_as_zero (bool, optional) – If True, will set wl_min as 0 before binning (makes bins look nicer than 0.2 to 1.2 um)

Returns:

Array of each photometric contribution function, corresponding to the wavelength bins photometric_all_wavelengths (np.array of floats):

Array containing photometric contributions across all wavelengths

bins (np.array of floats):

Wavelength bins (wl_min and wl_max for each bin) (for plotting)

Return type:

photometric_contribution (np.array of floats)

POSEIDON.contributions.plot_photometric_contribution(P, planet, photometric_contribution, photometric_all_wavelengths, spectrum_contribution_list_names, bins=[], return_fig=False, save_fig=False, file_label=None, dark_mode=False)

Plots the photometric contributions directly from outputs of photometric_contribution_function()

Parameters:

  • wl (np.array of float) – Model wavelength grid (μm).

  • P (np.array of float) – Model pressure grid (bar). (From atmosphere[‘P’])

  • photometric_contribution (np.array of floats) – Array of each photometric contribution function, corresponding to the wavelength bins

  • photometric_all_wavelengths (np.array of floats) – Array containing photometric contributions across all wavelengths

  • spectrum_contribution_list_names (np.array of string) – Array used for plotting (contains names and order of spectral contribution spectra)

  • bins (np.array of floats) – Wavelength bins (wl_min and wl_max for each bin) (for plotting and the legend)

  • return_fig (bool, optional) – Returns the fig object, in case you want it in the notebook to manipulate.

  • save_fig (bool, optional) – If True, saves a PDF in the POSEIDON output folder.

  • file_label (str, optional) – Optional label to append to end of the output file name.

  • dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).