Utilities API¶

These helpers prepare common input files and stellar spectra or read model output. Functions that download external data require network access and are identified in their docstrings.

Climate input files¶

species_dict_for_climate ¶

species_dict_for_climate(
    species, condensates, particles=None
)

Generate species-file data for AdiabatClimate.

Gas thermodynamic and saturation data are selected from the installed Zahnle Earth mechanism. Requested names absent from that mechanism are not included.

Parameters:

Name	Type	Description	Default
`species`	`sequence of str`	Gas species to include.	required
`condensates`	`sequence of str`	Included gas species that should be allowed to condense.	required
`particles`	`list[dict]`	Particle definitions and their elemental compositions, for example `[{'name': 'HCaer', 'composition': {'C': 6, 'H': 2}}]`.	`None`

Returns:

Type	Description
`dict`	Climate species-file data.

Raises:

Type	Description
`ValueError`	If `condensates` is not a subset of `species`.

species_file_for_climate ¶

species_file_for_climate(
    filename, species, condensates, particles=None
)

Write a species file for climate simulations with AdiabatClimate.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Output YAML path. An existing file is replaced.	required
`species`	`sequence of str`	Gas species to include.	required
`condensates`	`sequence of str`	Included gas species that should be allowed to condense.	required
`particles`	`list[dict]`	Particle definitions and their elemental compositions, for example `[{'name': 'HCaer', 'composition': {'C': 6, 'H': 2}}]`.	`None`

settings_dict_for_climate ¶

settings_dict_for_climate(
    planet_mass,
    planet_radius,
    surface_albedo,
    number_of_layers=50,
    number_of_zenith_angles=4,
    photon_scale_factor=1.0,
    opacities=None,
)

Generate settings-file data for AdiabatClimate.

Parameters:

Name	Type	Description	Default
`planet_mass`	`float`	Planet mass in grams.	required
`planet_radius`	`float`	Planet radius in cm.	required
`surface_albedo`	`float`	Dimensionless surface albedo.	required
`number_of_layers`	`int`	Number of atmospheric layers, by default 50.	`50`
`number_of_zenith_angles`	`int`	Number of solar zenith angles used for shortwave radiative transfer, by default 4.	`4`
`photon_scale_factor`	`float`	Dimensionless stellar-flux multiplier, by default 1.0.	`1.0`
`opacities`	`dict`	Opacity configuration. By default, enable the standard gas, scattering, photolysis, and MT_CKD water-continuum sources.	`None`

Returns:

Type	Description
`dict`	Climate settings-file data. The supplied `opacities` object is stored by reference rather than copied.

settings_file_for_climate ¶

settings_file_for_climate(
    filename,
    planet_mass,
    planet_radius,
    surface_albedo,
    number_of_layers=50,
    number_of_zenith_angles=4,
    photon_scale_factor=1.0,
    opacities=None,
)

Write an AdiabatClimate settings file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Output YAML path. An existing file is replaced.	required
`planet_mass`	`float`	Planet mass in grams.	required
`planet_radius`	`float`	Planet radius in cm.	required
`surface_albedo`	`float`	Dimensionless surface albedo.	required
`number_of_layers`	`int`	Number of atmospheric layers, by default 50.	`50`
`number_of_zenith_angles`	`int`	Number of solar zenith angles used for shortwave radiative transfer, by default 4.	`4`
`photon_scale_factor`	`float`	Dimensionless stellar-flux multiplier, by default 1.0.	`1.0`
`opacities`	`dict`	Opacity configuration. By default, enable the standard gas, scattering, photolysis, and MT_CKD water-continuum sources.	`None`

Stellar spectra¶

stefan_boltzmann ¶

stefan_boltzmann(T)

The Stefan-Boltzmann law

Parameters:

Name	Type	Description	Default
`T`	`float`	Temperature (K)	required

Returns:

Type	Description
`float`	Energy flux (W/m^2)

stefan_boltzmann_inverse ¶

stefan_boltzmann_inverse(F)

Inverse of the Stefan-Boltzmann law

Parameters:

Name	Type	Description	Default
`F`	`float`	Energy flux (W/m^2)	required

Returns:

Type	Description
`float`	Temperature (K)

equilibrium_temperature ¶

equilibrium_temperature(stellar_radiation, bond_albedo)

Equilibrium temperature of a planet.

Parameters:

Name	Type	Description	Default
`stellar_radiation`	`float`	Incident energy at a planet in W/m^2	required
`bond_albedo`	`float`	Bond albedo	required

Returns:

Type	Description
`float`	The equilibrium temperature (K)

