Inputs#

VSPEC can read in inputs in two ways:

From a YAML file
From a VSPEC.params.InternalParameters object

YAML is convenient because it is human-readable and can be easily ported between programs. Creating an InternalParameters instance directly in Python can also be convenient, especially when running many near-identical models.

The `VSPEC.params` YAML Format#

The most basic way to create an ObservationalModel object instance is through a YAML file:

import VSPEC
model = VSPEC.ObservationModel.from_yaml('my_config.yaml')

The file my_config.yaml contains all the necessary information to run VSPEC. YAML files have a hierarchical structure, so for example the header section looks like this:

header:
    data_path: transit
    teff_min: 2300 K
    teff_max: 3900 K
    desc: This is a VSPEC example.
    verbose: 0

The sections of a VSPEC YAML configuration file are below.

Note

Because the configuration file is parsed by a parameter object that knows what type to expect, it is possible to parse directly to an astropy.units.Quantity object. Any parameter that expects a quantity will read in the user input as:

u.Quantity(my_input)

So encoding the quantity as a string is very easy. For example the teff_min parameter can be set to 2300 K, and so after parsing it will be equivalent to having set it to 2300 * u.K.

`header`#

Key	Parses to	Description
`data_path`	`str`	The name of the directory inside `.vspec` where outputs will be saved.
`teff_min`	`astropy.units.Quantity`	The minimum effective temperature to include in the spectrum grid.
`teff_max`	`astropy.units.Quantity`	The maximum effective temperature to include in the spectrum grid.
`desc`	`str`	A description of the model.
`verbose`	`int`	The level of verbosity.
`seed`	`int`	The seed for the random number generator.
`spec_grid`	see spec_grid	Parameters that define the grid of spectral models.

`spec_grid`#

Key	Parses to	Description
`name`	`str`	The name of the spectral grid.
		Additional parameters (see below)

Note

The name parameter determines how the rest of this section is parsed.

See below for additional parameters

`name="vspec"`#

This is the default spectral grid what was created for VSPEC. It is made from PHOENIX stellar models [Husser et al., 2013].

Key	Parses to	Description
`max_teff`	`astropy.units.Quantity`	The maximum effective temperature to include in the grid.
`min_teff`	`astropy.units.Quantity`	The minimum effective temperature to include in the grid.
`impl_bin`, optional	`str`	The implementation of the binning algorithm, either ‘rust’ or ‘python’. Default is ‘rust’.
`impl_interp`, optional	`str`	The implementation of the interpolation algorithm, either ‘scipy’ or ‘jax’. Default is ‘scipy’.
`fail_on_missing`, optional	`bool`	If `True`, raise an error if a spectrum from the grid is not found. If `False`, download the needed spectra. Default is `False`.

`name="bb"`#

This replaces the grid interpolator with a forward model that produces a pure blackbody spectrum. This might be useful to use when testing variability as it is very fast.

Note

There are no additional parameters for this spectral model.

`star`#

Note

Available presets include static_proxima, spotted_proxima, flaring_proxima, and proxima.

Key	Parses to	Description
`psg_star_template`	`str`	The template for the star. See the PSG Handbook for options.
`teff`	`astropy.units.Quantity`	The effective temperature of the star.
`mass`	`astropy.units.Quantity`	The mass of the star.
`radius`	`astropy.units.Quantity`	The radius of the star.
`period`	`astropy.units.Quantity`	The rotational period of the star.
`misalignment`	`astropy.units.Quantity`	The misalignment between the stellar rotation axis and the orbital axis. This is the planet’s “mutual inclination”.
`misalignment_dir`	`astropy.units.Quantity`	The direction of stellar rotation axis misalignment, relative to the argument of periapsis.
`ld`	See ld	The limb darkening parameters of the star.
`spots`	See spots	The parameters to create star spots.
`faculae`	See faculae	The parameters to create faculae.
`flares`	See flares	The parameters to create flares.
`granulation`	See granulation	The parameters to create granulation.
`grid_params`	`int` or `tuple`	Stellar surface grid parameters. If `tuple`, the number of points in the latitude and longitude directions. If `int`, the number of total grid points for a Fibonacci spiral grid. In general the spiral grid is more efficient.
`spectral_grid`	`str`	The spectral grid to use. Either `default` for the default stellar grid from `Gridpolator`, or `bb` to use a blackbody forward model (very fast).

