Ask the virtual scientistClose

Initializing PSG

The tool can be operated in several ways: via a web interface, via a flexible application program interface (API) accessible from any scripting language (e.g., python, MATLAB, IDL), and it can be also operated by an installable suite via the Docker virtualization system. Parameters of PSG are defined for all modules and elements via a single configuration file, typically called config, which is formatted in a type of relaxed XML format.
The easiest way to start a simulation is by loading a configuration template file from the website; these templates are pre-saved configuration text files that are read by the radiative transfer modules when requesting an on-demand calculation. The configuration files are listed in the "Select Template" menu below the three main online sections of PSG (see Figure 2). Once a template configuration file is selected, and after clicking the "Load Template" button, all the parameters for the selected simulation are defined. Several templates targeting the main objects in the solar system are available, and any parameter of the run can be modified by clicking on the "Change" buttons, which will redirect into the three PSG modules, and then "Save settings". The user can also decide to not change any parameter after exploring the module by clicking "Cancel" or clicking "Reset" on the main page.
Essentially, the full purpose of the online web-interface GUI is to read/edit/save the configuration file before calling the PSG server requesting for a simulation. This file can also be downloaded and saved in your own computer for future operations by clicking the "Download configuration" button. In the same list-menu that reports the template files, it is possible to select "Upload config-file" option, which allows the user to upload pre-defined/saved files.
Once the configuration of the parameters is ready, one can start the calculation by clicking on "Generate Spectra". This will first verify the geometric parameters and pre-calculate geometric and atmospheric parameters. These will be fed together with the input configuration file to the radiative transfer modules for analysis. The output of these modules (and most databases accessed by PSG) are easy-to-read text files formatted as multi-column tables with a header defined by the # symbol. These output tables are read by the graphics module to produce the spectral plots.
When accessing the public PSG server (web and API), every user is identified by a cookie and their IP address, and has a unique configuration file associated to this ID. A limit of 100 API calls per day to the public server is defined for every ID, yet the user may obtain a higher limit (up to 100,000 simulations / day) by requesting a personal key (please send us an email). One can forgo any restrictions by installing PSG in any personal machine or computational cluster (e.g., AWS) via the free Docker architecture.
Types of parameters
 Planetary target  Viewing geometry
 Atmosphere: molecular abundances  Atmospheric scattering aerosols
 Surface properties  Instrument / telescope



Fundamentals of the Planetary Spectrum Generator
2022 Edition
Villanueva, Liuzzi, Faggi, Protopapa, Kofman,
Fauchez, Stone, Mandell
ISBN 978-0-578-36143-7
Library of Congress Control Number: 2022901290
NASA Goddard Space Flight Center
January 2022


Tutorial videos

Click on the thumbnails to play
 Chapter 1: Introduction  Chapter 6: Surface Scattering Modeling
 Chapter 2: Geometry and Orbital Modeling  Chapter 7: Mass spectrometry
 Chapter 3: Atmospheres, Exospheres and Comets  Chapter 8: Instruments and Noise Modeling
 Chapter 4: Radiative Transfer Modeling  Chapter 9: Retrieval Methods
 Chapter 5: Atmospheric Multiple Scattering  Chapter 10: API and Installation of PSG


Defining the object

PSG incorporates a 3D (three-dimensional) orbital calculator for most bodies in the Solar system, and all confirmed exoplanets. This information is used to calculate all possible geometry parameters needed when computing spectroscopic fluxes. The astronomical data is based on pre-computed ephemerides tables that provide orbital information from 1960 to 2050 with a precision of 1 minute.
In the "Target and geometry parameters" section, select the object, define date/time (UT) and press "Ephemeris" to load and calculate orbital parameters. This operation will fill the fields in this section by interpolating from high-precision pre-computed ephemeris tables.
JPL-Horizons: for bodies not defined in the object list (and for dates outside of the 1960-2050 range), PSG connects to the JPL-Horizons server and extracts orbital parameters for that object. For small bodies with no sun/obs-lat/lon, PSG defines them based on the ecliptic angles. The object-name provided should be unique, or JPL will require providing a specific JPL-Horizons record number (additional information).
For exoplanets, PSG performs the numerical integration of the orbit by extracting orbital parameters from the NASA Exoplanet Archive. PSG will search for specific ephemeris by clicking on these buttons: T) next primary transit; S) next secondary transit; P) next planet-star periapse. The name of the object should be compatible with that of the archive (see current list). Due to the uncertainty and degeneracies in the derivation of the orbital parameters for exoplanets, PSG assumes the following:
  • The longitude of ascending node (Ω) is assumed to be π.
  • The "season" identifies the true anomaly with respect to that of the secondary transit, with a phase of 180 corresponding to the primary transit.
  • In order to conserve the relationship between inclination, "season" or phase, sub-stellar lat/lon (slat/slon), and sub-observers lat/lon (olat/olon), for exoplanets PSG will set "olat = slat - inclination + 90.0" (if inclination is provided), and "olon = slon - season" (if season is provided).

Orbital parameters
Orbital parameters: In order to compute spectroscopic fluxes, one needs to establish the location of the object relative to its host-star, and the location of the observer relative to the object. The sub-observer parameters define the nadir position of the observer, while, the offsets, distance and velocity establish the lateral displacements (x/y), vertical altitude (z) and (dz/dt) parameters respectively.


Orbital and spectroscopic velocities