equilibrium_temperature_inverse ¶

equilibrium_temperature_inverse(Teq, bond_albedo)

Inverse of the equation for equilibrium temperature.

Parameters:

Name	Type	Description	Default
`Teq`	`float`	The equilibrium temperature (K)	required
`bond_albedo`	`float`	Bond albedo	required

Returns:

Type	Description
`float`	Incident energy at a planet in W/m^2

blackbody_cgs ¶

blackbody_cgs(T, lam)

Blackbody flux in cgs units in per unit wavelength (erg/cm^2/s/cm/sr)

Parameters:

Name	Type	Description	Default
`T`	`float`	Temperature (K)	required
`lam`	`ndarray[ndim=1,double]`	Wavelength (cm)	required

Returns:

Type	Description
`ndarray[ndim=1,double]`	The blackbody flux at the input wavelengths in erg/cm^2/s/cm/sr.

blackbody ¶

blackbody(T, wv)

Blackbody flux

Parameters:

Name	Type	Description	Default
`T`	`float`	Temperature (K)	required
`wv`	`ndarray[ndim=1,double]`	Wavelength (nm)	required

Returns:

Type	Description
`ndarray[ndim=1,double]`	The blackbody flux at the input wavelengths in mW/m^2/s/nm/sr.

grid_at_resolution ¶

grid_at_resolution(min_wv, max_wv, R)

Computes a grid of bins at a given resolution R

Parameters:

Name	Type	Description	Default
`min_wv`	`float`	Minimum bin extent	required
`max_wv`	`float`	Maximum bin extent	required
`R`	`float`	in resolution (dlam = lam/R)	required

Returns:

Type	Description
`ndarray[ndim=1,double]`	Edges of the wavelength grid

make_bins ¶

make_bins(wavs)

Given a series of wavelength points, find the edges of corresponding wavelength bins.

Parameters:

Name	Type	Description	Default
`wavs`	`ndarray[ndim=1,double]`	Input wavelengths	required

Returns:

Type	Description
`ndarray[ndim=1,double]`	Edges of the wavelength grid

energy_in_spectrum ¶

energy_in_spectrum(wv, F)

The total energy in a spectrum

Parameters:

Name	Type	Description	Default
`wv`	`ndarray[ndim=1,double]`	Wavelengths of stellar spectrum (nm)	required
`F`	`ndarray[ndim=1,double]`	Flux of the stellar spectrum (mW/m^2/nm)	required

Returns:

Type	Description
`float`	Energy in W/m^2

scale_spectrum_to_planet ¶

scale_spectrum_to_planet(
    wv, F, Teq=None, stellar_flux=None
)

Scales a stellar spectrum so that it has the correct incident flux at a planet. You must supply either a Teq or a stellar_flux

Parameters:

Name	Type	Description	Default
`wv`	`ndarray[ndim=1,double]`	Wavelengths of stellar spectrum (nm)	required
`F`	`ndarray[ndim=1,double]`	Flux of the stellar spectrum (mW/m^2/nm)	required
`Teq`	`float`	Zero-albedo equilibrium temperature of the planet (K), by default None	`None`
`stellar_flux`	`float`	Stellar flux at the planet (W/m^2), by default None	`None`

Returns:

Type	Description
`ndarray[ndim=1,double]`	The stellar spectrum rescaled so that it has the proper total bolometric flux at the planet (mW/m^2/nm).

append_blackbody_to_stellar_spectrum ¶

append_blackbody_to_stellar_spectrum(
    wv, F, Teff, wv_end=100000.0, nwb=1000
)

Appends a blackbody to a stellar spectrum

Parameters:

Name	Type	Description	Default
`wv`	`ndarray[ndim=1,double]`	Wavelengths of stellar spectrum (nm)	required
`F`	`ndarray[ndim=1,double]`	Flux of the stellar spectrum (mW/m^2/nm)	required
`Teff`	`float`	Stellar effective temperature	required
`wv_end`	`float`	Ending wavelength for the blackbody (nm), by default 100e3	`100000.0`
`nwb`	`int`	Number of blackbody bins, by default 1000	`1000`

Returns:

Name	Type	Description
`wv_new`	`ndarray[ndim=1,double]`	New wavelengths of stellar spectrum (nm)
`F_new`	`ndarray[ndim=1,double]`	New flux of the stellar spectrum (mW/m^2/nm)

photochem_spectrum_string ¶

photochem_spectrum_string(
    wv,
    F,
    Teq=None,
    stellar_flux=None,
    scale_to_planet=True,
    fmt="{:20}",
)