`ld`#

Note

Available presets include lambertian, proxima, solar, and trappist.

Key	Parses to	Description
`u1`	`float`	The first limb darkening coefficient.
`u2`	`float`	The second limb darkening coefficient.

`spots`#

Note

Available presets include none, mdwarf, and solar.

Key	Parses to	Description
`distribution`	`str`	The distribution of the spots. Either `iso` for an isotropic distribution or `solar` for two bands at \(\\pm 15^{\\circ}\) latitude.
`initial_coverage`	`float`	The spot coverage created initially by generating spots at random stages of life.
`equillibrium_coverage`	`float`	The fractional coverage of the star’s surface by spots. This is the value at growth-decay equilibrium.
`burn_in`	`astropy.units.Quantity`	The duration of the burn-in period, during which the spot coverage approaches equilibrium.
`area_mean`	`astropy.units.Quantity`	The mean area of a spot on the star’s surface in MSH.
`area_logsigma`	`float`	The standard deviation of the spot areas. This is a lognormal distribution, so the units of this value are dex.
`teff_umbra`	`astropy.units.Quantity`	The effective temperature of the spot umbrae.
`teff_penumbra`	`astropy.units.Quantity`	The effective temperature of the spot penumbrae.
`growth_rate`	`astropy.units.Quantity`	The rate at which new spots grow. Spots grow exponentially, so this quantity has units of 1/time.
`decay_rate`	`astropy.units.Quantity`	The rate at which existing spots decay [area/time].
`initial_area`	`astropy.units.Quantity`	The area of a spot at birth.

`faculae`#

Note

Available presets include none and std.

Key	Parses to	Description
`distribution`	`str`	The distribution of the spots. Currently only `iso` is supported.
`Equillibrium_coverage`	`float`	The fractional coverage of the star’s surface by spots. This is the value at growth-decay equilibrium.
`burn_in`	`astropy.units.Quantity`	The duration of the burn-in period, during which the spot coverage approaches equilibrium.
`mean_radius`	`astropy.units.Quantity`	The mean radius of the faculae.
`logsigma_radius`	`float`	The standard deviation of the radius in dex.
`mean_timescale`	`astropy.units.Quantity`	The mean faculae lifetime.
`logsigma_timescale`	`float`	The standard deviation of the lifetime in dex.
`depth`	`float`	The depth of the facula depression.
`floor_teff_slope`	`astropy.units.Quantity`	The slope of the radius-Teff relationship for the cool floor.
`floor_teff_min_rad`	`astropy.units.Quantity`	The minimum radius at which the floor is visible. Otherwise the facula is a bright point – even near disk center.
`floor_teff_base_dteff`	`astropy.units.Quantity`	The Teff of the floor at the minimum radius.
`wall_teff_slope`	`astropy.units.Quantity`	The slope of the radius-Teff relationship for the hot wall.
`wall_teff_intercept`	`astropy.units.Quantity`	The intercept of the radius-Teff relationship for the hot wall.

Note

The temperatures of a facula wall or floor are a function of the radius. See the vspec-vsm source for information on how these values are calculated.

`flares`#

Note

Available presets include none and std.

