Overview
The Pandeia Engine is a Python module (compatible with Python 3.6 and later) that functions as the computational engine of the JWST ETC and Roman ETC. It can be imported and run as a standalone module.
The engine itself can be run with the command
from pandeia.engine import perform_calculation result = perform_calculation.perform_calculation(calculation)
where "calculation" is a heirarchical dictionary describing a scene of sources, an instrument setup, and an extraction strategy.
Such dictionaries are available in JWST Webapp download files (as a JSON-formatted file named input.json, suitable for reading in with built-in Python functions) or default versions can be created with the function build_default_calc() and then edited:
from pandeia.engine import calc_utils calculation = calc_utils.build_default_calc("jwst","nircam","sw_imaging")
The command above produces the NIRCam calculation on the left.
The full API documentation, with all possible options and combinations for any instrument, is given below.
Top Level
The engine input api is a dict. At the top level of the dict, there are:
background:
string for canned background location lookup, or array of background values (see below)
background_level:
string for canned background level (optional; see below)
configuration:
dict: camera/telescope configuration
scene:
list: list of sources
strategy:
dict: strategy configuration
calculation: (optional)
dict: test interface for detector effects
fake_exception: (optional)
test interface
error, server_test:
reserved by server
Full Engine Input API
As of now, the engine requires the following information to perform a calculation:
Scene
scene: list (no default)
This is a list of Sources. Each Source is described by a dict with the following keys:
position: dict
Source position parameters described by the following keys:
x_offset: float (default 0.0)
Detector plane X offset from FOV center in arcseconds. Positive to the right.
Coordinates are set such that at the center of the center pixel is 0,0
y_offset: float (default 0.0)
Detector plane Y offset from FOV center in arcseconds. Positive is up.
Coordinates are set such that at the center of the center pixel is 0,0
orientation: float (default 0.0)
Detector plane orientation in degrees. Positive is in direction of +X.
(e.g. orientation=90 is UP, and orientation=-90 is DOWN)
shape: dict
Source shape parameters described by the following keys:
geometry: string (default "point")
Supported geometries are "point", "gaussian2d", "flat", "sersic", "sersic_scale", and "power". Required
additional source shape parameters are contingent on this parameter:
"point" requires no additional parameters.
"gaussian2d", "flat", "sersic", and "sersic_scale" all require these parameters:
major: float (default 0.1)
Semi-major axis in arcseconds. For "flat" this sets the size, for "gaussian2d"
this sets the sigma, for "sersic" this sets the effective radius (within which half the flux is
concentrated) and for "sersic_scale" this sets a scale length where I(r) = I(0)/e.
minor: float (default 0.1)
Semi-minor axis in arcseconds
norm_method: string (default 'integ_infinity')
Methods of surface brightness normalization to perform. Supported methods are:
* integ_infinity: Normalize to the total intensity of the source, integrated to infinity
* surf_center: Normalize to the surface brightness at the center of the source
* surf_scale: Normalize to the surface brightness at the scale radius (for gaussian2d, 1-sigma;
for sersic, the effective radius; for sersic_scale, the e-folding scale length;
NOT AVAILABLE FOR FLAT SOURCES)
surf_area_units: string (default 'arcsec^2')
Specifies what area the flux to be renormalized in spectrum/normalization/norm_flux is over.
* arcsec^2: the flux is per square arcsecond.
* sr: the flux is per steradian.
"sersic" and "sersic_scale" require one additional parameter:
sersic_index: float (default 1.0)
Power law index that sets the shape of a sersic profile.
sersic_index = 1.0 --> exponential
sersic_index = 0.5 --> gaussian
sersic_index = 4.0 --> de Vaucouleurs
"power" has its own parameters, different from the other profiles:
power_index: Power law index that sets the shape of the profile
r_core: Radius of the flat circular central core to which the profile is normalized
norm_method: string. For "power", must be set to 'surf_center'
surf_area_units: string (default 'arcsec^2'). Same as other profiles.
spectrum: dict
Source spectral parameters described by the following keys:
redshift: float (default 0.0)
Redshift to apply to the continuum. Since lines are added with physical units for their strength,
they are added to the spectrum after normalization and redshift.
extinction: dict
Defines how the spectrum is reddened by interstellar dust
law: string
Extinction law to use. Supported laws are
* ``mw_rv_31`` - WD01 Milky Way curve for an R_V value of 3.1 (default)
* ``mw_rv_40`` - WD01 Milky Way curve for an R_V value of 4.0
* ``mw_rv_55`` - WD01 Milky Way curve for an R_V value of 5.5
* ``hd210121`` - WD01 Extinction curve for high-latitude molecular cloud hd210121 with C/H = b_C = 40 ppm
in log-normal size dists
* ``lmc_avg`` - WD01 Average extinction curve for the LMC with C/H = b_C = 20 ppm in log-normal size dists
* ``lmc_2`` - WD01 LMC extinction curve with C/H = b_C = 10 ppm in log-normal size dists (30 Dor region)
* ``smc_bar`` - WD01 Extinction curve in SMC bar with C/H = b_C = 0 ppm in log-normal size dists
* ``chapman09`` - Chapman et al. (2009) mid-IR extinction curve derived from three molecular clouds:
Ophiuchus, Perseus, and Serpens
value: float
Level of extinction in units of unit
unit: string
Units of extinction. Allowed values are ``nh`` for hydrogen column density (cm^-2) and "mag" for magnitudes
of extinction in specified bandpass, ext_bandpass
bandpass: string
Bandpass to which extinction is normalized to if unit="mag". Allowed values are v, j, h, and k.
normalization: dict
Defines how the spectrum is to be scaled.
type: string
Method of normalization to perform. Supported methods are
* ``at_lambda`` - Specify norm_flux in fluxunit at a specfic wavelength, norm_wave
* ``hst`` - Specify a bandpass in the form of an "obsmode" string to pass along to synphot along with fluxunit and norm_flux
* ``jwst`` - Specify a bandpass as an instrument configuration in the form of a comma-separated string <instrument>,<mode>,<filter> along with fluxunit and norm_flux
* ``photsys`` - Specify bandpass in the form of a comma-separated string <photsys>,<filter>
* ``none`` - Do not normalize spectrum. Only valid for a spectrum type of 'input'.
norm_wave: float
Reference wavelength in 'norm_waveunit' at which spectrum will be scaled for type 'at_lambda'.
Ignored for other normalization types.
norm_flux: float
Reference flux in 'norm_fluxunit' to which spectrum will be scaled.
norm_fluxunit: string
Specify the flux units in which the normalization should occur.
Supports flam, fnu, vegamag, abmag, mjy, ujy, njy, jy
norm_waveunit: string
Specify the wavelength units used in normalization
bandpass: string
Specifies the key used to obtain the normalization bandpass for
types 'hst', 'jwst', and 'photsys'.
sed: dict
Defines the spectral energy distribution of the spectrum.
sed_type: string
Type of the spectral energy distribution. Each type requires its own set
of parameters. The analytic sed_types (none, flat, powerlaw, flat) all
require 'wmin', 'wmax', and 'sampling' to define the range and wavelength
sampling over which the model spectrum is calculated. However, they are only
available in the API for testing purposes and should not be configured via
the UI.
**no_continuum** - No continuum, specifically Flux = 0.0 over specified range [wmin, wmax]
wmin: float (default 0.5)
Minimum wavelength in microns
wmax: float (default 30.0)
Maximum wavelength in microns
sampling: int (default 200)
Sets the logarithmic wavelength sampling of the model spectrum
**flat** - Flat spectrum in specified units calculated over specified range [wmin, wmax]
wmin: float (default 0.5)
Minimum wavelength in microns
wmax: float (default 30.0)
Maximum wavelength in microns
sampling: int (default 200)
Sets the logarithmic wavelength sampling of the model spectrum
unit: string
Units of spectrum, either 'fnu' or 'flam'
**powerlaw** - Powerlaw spectrum where F ~ lambda ^ index calculated over range [wmin, wmax]
wmin: float (default 0.5)
Minimum wavelength in microns
wmax: float (default 30.0)
Maximum wavelength in microns
sampling: int (default 200)
Sets the logarithmic wavelength sampling of the model spectrum
unit: string
Units of spectrum, either 'fnu' or 'flam'
index: float
Exponent of the power law
**blackbody** - Blackbody spectrum calculated over range [wmin, wmax]
wmin: float (default 0.5)
Minimum wavelength in microns
wmax: float (default 30.0)
Maximum wavelength in microns
sampling: int (default 200)
Sets the logarithmic wavelength sampling of the model spectrum
temp: float
Temperature of the blackbody in Kelvin
**phoenix** - Parameterized stellar atmosphere models calculated by the Phoenix group
key: string
In webapp mode, a key is used to look up a predefined set of parameters. If not
in webapp mode and if key is not provided, model parameters can be passed directly:
teff: float
Effective temperature. Allowed range is 2000 K to 70000 K
log_g: float
Surface gravity in log10(cgs) units. Allowed range is 0.0 to 5.5.
metallicity: float
Metallicity in units of log10(solar metallicity). Allowed range is -4.0 to 0.5.
**hst_calspec** - HST standard star spectra
key: string
Key used to look up which spectrum to load.
**brown** - Integrated spectra of galaxies from Brown et al. (2014)
key: string
Key used to look up which spectrum to load.
**input** - spectrum provided via input arrays
spectrum: list-like or numpy.ndarray
The 0th index is taken to be wavelength in units of 'microns'.
The 1st index is taken to be the flux in units of 'mJy'.
lines: list (default [])
List of line definitions. Each definition is a dict with keys:
name: string (default 'no name')
Name of line (e.g. 'Hydrogen Alpha')
center: float (default 5.2)
Wavelength at line center in w_unit
strength: float (default 1.0e-14)
Strength of line in erg/cm^2/s for emission or
optical depth for absorption
profile: string
Line profile type:
* gaussian *default*
* voigt NOT YET IMPLEMENTED
emission_or_absorption: string
Line type:
* emission *default* (mJy)
* absorption (tau)
A profile type of **gaussian** (currently the only type) requires one additional parameter:
width: float (default 200.0)
Full-width half-max of line in km/s
When implemented, profile type of **voigt** will require two additional parameters:
gaussian_fwhm: float (default 200.0)
Full-width half-max of the gaussian core of the line in units of km/s
lorentzian_fwhm: float (default 500.0)
Full-width half-max of the lorentzian wings of the line in units of km/s
background: string (default 'minzodi') or list-like or numpy.ndarray
Possible string values are: none, minzodi, and ecliptic. String values trigger the use of
a canned background model at the location given. If a background spectrum is provided, it is
assumed that the 0th index is the wavelength in microns and the 1st index is the background
surface brightness in MJy/sr.
background_level: string (default 'benchmark').
Possible string values are "high", "medium", "low", and (only for minzodi location) "benchmark".
This value is only used if background is a string that's not none.
Effects
calculation: dict
Set of parameters to toggle the inclusion of different effects and noise parameters in a calculation.
This section is optional and largely for testing purposes. These are not supported in the UI.
If the parameter is None, the default from the instrument configuration is used. If the parameter is set
to True or False the effect is switched on or off, overriding the instrument default configurations.
Use at your own risk.
noise: dict
Noise components
crs: bool/None
Cosmic rays
ffnoise: bool/None
Flat-field noise
effects: dict
Effects that can affect the noise or detector response or both
saturation: bool/None
Pixel saturation
Instrument Configuration
configuration: dict
This is the configuration for the instrument and detector, using the following keys:
instrument: dict
The instrument configuration parameters
instrument: string
for JWST:
* miri
* nircam
* nirspec
* niriss
for Roman:
* wfi
mode: string
valid modes:
for JWST:
* imaging
* imaging_ts
* sw_imaging
* lw_imaging
* msa (called mos in the webapp)
* mos_ver
* mos_conf
* mrs
* mrs_ts
* soss
* ifu
* ifu_ver
* wfss
* ssgrism (called lw_tsgrism in the webapp)
* sw_ts
* lw_ts
* wfgrism
* lrsslit
* lrsslitless
* fixed_slit
* bots
* ami
* coronagraphy
* target_acq
for Roman:
* imaging
* spectroscopy
filter: string
(e.g. f070w)
disperser: string
(e.g. g235h)
aperture: string
(e.g. a200s1)
shutter_location: string (only valid for NIRSpec MSA, MOS_CONF, and MOS_VER modes)
Identifier string for slitlet position to use for MSA calculation
slitlet_shape: string or list (only valid for NIRSpec MSA, MOS_CONF, and MOS_VER modes)
A string denoting a slitlet grid shape.
Can also be a list of 2-element offsets describing set of shutters to be open. Offsets are from scene center
in units of shutter spacing.
(e.g. slitlet_shape = [[0,-2],[0,0],[0,2]])
detector: dict
Exposure configuration parameters.
subarray: string
full, 64x64, etc.; Instrument-dependent
readout_pattern: string
Instrument-dependent
ngroup: int
Number of groups
nint: int
Number of integrations
nexp: int
Number of exposures
dynamic_scene: boolean
Toggle whether to allow the size of the scene to expand dynamically to include all configured sources.
scene_size: float
Default size of the scene in arcseconds. Used if dynamic_scene is True.
max_scene_size: float
Maximum allowable scene_size in arcseconds.
Extraction Strategy
strategy: dict
Configuration parameters for observing strategy.
method: string
Instrument and mode dependent. Currently supported methods are:
* imagingapphot
* specapphot
* coronagraphy
* ifuapphot
* ifunodinscene
* ifunodoffscene
* msafullapphot
* msaapphot
* msashutterapphot
* soss
* taphot
* tacentroid
Planned methods that are not yet implemented include:
imagingoptphot, specoptphot, speclinephot
In most cases, only one extraction strategy is valid for a given mode.
units: string (default: "arcsec")
Angular units used by the strategy
target_source: string
Sent by the UI client, but currently unused by the engine
target_type: string
Sent by the UI client, but currently unused by the engine
The rest of the parameters will be method dependent. The parameters required
for **imagingapphot**, **specapphot**, **msaapphot**, and **ifuapphot** are:
background_subtraction: boolean
Toggle whether sky annulus background subtraction (True) or ideal noiseless background subtraction (False) is performed.
aperture_size: float
Size of extraction aperture in "units"
sky_annulus: list-like of format (float, float)
The inner and outer radii in "units" of sky region used for background subtraction
target_xy: list-like of format (float, float)
X and Y center position of the aperture and sky annulus
The parameters required for all spectroscopic modes (**specapphot**, **msafullapphot**, **soss**, **ifuapphot**,
**ifunodinscene**, **ifunodoffscene**) are:
reference_wavelength: float
Wavelength at which the scalar parameters should be extracted from.
The values extracted will be from the wavelength grid value (measured at center of a
pixel) closest to this requested value.
The parameters required for **ifunodinscene** and **ifunodoffscene** are:
aperture_size: float
Size of extraction aperture in "units"
target_xy: list-like of format (float, float)
X and Y center position of the aperture and sky annulus.
dithers: list of dicts with format {'x': <float>, 'y': <float>}
Dither positions given in "units" from center of the Scene.
The parameters required for **msafullapphot**, **msaapphot**, and **msashutterapphot** are:
shutter_offset: list-like of format (float, float)
Offset of shutter pattern from center of scene in "units"
dithers: list of dicts
Dither positions and MSA shutter configuration with the following format:
x: float
X position of the central shutter
y: float
Y position of the central shutter
on_source: list of bool
List of booleans denoting whether a shutter should be treated as source or sky.
Must specify the same number of shutter positions as the slitlet_shape.
(not necessary for msaapphot)
The parameters required for **soss** are:
background_subtraction: boolean
Toggle whether sky annulus background subtraction (True) or ideal noiseless background subtraction (False) is performed.
order: int
Specify which order to extract. Can be 1 or 2 with support for 3 forthcoming.
The parameters required for **coronagraphy** are:
target_xy: two-element list-like (float, float)
Position of extraction aperture
aperture_size: float
Radius of extraction aperture in 'units'
sky_annulus: two-element list-like (float, float)
Inner and outer radii of sky background estimation region in 'units'
contrast_azimuth: float
Azimuth (west of north) at which to calculate contrast curve
calc_type: string
Set to "contrast", identifies that this mode requires a contrast calculation.
pointing_error: two-element list-like (float, float)
Amount to shift occulted source to emulate imperfect pointing
delta_opd: float
Change in system OPD
scene_rotation: float, degrees
Rotation angle to apply to scene
psf_subtraction: string
Can be set to "optimal" (for autoscaling subtraction), "no_autoscale" (for subtraction without autoscaling),
"target_only" (for the science scene only and no subtraction), or "psf_only" (for the PSF subtraction source
only, and no subtraction)
psf_subtraction_source: Complete source dict in engine API format (see above)
Definition of source to use for PSF subtraction. This must be set here rather than as a source in the scene.
Position parameters must be specified, though they are ignored. Use psf_subtraction_xy to specify the
location of the psf subtraction source relative to the scene.
psf_subtraction_xy: two-element list-like (float, float)
Offset to apply to psf_subtraction_source, in 'units'
unocculted_xy: two-element list-like (float, float)
Offset to apply to source to measure contrast between occulted and unocculted observation, in 'units'
The parameters required for **taphot** are:
target_xy: list-like of format (float, float)
X and Y center position of the aperture and sky annulus.
background_subtraction: boolean
Choose to use background subtraction or not
The parameters required for **tacentroid** are:
target_xy: list-like of format (float, float)
X and Y center position of the aperture and sky annulus.
background_subtraction: boolean
Choose to use background subtraction or not
axis: string
Direction the centroid is calculated, "x" or "y"
The parameters required for the planned methods will be defined as the methods
are implemented.
Other
fake_exception: list of strings
If present, this list is searched for control terms that cause
perform_calculation to raise exceptions for testing purposes.
Currently recognized strings are:
'pandeia':
raise PandeiaException
'exception':
raise Exception
Other strings may be added later to add exceptions or modify
the details of the exception objects raised.