Application Program Interface (API)


PSG allows to perform operations remotely by employing a versatile online Application Program Interface (API). The API operates by sending a configuration file to the PSG servers, that can modified on the local machine as needed. Upon reception of the configuration file, PSG will compute the spectra and send back the planetary spectra. The great value of the API is that the user does not need to install / update the radiative transfer modules and databases on his/her computer, and by simply performing a 'curl' command, the user will run the simulations on high-performance NASA servers.
 
The configuration file is a relaxed form of XML (eXtensible Markup Language), the now preferred file type across applications. The spectra is provided in standard ASCII columns. The resulting units for the columns can be defined with the configuration XML file, while which type of data to provide (e.g., radiance, transmittance, noise) is provided by a POST command.
 
The communication with the server is performed via HTTPS, and this can be implemented via the 'curl' terminal command. A single line of 'curl', in which the user inputs are provided via a config.txt (example) will lead to spectra. The figure below better explains the inner workings of the PSG modules, and how the user can enable / disable the different modules, and request for different spectral outputs.
 
Application Program Interface (API)
Application Program Interface: PSG can be called from a local machine via the 'curl' command that employs the HTTP protocol for establishing the communication between the local machine and the PSG servers. The user sends a XML configuration file, and receives different type of spectral results (str, tel, srf, trn, atm, rad, noi), all standarized as text ASCII tables. The API will call the required modules (geometry, atmosphere, continuum, pumas/cem, generator) in a sequencial order, yet the user can also enable / disable modules as needed. Examples are presented in the next section.

Calling the API


In order to compute spectra, one first needs to create / modify a PSG configuration file. The user can choose to edit this file with any text editor or scripting language.
 
1) Obtain a template configuration file (e.g., config.txt). The easiest way to obtain a configuration file is by parameterizing PSG via the web interface until a desired spectrum is obtained. On the main page of PSG, then click on "Download config-file", this will download the XML configuration file. A generic template can be also downloaded here.
 
2) Modify the config.txt configuration file using a text-editor, or using any scripting / programming language. In order to better understand what each parameter means, please refer to the PSG documentation.
 
3) Open a terminal window and type the following command:
 
curl --data-urlencode file@config.txt https://psg.gsfc.nasa.gov/api.php
 
4) By default, the API will run all PSG modules employing this configuration file, and will return the total radiance spectra (rad file). As shown in the figure above, one can run only certain modules and request for a different type of spectral output. This is achieved by providing several POST keywords (see table below). For instance:
 
To return planetary transmittances without the header information:
curl -d type=trn -d whdr=n --data-urlencode file@config.txt https://psg.gsfc.nasa.gov/api.php
 
To return only stellar transmittances (the API will only run the module 'continuum'):
curl -d type=str --data-urlencode file@config.txt https://psg.gsfc.nasa.gov/api.php
 
5) With the API, the user can also compute ephmerides and/or atmospheric parameters. For instance:
 
a) Create a text file config.txt with this content:
<OBJECT-DATE>2017/01/15 14:30
<OBJECT>Mars
<GEOMETRY-REF>MRO

 
b) Call the API with this command:
curl -d type=cfg -d wephm=y -d watm=y --data-urlencode file@config.txt https://psg.gsfc.nasa.gov/api.php
 
 
IDL Matlab Python Matlab Fortran Bash
IDL driver package
(telluric, planets, exoplanet transits)
MATLAB driver package
(under development)
Python driver package
(under development)
C/C++ driver package
(under development)
Fortran driver package
(under development)
Bash driver package
(telluric, planets, exoplanet transits)

 

Installing a personal version of PSG in your computer


The user can install and run a local version of PSG via the Docker system. PSG is a complex suite of spectroscopic models and databases, coordinated by a general radiative-transfer scheme. Installing the whole suite on a personal system can be a daunting process and would entail a great deal of resources / memory / time. By employing the Docker virtualization system, the user can easily install a pre-configured Virtual Machine with PSG that provides web/API access as the normal PSG suite.
 
