Merge pull request #828 from mperrin/more_docs

Documentation additions for 1.3

README.rst

@@ -24,13 +24,14 @@ WebbPSF: Simulated Point Spread Functions for the James Webb and Nancy Grace Rom
 WebbPSF produces simulated PSFs for the James Webb Space Telescope, NASA's
 flagship infrared space telescope. WebbPSF can simulate images for any of the
 four science instruments plus the fine guidance sensor, including both direct
-imaging and coronagraphic modes.
+imaging, coronagraphic, and spectroscopic modes.
 
 WebbPSF also supports simulating PSFs for the upcoming Nancy Grace Roman Space Telescope (formerly WFIRST),
 including its Wide Field Instrument and a preliminary version of the Coronagraph Instrument.
 
-Developed by Marshall Perrin, Joseph Long, Neil Zimmerman, Robel Geda, Shannon
-Osborne, Marcio Melendez Hernandez, Lauren Chambers, Keira Brooks, Charles-Phillipe Lajoie, Jarron Leisenring, Alden Jurling, and collaborators, 2010-2020.
+Developed by Marshall Perrin, Joseph Long, Shannon Osborne, Robel Geda, Bradley Sappington, Marcio Meléndez, 
+Charles-Phillipe Lajoie, Jarron Leisenring, Neil Zimmerman, Keira Brooks, 
+Justin Otor, Trey Kulp, Lauren Chambers, Alden Jurling, and collaborators, 2010-2024.
 
 Documentation can be found online at https://webbpsf.readthedocs.io
 

docs/conf.py

@@ -102,7 +102,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/index.rst

@@ -43,39 +43,48 @@ Contents
 
 .. toctree::
    :maxdepth: 1
+   :caption: Getting Started
 
    intro.rst
    installation.rst
    relnotes.rst
    usage.rst
+   psf_grids.rst
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Modeling JWST PSFs
+
    jwst.rst
+   more_examples.rst
    jwst_measured_opds.ipynb
    jwst_detector_effects.ipynb
    jwst_matching_psfs_to_data.ipynb
    jwst_optical_budgets.ipynb
+   jwst_psf_subtraction.ipynb
    jwst_wavefront_deltas.ipynb
-   roman.rst
-   psf_grids.rst
-   more_examples.rst
-   poppy.rst
+   less_common_usage.rst
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Modeling Roman PSFs
 
-Advanced Usage
-^^^^^^^^^^^^^^
+   roman.rst
 
 .. toctree::
    :maxdepth: 1
+   :caption: Package Documentation
 
    api_reference.rst
    help.rst
    performance.rst
    sampling.rst
    fft_optimization.rst
-
-Appendices and Reference
-^^^^^^^^^^^^^^^^^^^^^^^^
+   poppy.rst
 
 .. toctree::
    :maxdepth: 1
+   :caption: Developer Reference
 
    available_opds.rst
    field_dependence/multifield_documentation.ipynb
@@ -89,7 +98,7 @@ Appendices and Reference
 
     * Perrin et al. 2014, `"Updated point spread function simulations for JWST with WebbPSF" <http://adsabs.harvard.edu/abs/2014SPIE.9143E..3XP>`_,  Proc. SPIE. 9143,
     * Perrin et al. 2012, `"Simulating point spread functions for the James Webb Space Telescope with WebbPSF", <http://adsabs.harvard.edu/abs/2012SPIE.8442E..3DP>`_ Proc SPIE 8842, and
-    * Perrin 2011, :download:`Improved PSF Simulations for JWST: Methods, Algorithms, and Validation <Improved_PSFs_for_Webb.pdf>`, JWST Technical report JWST-STScI-002469.
+    * Perrin 2011, `Improved PSF Simulations for JWST: Methods, Algorithms, and Validation <Improved_PSFs_for_Webb.pdf>`_, JWST Technical report JWST-STScI-002469.
 
     In particular, the 2012 SPIE paper gives a broad overview, the 2014 SPIE paper presents comparisons to instrument cryotest data, and the Technical Report document describes in more detail the relevant optical physics, explains design decisions and motivation for WebbPSF's architecture, and presents extensive validation tests demonstrating consistency between WebbPSF and other PSF simulation packages used throughout the JWST project.
 

docs/intro.rst

@@ -19,6 +19,7 @@ Introduction
 
 
 Conceptually, this simulation code has two layers of abstraction:
