pynrc 2.0.1
JWST NIRCam ETC and Simulator
License: MIT license
Keywords: jwst nircam etc simulator

========
Overview
========

A JWST NIRCam ETC and Simulator
===============================

.. image:: https://img.shields.io/pypi/v/pynrc.svg
        :target: https://pypi.python.org/pypi/pynrc
        :alt: Badge showing current released PyPI version
        
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5829553.svg
        :target: https://doi.org/10.5281/zenodo.5829553
        :alt: Zenodo DOI
   
.. image:: https://readthedocs.org/projects/pynrc/badge/?version=latest
        :target: https://pynrc.readthedocs.io/en/latest/?badge=latest
        :alt: Documentation Status

*Authors:* `Jarron Leisenring <https://github.com/JarronL>`_ 
(U. of Arizona, Steward Observatory)

*Contributors:* `Everett Schlawin <https://github.com/eas342>`_, 
`Jonathan Fraine <https://github.com/exowanderer>`_, 
`Jonathan Aguilar <https://github.com/aggle>`_

pyNRC is a set of Python-based tools for planning observations with JWST NIRCam, such as an ETC, a simple slope image simulator, and an enhanced data simulator compatible with the JWST pipeline.

While special attention has been placed on NIRCam coronagraphic modes, this package also works for a variety of NIRCam observing modes including:

- direct imaging 
- coronagraphic imaging
- weak lens imaging
- slitless grism spectroscopy
- DHS observations (TBI)

All PSFs are generated by `STPSF <https://stpsf.readthedocs.io>`_ as implemented by the `WebbPSF Extensions <https://github.com/JarronL/webbpsf_ext>`_ package to reproduce realistic JWST images and spectra.

Documentation can be found at https://pynrc.readthedocs.io.

Similar to some of its dependencies, pyNRC requires input data files in order to generate simulations. Due to the size of these files, they are not included with this source distribution. Please see the documentation for instructions on how to to download the required data files.

.. warning:: 

  pyNRC enables more modes than are officially allowed by the Observatory, (ie., filter + coronagraphic combinations, subarray sizes, etc.). Just because you can do something with pyNRC does not mean it will be supported in flight. Check out `JDocs`_ for more information.


.. _JDocs: https://jwst-docs.stsci.edu/jwst-near-infrared-camera/nircam-observing-modes


Simulating PSFs
===============

Simulating PSFs with STPSF can become computationally expensive if generating new ones on the fly, especially considering JWST PSFs vary with respect to wavelength, field position, and time-dependent wavefront error drift. In an effort to speed up this process, pyNRC uses STPSF to generate a series of monochromatic PSF simulations, then produces polynomial fits to each oversampled pixel. Storing the coefficients rather than a library of PSFS allows for quick creation (via matrix multiplication) of PSF images for an arbitrary number of wavelengths (subject to hardware memory limitations, of course). The applications range from quickly creating PSFs for many different stellar types over wide bandpasses to generating a large number of monochromatic PSFs for spectral dispersion.

In addition, each science instrument PSF is dependent on the detector position due to field-dependent wavefront errors. Such changes are tracked in STPSF, but it becomes burdensome to generate new PSFs from scratch at each location, especially for large starfields. Instead, these changes can be stored by the fitting the residuals of the PSF coefficients across an instrument's field of view, then interpolating for an arbitrary location. A similar scheme can be achieved for coronagraphic occulters, where the PSF changes as the source position moves with respect to the mask.

JWST's thermal evolution (e.g., changing the angle of the sunshield after slewing to a new target) causes small but significant distortions to the telescope backplane. STPSF has tools to modify OPDs, but high-fidelity simulations take time to calculate. Since the change to the PSF coefficients varies smoothly with respect to WFE drift components, it's simple to parameterize the coefficient residuals in a fashion similar to the field-dependence.


Revision History
================

v2.0.0 (Mar 14, 2025)
----------------------

 - Switch over from WebbPSF to STPSF.

v1.3.2 (Oct 7, 2024)
----------------------

 - Improved handling of LWBAR in ``nrc_hci`` and ``obs_hci`` classes. Specifically fixed double counting of PSF offsets along the bar.

v1.3.1 (Sept 19, 2024)
----------------------

 - Fix index transformations between image and oversampled equivalent

v1.3.0 (Sept 19, 2024)
----------------------

 - Bump to version 1.3.0 to attempt to fix PyPI upload issue

v1.2.2 (Sept 19, 2024)
----------------------

 - Bug fix in charge migration to check to break out if no saturated pixels
 - Correctly crop stellar PSF in ``obs_hci`` class while generating slope image

v1.2.1 (May 24, 2024)
---------------------

 - Bug fix for poppy requirement version. (should have been >1.1.0 rather than >1.2.0)