In order to provide flexibility, the PSG personal suite is organized in packages. By default, the personal suite of PSG comes with the PROGRAMS and BASE packages, yet the user can install many additional packages, expanding the capabilities of the local version. Specifically, the correlated-k tables for low/moderate spectral resolutions can be quite heavy, and should be installed only when strictly necessary. The local PSG site also keeps track of any updates of these packages with respect to the current PSG suite, and it will inform you if you are required to update the packages.
 
Docker Virtual Machine PSG can run in any personal computer (Mac, Linux or Windows based) with the Docker software. Docker containers wrap up software and all its dependencies (including the operative system) into a standardized package that includes everything it needs to run: code, runtime, system tools and libraries. This guarantees that PSG will always run the same and Docker makes its installation as simple as pulling a container image. This also means that PSG can be easily deployed in cloud computing environments (e.g., Google Cloud, Amazon Web Services).

1) Install the Docker application in your computer. This is relatively easy and it will establish a virtualization system in which PSG will run. Visit the Docker site at www.docker.com.
 
2) From the command line / terminal, enter the following commands to pull the PSG container from the publicly available Docker hub repository:
 
docker pull geronimovillanueva/psg
docker tag geronimovillanueva/psg psg
 
3) To run PSG and enable its API interface (add the keyword '--restart always' to keep PSG always running, even after re-booting):
 
docker run -d --name psg -p 3000:80 psg
 
4) To visit the local site of PSG, open your browser and go to http://localhost:3000, while to run the local version of the Application-Program-Interface (API), enter the following command:
 
curl --data-urlencode file@config.txt http://localhost:3000/api.php
 
5) The user can install, upgrade and remove packages by visiting http://localhost:3000. For performing this from the command line (e.g., inside a VM instance) follow these commands (where 'package' is the package name, all in lower case):
 
curl http://localhost:3000/index.php?install=package
curl http://localhost:3000/index.php?update=package
curl http://localhost:3000/index.php?remove=package
 
Some useful docker commands are:
 
docker stop psgStops the current PSG container.
docker restart psgRestarts the PSG service.
docker start psgStarts the PSG service if stopped.
docker rm psgRemoves the current container of PSG from docker memory. This operation deletes all updates/installed packages since its initial run, and resets PSG.
docker ps -aLists the status (e.g., stopped, started, exited) of all currently available containers. Containers cannot be re-run if they have already been created and therefore appear in this list (independently of the status). Restart if necessary, while if the user wants to reset PSG to its original image, remove the container (docker rm) and re-run it (docker run).
docker image lsLists all the available docker images. The user can spawn multiple instances/containers from the same image. When the user pulls the PSG image from the docker hub, then this image will appear in this list.
docker image rm psgDeletes the PSG image from memory. Any new PSG container/instance will require a re-pull of the image from the docker hub.
docker system prune -afDeletes all images and containers/instances from docker memory, fully resetting docker.

 
Available packages for PSG Personal Suite
Package programs, size: 264 kB (uncompressed 660 kB)
Latest version: 2018-12-13
 
Operational software and programs required by PSG. This package includes all the necessary binaries to perform the radiative transfer calculations and retrievals, together with the PHP server interpreter modules. This package cannot be removed (it is fundamental for the operation of PSG), and it should be constantly updated to reflect the upgrades performed to the suite.
Package base, size: 0.3 GB (uncompressed 1.4 GB)
Latest version: 2018-10-15
 
This package includes the basic spectroscopic data for performing line-by-line calculations across a broad range of wavelengths and domains. It includes:
  • HITRAN line-by-line database formatted for PSG (binary) with collissional information for CO2, H2, He when available.
  • HITRAN Collission-Induced-Absorption (CIA) database for many species due to various collisionally interacting atoms or molecules. Some CIA spectra are given over an extended range of frequencies.
  • UV cross-sections database for a multiple species (ingested automatically by the RT modules when applicable).
  • Kurucz's stellar templates.
  • Scattering models for hundreds of optical constants (HRI, GSFC, Mie scattering), and for typical Mars aerosols (dust, water-ice, T-max based on Wolff et al.)
Package surfaces, size: 32.8 MB (uncompressed 131.7 MB)
Latest version: 2018-10-05
 