+
  * A base package for wavefront propagation through generic optical systems (provided by :py:mod:`POPPY <poppy>`)
  * Models of the JWST and Roman instruments implemented on top of that base system (provided by :py:mod:`WebbPSF <webbpsf>`)
 

docs/jwst_detector_effects.ipynb

@@ -16,9 +16,15 @@
     "\n",
     "These effects come in two flavours:\n",
     " 1.  Interpixel capacitance (IPC, for NIRCam, NIRISS, and MIRI) and Post-pixel coupling (PPC, NIRCam only), via convolution kernels measured from flight and ground-testing data.\n",
-    " 2. Charge diffusion, via a simple ad hoc Gaussian convolution, with parameters tuned to match in-flight empirical PSFs for NIRCam, NIRISS, and MIRI. \n",
-    "\n",
-    "### Detector physics is complicated. \n",
+    " 2. Charge diffusion, via a simple ad hoc Gaussian convolution, with parameters tuned to match in-flight empirical PSFs for NIRCam, NIRISS, and MIRI. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5d801438-5428-40a5-8c2c-906a0865c9e8",
+   "metadata": {},
+   "source": [
+    "## Detector physics is complicated. \n",
     "\n",
     "Please note that these are *simplified* models of extremely complex detector physics and nonlinearity. \n",
     "The true physical behavior is more complex, and includes for instance illumination- and time-dependent variations often referred to as the \"brighter-fatter effect\". See for instance [Plazas et al. 2018](https://iopscience.iop.org/article/10.1088/1538-3873/aab820/meta), [Argyriou et al. 2023](https://ui.adsabs.harvard.edu/abs/2023arXiv230313517A/abstract). Detector physics modeling at that level is outside of the scope of WebbPSF. \n",
@@ -497,7 +503,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.3"
+   "version": "3.11.7"
   }
  },
  "nbformat": 4,

docs/jwst_matching_psfs_to_data.ipynb

@@ -227,7 +227,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.3"
+   "version": "3.11.7"
   }
  },
  "nbformat": 4,

docs/less_common_usage.rst