Key	Parses to	Description
`dist_teff_mean`	`astropy.units.Quantity`	The mean temperature of the flares.
`dist_teff_sigma`	`astropy.units.Quantity`	The standard deviation of the flare temperatures.
`dist_fwhm_mean`	`astropy.units.Quantity`	The mean FWHM of the flare lightcurves [time].
`dist_fwhm_logsigma`	`float`	The standard deviation of the FWHM in dex.
`alpha`	`float`	The slope of the frequency-energy powerlaw.
`beta`	`float`	The intercept of the frequency-energy powerlaw.
`min_energy`	`astropy.units.Quantity`	The minimum energy of the flares. Set to infinity to disable.
`cluster_size`	`int`	The typical number of flares in each cluster.

`granulation`#

Note

Available presets include none and std.

Key	Parses to	Description
`mean`	`float`	The mean coverage of low-teff granulation.
`amp`	`float`	The amplitude of granulation oscillations.
`period`	`astropy.units.Quantity`	The period of granulation oscillations.
`dteff`	`astropy.units.Quantity`	The difference between the quiet photosphere and the low-teff granulation region.

`planet`#

Note

Available presets include proxcenb and std.

Key	Parses to	Description
`name`	`str`	The name of the planet.
`radius`	`astropy.units.Quantity`	The radius of the planet.
`gravity`	see gravity	The mass/surface gravity/density of the planet.
`semimajor_axis`	`astropy.units.Quantity`	The semi-major axis of the planet’s orbit.
`orbit_period`	`astropy.units.Quantity`	The period of the planet’s orbit.
`rotation_period`	`astropy.units.Quantity`	The rotation period of the planet.
`eccentricity`	`float`	The eccentricity of the planet’s orbit
`obliquity`	`astropy.units.Quantity`	The obliquity (tilt) of the planet. Not currently implemented.
`obliquity_direction`	`astropy.units.Quantity`	The direction of the planet’s obliquity. The true anomaly at which the planet’s north pole faces away from the star.
`init_phase`	`astropy.units.Quantity`	The phase of the planet at the beginning of the simulation.
`init_substellar_lon`	`astropy.units.Quantity`	The initial substellar longitude of the planet.

`gravity`#

Key	Parses to	Description
`mode`	`str`	The mode of the gravity parameter. Valid options are ‘g’, ‘rho’, and ‘kg’.
`value`	`astropy.units.Quantity`	The value of the gravity parameter. Can be any unit so long as the physical type is correct.

`system`#

Key	Parses to	Description
`distance`	`astropy.units.Quantity`	The distance to the system.
`inclination`	`astropy.units.Quantity`	The inclination of the system. Transit occurs when \(i=90^{\circ}\).
`phase_of_periasteron`	`astropy.units.Quantity`	The phase of the planet when it reaches periasteron. Only necessary for planets with non-zero obliquity or non-zero eccentricity.

`obs`#

Key	Parses to	Description
`observation_time`	`astropy.units.Quantity`	The total time of the observation.
`integration_time`	`astropy.units.Quantity`	The integration time of each epoch of observation.

`inst`#

Note

Available presets include mirecle, miri_lrs, and niriss_soss.

Key	Parses to	Description
`single` \| `coronagraph`	see single or coronagraph	The type of telescope to use.
`bandpass`	see bandpass	The bandpass & resolution of the observation.
`detector`	see detector	The detector properties of the observation.

`single`#

Key	Parses to	Description
`aperture`	`astropy.units.Quantity`	The aperture size of the telescope.
`zodi`	`float`	The level of the zodiacal background. See the PSG Handbook for details.

`coronagraph`#

Warning

Use this instrument type with caution. It is not well tested and not fully implemented. Pull requests are welcome.

Key	Parses to	Description
`aperture`	`astropy.units.Quantity`	The aperture size of the telescope.
`zodi`	`float`	The level of the zodiacal background. See the PSG Handbook for details.
`contrast`	`float`	The contrast of the coronagraphic system.
`iwa`	`PSGtable`	The inner working angle of the coronagraph.

`bandpass`#

Key	Parses to	Description
`wl_blue`	`astropy.units.Quantity`	The minimum wavelength.
`wl_red`	`astropy.units.Quantity`	The maximum wavelength.
`resolving_power`	`int`	The resolving power of the observation.
`wavelength_unit`	`astropy.units.Unit`	The unit to be used on the spectral axis.
`flux_unit`	`astropy.units.Unit`	The unit to be used on the flux axis.