The surface spectroscopic package includes the complete repository of optical constants and reflectances from all databases handled by PSG (e.g., USGS, JENA).
Package atmospheres, size: 1.2 GB (uncompressed 3 GB)
Latest version: 2018-10-05
 
This package includes the climatological and atmospheric files needed by the 'atmosphere' module. Specifically, it includes:
  • Atmospheric templates for most Solar-System bodies.
  • Earth MERRA2 auxiliary data (e.g., topography) and Mars LMD climatology database.
  • Exoplanet basic templates.
  • Exoplanet Parmentier T/P model and Kempton equilibrium chemistry modules.
Package ephm, size: 1.2 GB (uncompressed 1.8 GB)
Latest version: 2018-10-05
 
The ephemerides package includes orbital and geometric used by the 'geometry' module. Specifically, it includes:
  • Ephemerides information for hundreds of Solar-System bodies (1960-2050).
  • Ephemerides information for dozens of planetary missions (e.g., Cassini, MAVEN).
Package telluric, size: 1 GB (uncompressed 2.4 GB)
Latest version: 2018-10-05
 
This package includes the database of telluric transmittances necessary when computing spectra as observed with ground-based observatories. It includes:
  • Database of telluric transmittances pre-computed for 5 altitudes and 4 columns of water for each case.
  • The altitudes include that of Mauna-Kea/Hawaii (4200 m), Paranal/Chile (2600 m), SOFIA (14,000 m) and balloon observatories (35,000 m).
  • The water vapor column was established by scaling the tropical water profile by a factor of 0.1, 0.3 and 0.7 and 1.
Package xcross, size: 0.8 GB (uncompressed 2.6 GB)
Latest version: 2018-10-05
 
This package contains hundreds of absorption cross-sections for complex volatiles as reported by the latest HITRAN release.
Package lines, size: 0.3 GB (uncompressed 1.1 GB)
Latest version: 2018-10-05
 
This package contains line-by-line spectroscopic information from several databases.
  • GEISA database.
  • JPL Molecular spectroscopy database.
  • CDMS molecular spectroscopy database.
Package fluor, size: 2.3 GB (uncompressed 2.8 GB)
Latest version: 2018-10-05
 
This package contains non-LTE fluorescence efficiencies for dozens of species, suitable when synthesizing cometary spectra in the UV/optical/IR range.
Package exo, size: 0.2 GB (uncompressed 1.1 GB)
Latest version: 2018-10-05
 
This package contains molecular and atomic cross-sections applicable for exoplanetary modeling, and it is based on the database employed by the open source 'Exo-Transmit' code (Kempton et al. 2017).
Package corrklow, size: 7.4 GB (uncompressed 13.3 GB)
Latest version: 2018-10-05
 
This package contains correlated-k tables for the main HITRAN species (H2O, CO2, O3, N2O, CO, CH4, O2, SO2, NO2, NH3, HCl, OCS, H2CO, N2, HCN, C2H2, C2H4, PH3, H2S, C2H4, H2), and for different collissional partners (e.g., CO2, H2, He) when available. The tables were computed with PUMAS assuming wings of 25 cm-1 and a fine core of 1 cm-1 where maximum resolution calculations are applied.
This is the 'low' resolution package applicable to synthesis of spectra with a resolving power lower/equal than 500.
Package corrkmed, size: 58 GB (uncompressed 132.5 GB)
Latest version: 2018-08-09
 
This package contains correlated-k tables for the main HITRAN species (H2O, CO2, O3, N2O, CO, CH4, O2, SO2, NO2, NH3, HCl, OCS, H2CO, N2, HCN, C2H2, C2H4, PH3, H2S, C2H4, H2), and for different collissional partners (e.g., CO2, H2, He) when available. The tables were computed with PUMAS assuming wings of 25 cm-1 and a fine core of 1 cm-1 where maximum resolution calculations are applied.
This is the 'med' resolution package applicable to synthesis of spectra with a resolving power greater than 500 and lower/equal to 5000.

 
 

Types of planetary spectra and special keywords