@@ -0,0 +1,124 @@
+*************************
+Less Common Usage Options
+*************************
+
+This page documents options which exist, but are less frequently likely to be of use.  This section serves as a catch-all for some more esoteric customizations and applications. See also the :ref:`more_examples` page.
+
+
+Adjusting simulated telescope line-of-sight pointing jitter
+------------------------------------------------------------
+
+Imprecisions in telescope pointing can have the effect of smearing out the PSF. WebbPSF models these as a Gaussian convolution. To simulate this with WebbPSF, the option names are ``jitter`` and ``jitter_sigma``.
+
+>>> instrument.options['jitter'] = 'gaussian'   # jitter model name or None
+>>> instrument.options['jitter_sigma'] = 0.009  # in arcsec per axis, default 0.007
+
+
+
+
+Writing out only downsampled images
+-----------------------------------
+
+Perhaps you may want to calculate the PSF using oversampling, but to save disk space you only want to write out the PSF downsampled to detector resolution.
+
+   >>> result =  inst.calc_psf(args, ...)
+   >>> result['DET_SAMP'].writeto(outputfilename)
+
+Or if you really care about writing it as a primary HDU rather than an extension, replace the 2nd line with
+
+   >>> pyfits.PrimaryHDU(data=result['DET_SAMP'].data, header=result['DET_SAMP'].header).writeto(outputfilename)
+
+
+Writing out intermediate images
+-------------------------------
+
+Your calculation may involve intermediate pupil and image planes (in fact, it most likely does). WebbPSF / POPPY allow you to inspect the intermediate pupil and image planes visually with the display keyword argument to :py:meth:`~webbpsf.JWInstrument.calc_psf`. Sometimes, however, you may want to save these arrays to FITS files for analysis. This is done with the ``save_intermediates`` keyword argument to :py:meth:`~webbpsf.JWInstrument.calc_psf`.
+
+The intermediate wavefront planes will be written out to FITS files in the current directory, named in the format ``wavefront_plane_%03d.fits``. You can additionally specify what representation of the wavefront you want saved with the ``save_intermediates_what`` argument to :py:meth:`~webbpsf.JWInstrument.calc_psf`. This can be ``all``, ``parts``, ``amplitude``, ``phase`` or ``complex``, as defined as in :py:meth:`poppy.Wavefront.asFITS`. The default is to write ``all`` (intensity, amplitude, and phase as three 2D slices of a data cube).
+
+If you pass ``return_intermediates=True`` as well, the return value of calc_psf is then ``psf, intermediate_wavefronts_list`` rather than the usual ``psf``.
+
+.. warning::
+
+   The ``save_intermediates`` keyword argument does not work when using parallelized computation, and WebbPSF will fail with an exception if you attempt to pass ``save_intermediates=True`` when running in parallel. The ``return_intermediates`` option has this same restriction.
+
+
+Providing your own OPDs or pupils from some other source
+--------------------------------------------------------
+
+It is straight forward to configure an Instrument object to use a pupil OPD file of your own devising, by setting the ``pupilopd`` attribute of the Instrument object:
+
+        >>> niriss = webbpsf.NIRISS()
+        >>> niriss.pupilopd = "/path/to/your/OPD_file.fits"
+
+If you have a pupil that is an array in memory but not saved on disk, you can pass it in as a fits.HDUList object :
+
+        >>> myOPD = some_function_that_returns_properly_formatted_HDUList(various, function, args...)
+        >>> niriss.pupilopd = myOPD
+
+Likewise, you can set the pupil transmission file in a similar manner by setting the ``pupil`` attribute:
+
+        >>> niriss.pupil = "/path/to/your/OPD_file.fits"
+
+
+Please see the documentation for :py:class:`poppy.FITSOpticalElement` for information on the required formatting of the FITS file.
+In particular, you will need to set the `PUPLSCAL` keyword, and OPD values must be given in units of meters.
+
+
+
+
+Subclassing a JWInstrument to add additional functionality
+----------------------------------------------------------
+
+Perhaps you want to modify the OPD used for a given instrument, for instance to
+add a defocus. You can do this by subclassing one of the existing instrument
+classes to override the :py:meth:`JWInstrument._addAdditionalOptics` function. An :py:class:`OpticalSystem <poppy.OpticalSystem>` is
+basically a list so it's straightforward to just add another optic there. In
+this example it's a lens for defocus but you could just as easily add another
+:py:class:`FITSOpticalElement <poppy.FITSOpticalElement>` instead to read in a disk file.
+
+
+Note, we do this as an example here to show how to modify an instrument class by
+subclassing it, which can let you add arbitrary new functionality.
+There's an easier way to add defocus specifically; see below.
+
+
+    >>> class FGS_with_defocus(webbpsf.FGS):
+    >>>     def __init__(self, *args, **kwargs):
+    >>>         webbpsf.FGS.__init__(self, *args, **kwargs)
+    >>>         # modify the following as needed to get your desired defocus
+    >>>         self.defocus_waves = 0
+    >>>         self.defocus_lambda = 4e-6
+    >>>     def _addAdditionalOptics(self, optsys, *args, **kwargs):
+    >>>         optsys = webbpsf.FGS._addAdditionalOptics(self, optsys, *args, **kwargs)
+    >>>         lens = poppy.ThinLens(
+    >>>             name='FGS Defocus',
+    >>>             nwaves=self.defocus_waves,
+    >>>             reference_wavelength=self.defocus_lambda
+    >>>         )
+    >>>         lens.planetype = poppy.PUPIL  # tell propagation algorithm which this is
+    >>>         optsys.planes.insert(1, lens)
+    >>>         return optsys
+    >>>
+    >>> fgs2 = FGS_with_defocus()
+    >>> # apply 4 waves of defocus at the wavelength
+    >>> # defined by FGS_with_defocus.defocus_lambda
+    >>> fgs2.defocus_waves = 4
+    >>> psf = fgs2.calc_psf()
+    >>> webbpsf.display_psf(psf)
+
+
+Defocusing an instrument
+--------------------------------
+
+The instrument options dictionary also lets you specify an optional defocus
+amount.  You can specify both the wavelength at which it should be applied, and
+the number of waves of defocus (at that wavelength, specified as waves
+peak-to-valley over the circumscribing circular pupil of JWST).
+
+
+   >>> nircam.options['defocus_waves'] = 3.2
+   >>> nircam.options['defocus_wavelength'] = 2.0e-6
+
+
+

docs/more_examples.rst

@@ -2,7 +2,7 @@
 .. _more_examples:
 
 =============================
-More Examples
+More Examples for JWST
 =============================