POSEIDON.clouds =============== .. py:module:: POSEIDON.clouds .. autoapi-nested-parse:: Functions that are used to incorporate aerosols into POSEIDON Attributes ---------- .. autoapisummary:: POSEIDON.clouds.all_etas POSEIDON.clouds.all_xs POSEIDON.clouds.all_Qexts POSEIDON.clouds.all_Qscats POSEIDON.clouds.all_Qbacks POSEIDON.clouds.all_gs POSEIDON.clouds.wl_Mie_empty POSEIDON.clouds.free_or_file Functions --------- .. autoapisummary:: POSEIDON.clouds.wl_grid_constant_R POSEIDON.clouds.find_nearest POSEIDON.clouds.plot_effective_cross_section_aerosol POSEIDON.clouds.plot_aerosol_number_density_fuzzy_deck POSEIDON.clouds.load_refractive_indices_from_file POSEIDON.clouds.plot_refractive_indices_from_file POSEIDON.clouds.compute_and_plot_aerosol_cross_section_from_file POSEIDON.clouds.compute_and_plot_effective_cross_section_constant POSEIDON.clouds.plot_clouds POSEIDON.clouds.plot_lognormal_distribution POSEIDON.clouds.database_properties_plot POSEIDON.clouds.vary_one_parameter POSEIDON.clouds.compute_relevant_Mie_properties POSEIDON.clouds.load_aerosol_grid POSEIDON.clouds.interpolate_sigma_Mie_grid POSEIDON.clouds.Mie_cloud POSEIDON.clouds.get_iterations_required POSEIDON.clouds.get_An POSEIDON.clouds.get_As POSEIDON.clouds.get_extinctions POSEIDON.clouds.get_from_cache POSEIDON.clouds.add POSEIDON.clouds.get_and_update POSEIDON.clouds.Mie_cloud_free POSEIDON.clouds.precompute_cross_sections_one_aerosol_LXMIE POSEIDON.clouds.precompute_cross_sections_one_aerosol_custom_LXMIE POSEIDON.clouds.precompute_cross_sections_from_indices_LXMIE POSEIDON.clouds.compute_mie_properties POSEIDON.clouds.precompute_cross_sections_one_aerosol_miepython POSEIDON.clouds.precompute_cross_sections_from_indices_miepython POSEIDON.clouds.make_aerosol_database POSEIDON.clouds.switch_aerosol_in_opac Module Contents --------------- .. py:function:: wl_grid_constant_R(wl_min, wl_max, R) Create a wavelength array with constant spectral resolution (R = wl/dwl). :param wl_min: Minimum wavelength of grid (μm). :type wl_min: float :param wl_max: Maximum wavelength of grid (μm). :type wl_max: float :param R: Spectral resolution of desired wavelength grid. :type R: int or float :returns: Model wavelength grid (μm). :rtype: wl (np.array of float) .. py:function:: find_nearest(array, value) .. py:function:: plot_effective_cross_section_aerosol(aerosol, wl, r_m) Plots the effective extinction cross section of an aerosol in the database for visualization purposes :param aerosol: Aerosol name :type aerosol: string :param wl: Model wavelength grid (μm) :type wl: np.array of float :param r_m: Mean particle sizes (in um) :type r_m: float :returns: Outputs a plot of wl (x) vs log effective extincrion cross section (y) .. py:function:: plot_aerosol_number_density_fuzzy_deck(atmosphere, log_P_cloud, log_n_max, fractional_scale_height) Plots the number density of an aerosol above a fuzzy deck :param atmosphere: Collection of atmospheric properties. :type atmosphere: dict :param Fuzzy Deck Arguments: :param log_P_cloud: Cloud Top Pressure (everything below P_cloud is opaque). If cloud coverage is complete, P_cloud is located at R_p :type log_P_cloud: float :param log_n_max: Logorithm of maximum number density (at the cloud top) :type log_n_max: array of float :param fractional_scale_height: fractional scale height of aerosol :type fractional_scale_height: array of float :returns: Outputs a plot of pressure (y) versus number density of aerosol (x) .. py:function:: load_refractive_indices_from_file(wl, file_name) Loads in the refractive indices from a text file (columns : wl n k) Either the first two rows are skipped, or the header is assumed to be comments ('#') :param wl: Model wavelength grid (μm). :type wl: np.array of float :param file_name: File name (with directory included) :type file_name: string :returns: r_i_real (np.array of float) Array with the loaded in real indices interpolated onto wl_Mie r_i_complex (np.array of float) Array with the loaded in imaginary indices interpolated onto wl_Mie .. py:function:: plot_refractive_indices_from_file(wl, file_name, species=None) Plots the refractive indices from a txt file (columns : wl n k) Either the first two rows are skipped, or the header is assumed to be comments ('#') :param wl: Model wavelength grid (μm). :type wl: np.array of float :param file_name: File name (with directory included) :type file_name: string :param species: Species name for the title of the plot. :type species: string, optional :returns: Outputs a plot of wl (x) vs refractive indices (y) .. py:function:: compute_and_plot_aerosol_cross_section_from_file(wl, r_m, file_name, species=None) Plots the effective cross sections from a txt file (columns : wl n k) Either the first two rows are skipped, or the header is assumed to be comments ('#') This function precomputes the cross sections directly, and plots them :param wl: Model wavelength grid (μm). :type wl: np.array of float :param r_m: Mean particle size (um). :type r_m: float :param file_name: File name (with directory included). :type file_name: string :param species: Species name for the title of the plot. :type species: string, optional :returns: Outputs a plot of wl (x) vs different cross sections, asymmetry parameter, and single scattering albedo (y) .. py:function:: compute_and_plot_effective_cross_section_constant(wl, r_m, r_i_real, r_i_complex) Plots the effective cross sections for a constant (with wavelength) refractive index This function precomputes the cross sections directly, and plots them :param wl: Model wavelength grid (μm). :type wl: np.array of float :param r_m: Mean particle size (um) :type r_m: float :param r_i_real: Real refractive index (only used for constant, free refractive index) :type r_i_real: float :param r_i_complex: Complex refractive index (only used for constant, free refractive index) :type r_i_complex: float :returns: Outputs a plot of wl (x) vs effective extinction cross section (y) .. py:function:: plot_clouds(planet, model, atmosphere, colour_list=[]) Plots how the aerosols look like in the forward model atmosphere. Very similar to how plot_PT or plot_chem work This function precomputes the cross sections directly, and plots them :param planet: Collection of planetary properties used by POSEIDON. :type planet: dict :param model: A specific description of a given POSEIDON model. :type model: dict :param atmosphere: Collection of atmospheric properties. :type atmosphere: dict :param colour_list: List of colours for each retrieved chemical profile. :type colour_list: list, optional :returns: Outputs a plot of mixing ratio (x) vs pressure (y) .. py:function:: plot_lognormal_distribution(r_m_std_dev=0.5) Plots the lognormal distribution (which points are computed and integrated over) :param r_m_std_dev: Width of the lognormal distribution :type r_m_std_dev: float :returns: Outputs a plot particle size distributions .. py:function:: database_properties_plot(file_name) Plots the refractive index and aerosol properties in the aerosol database (same format as aerosol-database.pdf) :param file_name: Name of refractive index file, with file path included :type file_name: string :returns: Outputs a plot of refractive index, sigma_ext,eff, g, and w for an aerosol in the database .. py:function:: vary_one_parameter(model, planet, star, param_name, vary_list, wl, opac, P, P_ref, R_p_ref, PT_params_og, log_X_params_og, cloud_params_og, spectrum_type='transmission', y_min=None, y_max=None, y_unit='transit_depth', wl_max=None) This function is utilized in tutorial noteooks to show how turning a knob on a parameter changes a resultant spectrum :param model: A specific description of a given POSEIDON model. :type model: dict :param planet: Collection of planetary properties used by POSEIDON. :type planet: dict :param star: Collection of stellar properties used by POSEIDON. :type star: dict :param param_name: Name of the parameter to vary :type param_name: string :param vary_list: Array containing values to test :type vary_list: array of float :param wl: Model wavelength grid (μm). :type wl: np.array of float :param opac: Collection of cross sections and other opacity sources. :type opac: dict :param P: Model pressure grid (bar). :type P: np.array of float :param P_ref: Reference pressure (bar). :type P_ref: float :param R_p_ref: Planet radius corresponding to reference pressure (m). :type R_p_ref: float :param PT_params_og: Original parameters defining the pressure-temperature field. :type PT_params_og: np.array of float :param log_X_params_og: Original parameters defining the log-mixing ratio field. :type log_X_params_og: np.array of float :param cloud_params_og: Original parameters defining atmospheric aerosols. :type cloud_params_og: np.array of float :param spectrum_type: The type of spectrum for POSEIDON to compute (Options: transmission / emission / direct_emission / transmission_time_average). :type spectrum_type: str :param y_min: Minimum value for the y-axis. :type y_min: float :param y_max: Maximum value for the y-axis. :type y_max: float :param y_unit: The unit of the y-axis (Options: 'transit_depth', 'eclipse_depth', '(Rp/Rs)^2', '(Rp/R*)^2', 'Fp/Fs', 'Fp/F*', 'Fp'). :type y_unit: str :returns: Outputs a plot of resultant spectra with the param_name at the vary_list values. .. py:function:: compute_relevant_Mie_properties(model, aerosol_species, aerosol_stored, P, wl, r, H, n, r_m, r_i_real, r_i_complex, P_cloud, P_cloud_bottom, log_X_Mie, log_n_max, fractional_scale_height, lognormal_logwidth_free, log_r_m_std_dev) .. py:function:: load_aerosol_grid(aerosol_species, grid='aerosol', comm=MPI.COMM_WORLD, rank=0, lognormal_logwith_free=False, sigma_Mie_grid=[], wl_grid=[], r_m_grid=[], log_r_m_std_dev_array=[], loading_opac=False) Load a aerosol cross section grid (similar to load_chemistry_grid in chemistry.py) :param aerosol_species: List of aerosol species to load mixing ratios from grid. :type aerosol_species: list or np.array of str :param grid: Name of the pre-computed aerosol cross section grid. The file should be located in the POSEIDON input directory (specified in your .bashrc file) with a name format like 'GRID_database.hdf5' (e.g. 'aerosol_database.hdf5'). By default, POSEIDON ships with an aerosol grid computed from the LX-MIE algorithm: (Options: aerosol). :type grid: str :param comm: Communicator used to allocate shared memory on multiple cores. :type comm: MPI communicator :param rank: Rank used to allocate shared memory on multiple cores. :type rank: MPI rank :param lognormal_logwidth_free: If log_r_m_std_dev is a free parameter in the grid being used :type lognormal_logwidth_free: bool :param sigme_Mie_grid: Array to store aerosol properties. Is empty in forward models, or passed by opacity_tables :type sigme_Mie_grid: array :param wl_grid: Array to store aerosol wavelength grid. Is empty in forward models, or passed by opacity_tables :type wl_grid: array :param rm_grid: Array to store aerosol radii grid. Is empty in forward models, or passed by opacity_tables :type rm_grid: array :param log_r_m_std_dev_array: Array to store aerosol log width grid. Is empty in forward models, or passed by opacity_tables :type log_r_m_std_dev_array: array :param loading_opac: If true, is being called in opacity_tables and is just loading in sigma_Mie_grid :type loading_opac: bool :returns: Dictionary containing the loaded in aerosol properties. :rtype: aerosol_grid (dict) .. py:function:: interpolate_sigma_Mie_grid(aerosol_grid, wl, r_m_array, aerosol_species, return_dict=True, lognormal_logwith_free=False, log_r_m_std_dev=0.5) Interpolate a pre-computed grid of aerosol cross sections onto a model wl range, and mean particle size. :param aerosol_grid: Dictionary containing the aerosol cross section database. :type aerosol_grid: dict :param wl: Model wavelength grid (μm). :type wl: np.array of float :param r_m_array: Mean particle size (in um) (for each aerosol_species) :type r_m_array: float :param chemical_species: List of chemical species to interpolate mixing ratios for. :type chemical_species: str or np.array of str :param return_dict: If False, return an array of shape (len(species), len(P_array)). If True, will return a dictionary :type return_dict: bool :returns: A dictionary of effective cross sections with keys being the same names as specified in aerosol_species. sigma_Mie_interp_array (np.array of float) ---> if return_dict=False: An array containing the effective cross sections for the species specified in aerosol_species. :rtype: sigma_Mie_interp_dict (dict) ---> if return_dict = True .. py:function:: Mie_cloud(P, wl, r, H, n, r_m, aerosol_species, cloud_type, aerosol_grid=None, P_cloud=0, log_n_max=0, fractional_scale_height=0, log_X_Mie=0, P_cloud_bottom=0, log_r_m_std_dev=0.5, lognormal_logwidth_free=False) Calculates the number density n(P) and cross section sigma(wavelength) for different aerosol cloud models Also pulls the asymmetry parameter and single scattering albedo Utilized the precomputed, aerosol database Outputs from this function are then utilized to generated extinction coefficients in core.py :param P: Model pressure grid (bar). (From atmosphere['P']) :type P: np.array of float :param wl: Model wavelength grid (μm). :type wl: np.array of float :param r: Radial distant profile (m). (From atmosphere['P']) :type r: 3D np.array of float :param H: gas scale height :type H: np.array of float :param n: total number density array :type n: np.array of float :param r_m: Mean particle sizes (in um) :type r_m: np.array of float :param aerosol_species: Array with aerosol species in it :type aerosol_species: np.array of string :param cloud_type: uniform_X, fuzzy_deck, slab, opaque_deck_with_slab, fuzzy_deck_with_slab :type cloud_type: string :param aerosol_grid: Precomputed aerosol cross section dictionary If = None, loads it in :type aerosol_grid: dict :param -------- Semi- Optional Arguments -------: :param Fuzzy Deck Arguments: :param P_cloud: Cloud Top Pressure (everything below P_cloud is opaque). If cloud coverage is complete, P_cloud is located at R_p :type P_cloud: float :param log_n_max: Logorithm of maximum number density (at the cloud top) :type log_n_max: array of float :param fractional_scale_height: fractional scale height of aerosol :type fractional_scale_height: array of float :param Uniform X Arguments: :param log_X_Mie: Mixing ratio for a mie aerosol (either specified or free, only for uniform haze models) :type log_X_Mie: array of float :param Slab Arguments: :param P_cloud: Cloud Top Pressure (everything between P_cloud and P_cloud_bottom is uniform X). :type P_cloud: float :param P_cloud_bottom: Pressure of the bottom of the slab :type P_cloud_bottom: array of float :param -------- Optional Arguments -------: :param log_r_m_std_dev: Geometric standard deviation for particle size :type log_r_m_std_dev: float :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 Returns: n_aerosol, sigma_Mie .. py:data:: all_etas :value: [] .. py:data:: all_xs :value: [] .. py:data:: all_Qexts :value: [] .. py:data:: all_Qscats :value: [] .. py:data:: all_Qbacks :value: [] .. py:data:: all_gs :value: [] .. py:data:: wl_Mie_empty .. py:data:: free_or_file :value: '' .. py:function:: get_iterations_required(xs, c=4.3) .. py:function:: get_An(zs, n) .. py:function:: get_As(max_n, zs) .. py:function:: get_extinctions(m, xs) .. py:function:: get_from_cache(eta, xs, max_frac_error=0.05) .. py:function:: add(eta, xs, Qexts, Qscats, Qbacks, g, size_limit=1000000) .. py:function:: get_and_update(eta, xs) .. py:function:: Mie_cloud_free(P, wl, wl_Mie_in, r, H, n, r_m, r_i_real, r_i_complex, cloud_type, P_cloud=0, log_n_max=0, fractional_scale_height=0, log_X_Mie=0, P_cloud_bottom=-100, r_m_std_dev=0.5, z_max=5, num_integral_points=100, algorithm='miepython') Calculates the number density n(P) and cross section sigma(wavelength) for different aerosol cloud models Also pulls the asymmetry parameter and single scattering albedo Utilized the LX-Mie algorithm to compute constant refractive index or file_read refractive index files Outputs from this function are then utilized to generated extinction coefficients in core.py :param P: Model pressure grid (bar). (From atmosphere['P']) :type P: np.array of float :param wl: Model wavelength grid (μm). :type wl: np.array of float :param r: Radial distant profile (m). (From atmosphere['P']) :type r: 3D np.array of float :param H: gas scale height :type H: np.array of float :param n: total number density array :type n: np.array of float :param r_m: Mean particle sizes (in um) :type r_m: float :param cloud_type: uniform_X, fuzzy_deck, slab, opaque_deck_with_slab, fuzzy_deck_with_slab :type cloud_type: string :param -------- Semi- Optional Arguments -------: :param Fuzzy Deck Arguments: :param P_cloud: Cloud Top Pressure (everything below P_cloud is opaque). If cloud coverage is complete, P_cloud is located at R_p :type P_cloud: float :param log_n_max: Logorithm of maximum number density (at the cloud top) :type log_n_max: float :param fractional_scale_height: fractional scale height of aerosol :type fractional_scale_height: float :param Uniform X Arguments: :param log_X_Mie: Mixing ratio for a mie aerosol (either specified or free, only for uniform haze models) :type log_X_Mie: float :param MUST have either a specified aerosol OR a r_i_real + r_i_complex: :param r_i_real: Real refractive index (only used for constant, free refractive index) :type r_i_real: float :param r_i_complex: Complex refractive index (only used for constant, free refractive index) :type r_i_complex: float :param Slab Arguments: :param P_cloud: Cloud Top Pressure (everything between P_cloud and P_cloud_bottom is uniform X). :type P_cloud: float :param P_cloud_bottom: Pressure of the bottom of the slab :type P_cloud_bottom: array of float :param -------- Optional Arguments -------: :param r_m_std_dev: Geometric standard deviation for particle size :type r_m_std_dev: float :param z_max: Maximum z that you want the effective cross section integral carried out over z = [ln(r) - ln(r_m)] / [r_m_std_dev^2], where r is the particle size Integral carried out from -z to z with more density around 0 (size ~ mean size) :type z_max: float :param num_integral_points: Number of points in the z array :type num_integral_points: int :param R_Mie: Optional wavelength resolution used to calculate ETA :type R_Mie: int :param algorithm: Either 'LX-MIE' or 'miepython'. The second is faster, and therefore the default. :type algorithm: str Returns: n_aerosol, sigma_Mie .. py:function:: precompute_cross_sections_one_aerosol_LXMIE(file_name, aerosol_name, saveall=False) Calculates .npy files from a refractive index txt file (lab data) Takes ~ a day to generate the npy file that then can be easily added to the aerosol database Please ensure that the first two rows are skippable, or that the header is commented out (#) and that the columns are Wavelength (microns) | Real Index | Imaginary Index For better commented code on how the LX-MIE/PLATON algorithm works, see Mie_cloud_free() INPUTS file_name (txt): file name of the txt file with the directory included aerosol_name (txt): name that you want the npy file saved with saveall (bool): saves all auxiliary arrays to precomputed_Mie_properties directory .. py:function:: precompute_cross_sections_one_aerosol_custom_LXMIE(file_name, aerosol_name, log_r_m_std_dev=0.5, log_r_m_min=-3, log_r_m_max=1, saveall=False) Calculates .npy files from a refractive index txt file (lab data) Takes ~ a day to generate the npy file that then can be easily added to the aerosol database Please ensure that the first two rows are skippable, or that the header is commented out (#) and that the columns are Wavelength (microns) | Real Index | Imaginary Index Same as precompute_cross_sections_one_aerosol but allows for customization For better commented code on how the LX-MIE/PLATON algorithm works, see Mie_cloud_free() INPUTS file_name (txt): file name of the txt file with the directory included aerosol_name (txt): name that you want the npy file saved with r_m_std_dev (float, optional): standard deviations of the lognormal distributions log_r_m_min (float, optional): mininum radii to be computed log_r_m_max (float, optional): maximum radii to be computed .. py:function:: precompute_cross_sections_from_indices_LXMIE(wl, real_indices_array, imaginary_indices_array, r_m) Calculates and returns the effective cross section from an input wl grid, real and imaginary indices array And the particle size in um Allows the user to directly quirey the LX_MIE algorithm with their refractive index data Before running the full precompute cross sections one aerosol function INPUTS wl (np.array of float): Model wavelength grid (μm). real_indices_array (np.array of float): Real indices imaginary_indices_array (np.array of float): Imaginary indices r_m (float) : Mean particle size (in um) .. py:function:: compute_mie_properties(r_m, wl_Mie, eta_array, r_m_array, ext_array, scat_array, abs_array, back_array, w_array, g_array, z_max, num_integral_points, log_r_m_std_dev, idx_start, idx_end) .. py:function:: precompute_cross_sections_one_aerosol_miepython(file_name, aerosol_name, log_r_m_std_dev=0.5, number_cores=1, log_r_m_min=-3, log_r_m_max=1, saveall=False) Same as precompute_cross_sections_one_aerosol_custom except it uses miepython instead of LX-MIE (much faster) It also can be run on multiple cores and solve for different particle size distributions INPUTS file_name (txt): file name of the txt file with the directory included aerosol_name (txt): name that you want the npy file saved with log_r_m_std_dev (float, optional): standard deviations of the lognormal distributions number_cores (int, optional): Number of cores to run things on (makes precomputation much faster) log_r_m_min (float, optional): mininum radii to be computed log_r_m_max (float, optional): maximum radii to be computed saveall (bool, optional): saves all the extra arrays .. py:function:: precompute_cross_sections_from_indices_miepython(wl, real_indices_array, imaginary_indices_array, r_m) Calculates and returns the effective cross section from an input wl grid, real and imaginary indices array And the particle size in um Allows the user to directly quirey the miepython algorithm with their refractive index data Before running the full precompute cross sections one aerosol function INPUTS wl (np.array of float): Model wavelength grid (μm). real_indices_array (np.array of float): Real indices imaginary_indices_array (np.array of float): Imaginary indices r_m (float) : Mean particle size (in um) .. py:function:: make_aerosol_database() Regenerates the aerosol_database from all npy files in input/aerosol_Mie_properties/ This functionality allows for users to create new eff cross section arrays using precompute_cross_sections_one_aerosol() With their own lab data and add it to the database Assumes the nominal wl_Mie and r_m_array used in the functions above (not custom particle sizes) Takes into account lognormal logwidth used to generate cross sections .. py:function:: switch_aerosol_in_opac(model, opac)