v1.2.0 (May 13, 2024)
---------------------

 - Bring up to date with WebbPSF v1.2.0 and webbpsf_ext v1.2.0
 - Add analysis tools for PCA and NMF PSF subtraction
 - Add a number of simulation features to match flight performance

v1.0.4 (Dec 28, 2021)
---------------------

 - check if ``im_star`` is int or float if not None
 - set ``nexposures = 1`` for level1b using ``NIRCam()`` class function
 - deprecate nghxrg.py
 - add tutorial ipynb files
 - update api docs auto generation
 - use ``webbpsf_ext`` v1.0.4

v1.0.3 (Dec 23, 2021)
---------------------

- Minor updates to seamlessly generate new releases on PyPI and new docs on readthedocs

v1.0.1 (Dec 14, 2021)
---------------------

- Default OPD JWST_OTE_OPD_RevAA_prelaunch_predicted.fits

v1.0.0 (Nov 22, 2021)
---------------------

- Updates to work with WebbPSF v1 release candidate
- Move PSF generation to new ``webbpsf_ext`` package (https://github.com/JarronL/webbpsf_ext)
- Create DMS-like level1b FITS files using pipeline data models for imaging and coronagraphy
- PSF coefficients now use Legendre polynomials by default
- Create calibration files for each SCA (darks, IPC, noise, flats, linearity, etc)
- Background roll-off at grism edges
- SIAF-aware locations

v0.9.0beta (no release)
-----------------------

- Updates to work with WebbPSF 0.9.0.
- Start working on commissioning and DMS-like data
- Add more advanced time-dependent detector effects
- BEX model isochrones for low-mass companions from Linder et al (2019)
- There was a pandemic...

v0.8.0beta (no release)
-----------------------

- Updates to work with WebbPSF 0.8.0.
- Phasing out support for Python 2
- Add info on saturation limits in terms of surface brightness 
- Include option to create grism 2nd order
- Detector pixel timing bugs
- Field-dependent WFE extrapolated beyond FoV for better sampling diversity
- Included field-dependent WFE for coronagraphy
- Added wavelength dispersion of LW coronagraphic PSF

v0.7.0 (Jun 2018)
-----------------

- Did not make it out of development before WebbPSF 0.8.0 release.
- Works with WebbPSF 0.7.0.

  - Field-dependent WFE
  - Image plane distortions

- Implemented ``jwst_backgrounds`` (not required)


v0.6.5 (Mar 2018)
-----------------

- Fixed a critical bug where the off-axis PSF size was incorrect
  when performing WFE drift calculations.

v0.6.4 (Mar 2018)
-----------------

- Off-axis PSFs now get drifted in the same way as their on-axis
  counterparts.
- Created an intermediate ``nrc_hci`` class to enable offsets of WFE drifted PSFs.


v0.6.3 (Mar 2018)
-----------------

- First PyPI release.
- Effectively the same as 0.6.2, but better documentation of packaging and distributing.


v0.6.2 (Mar 2018)
-----------------

- Implemented coronagraphic wedges, including arbitrary offsets along bar
- Renamed ``obs_coronagraphy`` to ``~pynrc.obs_hci``

  - Faster modeling of off-axis PSFs
  - Include coronagraphic features (e.g.: ND squares) in slope images
  - Roll subtracted images include option to use Roll1-Roll2
  - Fixed bug that was slowing down PSF convolution of disks

- Can now generate docs directly from Jupyter notebooks using nbsphinx extension
- Coronagraphic tutorials for docs
- Create the ``source_spectrum`` class to fit spectra to observed photometry.

v0.6.0 (Dec 2017)
-----------------

- Support for Python 3 (mostly ``map``, ``dict``, and index fixes)
- Updated code comments for ``sphinx`` and ``readthedocs`` documentation
- Create ``setup.py`` install file
- Modify grism PSF shapes due to aperture shape
- Detector frames times based on ASIC microcode build 10
- Headers for DMS data
- Three major changes to PSF coefficients

  - coefficients based on module (SWA, SWB, LWA, LWB), rather than filter
  - WFE drift coefficient relations
  - field-dependent coefficient relation

v0.5.0 (Feb 2017)
-----------------

- Initial GitHub release
- Match version numbering to ``WebbPSF`` equivalent
- ND Acquisition mode
- Ramp settings optimizer
- Can now simulate ramps with detector noise
- Query Euclid's IPAC server for time/position-dependent Zodiacal emission
- Added example Jupyter notebooks

v0.1.2 (Jan 2017)
-----------------
- Observations subclass for coronagraphs and direct imaging

v0.1.1 (Sep 2016)
-----------------
- Add support for LW slitless grism
- Add support for extended sources

v0.1.0 (Aug 2016)
-----------------
- Rewrite of ``SimNRC`` and rename ``pynrc``
- Object oriented ``multiaccum``, ``DetectorOps``, and ``NIRCam`` classes
- Create separate detector instances in ``NIRCam`` class