`detector`#

Key	Parses to	Description
`beam_width`	`astropy.units.Quantity`	The width of the field of view.
`integration_time`	`astropy.units.Quantity`	The integration time on the detector for saturation purposes. This effects the read noise of the observation.
`ccd`	see ccd	The CCD used for the observation.

`ccd`#

Key	Parses to	Description
`pixel_sampling`	`int`	The number of pixels comprising a resolution element.
`read_noise`	`astropy.units.Quantity`	The read noise of the CCD in electrons.
`dark_current`	`astropy.units.Quantity`	The dark current of the CCD in electrons/second.
`throughput`	`float`	The throughput of the optical system.
`emissivity`	`float`	The emissivity of the optical system.
`temperature`	`astropy.units.Quantity`	The temperature of the optical system.

`psg`#

Key	Parses to	Description
`gcm_binning`	`int`	The number of GCM points to bin together. Use 200 for testing and 3 for science (depending on the native resolution of your gcm).
`phase_binning`	`int`	Planetary epoch binning. Useful if your star changes on a shorter timescale than your planet. For example, if set to 4, a planet spectrum will be calculated for every fourth stellar spectrum and will be interpolated otherwise.
`use_molecular_signatures`	`bool`	Whether to have PSG consider the planetary atmosphere. If False, PSG will return a blackbody spectrum. Useful for testing.
`use_continuum_stellar` (optional)	`bool`	Whether to have PSG use a stellar atmosphere model. Otherwise, the stellar spectrum is a blackbody. While not guaranteed, there is no expectation that this parameter has any effect on VSPEC outputs. Default is `True`.
`nmax`	`int`	The number of n-stream pairs for scattering aerosols calculations. See the PSG Handbook for details.
`lmax`	`int`	The number of Legendre polynomials for scattering aerosols calculations. See the PSG Handbook for details.
`continuum`	`list of str`	The continuum opacities to include in the radiative transfer calculation. Typically these include `Rayleigh`, `Refraction`, and `CIA_all`.

`gcm`#

Note

In order to support many types of GCM input this section can be configured many ways.Read the following carefully.

Key	Parses to	Description
`mean_molecular_weight`	`float`	The mean molecular weight of the GCM in amu.
`binary` \| `waccm` \| `exocam` \| `exoplasim` \| `vspec`	see binary, waccm, exocam, exoplasim, vspec	The GCM type and parameters.

`binary`#

Key	Parses to	Description
`path`	`pathlib.Path`	The path to the PSG-readable GCM file. The contents of this file are parsed by `pypsg.globes.GCMdecoder` into a `pypsg.globes.PyGCM` object.

`waccm`#

Key	Parses to	Description
`path`	`pathlib.Path`	The path to the WACCM netCDF file.
`itime` (optional)	`int`	The index of the time axis to use. If this is specified, then the GCM is static. Otherwise, it is assumed that the GCM changes as a function of time, and the `tstart` parameter must be specified.
`tstart` (optional)	`astropy.units.Quantity`	The start time of the GCM. Only used if `itime` is not specified.
`molecules`	`list of str`	Which molecular species to look for in the GCM file. Use the same names as in PSG.
`aerosols` (optional)	`list of str`	Which aerosol species to look for in the GCM file. Use the same names as in PSG.
`background` (optional)	`str`	The background molecular species. The abundances in `molecules` will be subtracted from unity and the difference will be included as this background species. If this species is already in `molecules`, then an error will be raised.
`lon_start` (optional)	`float`	The longitude of the first point on the longitudinal axis. Default is `-180`.
`lat_start` (optional)	`float`	The latitude of the first point on the latitudinal axis. Default is `-90`.

`exocam`#