Requested spectra (type keyword)
radIntegrated fluxes, incorporating all planetary and stellar transmittances, and considering the specific instrument / observatory parameters. This file is computed by the module generator. This is the default output setting.
noiSynthetic observational noise, including the noise introduced by the planet itself, its star (if present within the field), background sources (e.g., exozodii, local zodiacal dust, CMB), the terrestrial atmosphere (if observing from ground), and the instrument performance. This file is computed by the module generator.
trnIntegrated planetary transmittance spectra, including all geometry considerations and requested atmospheric parameters. This file is computed by the module PUMAS only.
atmIntegrated planetary fluxes as observed at the planet in units of [W m-2 sr-1 um-1]. This file is computed by the modules PUMAS and CEM.
strStellar transmittance spectrum. This file is computed by the module continuum.
telTerrestrial transmittance spectrum. This file is computed by the module continuum.
srfSurface reflectance and emissivity spectra. This file is computed by the module continuum.
cfgThe API will return the updated configuration file. This file is computed by the modules geometry and atmosphere.
allThis keyword will return all the resulting spectra, and the configuration file.

 
Special keywords
wgeoThe geometry module computes the observational angles (GEOMETRY-SOLAR-ANGLE, GEOMETRY-OBS-ANGLE) and the beam/planet ratio (GEOMETRY-PLANET-FRACTION) employing the geometry information provided by the user in the XML configuration file. For exoplanets, it also computes the planet transit factor (GEOMETRY-STAR-FRACTION), and the planet-star distance (GEOMETRY-STAR-DISTANCE). This information is then saved into the configuration file to be used by the other modules. The default is wgeo=y, yet one can disable this computation with wgeo=n.
wephmThis keyword enables the calculation of ephemeris parameters based on the object name and the provided date:
  • wephm=y computes ephemeris for the date provided.
  • wephm=N computes ephemeris for the current date/time.
  • wephm=T for exoplanets, it searches the next primary transit event, while for Solar System bodies it computes the ephemeris for [date - one day].
  • wephm=S for exoplanets, it searches the next secondary transit event, while for Solar System bodies it computes the ephemeris for [date + one day].
  • wephm=P for exoplanets, it searches the next periastron event.
  • wephm=n disables the ephemerides module (default).
watmThis keyword enables / disables the atmosphere module - Default watm=n.
whdrThis keyword allows to disable outputing the header information - Default whdr=y.

 

Full list of parameters accepted by PSG


