diff --git a/docs/index.rst b/docs/index.rst index f6dfac53..5ec5fc80 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,7 +29,7 @@ WebbPSF is a Python package that computes simulated PSFs for the JWST instrument * Model any detector effects such as pixel MTF, intrapixel sensitivity variations, interpixel capacitance, or any noise sources. Add those separately with your favorite detector model code. -The WebbPSF software system includes two Python packages: a lower-level optical propagation library (:py:mod:`POPPY `) plus an implementation of the JWST instruments using that library (:py:mod:`WebbPSF `). This documentation explains the programming interfaces and graphical user interface, and provides usage examples for each. +The WebbPSF software system is composed of two Python packages: a lower-level optical propagation library (:py:mod:`POPPY `) plus an implementation of the JWST instruments using that library (:py:mod:`WebbPSF `). This documentation explains the programming interfaces and graphical user interface of WebbPSF, as well as providing a :ref:`quick overview ` of POPPY. .. admonition:: Quickstart IPython Notebook diff --git a/docs/poppy.rst b/docs/poppy.rst index 3c0269c6..94f17de8 100644 --- a/docs/poppy.rst +++ b/docs/poppy.rst @@ -1,3 +1,5 @@ +.. _poppy_overiew: + ********************************************************* Overview of POPPY (Physical Optics Propagation in Python) ********************************************************* @@ -5,7 +7,7 @@ Overview of POPPY (Physical Optics Propagation in Python) POPPY, which stands for Physical Optics Propagation in Python, implements an object-oriented system for modeling physical optics propagation with diffraction, particularly for telescopic and coronagraphic imaging. (Right now only image and pupil planes are supported; intermediate planes are a future goal.) .. note:: - This is an *abbreviated* version of the documentation for POPPY, included here as a brief summary relevant for WebbPSF. For more comprehensive documentation for POPPY please see `the full POPPY documentation `_ + This is an *abbreviated* version of the documentation for POPPY, included here as a brief summary relevant for WebbPSF. For more comprehensive documentation for POPPY please see `the full POPPY documentation `_ @@ -26,9 +28,9 @@ of useful utility functions for analysing and plotting PSFs, documented below. The Object-Oriented Optical Model ================================= -To model optical propagation, POPPY implements an object-oriented system for representing an optical train. There are a variety of :py:class:`OpticalElement` classes representing both physical elements as apertures, mirrors, and apodizers, and also implicit operations on wavefronts, such as rotations or tilts. Each :py:class:`OpticalElement` may be defined either via analytic functions (e.g. a simple circular aperture) or by numerical input FITS files (e.g. the complex JWST aperture with appropriate per-segment WFE). A series of such :py:class:`OpticalElements ` is chained together in order in an :py:class:`OpticalSystem` class. That class is capable of generating :py:class:`Wavefronts ` (another class) suitable for propagation through the desired elements (with correct array size and sampling), and then performing the optical propagation onto the final image plane. +To model optical propagation, POPPY implements an object-oriented system for representing an optical train. There are a variety of :py:class:`~poppy.OpticalElement` classes representing both physical elements as apertures, mirrors, and apodizers, and also implicit operations on wavefronts, such as rotations or tilts. Each :py:class:`~poppy.OpticalElement` may be defined either via analytic functions (e.g. a simple circular aperture) or by numerical input FITS files (e.g. the complex JWST aperture with appropriate per-segment WFE). A series of such :py:class:`OpticalElements ` is chained together in order in an :py:class:`~poppy.OpticalSystem` class. That class is capable of generating :py:class:`Wavefronts ` (another class) suitable for propagation through the desired elements (with correct array size and sampling), and then performing the optical propagation onto the final image plane. -There is an even higher level class :py:class:`Instrument` which adds support for selectable instrument mechanisms (such as filter wheels, pupil stops, etc). In particular it adds support for computing via synthetic photometry the appropriate weights for multiwavelength computations through a spectral bandpass filter, and for PSF blurring due to pointing jitter (neither of which effects are modeled by :py:class:`OpticalSystem`). Given a specified instrument configuration, an appropriate :py:class:`OpticalSystem` is generated, the appropriate wavelengths and weights are calculated based on the bandpass filter and target source spectrum, the PSF is calculated, and optionally is then convolved with a blurring kernel due to pointing jitter. All of the WebbPSF instruments are implemented by subclassing ``poppy.Instrument``. +There is an even higher level class :py:class:`~poppy.Instrument` which adds support for selectable instrument mechanisms (such as filter wheels, pupil stops, etc). In particular it adds support for computing via synthetic photometry the appropriate weights for multiwavelength computations through a spectral bandpass filter, and for PSF blurring due to pointing jitter (neither of which effects are modeled by :py:class:`~poppy.OpticalSystem`). Given a specified instrument configuration, an appropriate :py:class:`~poppy.OpticalSystem` is generated, the appropriate wavelengths and weights are calculated based on the bandpass filter and target source spectrum, the PSF is calculated, and optionally is then convolved with a blurring kernel due to pointing jitter. All of the WebbPSF instruments are implemented by subclassing :py:class:`poppy.Instrument`. Algorithms, Approximations, and Performance =========================================== @@ -37,7 +39,7 @@ POPPY presently assumes that optical propagation can be modeled using Fraunhofer Two different algorithmic flavors of Fourier transforms are used in POPPY. The familiar FFT algorithm is used for transformations between pupil and image planes in the general case. This algorithm is relatively fast (*O(N log(N))*) but imposes strict constraints on the relative sizes and samplings of pupil and image plane arrays. Obtaining fine sampling in the image plane requires very large oversized pupil plane arrays and vice versa, and image plane pixel sampling becomes wavelength dependent. -To avoid these constraints, for transforms onto the final :py:class:`Detector` plane, instead a Matrix Fourier Transform (MFT) algorithm is used (See `Soummer et al. 2007 Optics Express `_). This allows computation of the PSF directly on the desired detector pixel scale or an arbitrarily finely subsampled version therof. For equivalent array sizes *N*, the MFT is slower than the FFT(*O(N^3)*), but in practice the ability to freely choose a more appropriate *N* (and to avoid the need for post-FFT interpolation onto a common pixel scale) more than makes up for this and the MFT is faster. +To avoid these constraints, for transforms onto the final :py:class:`Detector` plane, instead a Matrix Fourier Transform (MFT) algorithm is used (See `Soummer et al. 2007 Optics Express `_). This allows computation of the PSF directly on the desired detector pixel scale or an arbitrarily finely subsampled version therof. For equivalent array sizes *N*, the MFT is slower than the FFT (*O(N^3)*), but in practice the ability to freely choose a more appropriate *N* (and to avoid the need for post-FFT interpolation onto a common pixel scale) more than makes up for this and the MFT is faster. --------------