When performing high-resolution spectroscopic simulations, a detailed and accurate description of the different velocities is of paramount importance. In PSG, these parameters are specifically captured via three fields: OBJECT-OBS-VELOCITY, OBJECT-STAR-VELOCITY and GEOMETRY-ROTATION. Each sub-component of the sources sampled by the field-of-view (FOV) will have a particular Doppler shift associated to the object's rotation and orbital parameters. As summarized in the figure below, the stellar fluxes will have a Doppler shift that integrates the full system velocity and that of the star as being affected by the planet. This "tug" of the star by the orbiting planets is now of the prime methods used to characterize the properties of exoplanets.
The integration of all these Doppler effects is particularly relevant when employing the cross-correlation method in exoplanetary research. This method compares residual planetary spectra at different phases with a synthetic set of templates shifted following the orbital motion of the planet (and all the associated Doppler shifts). This is the prime method to characterize exoplanets using ground-based observatories, since telluric signatures are static spectroscopically, yet the planetary signatures shift by km/s across the planetary orbit.
Orbital parameters
Orbital velocities and Doppler shifts: The motion of the planets across their orbit introduces spectroscopic shifts on the planetary and stellar fluxes. This motion also perturbs or "tugs" the host-star, introducing a Doppler shift on the stellar signatures. In PSG, all these effects are taken into account when synthesizing spectra, and described via three fields: OBJECT-OBS-VELOCITY, OBJECT-STAR-VELOCITY and GEOMETRY-ROTATION. This figure describes how these three fields (calculated by PSG's Geometry module) encode the Doppler information of the motions for the whole system.


Types of stellar-hosts

PSG includes the possibility to integrate stellar templates by adopting the Kurucz 2005 stellar templates (0.15-300 μm), which is complemented at short wavelengths (<0.4 μm; X-ray, EUV, FUV) with the MUSCLES Treasurey Survey (France et al. 2016). When considering the G-type template, the spectrum is complemented with the ACE solar spectrum (2-14 μm) in the infrared and with the LISIRD template (<0.4 μm) in the UV. PSG picks the template based on the stellar type and temperature, and all fluxes are scaled to the actual effective stellar temperature of the star. The stellar information is used to compute reflected stellar/solar fluxes, and also to compute the total observable exoplanet fluxes, when the (exo)planet and star are within the field-of-view (FOV).
To download the fluxes shown below click on the following links: Sun (G2V, 5778K), HD85512 (K6Vk, 4305K), HD40307 (K2.5V, 4783K), HD97658 (K1V C, 5156K), V-EPS-ERI (K2V B, 5162K), GJ551 (M5.5V, 2800K), GJ1214 (M4.5V, 2935K), GJ876 (M3.5V, 3062K), GJ436 (M3V B, 3281K), GJ581 (M3V C, 3295K), GJ667C (M1.5V, 3327K), GJ176 (M2.5V, 3416K), GJ832 (M2/3V, 3816K). The fluxes are in units of spectral radiance in [W/m2/um/sr], and in order to compute the actual spectral irradiance [W/m2/um] received by the planet one needs to multiply by the solid angle encompassed by star as seen from the planet (Ω = 6.807E−5 ⋅ (Rstar/Dstar)2 [sr]), where Rstar is the star size with respect to our Sun [1.0 for Sun], and Dstar is the distance to the star in AU [1.0 for Earth].
Stellar templates
Stellar templates: PSG allows to integrate a broad range of stellar templates, with the UV templates shown in this figure. The UV templates (<0.4 μm) are based on the MUSCLES Treasurey Survey (France et al. 2016), with the UV solar template derived from the LISIRD tool (LASP). The templates at longer wavelengths (i.e., 0.15-300 μm, optical, IR and radio) are based on the Kurucz 2005 spectral templates, which is complemented with the ACE solar spectrum (2-14 μm) for the G-type.


Types of geometries

Once the locations of the object relative to its host-star and that of the observer relative to the object, one needs to define the observing geometry. PSG allows to define for different observing geometries: observatory, nadir, limb, solar/stellar occultation and from-surface (looking-up).
To compute incidence/emission angles, PSG employs a hybrid approach in which the geometry module computes fluxes and geometry parameters (e.g., emission:αi and incidence:βi angles) across the sampled FOV/disk employing a grid of 140 × 140 points (19,600 sets of geometry values). The point-by-point fluxes are computed employing a Lambertian model, and are then used to determine the contribution function (wi) for each of these points to the total flux. The effective emission angle (α) and incidence angle (β) are then calculated as the flux weighted value across the FOV, α = cos−1(sum(wi • cos(αi)) and β = cos−1(sum(wi • cos(βi)). The same procedure is used to compute the effective sub-solar and sub-observer latitudes and longitudes. PSG allows for sub-sampling of the disk, see more details here.
Observatory Nadir Limb Stellar Looking Up
Observatory: in this configuration the observer is located above the sub-obs location, and lateral displacements (x/y) are entered as offsets. Nadir: in this configuration the observer is located above the sub-obs location, and only the distance (z) and angle relative to this point are defined. Of relevance to orbiters. Limb: in this configuration the observation is performed tangentially to the surface towards empty space. The sub-obs point defines the shortest distance to the surface. Solar/stellar occultation: in this configuration the observation is performed tangentially to the surface towards the sun or a star. The sub-obs point defines the shortest distance to the surface. Looking up: in this configuration, the observer is located at a specific altitude and observes upwards. Of relevance for computing telluric radiances / transmittances.