Type Keyword Range Description
OBJECT S50 Object type (e.g., Exoplanet) or object name for the main bodies in the Solar System
OBJECT-NAME S50 Object name
OBJECT-DATE S20 Date of the observation (yyyy/mm/dd hh:mm) in Universal time [UT]
OBJECT-DIAMETER 1e-2 1e8 Diameter of the object [km]
OBJECT-GRAVITY 0 1e35 Gravity/density/mass of the object
OBJECT-GRAVITY-UNIT S10 Unit for the OBJECT-GRAVITY field, g:'Surface gravity [m/s2]', rho:'Mean density [g/cm3]', or kg:'Total mass [kg]'
OBJECT-STAR-DISTANCE 0 1e5 Distance of the planet to its parent star [AU]
OBJECT-STAR-VELOCITY -1e4 1e4 Velocity of the planet with respect to its parent star (in the observer-planet vector) [km/s]
OBJECT-SOLAR-LONGITUDE -360 360 Sub-solar east longitude [degrees] / For exoplanets, longitude of periapse [degrees]
OBJECT-SOLAR-LATITUDE -90 90 Sub-solar latitude [degrees] / For exoplanets, orbital eccentricity
OBJECT-SEASON 0 360 Angular parameter (season/phase) that defines the position of the planet moving along its Keplerian orbit, where 0:'Northern Hemisphere Spring Equinox', 90:'Northern Hemisphere Summer Solstice', 180:'Northern Hemisphere Autumn Equinox', 270:'Northern hemisphere Winter Solstice' [degrees]
OBJECT-STAR-TYPE S1 Stellar type of the parent star [O/B/A/F/G/K/M]
OBJECT-STAR-TEMPERATURE 1 1e5 Temperature of the parent star [K]
OBJECT-STAR-RADIUS 1e-3 1e8 Radius of the parent star [Rsun]
OBJECT-OBS-LONGITUDE -360 360 Sub-observer east longitude [degrees]
OBJECT-OBS-LATITUDE -90 90 Sub-observer latitude [degrees]
OBJECT-OBS-VELOCITY -1e4 1e4 Relative velocity between the observer and the object [km/s]
OBJECT-PERIOD 0 1e8 This field is computed by the geometry module - It is the apparent rotational period of the object as seen from the observer [days]
GEOMETRY S20 Type of observing geometry, Telescope / Nadir / Limb / Solar / Stellar / Lookingup / LookingSolar
GEOMETRY-REF S50 Reference geometry (e.g., ExoMars, Maunakea), default is user defined or 'User'
GEOMETRY-OFFSET-NS -1e6 1e6 Right-ascension offset with respect to the sub-observer location
GEOMETRY-OFFSET-EW -1e6 1e6 Declination offset with respect to the sub-observer location
GEOMETRY-OFFSET-UNIT S10 Unit of the GEOMETRY-OFFSET field, arcsec / arcmin / degree / km / diameter
GEOMETRY-OBS-ALTITUDE 0 1e8 Distance between the observer and the surface of the planet
GEOMETRY-ALTITUDE-UNIT S10 Unit of the GEOMETRY-OBS-ALTITUDE field, AU / km / diameter and pc:'parsec'
GEOMETRY-USER-PARAM 0 1000 Parameter for the selected geometry, for Nadir / Lookingup this field indicates the zenith angle [degrees], for limb / occultations this field indicates the atmospheric height [km] being sampled
GEOMETRY-STELLAR-TYPE S1 For stellar occultations, this field indicates the type of the occultation star [O/B/A/F/G/K/M]
GEOMETRY-STELLAR-TEMPERATURE 1 1e5 For stellar occultations, this field indicates the temperature [K] of the occultation star
GEOMETRY-STELLAR-MAGNITUDE -30 30 For stellar occultations, this field indicates the brightness [magnitude] of the occultation star
GEOMETRY-OBS-ANGLE 0 360 This field is computed by the geometry module - It indicates the angle between the observer and the planetary surface
GEOMETRY-SOLAR-ANGLE 0 360 This field is computed by the geometry module - It indicates the angle between the Sun and the planetary surface
GEOMETRY-DISK-ANGLES 1 10 This field allows to divide the observable disk in finite rings so radiative-transfer calculations are performed with higher accuracy.
GEOMETRY-PHASE -360 360 This field is computed by the geometry module - It indicates the phase between the Sun and observer
GEOMETRY-PLANET-FRACTION 0 1 This field is computed by the geometry module - It indicates how much the beam fills the planetary area (1:maximum)
GEOMETRY-STAR-FRACTION 0 1 This field is computed by the geometry module - It indicates how much the beam fills the parent star (1:maximum)
GEOMETRY-STAR-DISTANCE -1 1e8 This field is computed by the geometry module - It indicates the projected distance between the beam and the parent star
GEOMETRY-ROTATION S15 This field is computed by the geometry module - It indicates the rotational Doppler shift [km/s] affecting the spectra and the spread of rotational velocities [km/s] within the FOV
ATMOSPHERE-STRUCTURE S100 The structure of the atmosphere, None / Equilibrium:'Hydrostatic equilibrium' / Coma:'Cometary expanding coma'
ATMOSPHERE-PRESSURE 0 1e35 For equilibrium atmospheres, this field defines the surface pressure; while for cometary coma, this field indicates the gas production rate
ATMOSPHERE-PUNIT S20 The unit of the ATMOSPHERE-PRESSURE field, Pa:Pascal / bar / kbar / mbar / ubar / at / atm / torr / psi / gas:'molecules / second' / gasau:'molecules / second at rh=1AU'
ATMOSPHERE-TEMPERATURE 1 1e4 For atmospheres without a defined P/T profile, this field indicates the temperature across all altitudes
ATMOSPHERE-WEIGHT 1 1e3 Molecular weight of the atmosphere [g/mol] and expansion velocity [m/s] for expanding atmospheres
ATMOSPHERE-NGAS 0 20 Number of gases to include in the simulation
ATMOSPHERE-GAS S300 Name of the gases to include in the simulation, e.g 'H2O,CO2'
ATMOSPHERE-TYPE S300 Sub-type of the gases, e.g. 'HIT[1],HIT[2]'
ATMOSPHERE-ABUN S300 Abundance of gases. The values can be assumed to be same across all altitudes/layers [%,ppmv,ppbv,pptv,m-2], or as a multiplier [scaler] to the provided vertical profile (see ATMOSPHERE-LAYERS-MOLECULES)
ATMOSPHERE-UNIT S300 Unit of the ATMOSPHERE-ABUN field, % / ppmv / ppbv / pptv / m2:'molecules/m2' / scl:'scaler of profile'
ATMOSPHERE-TAU S300 For expanding cometary coma, this field indicates the photodissociation lifetime of the molecules [s]
ATMOSPHERE-NAERO 0 20 Number of aerosols to include in the simulation
ATMOSPHERE-AEROS S300 Name of the aerosols to include in the simulation
ATMOSPHERE-ATYPE S300 Sub-type of the aerosols
ATMOSPHERE-AABUN S300 Abundance of aerosols. The values can be assumed to be same across all altitudes/layers [%,ppm,ppb,ppt,Kg/m2], or as a multiplier [scaler] to the provided vertical profile (see ATMOSPHERE-LAYERS-MOLECULES)
ATMOSPHERE-AUNIT S300 Unit of the ATMOSPHERE-AABUN field, % / ppmv / ppbv / pptv / m2:'molecules/m2' / scl:'scaler of profile'
ATMOSPHERE-ASIZE S300 Effective radius of the aerosol particles
ATMOSPHERE-ASUNI S300 Unit of the aerosol particles [um / scaler] - Default is [um]
ATMOSPHERE-NMAX 0 100 When performing scattering aerosols calculations, this parameter indicates the number of n-stream pairs - Use 0 for extinction calculations
ATMOSPHERE-LMAX 0 100 When performing scattering aerosols calculations, this parameter indicates the number of scattering Legendre polynomials used for describing the phase function - Use 0 for extinction calculations
ATMOSPHERE-DESCRIPTION S200 Description establishing the source/reference for the vertical profile
ATMOSPHERE-LAYERS 0 999 Number of layers of the atmospheric vertical profile
ATMOSPHERE-LAYERS-MOLECULES S500 Molecules quantified by the vertical profile
ATMOSPHERE-LAYER S500 Values for that specific layer: Pressure[bar], Temperature[K], gases[mol/mol], aerosols [kg/kg] - Optional fields: Altitude[km], X_size[m, aerosol X particle size]
SURFACE-TEMPERATURE 0 1e5 Temperature of the surface [K]
SURFACE-ALBEDO 0 1.0 Albedo the surface [0:non-reflectance, 1:fully-reflective]
SURFACE-EMISSIVITY 0 1.0 Emissivity of the surface [0:non-emitting, 1:perfect-emitter]
SURFACE-PHASEG -1.0 1.0 One-term Henyey-Greenstein g-factor [0:isotropic, -1:backward scatterer, +1:forward scatterer]
SURFACE-GAS-RATIO 0 1e3 For expanding cometary coma, this value indicates an scaling value for the dust in the coma.
SURFACE-GAS-UNIT S50 Unit of the dust abundance, [ratio] is dust/gas mass ratio, while [afrho] is the Afrho value and [lafrho] is log[Afrho/Q]
SURFACE-NSURF 0 20 Number of components describing the surface properties [areal mixing]
SURFACE-SURF S300 Name of surface components to be included in the simulation
SURFACE-TYPE S300 Sub-type of the surface components
SURFACE-ABUN S300 Relative abundance of the surface components
SURFACE-UNIT S300 Unit of the SURFACE-ABUN field, % / ppm / ppv
SURFACE-THICK S300 Thickness for each surface component [um]
GENERATOR-RANGE1 1e-5 1e7 Lower spectral range for the simulation
GENERATOR-RANGE2 1e-5 1e7 Upper spectral range for the simulation
GENERATOR-RANGEUNIT S10 Unit of the GENERATOR-RANGE fields, um / nm / mm / An:'Angstrom' / cm:'Wavenumber [cm-1]' / MHz / GHz / kHz
GENERATOR-RESOLUTION 1e-6 1e8 Spectral resolution for the simulation. PSG assumes that the sampling resolution is equal is to the instrumental resolution, yet radiative transfer resolutions are always performed at the necessary/higher resolutions in order to accurately describe the lineshapes
GENERATOR-RESOLUTIONUNIT S10 Unit of the GENERATOR-RESOLUTION field, RP:'Resolving power' / um / nm / mm / An:'Angstrom' / cm:'Wavenumber [cm-1]' / MHz / GHz / kHz
GENERATOR-GAS-MODEL S1 Flag indicating whether to include molecular signatures as generated with PUMAS or CEM [Y/N]
GENERATOR-CONT-MODEL S1 Flag indicating whether to include continuum signatures as generated by the surface, the star (when in the field) and dust/nucleus (when synthesizing comets) [Y/N]
GENERATOR-CONT-STELLAR S1 Flag indicating whether to include stellar absorption signatures in the reflected sunlight / stellar spectra [Y/N]
GENERATOR-TRANS-SHOW S1 Flag indicating whether we are synthesizing planetary spectra (not of Earth) as observed with a ground-based telescope. This flag will ensure that the noise module properly includes telluric signatures.
GENERATOR-TRANS-APPLY S1 Flag indicating whether to show the spectra divided by the telluric transmittance [N], or as observed and affected by transmittance [Y]
GENERATOR-TRANS S20 Keyword [SS-WW] indicating the site [SS] and water abundance [WW]. Values of SS are 00:'0m (sea level)', 01:'2,600m (8,500 feet)', 02:'4,200m (14,000 feet)', 03:'14,000m (46,000 feet)', 04:'35,000m (120,000 feet)'. Values of WW are 00:'10% tropical', 01:'30% tropical', 02:'70% tropical', 03:'100% tropical'
GENERATOR-RADUNITS S20 Radiation unit for the generated spectra, see full list of permitted keywords in the 'Modeling > Radiation Units' section
GENERATOR-LOGRAD S1 Flag indicating whether to show the spectra employing a logarithmic scale
GENERATOR-TELESCOPE S10 Type of telescope, SINGLE:'single dish telescope / instrument' / ARRAY:'Interferometric array' / CORONA:'Coronagraph'
GENERATOR-BEAM 1e-3 1e6 Full width half-maximum (FWHM) of the instrument's beam
GENERATOR-BEAM-UNIT S20 Unit of the GENERATOR-BEAM field, arcsec / arcmin / degree / km / diameter:'beamsize in terms of the planet's diameter' / diffrac:'defined by the telescope diameter and center wavelength'
GENERATOR-DIAMTELE 1e-5 1e5 Diameter of the main reflecting surface of the telescope / instrument [m]
GENERATOR-TELESCOPE1 S100 For interferometers, the number of telescopes; for coronagraphs, the instrument's constrast
GENERATOR-TELESCOPE2 S100 For coronagraphic observations, the exozodi level
GENERATOR-TELESCOPE3 S100 For coronagraphic observations, the inner working angle (IWA) in units of [L/D]
GENERATOR-NOISE S20 Keyword identifying the noise model to consider, NO:'None' / TRX:'Receiver temperature / radio' / RMS:'Constant noise in radiation units' / BKG:'Constant noise with added background' / NEP:'Power equivalent noise detector model' / D*:'Detectability noise detector model' / CCD:'Image sensor'
GENERATOR-NOISETIME 0.0 1e7 Exposure time per frame [sec]
GENERATOR-NOISEFRAMES 1 1e5 Number of exposures
GENERATOR-NOISEPIXELS 1 1e9 Total number of pixels that encompass the beam (GENERATOR-BEAM) and the spectral unit (GENERATOR-RESOLUTION)
GENERATOR-NOISE1 0.0 1e20 First noise model parameter - For RMS, 1-sigma noise; for TRX, the receiver temperature; for BKG, the 1-sigma noise; for NEP, the sensitivity in W/sqrt(Hz); for DET, the sensitivity in cm.sqrt(Hz)/W; for CCD, the read noise [e-]
GENERATOR-NOISE2 0.0 1e20 Second noise model parameter - For RMS, not used; for TRX, the sideband g-factor; for BKG, the not used; for NEP, not used; for DET, the pixel size [um]; for CCD, the dark rate [e-/s]
GENERATOR-NOISEOEFF 0.0 1.0 Total throughput of the telescope+instrument, from photons arriving to the main mirror to photons being quantified by the detector [0:none to 1:perfect]. The user can provide wavelength dependent values as neff@wavelength[um] (e.g., '0.087@2.28,0.089@2.30,0.092@2.31,0.094@2.32,...')
GENERATOR-NOISEOEMIS 0.0 1.0 Emissivity of the telescope+instrument optics [0 to 1]
GENERATOR-NOISEOTEMP 0.0 1e4 Temperature of the telescope+instrument optics [K]
GENERATOR-INSTRUMENT S500 Text describing if an instrument template was used to define the GENERATOR parameters
RETRIEVAL-GAMMA 0 1e3 The parameter Gamma (or Levenberg-Marquart parameter) is the extra regularization parameter (e.g., 0:Classic LM, 1:classic Rodgers' formalism, 10:Heavily tailored to the a-priori).
RETRIEVAL-RANGEUNIT S10 Spectral unit of the user-provided data for the retrieval, um / nm / mm / An:'Angstrom' / cm:'Wavenumber [cm-1]' / MHz / GHz / kHz
RETRIEVAL-RESOLUTION 1e-6 1e8 Instrument's spectral resolution [FWHM] of the user-provided data. This value is independent of the sampling rate of the data, and refers to the actual spectral resolution of the instrument.
RETRIEVAL-RESOLUTIONUNIT S10 Unit of the RETRIEVAL-RESOLUTION field, RP:'Resolving power' / um / nm / mm / An:'Angstrom' / cm:'Wavenumber [cm-1]' / MHz / GHz / kHz
RETRIEVAL-FLUXSCALER 0 1E30 Scaling value to be applied to all fluxes of the user-provided data file.
RETRIEVAL-FREQSHIFT -1e5 1e5 Frequency/wavelength shift to be applied to the data.
RETRIEVAL-FLUXLABELS S100 Labels for the columns of the data file.
RETRIEVAL-FITGAIN -1 10 Polynomical degree of the instrument's gain function, -1:None, 0:Constant, 1:Sloped, 2:Quadratic, etc.
RETRIEVAL-FITGAIN-PHOTOMETRIC S1 Flag indicating whether to preserve the photometric information of the data (zeroth order of gain fitting) [Y:Disable 0th order / N:Enable]
RETRIEVAL-REMOVEOFFSET -1 10 Polynomical degree of the residual offset, -1:None, 0:Constant, 1:Sloped, 2:Quadratic, etc.
RETRIEVAL-REMOVEFRINGE 0 9 Maximum number of spectral fringes to be removed from the data.
RETRIEVAL-FITSTELLAR S1 Flag indicating whether to fit the intensity of the solar/stellar features [Y/N]
RETRIEVAL-FITFREQ S1 Flag indicating whether to refine the spectral calibration [Y/N]
RETRIEVAL-FITRESOLUTION S1 Flag indicating whether to fit the spectral resolution [Y/N]
RETRIEVAL-FITTELLURIC S1 Flag indicating whether to refine the telluric features [Y/N]. This is done by perturbing the selected telluric column/water abundances.
RETRIEVAL-NVARS 0 1000 Number of model variables to be retrieved.
RETRIEVAL-VARIABLES S30000 Name of the variables of the retrieval (comma separated).
RETRIEVAL-VALUES S30000 A-priori and resulting values of the retrieval parameters (comma separated).
RETRIEVAL-SIGMAS S30000 Resulting 1-sigma uncertainties (corrected by chi-square) of the retrieval parameters (comma separated).
RETRIEVAL-MIN S30000 Lower boundary permitted for each parameter (comma separated).
RETRIEVAL-MAX S30000 Upper boundary permitted for each parameter (comma separated).
RETRIEVAL-UNITS S30000 Magnitude unit of the a-priori and boundary entries (comma separated).
RETRIEVAL-STATUS S30 Flag indicating the status of the retrieval suite (e.g., RUNNING, OK)