Rescales a stellar spectrum to a planet, then converts it a string representing a photochem stellar flux file.

Parameters:

Name	Type	Description	Default
`wv`	`ndarray[ndim=1,double]`	Wavelengths of stellar spectrum (nm)	required
`F`	`ndarray[ndim=1,double]`	Flux of the stellar spectrum (mW/m^2/nm)	required
`Teq`	`float`	Zero-albedo equilibrium temperature of the planet (K), by default None	`None`
`stellar_flux`	`float`	Stellar flux at the planet (W/m^2), by default None	`None`
`scale_to_planet`	`bool`	If True, then the stellar flux will be rescaled to the planet, be default True.	`True`
`fmt`	`str`	Format string, by default '{:20}'	`'{:20}'`

Returns:

Type	Description
`str`	A photochem stellar flux file as a string.

save_photochem_spectrum ¶

save_photochem_spectrum(
    wv,
    F,
    outputfile,
    Teq=None,
    stellar_flux=None,
    scale_to_planet=True,
    fmt="{:20}",
)

Rescales a stellar spectrum to a planet, if desired, then saves the spectrum in the photochem format.

Parameters:

Name	Type	Description	Default
`wv`	`ndarray[ndim=1,double]`	Wavelengths of stellar spectrum (nm)	required
`F`	`ndarray[ndim=1,double]`	Flux of the stellar spectrum (mW/m^2/nm)	required
`outputfile`	`str`	Path to the output stellar file.	required
`Teq`	`float`	Zero-albedo equilibrium temperature of the planet (K), by default None	`None`
`stellar_flux`	`float`	Stellar flux at the planet (W/m^2), by default None	`None`
`scale_to_planet`	`bool`	If True, then the stellar flux will be rescaled to the planet, be default True.	`True`
`fmt`	`str`	Format string, by default '{:20}'	`'{:20}'`

rebin_to_needed_resolution ¶

rebin_to_needed_resolution(wv, F)

Rebins a stellar spectrum to 4x the resolution needed by the photochemical and climate models.

Parameters:

Name	Type	Description	Default
`wv`	`ndarray[ndim=1,double]`	Wavelengths of stellar spectrum (nm)	required
`F`	`ndarray[ndim=1,double]`	Flux of the stellar spectrum (mW/m^2/nm)	required

Returns:

Name	Type	Description
`wv_new`	`ndarray[ndim=1,double]`	New wavelengths of stellar spectrum (nm)
`F_new`	`ndarray[ndim=1,double]`	New flux of the stellar spectrum (mW/m^2/nm)

solar_spectrum ¶

solar_spectrum(
    outputfile=None,
    age=0.0,
    append_blackbody=True,
    Teq=None,
    stellar_flux=None,
    scale_before_age=True,
    needed_resolution=True,
)

The Sun's spectrum throughout all time. For the Modern Sun, we use the Thuillier et al. (2004) (https://doi.org/10.1029/141GM13), ATLAS 1 reference spectrum packaged with Photochem. Then we scale the spectrum into the past/future with the Claire et al. (2012) YoungSun routine.

Parameters:

Name	Type	Description	Default
`outputfile`	`str`	If supplied, this is the output file name, by default None	`None`
`age`	`float`	Age of the sun in billions of years ago, by default 0.0	`0.0`
`append_blackbody`	`bool`	If True, then a blackbody is appended, by default True	`True`
`Teq`	`float`	Zero-albedo equilibrium temperature of the planet (K), by default None	`None`
`stellar_flux`	`float`	Stellar flux at the planet (W/m^2), by default None	`None`
`scale_before_age`	`bool`	If True, then the spectrum is scaled before the `youngsun` routine is applied. If False, then scaling occurs afterward, by default True.	`True`
`needed_resolution`	`bool`	If True, then the spectrum is rebinned to a resolution 4x higher than what is used by the photochemical and climate models, which should be an adequately high resolution, by default True.	`True`

Returns:

Name	Type	Description
`wv`	`ndarray[ndim=1,double]`	Wavelengths of stellar spectrum (nm)
`F`	`ndarray[ndim=1,double]`	Flux of the stellar spectrum at Earth (mW/m^2/nm)

hazmat_spectrum ¶

hazmat_spectrum(
    star_name,
    model="model",
    outputfile=None,
    Teq=None,
    stellar_flux=None,
    needed_resolution=True,
)

