From 0cee3b99e7c12e4b725ddf662b818943da1aac91 Mon Sep 17 00:00:00 2001 From: Marshall Perrin Date: Wed, 12 Dec 2018 10:53:39 -0500 Subject: [PATCH] Docs updates for 0.8.0 (#258) * refresh install docs * Docs update, 0.8.0 release candidate 1 * Update docs/index.rst Co-Authored-By: mperrin and shanosborne --- README.rst | 2 +- docs/index.rst | 6 +++--- docs/installation.rst | 45 +++++++++++++++++-------------------------- docs/intro.rst | 39 ++++++++++++++++--------------------- docs/relnotes.rst | 41 +++++++++++++++++++++++++++++---------- setup.py | 2 +- 6 files changed, 71 insertions(+), 64 deletions(-) diff --git a/README.rst b/README.rst index c4c4a20b..36f46071 100644 --- a/README.rst +++ b/README.rst @@ -26,7 +26,7 @@ WebbPSF also supports simulating PSFs for the upcoming Wide Field Infrared Surve 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, and collaborators, 2010-2018. +Osborne, Marcio Melendez Hernandez, Lauren Chambers, Keira Brooks, and collaborators, 2010-2018. Documentation can be found online at https://webbpsf.readthedocs.io diff --git a/docs/index.rst b/docs/index.rst index cfd23c61..8eccb711 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ Documentation for WebbPSF =============================== -WebbPSF is a Python package that computes simulated PSFs for the JWST instruments (and now for WFIRST too), taking into account detector pixel scales, rotations, filter profiles, and point source spectra. It is *not* a full optical model of JWST, but rather a tool for transforming optical path difference (OPD) maps, created with some other tool, into the resulting PSFs as observed with JWST's instruments. +WebbPSF is a Python package that computes simulated point spread functions (PSFs) for NASA's JWST and WFIRST observatories. WebbPSF transforms models of telescope and instrument optical state into PSFs, taking into account detector pixel scales, rotations, filter profiles, and point source spectra. It is *not* a full optical model of JWST, but rather a tool for transforming optical path difference (OPD) maps, created with some other tool, into the resulting PSFs as observed with JWST's or WFIRST's instruments. .. figure:: ./fig_instrument_comparison.png :scale: 45 % @@ -32,11 +32,11 @@ WebbPSF is a Python package that computes simulated PSFs for the JWST instrument * Contain in itself any detailed thermal or optical model of JWST or WFIRST. For the results of end-to-end integrated simulations of JWST, see for instance `Predicted JWST imaging performance (Knight, Lightsey, & Barto; Proc. SPIE 2012) `_. For WFIRST modeling, see `the WFIRST Reference Info page `_ * Model spectrally dispersed PSFs produced by any of the spectrograph gratings. It does, however, let you produce monochromatic PSFs in these modes, suitable for stitching together into spectra using some other software. -* Model detector effects such as pixel MTF, intrapixel sensitivity variations, interpixel capacitance, or any noise sources. Add those separately with your favorite detector model code. (\*Note, one particularly significant +* Model most detector effects such as pixel MTF, intrapixel sensitivity variations, interpixel capacitance, or any noise sources. Add those separately with your favorite detector model code. (\*Note, one particularly significant detector scattering for MIRI imaging has now been added.) **Contributors:** -WebbPSF has been developed by Marshall Perrin, Joseph Long, Neil Zimmerman, Robel Geda, Shannon Osborne, and Marcio Melendez Hernandez, with contributions from Jarron Leisenring, Ewan Douglas, Charles Lajoie, Megan Sosey, and the developers of the astropy-helpers template framework. +WebbPSF has been developed by Marshall Perrin, Joseph Long, Neil Zimmerman, Robel Geda, Shannon Osborne, Marcio Melendez Hernandez, Lauren Chambers, and Keira Brooks, with contributions from Jarron Leisenring, Ewan Douglas, Charles Lajoie, Megan Sosey, and the developers of the astropy-helpers template framework. Getting Started with WebbPSF ---------------------------- diff --git a/docs/installation.rst b/docs/installation.rst index ae9d8f90..5d3d5731 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -5,16 +5,21 @@ Requirements & Installation The latest released version of WebbPSF can be installed with the conda package management system or `using pip `_. + +Recommended best method: Installing via AstroConda +-------------------------------------------------- + For ease of installation, we recommend using `AstroConda `_, an astronomy-optimized software distribution for scientific Python built on Anaconda. Install AstroConda according to `their instructions `_, then activate the environment with:: $ source activate astroconda (Note: if you named your environment something other than ``astroconda``, change the above command appropriately.) -Next, install WebbPSF (along with its dependencies and required reference data) with:: +Next, install WebbPSF (along with all its dependencies and required reference data) with:: (astroconda)$ conda install webbpsf + .. admonition:: Optional: sign up to receive announcement of updates This is entirely optional, but you may wish to sign up to the mailing list ``webbpsf-users@stsci.edu``. This is a low-traffic moderated announce-only list, to which we will periodically post announcements of updates to this software. @@ -43,47 +48,31 @@ Upgrading to the latest version is done with ``conda update -n webbpsf-env --all Installing with pip ------------------- -**If you have Python 2.7, 3.4, or 3.5 already installed another way**, WebbPSF and its underlying optical library POPPY may be installed from the `Python Package Index `_ in the usual manner for Python packages. :: +WebbPSF and its underlying optical library POPPY may be installed from the `Python Package Index `_ in the usual manner for Python packages. :: $ pip install --upgrade webbpsf [... progress report ...] Successfully installed webbpsf -Note that ``pip install webbpsf`` only installs the program code. You still must download and install the data files, as :ref:`described below `. +Note that ``pip install webbpsf`` only installs the program code. **If you install via pip, you must manually download and install the data files, as :ref:`described below `.** To obtain source spectra for calculations, you should also follow :ref:`installation instructions for pysynphot `. -To use the Jupyter Notebook GUI, you will need to install ``ipywidgets``:: - - $ pip install ipywidgets - $ jupyter nbextension enable --py --sys-prefix widgetsnbextension - -(See `the ipywidgets README `_ for more info.) - -.. tip:: - - If you wish to install WebbPSF on a machine for which you do not have administrative access, you can do so by using Python's - built-in `"--user" mechanism `_ - for installing packages into your home directory. :: - - $ pip install webbpsf --user - -.. warning:: - - If you get the message ``SystemError: Cannot compile 'Python.h'. Perhaps you need to install python-dev|python-devel.`` during install *even when Python.h is available*, this means ``setup.py`` was unable to install NumPy. This can sometimes be fixed by executing ``pip install numpy`` separately, before installing WebbPSF. See the bug report at `numpy/numpy#2434 `_ for details. .. _pysynphot_install: Installing or updating pysynphot -------------------------------- -Pysynphot is an optional dependency, but is highly recommended. Installation instructions can be found `here in the POPPY docs `_. +Pysynphot is an optional dependency, but is highly recommended. Pysynphot is best installed via AstroConda. Further installation instructions can be found `here in the POPPY docs `_. .. _data_install: Installing the Required Data Files ---------------------------------- +*If you install via pip or manually*, you must install the data files yourself. If you install via Conda, the data files are automatically installed, in which case you can skip this section. + Files containing such information as the JWST pupil shape, instrument throughputs, and aperture positions are distributed separately from WebbPSF. To run WebbPSF, you must download these files and tell WebbPSF where to find them using the ``WEBBPSF_PATH`` environment variable. 1. Download the following file: `webbpsf-data-0.7.0.tar.gz `_ [approx. 240 MB] @@ -111,13 +100,13 @@ You should now be able to successfully ``import webbpsf`` in a Python session, o Software Requirements --------------------- -**Required Python version**: WebbPSF is supported on both Python 2.7 and 3.4+. +**Required Python version**: WebbPSF 0.8 and above require Python 3.5 or higher. **Required Python packages**: * Recent versions of `NumPy, SciPy `_ and `matplotlib `_, if not installed already. -* `Astropy `_, 1.0 or more recent. -* `POPPY `_, 0.5.0 or more recent. +* `Astropy `_ +* `POPPY `_ **Recommended Python packages**: @@ -129,14 +118,16 @@ Software Requirements **Optional Python packages**: Some calculations with POPPY can benefit from the optional packages `psutil `_ and `pyFFTW `_, but these are not needed in general. See `the POPPY installation docs `_ for more details. -These optional packages are only worth adding for speed improvements if you are spending substantial time running calculations. +These optional packages are only worth adding for speed improvements if you are spending substantial time running calculations. + +Additional packages are needed for the optional use of GPUs to accelerate calculations. See the POPPY documentation. .. _install_dev_version: Installing a pre-release version or contributing to WebbPSF development ----------------------------------------------------------------------- -The `WebbPSF source code repository `_ is hosted at GitHub, as is the repository for `POPPY `_. Users may clone or fork in the usual manner. Pull requests with code enhancements welcomed. +The `WebbPSF source code repository `_ is hosted at GitHub, as is the repository for `POPPY `_. Users may clone or fork in the usual manner. Pull requests with code enhancements welcomed. To install the current development version of WebbPSF, you can use ``pip`` to install directly from a ``git`` repository. To install WebbPSF and POPPY from ``git``, uninstall any existing copies of WebbPSF and POPPY, then invoke pip as follows:: diff --git a/docs/intro.rst b/docs/intro.rst index 9e307340..98a5bb3b 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -14,28 +14,23 @@ GUI can provide a quicker method for many simple interactive calculations. Why WebbPSF? ------------ -WebbPSF replaced an older PSF simulation package, ``JWPSF``, that was in use prior to 2011. -From a user's perspective WebbPSF provides the following enhancements over JWPSF: - -* Updated to the most recent JWST pupil and OPD models, Revision V. -* Added TFI and FGS models. TFI then updated to NIRISS. -* Updated lists of available filters. -* Added support for coronagraphic and spectroscopic observing modes. -* Includes the detector rotations, particularly for MIRI and NIRSpec -* Adds ability to set output image FOV size and pixel sampling, separate from the oversampling factor used for the optical propagation. -* New & improved graphical user interface. - - -Perhaps even more importantly, the underlying codebase has been entirely replaced and revamped. The most -significant additions from a programmer's perspective include: - -* Much cleaner object-oriented interface. Better abstraction of details across layers. -* Support for optics defined by analytic functions -* Support for coordinate rotations and rotated optics. -* Arbitrary oversampling for coronagraphic models. -* Matrix Fourier Transform algorithm from Soummer et al. implemented for arbitrary detector sampling. -* Optional parallelization for improved speed and efficient use of multiple processor cores. -* Uses ``pysynphot`` library (same as the HST & JWST exposure time calculators) for consistent treatment of filter bandpasses and source spectra. +For any space telescope, an ability to predict the properties of +point spread functions (PSFs) is needed before launch for a wide +range of preparatory science studies and tool development. +Tools for producing high +quality model PSFs must be easily accessible to the entire astronomical +community. +WebbPSF provides an easy-to-use tool for PSF simulations of JWST and WFIRST, in +the style of the highly successful "Tiny Tim" PSF simulator for Hubble. + +WebbPSF +simulations are based on a mixture of observatory design parameters and +as-built properties. The software provides a highly flexible and scriptable toolkit in +Python for simulating a very wide range of observing modes and science scenarios, using +efficient computational methods (including optional parallelization and use of GPUs). WebbPSF +is a key building block in higher-level observatory simulators, including the +JWST `Exposure Time Calculator `_. + .. _intro_algorithms: diff --git a/docs/relnotes.rst b/docs/relnotes.rst index 62a50f72..3194b7e5 100644 --- a/docs/relnotes.rst +++ b/docs/relnotes.rst @@ -18,14 +18,14 @@ See https://github.com/mperrin/webbpsf/issues for currently open issues and enha **The following factors are NOT included in these simulations:** * Coronagraphic masks are assumed to be perfect (i.e. the masks exactly match their design parameters.) -* Most detector effects, such as intrapixel sensitivity variations or interpixel capacitance. There are currently no plans to include these WebbPSF itself. Generate a subsampled PSF and use a separate detector model code instead. The one exception is a scattering artifact in the MIRI imager detector substrate. +* Most detector effects, such as intrapixel sensitivity variations or interpixel capacitance. There are currently no plans to include these WebbPSF itself. Generate a subsampled PSF and use a separate detector model code instead. The one exception is a scattering artifact in the MIRI imager detector substrate. Road Map for Future Releases -------------------------------- -* Continued validation and updates as needed based on further analyses of instrument and telescope hardware test data. +* 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. -* Improved models for telescope WFE evolution over time. -* 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. +* Improved models for telescope WFE evolution over time. +* 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: @@ -36,15 +36,36 @@ Version History and Change Log Version 0.8.0 ============= -*2018 Dec 07* +*2018 Dec 15* -- *Added new capability to create grids of fiducial, distorted PSFs* spanning a chosen instrument/detector. This new ``psf_grid`` method is meant to be used as the first step of using the ``photutils`` package to do PSF-fitting photometry on simulated JWST PSFs. This method will output a list of or single ``photutils`` ``GriddedPSFModel`` object(s) which can then be read into ``photutils`` to apply interpolation to the grid and simulate a spatially dependent PSF anywhere on the instrument. See this `Jupyter notebook `_ for examples. This method requires ``photutils`` version 0.6 or higher. [`#241, ` _, @shanosborne with inputs from @mperrin, @larrybradley, @hcferguson, and @eteq] -- *Improved the application of distortion to PSFs* to allow distorted PSFs to be created when the output mode is set to only “oversampled” or only “detector-sampled.” When either of these modes is set in the options dictionary, the output will be an HDUList object with two extensions, where the 1st extension is the same PSF as in the 0th extension but with distortion applied. [`#229, ` _, @shanosborne] +This release focused on software engineering improvements, rather than changes in any of the optical models or reference data. In particular, there are NO changes in the reference data files; WebbPSF version 0.8 will continue to use the same reference data as distributed for version 0.7. -**Bug fixes and minor changes:** +.. admonition:: Python version support: Python 3 required + + This version drops support for Python 2.7. The minimum supported version of Python is now 3.5. + +**New functionality:** -- All JWST Instruments: Fix for distorted PSFs which were shifted off-center compared to their undistorted counterparts. These distorted PSFs had always been created in the correct detector location, but the values in the array returned by ``calc_psf`` were shifted off from the center. This bug was particularly apparent when the PSFs were set with a location near the edge of the detector. [`#219, ` _, @shanosborne] -- Various smaller code cleanup and doc improvements, including code cleanup for better Python PEP8 style guide compliance [@shanosborne] +- *Added new capability to create grids of fiducial, distorted PSFs* spanning a chosen instrument/detector. This new ``psf_grid`` method is meant to be used as the first step of using the ``photutils`` package to do PSF-fitting photometry on simulated JWST PSFs. This method will output a list of or single ``photutils`` ``GriddedPSFModel`` object(s) which can then be read into ``photutils`` to apply interpolation to the grid and simulate a spatially dependent PSF anywhere on the instrument. See this `Jupyter notebook `_ for examples. This method requires ``photutils`` version 0.6 or higher. [`#241, ` _, @shanosborne with inputs from @mperrin, @larrybradley, @hcferguson, and @eteq] + +**Bug fixes and small changes:** + +- *Improved the application of distortion to PSFs* to allow distorted PSFs to be created when the output mode is set to only “oversampled” or only “detector-sampled.” When either of these modes is set in the options dictionary, the output will be an HDUList object with two extensions, where the 1st extension is the same PSF as in the 0th extension but with distortion applied. [`#229, ` _, @shanosborne] +- Also fixed distorted PSFs which were shifted off-center compared to their undistorted counterparts. These distorted PSFs had always been created in the correct detector location, but the values in the array returned by ``calc_psf`` were shifted off from the center. This bug was particularly apparent when the PSFs were set with a location near the edge of the detector. [`#219, ` _, @shanosborne] +- Fix FITS output from JWST OTE linear model, plus typo fixes and PEP8 improvements [#232, @laurenmarietta] +- Display code added for the PSF grid functionality mentioned above [#247, @mperrin] + +**Software and Package Infrastructure Updates:** + +- Removed Python 2.7 compatibility code, use of six and 2to3 packages, and Python 2 test cases on Travis (#236, #239, @mperrin, @kjbrooks] +- Packaging re-organized for consistency with current STScI package template (#240, @robelgeda) +- Documentation template updated for consistency with current STScI docs template (#250, @robelgeda) +- Documentation added or updated for a variety of features [#248, @mperrin] +- Various smaller code cleanup and doc improvements, including code cleanup for better Python PEP8 style guide compliance [#227, #255, @shanosborne] +- Updated to newer syntax for specifying pupil shifts of optical elements [#257, @mperrin] +- Unit tests added for defocused instruments, including the NIRCam weak lenses [#256, @mperrin] +- Updated astropy-helpers submodule to 3.0.2 [#249, @mperrin] +- Software development repo on Github shifted to within the `spacetelescope organization `_. -------- diff --git a/setup.py b/setup.py index 28e55649..ebc4037d 100755 --- a/setup.py +++ b/setup.py @@ -71,7 +71,7 @@ builtins._ASTROPY_PACKAGE_NAME_ = PACKAGENAME # VERSION should be PEP386 compatible (http://www.python.org/dev/peps/pep-0386) -VERSION = '0.7.1dev' +VERSION = '0.8.0rc1' # Indicates if this version is a release version RELEASE = 'dev' not in VERSION