Key	Parses to	Description
`path`	`pathlib.Path`	The path to the ExoCAM netCDF file.
`itime` (optional)	`int`	The index of the time axis to use. If this is specified, then the GCM is static. Otherwise, it is assumed that the GCM changes as a function of time, and the `tstart` parameter must be specified.
`tstart` (optional)	`astropy.units.Quantity`	The start time of the GCM. Only used if `itime` is not specified.
`molecules`	`list of str`	Which molecular species to look for in the GCM file. Use the same names as in PSG.
`aerosols` (optional)	`list of str`	Which aerosol species to look for in the GCM file. Use the same names as in PSG.
`background` (optional)	`str`	The background molecular species. The abundances in `molecules` will be subtracted from unity and the difference will be included as this background species. If this species is already in `molecules`, then an error will be raised.
`lon_start` (optional)	`float`	The longitude of the first point on the longitudinal axis. Default is `-180`.
`lat_start` (optional)	`float`	The latitude of the first point on the latitudinal axis. Default is `-90`.
`mean_molecular_mass` (optional)	`float`	The mean molecular mass of the GCM. Must be specified if `H2O` is in `molecules`. This is because ExoCAM treats water as humidity.

`exoplasim`#

Key	Parses to	Description
`path`	`pathlib.Path`	The path to the ExoPlasim netCDF file.
`itime`	`int`	The index of the time axis to use.
`molecules`	`list of str`	Which molecular species to look for in the GCM file. Use the same names as in PSG.
`aerosols` (optional)	`list of str`	Which aerosol species to look for in the GCM file. Use the same names as in PSG.
`background` (optional)	`str`	The background molecular species. The abundances in `molecules` will be subtracted from unity and the difference will be included as this background species. If this species is already in `molecules`, then an error will be raised.
`lon_start` (optional)	`float`	The longitude of the first point on the longitudinal axis. Default is `-180`.
`lat_start` (optional)	`float`	The latitude of the first point on the latitudinal axis. Default is `-90`.
`mean_molecular_mass` (optional)	`float`	The mean molecular mass of the GCM. Must be specified if `H2O` is in `molecules`. This is because ExoPlasim treats water as humidity.

`vspec`#

Warning

This is a minimal atmosphere model. It is useful for testing or when a sophisticated model is not necessary.

Key	Parses to	Description
`nlayer`	`int`	The number of layers in the GCM.
`nlon`	`int`	The number of longitude points in the GCM.
`nlat`	`int`	The number of latitude points in the GCM.
`epsilon`	`float`	The thermal inertia of the GCM. See Cowan and Agol [2011].
`p_surf`	`astropy.units.Quantity`	The surface pressure of the GCM.
`p_stop`	`astropy.units.Quantity`	The pressure at the top of the atmosphere.
`wind_u`	`astropy.units.Quantity`	The U component (west-to-east) of the GCM’s wind.
`wind_v`	`astropy.units.Quantity`	The V component (south-to-north) of the GCM’s wind.
`gamma`	`float`	The adiabatic index of the GCM atmosphere.
`albedo`	`float`	The surface albedo of the GCM.
`emissivity`	`float`	The surface emissivity of the GCM.
`molecules`	`list of str`	The molecular species in the GCM.
`lat_redistribution` (optional)	`float`	The latitudinal redistribution factor of the GCM. If `1`, the poles have the same temperature as the equator. If `0`, then there is no heat redistribution. Default is `0.0`.

VSPEC.params Package#

The VSPEC parameters module.

This classes instruct the behavior of the rest of the VSPEC package.

Classes#

