Merge pull request #369 from mperrin/docs-update

Docs update: add JWST SI reference figures; remove redundant install docs
spacetelescope · Jun 23, 2020 · cc70cb8 · cc70cb8
2 parents 78ccf88 + df56a99
commit cc70cb8
Show file tree

Hide file tree

Showing 13 changed files with 95 additions and 23 deletions.
diff --git a/docs/intro.rst b/docs/intro.rst
@@ -104,17 +104,7 @@ See :ref:`Optimizing Performance and Parallelization <performance_and_paralleliz
 Getting WebbPSF
 ---------------
 
-The WebbPSF software is installable through pip, but it depends on data files distributed through STScI. Since there is more than one way to install scientific Python software, the possibilities are covered in :ref:`installation`.
-
-The `AstroConda <http://astroconda.readthedocs.io/en/latest/>`_ distribution includes WebbPSF and its associated data files. If you installed the packages into an environment named ``astroconda``, the command to upgrade all STScI software (including WebbPSF) to the latest version would be ``conda update --name astroconda stsci``.
-
-For those who prefer to use pip (and have NumPy, SciPy, and matplotlib already installed) the command is::
-
-   $ pip install -U webbpsf
-
-This command installs (or upgrades) WebbPSF to the latest version on `PyPI <https://pypi.python.org/>`_. Before WebbPSF will run, you must :ref:`download the WebbPSF data files <data_install>` and set the ``WEBBPSF_DATA`` environment variable to point to the place you extracted them. You may also want to :ref:`install Pysynphot <pysynphot_install>`, an optional dependency, to improve PSF fidelity.
-
-For detailed installation instructions, refer to :ref:`installation`. (This document also explains how to install optional dependencies, install supporting data files, :ref:`install from GitHub source <install_dev_version>`, etc.)
+See :ref:`installation`.
 
 .. _quickstart:
 

diff --git a/docs/jwst.rst b/docs/jwst.rst
@@ -234,32 +234,68 @@ channels. When enabled, these are added to the final pupil of the optical
 train, i.e. after the coronagraphic image planes. For field-points outside of
 the measurement bounds, WebbPSF performs an extrapolation routine.
 
-The coronagraph field points are far off axis, and this comes with significant WFE 
+.. image:: ./jwst_figures/opds_combined_for_NIRCam_A_SW.png
+   :scale: 45 %
+   :align: center
+   :alt: NIRCam A SW WFE
+
+.. image:: ./jwst_figures/opds_combined_for_NIRCam_A_SW.png
+   :scale: 45 %
+   :align: center
+   :alt: NIRCam B SW WFE
+
+.. image:: ./jwst_figures/opds_combined_for_NIRCam_A_LW.png
+   :scale: 45 %
+   :align: center
+   :alt: NIRCam A LW WFE
+
+.. figure:: ./jwst_figures/opds_combined_for_NIRCam_B_LW.png
+   :scale: 45 %
+   :align: center
+   :alt: NIRCam B LW WFE
+
+   Instrument WFE models for NIRCam. Click for full size.
+
+
+The coronagraph field points are far off axis, and this comes with significant WFE
 added compared to the inner portion of the NIRCam field of view. While SI WFE for
-imaging mode were measured directly from the instrument during ISIM CV3, the 
+imaging mode were measured directly from the instrument during ISIM CV3, the
 coronagraphic WFE maps were built based on the NIRCam Zemax optical model.
 This model was first validated in imaging mode, and then the appropriate optical
 elements were inserted to produce the coronagraphic configuration.
-In this case, both modules were assumed have the exact same (albeit, mirrored) 
-field-dependent WFE maps.
+In this case, both modules were assumed have the exact same (albeit, mirrored)
+field-dependent WFE maps. Note, this substantial WFE occurs physically *after*
+the coronagraphic focal plane spots in NIRCam, and is modeled as such in WebbPSF.
+
 
 Wavelength-Dependent Focus Variations
 ---------------------------------------
 
 NIRCam's wavelength-dependent defocus was measured during ISIM CV2 at a given field point
 (See JWST-RPT-029985 by Randal Telfer). Overall, the measurements are consistent with
-predictions from the nominal optical model. The departure of the data from the 
+predictions from the nominal optical model. The departure of the data from the
 model curve has been determined to be from residual power in individual filters.
-In particular, the F323N filter has a significant extra defocus; WebbPSF includes 
+In particular, the F323N filter has a significant extra defocus; WebbPSF includes
 this measured defocus if the selected filter is F323N.
 