Downloads a HAZMAT spectrum (https://archive.stsci.edu/hlsp/hazmat), then rescale the spectrum so that it has a total bolometric insolation at a planet consistent with Teq or stellar_flux. Finally, the spectrum can be saved to outputfile in photochem format.

Parameters:

Name	Type	Description	Default
`star_name`	`str`	Name of the HAZMAT star	required
`model`	`str`	Model group (for TRAPPIST-1), either "1a", "2a", or "2b", or "model" for GJ stars.	`'model'`
`outputfile`	`str`	If not None, then this is the output filename, be default None.	`None`
`Teq`	`float`	Zero-albedo equilibrium temperature of the planet (K), by default None	`None`
`stellar_flux`	`float`	Stellar flux at the planet (W/m^2), by default None	`None`
`needed_resolution`	`bool`	If True, then the spectrum is rebinned to a resolution 4x higher than What is used by the photochemical and climate models which should be an adequately high resolution, by default True.	`True`

print_hazmat_stars ¶

print_hazmat_stars()

Prints the stars avaliable in the HAZMAT catalogue

muscles_spectrum ¶

muscles_spectrum(
    star_name,
    outputfile=None,
    Teq=None,
    stellar_flux=None,
    needed_resolution=True,
    verbose=True,
)

Downloads a MUSCLES spectrum (https://archive.stsci.edu/prepds/muscles/), then adds on a blackbody extending the star to 100 microns, and finally rescale the spectrum so that it has a total bolometric insolation at a planet consistent with Teq or stellar_flux. Finally, the spectrum can be saved to outputfile in photochem format.

Parameters:

Name	Type	Description	Default
`star_name`	`str`	Name of the MUSCLES star	required
`outputfile`	`str`	If not None, then this is the output filename, be default None.	`None`
`Teq`	`float`	Zero-albedo equilibrium temperature of the planet (K), by default None	`None`
`stellar_flux`	`float`	Stellar flux at the planet (W/m^2), by default None	`None`
`needed_resolution`	`bool`	If True, then the spectrum is rebinned to a resolution 4x higher than What is used by the photochemical and climate models which should be an adequately high resolution, by default True.	`True`
`verbose`		If True, then some information will be printed.	`True`

closest_muscles_to_Teff ¶

closest_muscles_to_Teff(Teff)

Finds the star in the MUSCLES catalogue with an effective temperature closest to Teff.

Parameters:

Name	Type	Description	Default
`Teff`	`float`	Stellar effective temperature (K)	required

Returns:

Type	Description
`dict`	Dictionary with the MUSCLES star name and properties.

print_muscles_stars ¶

print_muscles_stars()

Prints the stars avaliable in the MUSCLES catalogue

Model output¶

reformat_output_dict ¶

reformat_output_dict(sol)

Convert raw evolution output to a species-keyed dictionary.

Parameters:

Name	Type	Description	Default
`sol`	`dict`	Output from evo_read_evolve_output.	required

Returns:

Type	Description
`dict[str, ndarray]`	`time` in seconds, `alt` in km, and one `(nz, nt)` number-density array in molecules/cm^3 for each evolved species.

evo_read_evolve_output ¶

evo_read_evolve_output(filename)

Read the unformatted binary file written by EvoAtmosphere.evolve.

A partially written final record is discarded, so output from an interrupted integration can still be inspected.

Parameters:

Name	Type	Description	Default
`filename`	`str or path - like`	Evolution output file.	required

Returns:

Type	Description
`dict`	Species names; `time` in seconds; `top_atmos` in cm; `alt` in km with shape `(nz, nt)`; and evolved gas and condensed-material number densities in molecules/cm^3 with shape `(nq, nz, nt)`.

Reaction mechanisms¶

FormatReactions ¶

FormatReactions(filename, outfile)

Format a YAML chemical reaction network.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path of input reaction network file.	required
`outfile`	`str`	Path of output formatted reaction network file.	required

FormatSettings ¶

FormatSettings(infile, outfile)

Format a Photochem settings YAML file.

Parameters:

Name	Type	Description	Default
`infile`	`str`	Path to input settings file.	required
`outfile`	`str`	Path of output formatted settings file.	required

resave_mechanism_with_atoms ¶

resave_mechanism_with_atoms(
    infile,
    outfile,
    atoms_names,
    exclude_species=[],
    remove_particles=False,
    remove_reaction_particles=False,
)

Alters a reaction mechanism file with altered atoms.

Parameters:

Name	Type	Description	Default
`infile`	`str`	Path to input yaml file	required
`outfile`	`str`	Path to output yaml file	required
`atoms_names`	`list`	List of atoms to include in the output file	required
`exclude_species`	`list`	List of species to exclude, by default []	`[]`
`remove_particles`	`bool`	If True, then all particles are removed, by default False	`False`
`remove_reaction_particles`	`bool`	If True, then partcles forming from reactions are removed, by default False	`False`

generate_zahnle_earth_thermo ¶

generate_zahnle_earth_thermo(
    outfile="zahnle_earth_thermo.yaml",
    atoms_names=None,
    exclude_species=[],
    remove_particles=False,
)

Generates a thermodynamic file for equilibrium solving that includes condensible species (e.g., H2O condensate).

Parameters:

Name	Type	Description	Default
`outfile`	`str`	Name of the output file, by default 'zahnle_earth_thermo.yaml'	`'zahnle_earth_thermo.yaml'`
`atoms_names`	`list`	List of atoms to keep. By default all atoms in the mechanism are kept	`None`
`exclude_species`	`list`	List of species to exclude.	`[]`
`remove_particles`	`bool`	If True, then particles (i.e. condensates) will be removed, by default False.	`False`

zahnle_rx_and_thermo_files ¶

zahnle_rx_and_thermo_files(
    atoms_names=["H", "He", "N", "O", "C", "S"],
    rxns_filename="photochem_rxns.yaml",
    thermo_filename="photochem_thermo.yaml",
    exclude_species=[],
    remove_particles=False,
    remove_reaction_particles=False,
)

Generates input reactions and thermodynamic files for photochem by altering the main reaction network (zahnle_earth.yaml).

Parameters:

Name	Type	Description	Default
`atoms_names`	`list`	Atoms to include in the thermodynamics, by default ['H','He','N','O','C','S']	`['H', 'He', 'N', 'O', 'C', 'S']`
`rxns_filename`	`str`	Name of output reactions file, by default 'photochem_rxns.yaml'	`'photochem_rxns.yaml'`
`thermo_filename`	`str`	Name of output thermodynamic file, by default 'photochem_thermo.yaml'	`'photochem_thermo.yaml'`
`exclude_species`	`list`	List of species to exclude.	`[]`
`remove_particles`	`bool`	If True, then particles will be removed, by default False.	`False`
`remove_reaction_particles`	`bool`	If True, then reactions particles are removed, by default False.	`False`

atmos2yaml ¶

atmos2yaml(
    rx_file,
    species_file,
    outfile,
    photo_database="Photochem",
    with_citations=False,
)

Convert an Atmos mechanism to Photochem YAML format.

Parameters:

Name	Type	Description	Default
`rx_file`	`str`	Path to Atmos reactions file (e.g. reactions.rx)	required
`species_file`	`str`	Path to Atmos species file (e.g. species.dat)	required
`outfile`	`str`	Name of output .yaml file in photochem format	required
`photo_database`	`str`	Options are "Photochem" or "Atmos". If "Photochem", then will use all possible photolysis reactions given the cross section data contained within Photochem. If "Atmos", then will photolysis reactions in rx_file that are possible, given Photochem cross section data.	`'Photochem'`
`with_citations`	`bool`	Preserve reaction citations from the Atmos input when available.	`False`

atmosbc2yaml ¶

atmosbc2yaml(species_file, outfile, short_lived=False)

Converts Atmos boundary conditions into .yaml format compatible with Photochem.

Parameters:

Name	Type	Description	Default
`species_file`	`str`	Path to Atmos species file which contains boundary conditions (e.g. species.dat)	required
`outfile`	`str`	Name of output .yaml file which will contain boundary conditions	required
`short_lived`	`bool`	Include Atmos short-lived species declarations, by default False.	`False`

vulcan2yaml ¶

vulcan2yaml(
    vulcan_rx_filename, thermo_folder, data_dir=None
)

Converts Vulcan reactions and cross sections to a format that works with Photochem. Upon return, the routine will have saved a yaml file with a similar name to the input vulcan_rx_filename, and also a directory "vulcandata", which is a copy of the Photochem data, except with the Vulcan photolysis cross sections.

Parameters:

Name	Type	Description	Default
`vulcan_rx_filename`	`str`	Path to Vulcan input reactions file.	required
`thermo_folder`	`str`	Path to Vulcan "thermo" folder	required
`data_dir`	`str`	Path to the Photochem data folder. If `None`, then the data shipped with Photochem is used.	`None`

photochem2cantera ¶

photochem2cantera(infile, outfile)

Generates .yaml file compatible with Cantera from a Photochem reactions file.

Parameters:

Name	Type	Description	Default
`infile`	`str`	Photochem .yaml reactions file	required
`outfile`	`str`	Output .yaml file in Cantera format.	required