Overview

The Pandeia Engine is a Python module (compatible with Python 3.9 and later) that functions as the computational engine of the JWST ETC and Roman WFI ETC. It can be imported and run as a standalone module.

API Compatibility

The Pandeia Engine API may change at any time. The following information and examples are for Pandeia Engine 3.x, 4.x, and 2024.x only, and are not guaranteed to be accurate or functional for previous or future releases. Updates (and information about planned pending API changes) can be found on the Pandeia Engine News page.


Engine inputs take the form of a hierarchical Python dictionary describing, in different sections, the instrument setup, the scene with definitions of all sources within it, and the flux extraction strategy.

Such input dictionaries are available in the JWST Webapp or Roman Webapp download files (as a JSON-formatted file named input.json, suitable for reading in with the built-in Python 'json' module). Alternatively, default versions of calculations can be created with the function build_default_calc() and then edited.

API Checking

The Pandeia Engine expects a specific hierarchical format, but does not generally validate the format. It may silently replace missing or misplaced information with defaults, and it will generally not warn about unexpected keywords. By design, the Engine does not validate inputs: setups that may not be permitted in the Webapp or in APT may compute, but we do not and cannot guarantee the validity of the results.

Create a default calculation

Create a default calculation
from pandeia.engine import calc_utils
from pandeia.engine import perform_calculation

calculation = calc_utils.build_default_calc("jwst","nircam","sw_imaging")
results = perform_calculation.perform_calculation(calculation)

The command above produces the NIRCam SW Imaging calculation below, and then runs it through the engine. "results" will be a dictionary, defined in the Output API documentation

Load a calculation from the JWST Webapp or Roman Webapp

Calculation downloads from the JWST Webapp or Roman Webapp contain the engine inputs in a JSON-formatted text file called input.json.

Load a calculation from a file
import json
from pandeia.engine import perform_calculation

with open("input.json") as infile:
    calculation = json.load(infile)

results = perform_calculation.perform_calculation(calculation)

The command above reads a file called "input.json" in the current directory, loads it into a Python dictionary, and runs it through the engine. "results" will be a dictionary, defined in the Output API documentation. Results should match the webapp.


Full API


The full API documentation, with all possible options and combinations for any instrument, can be found in engine_input_api.rst

Examples

The following calculation defines a JWST NIRCam observation in SW Imaging mode using the full subarray and rapid readout pattern and f070w filter, for a flat-spectrum (in fnu) point source normalized to 0.001 mJy, intended to be observed with a 0.2" aperture. Note that it specifies a background precomputed for the JWST minzodi benchmark position; actual user-configured backgrounds are available in the JWST Webapp (and can be downloaded from there)

(click here to download as a JSON file: sw_f070w_rapid_full.jeng)

JWST NIRCam SW Imaging
{
    "background": "minzodi",
    "background_level": "benchmark",
    "calculation": {
        "effects": {
            "saturation": null
        },
        "noise": {
            "crs": null,
            "dark": null,
            "excess": null,
            "ffnoise": null,
            "readnoise": null,
            "scatter": null
        }
    },
    "configuration": {
        "detector": {
            "nexp": 1,
            "ngroup": 10,
            "nint": 1,
            "readout_pattern": "rapid",
            "subarray": "full"
        },
        "instrument": {
            "aperture": "sw",
            "disperser": null,
            "filter": "f070w",
            "instrument": "nircam",
            "mode": "sw_imaging"
        }
    },
    "scene": [
        {
            "position": {
                "orientation": 0.0,
                "x_offset": 0.0,
                "y_offset": 0.0
            },
            "shape": {
                "geometry": "point"
            },
            "spectrum": {
                "extinction_first": true, 
                "extinction": {
                    "bandpass": "j",
                    "law": "mw_rv_31",
                    "unit": "mag",
                    "value": 0.0
                },
                "lines": [],
                "name": "generic source",
                "normalization": {
                    "norm_flux": 0.001,
                    "norm_fluxunit": "mjy",
                    "norm_wave": 2.0,
                    "norm_waveunit": "microns",
                    "type": "at_lambda"
                },
                "redshift": 0.0,
                "sed": {
                    "sed_type": "flat",
                    "unit": "fnu",
                    "z": 0.0
                }
            }
        }
    ],
    "strategy": {
        "aperture_size": 0.1,
        "background_subtraction": true,
        "display_string": "Imaging Aperture Photometry",
        "is_aperture_ee": false,
        "method": "imagingapphot",
        "sky_annulus": [
            0.22,
            0.4
        ],
        "target_source": "1",
        "target_type": "coords",
        "target_xy": [
            0.0,
            0.0
        ],
        "units": "arcsec"
    }
}

The following dictionary defines a Roman WFI Imaging observation with the F087 filter, "full" subarray, c2a_img_hlwas ma table, and the maximum number of resultants; for a 0.001 mJy flat-spectrum point source (in fnu) intended to be observed with a 0.2" aperture.

(click here to download as a JSON file: imaging_f087_c2a_img_hlwas_full.jeng

Roman WFI Imaging
{
    "background": "minzodi",
    "background_level": "benchmark",
    "calculation": {
        "effects": {
            "saturation": null
        },
        "noise": {
            "crs": null,
            "dark": null,
            "excess": null,
            "ffnoise": null,
            "readnoise": null,
            "scatter": null
        }
    },
    "configuration": {
        "detector": {
            "ma_table_name": "c2a_img_hlwas",
            "nexp": 1,
            "nresultants": -1,
            "subarray": "full"
        },
        "instrument": {
            "aperture": "imaging",
            "disperser": null,
            "filter": "f087",
            "instrument": "wfi",
            "mode": "imaging"
        }
    },
    "scene": [
        {
            "position": {
                "orientation": 0.0,
                "x_offset": 0.0,
                "y_offset": 0.0
            },
            "shape": {
                "geometry": "point"
            },
            "spectrum": {
                "extinction": {
                    "bandpass": "j",
                    "law": "mw_rv_31",
                    "unit": "mag",
                    "value": 0.0
                },
                "extinction_first": true,
                "lines": [],
                "name": "generic source",
                "normalization": {
                    "norm_flux": 0.001,
                    "norm_fluxunit": "mjy",
                    "norm_wave": 2.0,
                    "norm_waveunit": "microns",
                    "type": "at_lambda"
                },
                "redshift": 0.0,
                "sed": {
                    "sed_type": "flat",
                    "unit": "fnu",
                    "z": 0.0
                }
            }
        }
    ],
    "strategy": {
        "aperture_size": 0.2,
        "background_subtraction": true,
        "display_string": "Imaging Aperture Photometry",
        "is_aperture_ee": false,
        "method": "imagingapphot",
        "sky_annulus": [
            0.4,
            0.6
        ],
        "target_source": "1",
        "target_type": "coords",
        "target_xy": [
            0.0,
            0.0
        ],
        "units": "arcsec"
    }
}
  • No labels