-All SI WFE maps were derived from measurements with the F212N and F323N filters. 
+
+.. figure:: ./jwst_figures/nircam_focus_model.png
+   :scale: 45 %
+   :align: center
+   :alt: NIRCam Defocus Model
+
+   Instrument focus models for NIRCam. Click for full size.
+
+
+
+All SI WFE maps were derived from measurements with the F212N and F323N filters.
 WebbPSF utilizes polynomial fits to the nominal focus model to derive focus offset values
 relative to these narrowband filters for a given wavelength. The derived delta focus
-is then translated to a Zernike focus image, which is subsequently applied to the 
+is then translated to a Zernike focus image, which is subsequently applied to the
 instrument OPD map.
 
 
+
 NIRSpec
 =======
 
@@ -294,6 +330,16 @@ SI internal WFE measurements are from ISIM CV3 testing (See JWST-RPT-032131 by D
 
 The ISIM CV3 data on their own do not indicate how the sources of WFE are distributed within the NIRSpec optical train. For simulation purposes here, the SI WFE measurements are allocated as 1/3 in the foreoptics, prior to the MSA image plane, and 2/3 in the spectrograph optics, after the MSA image plane. This follows a recommendation from Maurice Te Plate of the NIRSpec team, based on metrology and testing of the NIRSpec flight model optics.
 
+
+.. figure:: ./jwst_figures/opds_combined_for_NIRSpec.png
+   :scale: 45 %
+   :align: center
+   :alt: NIRSpec WFE
+
+
+   Instrument WFE models for NIRSpec. Click for full size.
+
+
 NIRISS
 ======
 
@@ -353,6 +399,13 @@ SI WFE
 
 SI internal WFE measurements are from ISIM CV3 testing (See JWST-RPT-032131 by David Aronstein et al.).
 
+.. figure:: ./jwst_figures/opds_combined_for_NIRISS.png
+   :scale: 45 %
+   :align: center
+   :alt: NIRISS WFE
+
+   Instrument WFE models for NIRISS. Click for full size.
+
 
 MIRI
 ====
@@ -397,6 +450,14 @@ SI internal WFE measurements are from ISIM CV3 testing (See JWST-RPT-032131 by D
 The SI internal WFE measurements, when enabled, are added to the final pupil of the optical
 train, i.e. after the coronagraphic image planes.
 
+.. figure:: ./jwst_figures/opds_combined_for_MIRI.png
+   :scale: 45 %
+   :align: center
+   :alt: MIRI WFE
+
+   Instrument WFE models for MIRI. Click for full size.
+
+
 
 Minor Field-Dependent Pupil Vignetting
 ----------------------------------------
@@ -420,3 +481,17 @@ SI WFE
 ------
 
 SI internal WFE measurements are from ISIM CV3 testing (See JWST-RPT-032131 by David Aronstein et al.).
+
+
+.. figure:: ./jwst_figures/opds_combined_for_FGS_1.png
+   :scale: 45 %
+   :align: center
+   :alt: FGS 1 WFE
+
+.. figure:: ./jwst_figures/opds_combined_for_FGS_2.png
+   :scale: 45 %
+   :align: center
+   :alt: FGS 2 WFE
+
+
+   Instrument WFE models for FGS. Click for full size.
diff --git a/docs/jwst_figures/nircam_focus_model.png b/docs/jwst_figures/nircam_focus_model.png
diff --git a/docs/jwst_figures/opds_combined_for_FGS_1.png b/docs/jwst_figures/opds_combined_for_FGS_1.png
diff --git a/docs/jwst_figures/opds_combined_for_FGS_2.png b/docs/jwst_figures/opds_combined_for_FGS_2.png
diff --git a/docs/jwst_figures/opds_combined_for_MIRI.png b/docs/jwst_figures/opds_combined_for_MIRI.png
diff --git a/docs/jwst_figures/opds_combined_for_NIRCam_A_LW.png b/docs/jwst_figures/opds_combined_for_NIRCam_A_LW.png
diff --git a/docs/jwst_figures/opds_combined_for_NIRCam_A_SW.png b/docs/jwst_figures/opds_combined_for_NIRCam_A_SW.png
diff --git a/docs/jwst_figures/opds_combined_for_NIRCam_B_LW.png b/docs/jwst_figures/opds_combined_for_NIRCam_B_LW.png
diff --git a/docs/jwst_figures/opds_combined_for_NIRCam_B_SW.png b/docs/jwst_figures/opds_combined_for_NIRCam_B_SW.png
diff --git a/docs/jwst_figures/opds_combined_for_NIRISS.png b/docs/jwst_figures/opds_combined_for_NIRISS.png
diff --git a/docs/jwst_figures/opds_combined_for_NIRSpec.png b/docs/jwst_figures/opds_combined_for_NIRSpec.png
diff --git a/docs/relnotes.rst b/docs/relnotes.rst
@@ -24,7 +24,6 @@ Road Map for Future Releases
 --------------------------------
 * Continued validation and updates as needed based on further analyses of instrument and telescope hardware test data.
 * Support for the NIRSpec and MIRI IFUs may be added in a future release; level of detail is still TBD.
-* Possibly: separate handling of pre- and post- coronagraphic WFE in instruments, or pre- and post- NIRSpec MSA plane WFE; pending receipt of test data and models from the instrument teams.
 
 .. _whatsnew:
 
@@ -35,14 +34,22 @@ Version 0.9.1
 =============
 *2020 June 22*
 
-This minor release resolves several bugs and occasional installation issues and updates behind-the-scenes package infrastructure for consistency with current astropy and numpy releases. There are small improvements to a few aspects of JWST models as detailed below (in particular for wavelength dispersion in NIRCam LW coronagraphy and in tools for modeling time-dependent WFE) but the vast majority of JWST PSF calculations are not changed in any way. There are no changes in reference data, so the WebbPSF reference data files for 0.9.0 should continue to be used with this release.
+This minor release resolves several bugs and occasional installation issues and updates behind-the-scenes package infrastructure for consistency with current astropy and numpy releases. There are small improvements to a few aspects of JWST models as detailed below (in particular for wavelength dispersion in NIRCam LW coronagraphy and in tools for modeling time-dependent WFE) but the vast majority of JWST PSF calculations are not changed in any way.
+
+There are no changes in reference data, so the WebbPSF reference data files for 0.9.0 should continue to be used with this release.
+
+.. admonition:: Python version support: Python 3.6+ required
+
+        This version drops support for Python 3.5. The minimum supported version of Python is now 3.6.
+
 
 **JWST Improvements**
 
 - *Apply wavelength dependent offsets for NIRCam coronagraphic PSFs* due to the dispersion from the optical wedge in the coronagraphic pupil masks. This primarily affects the LW channel with approximately 0.015 mm/um dispersion. The SW channel is almost a factor of 10 smaller and mostly negligible, but has been included for completeness. [:pr:`347`, :user:`JarronL`]
 - *Improved models for OTE wavefront variations over time* by adding utility functions for decomposing WFE models into piston, tip, tilt motions in the JWST control coordinate system, adding a model for frill-induced WFE drift, adding a model for IEC-heater-induced WFE drift, and adding an option to adjust amplitude of OTE backplane thermal drift model for B.O.L. vs E.O.L. expected amplitudes. [:pr:`340`, :user:`mperrin`]
-- *Add new ``aperturename`` attribute* for JWST instruments which returns the SIAF aperture name used for transforming between the detector position and instrument field of view on the sky. [:pr:`360`, :user:`mperrin`]. Releatedly, improves setting of detector geometry for NIRCam to automatically set the SIAF aperture name based on detector, filter, and coronagraph image mask and pupil mask settings. This can be turned off by setting ``auto_apname=False``. [:pr:`351`, :user:`JarronL`]
-- Add model for image jitter with JWST in coarse point mode under two different assumptions about LOS stability: ``'PCS=Coarse'`` and ``'PCS=Coarse_Like_ITM'``. This is relevant only for commissioning simulations. [:pr:`345`, :pr:`346`, :user:`mperrin`]
+- *Add new* ``aperturename`` *attribute* for JWST instruments which returns the SIAF aperture name used for transforming between the detector position and instrument field of view on the sky. [:pr:`360`, :user:`mperrin`]. Releatedly, improves setting of detector geometry for NIRCam to automatically set the SIAF aperture name based on detector, filter, and coronagraph image mask and pupil mask settings. This can be turned off by setting ``auto_apname=False``. [:pr:`351`, :user:`JarronL`]
+- Add model for image jitter with JWST in coarse point mode under two different assumptions about LOS stability. This is relevant only for commissioning simulations. [:pr:`345`, :pr:`346`, :user:`mperrin`]
+- Documentation updates, in particular adding :ref:`figures of JWST instrument internal wavefront error models <jwst_instruments>`. [:pr:`369`, :user:`mperrin`]
 
 **General bug fixes and small changes:**