`BandpassParameters`(wl_blue, wl_red, ...)	Class to store bandpass parameters for observations.
`BaseParameters`(**kwargs)	Base class for Parameters
`BlackbodyGridParameters`()	Parameter container for a forward-model blackbody stellar spectrum.
`CoronagraphParameters`(aperture, zodi, ...)	Parameters for a coronagraph telescope.
`DetectorParameters`(beam_width, ...)	Class to store detector parameters for observations.
`FaculaParameters`(distribution, ...)	Facula Parameters
`FlareParameters`(dist_teff_mean, ...)	Class to store stellar flare parameters
`GranulationParameters`(mean, amp, period, dteff)	Granulation Parameters
`GravityParameters`(mode, value)	Class representing gravity parameters.
`Header`(data_path, spec_grid, seed[, ...])	Header for VSPEC simulation
`InstrumentParameters`(telescope, bandpass, ...)	Class to store instrument parameters for observations.
`InternalParameters`(header, star, planet, ...)	Class to store parameters for a VSPEC simulation.
`LimbDarkeningParameters`(u1, u2)	Limb Darkening Parameters for the Quadratic Limb Darkening Law
`ObservationParameters`(observation_time, ...)	Class storing parameters for observations.
`PlanetParameters`(name, radius, gravity, ...)	Class representing planet parameters.
`SingleDishParameters`(aperture, zodi)	Parameters for a single dish telescope.
`SpotParameters`(distribution, ...)	Parameters controling variability from star spots.
`StarParameters`(psg_star_template, teff, ...)	Parameters describing the `VSPEC` stellar model.
`SystemParameters`(distance, inclination, ...)	Class representing system parameters.
`TelescopeParameters`(aperture, mode, zodi[, ...])	Base class for telescope Parameters.
`VSPECGridParameters`(max_teff, min_teff[, ...])	Parameter container for the default VSPEC grid.
`ccdParameters`(pixel_sampling, read_noise, ...)	Class to store CCD parameters for observations.
`gcmParameters`(gcm_getter, mean_molec_weight, ...)	Class to store GCM parameters.
`psgParameters`(gcm_binning, phase_binning, ...)	Class to store parameters for the Planetary Spectrum Generator (PSG).

Class Inheritance Diagram#

Inheritance diagram of VSPEC.params.observation.BandpassParameters, VSPEC.params.base.BaseParameters, VSPEC.params.read.BlackbodyGridParameters, VSPEC.params.observation.CoronagraphParameters, VSPEC.params.observation.DetectorParameters, VSPEC.params.stellar.FaculaParameters, VSPEC.params.stellar.FlareParameters, VSPEC.params.stellar.GranulationParameters, VSPEC.params.planet.GravityParameters, VSPEC.params.read.Header, VSPEC.params.observation.InstrumentParameters, VSPEC.params.read.InternalParameters, VSPEC.params.stellar.LimbDarkeningParameters, VSPEC.params.observation.ObservationParameters, VSPEC.params.planet.PlanetParameters, VSPEC.params.observation.SingleDishParameters, VSPEC.params.stellar.SpotParameters, VSPEC.params.stellar.StarParameters, VSPEC.params.planet.SystemParameters, VSPEC.params.observation.TelescopeParameters, VSPEC.params.read.VSPECGridParameters, VSPEC.params.observation.ccdParameters, VSPEC.params.gcm.gcmParameters, VSPEC.params.gcm.psgParameters

Inputs#

The VSPEC.params YAML Format#

header#

spec_grid#

name="vspec"#

name="bb"#

star#

ld#

spots#

faculae#

flares#

granulation#

planet#

gravity#

system#

obs#

inst#

single#

coronagraph#

bandpass#

detector#

ccd#

psg#

gcm#

binary#

waccm#

exocam#

exoplasim#

vspec#

VSPEC.params Package#

Classes#

Class Inheritance Diagram#

The `VSPEC.params` YAML Format#

`header`#

`spec_grid`#

`name="vspec"`#

`name="bb"`#

`star`#

`ld`#

`spots`#

`faculae`#

`flares`#

`granulation`#

`planet`#

`gravity`#

`system`#

`obs`#

`inst`#

`single`#

`coronagraph`#

`bandpass`#

`detector`#

`ccd`#

`psg`#

`gcm`#

`binary`#

`waccm`#

`exocam`#

`exoplasim`#

`vspec`#