Merge pull request #656 from spacetelescope/develop

Merge Develop into Stable for 1.1.2 release

.github/workflows/build.yml

@@ -0,0 +1,15 @@
+name: build
+
+on:
+  release:
+    types: [ released ]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish_pure_python.yml@v1
+    with:
+      upload_to_pypi: ${{ (github.event_name == 'release') && (github.event.action == 'released') }}
+    secrets:
+      pypi_token: ${{ secrets.PYPI_PASSWORD_STSCI_MAINTAINER }}

.github/workflows/ci_workflows.yml

@@ -41,17 +41,17 @@ jobs:
 
           - name: Try minimum supported versions
             os: ubuntu-latest
-            python: '3.9'
-            toxenv: py39-legacy-test
+            python: '3.10'
+            toxenv: py310-legacy-test
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
     - name: Set up Python ${{ matrix.python }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python }}
 
@@ -73,6 +73,6 @@ jobs:
 
     - name: Upload coverage to codecov
       if: ${{ contains(matrix.toxenv,'-cov') }}
-      uses: codecov/codecov-action@v2
+      uses: codecov/codecov-action@v3
       with:
         file: ./coverage.xml

readthedocs.yml → .readthedocs.yaml

@@ -9,7 +9,9 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.11"
+  apt_packages:
+    - graphviz
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -26,4 +28,4 @@ python:
     - method: pip
       path: .
       extra_requirements:
-        - docs
+        - docs

conftest.py

@@ -19,7 +19,3 @@
 
 TESTED_VERSIONS['poppy'] = __version__
 
-## Uncomment the following line to treat all DeprecationWarnings as
-## exceptions
-# from astropy.tests.helper import enable_deprecations_as_exceptions
-# enable_deprecations_as_exceptions()

docs/conf.py

@@ -60,26 +60,24 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx.ext.mathjax",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.inheritance_diagram",
     "sphinx.ext.viewcode",
     "sphinx.ext.autosummary",
-    "sphinx.ext.mathjax",
     "sphinx_automodapi.automodapi",
     "sphinx_issues",
     "nbsphinx",
     "numpydoc",
+    "IPython.sphinxext.ipython_console_highlighting",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
+# The suffix of source filenames.
 source_suffix = ".rst"
 
 # The master toctree document.
@@ -90,7 +88,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.
@@ -101,23 +99,55 @@
     ".DS_Store",
     "_templates",
     "**.ipynb_checkpoints",
+    "figures/**.ipynb",
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+pygments_style = "default"
 
+# -- Options for Extensions --------------------------------------------------
+
+# Do not have autoapi create inheritance diagrams
+automodapi_inheritance_diagram = False
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "stsci_rtd_theme"
-html_theme_path = [stsci_rtd_theme.get_html_theme_path()]
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    "collapse_navigation": True,
+    "sticky_navigation": False,
+    # "nosidebar": "false",
+    # "sidebarbgcolor": "#4db8ff",
+    # "sidebartextcolor": "black",
+    # "sidebarlinkcolor": "black",
+    # "headbgcolor": "white",
+}
+
+html_logo = '_static/stsci_pri_combo_mark_white.png'
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -164,24 +194,17 @@
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
+# (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-    (
-        master_doc,
-        "poppy.tex",
-        "poppy Documentation",
-        "Space Telescope Science Institute",
-        "manual",
-    ),
+    ("index", project + ".tex", project + " Documentation", author, "manual")
 ]
 
 
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "poppy", "poppy Documentation", [author], 1)]
+man_pages = [("index", project.lower(), project + " Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------------

docs/fft_optimization.rst

@@ -4,7 +4,7 @@ Appendix B: Optimizing FFT Performance with FFTW
 .. warning::
 
     This page is obsolete, and superceded by subsequent library development. You probably want
-    to use Intel MKL rather than FFTW. See :ref:`_performance_and_parallelization`.
+    to use Intel MKL rather than FFTW. See :ref:`performance_and_parallelization`.
 
 Optimizing numerical performance of FFTs is a complicated subject. Just using the FFTW library is no guarantee of optimal performance; you need to know how to configure it.
 

docs/figures/README Figure.ipynb

@@ -1,5 +1,15 @@
 {
  "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# README Figure Generator\n",
+    "\n",
+    "When runs, generates the figure 'readme_fig.png'."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,

docs/fresnel.rst

@@ -28,8 +28,7 @@ The API has been kept as similar as possible to the original Fraunhofer mode of
 poppy. There are :class:`~poppy.FresnelWavefront` and :class:`~poppy.FresnelOpticalSystem` classes, which can
 be used for the most part similar to the :class:`~poppy.Wavefront` and :class:`~poppy.OpticalSystem` classes.
 
-Users are encouraged to consult the Jupyter notebook `Fresnel_Propagation_Demo
-<https://github.com/spacetelescope/poppy/blob/develop/notebooks/Fresnel_Propagation_Demo.ipynb>`_
+Users are encouraged to consult the Jupyter notebook `Fresnel_Propagation_Demo`_
 for examples of how to use the Fresnel code.
 
 Key Differences from Fraunhofer mode
@@ -95,8 +94,7 @@ Example Jupyter Notebooks
 .. admonition:: Fresnel tutorial notebook
 
    For more details and examples of code usage, consult the Jupyter
-   notebook `Fresnel_Propagation_Demo
-   <https://github.com/spacetelescope/poppy/blob/stable/notebooks/Fresnel_Propagation_Demo.ipynb>`_.
+   notebook `Fresnel_Propagation_Demo`_.
    In addition to details on code usage, this includes a worked example of
    a Fresnel model of the Hubble Space Telescope.
 
@@ -139,3 +137,4 @@ The following references were helpful in the development of this code.
       `Integrated Modeling of Telescopes <http://www.amazon.com/Integrated-Modeling-Telescopes-Astrophysics-Science/dp/1461401488>`_,
       Springer Science & Business Media.
 
+.. _Fresnel_Propagation_Demo: https://github.com/spacetelescope/poppy/blob/stable/notebooks/Fresnel_Propagation_Demo.ipynb

docs/gpu_acceleration.rst

@@ -1,78 +1,76 @@
 GPU Accelerated Optical Calculations
 ====================================
 
-
-
 .. admonition:: Placeholder docs
-   This page is a placeholder for more complete documentation to be added later about usage of GPUs for fast optical calculations.
-
 
+   This page is a placeholder for more complete documentation to be added later about 
+   usage of GPUs for fast optical calculations.
 
-Thanks to team members Kian Milani and Ewan Douglas (University of Arizona), poppy now includes a
-high performance option using NVidia GPUs to significantly accelerate optical calculations, in some
-cases by ~20x to 80x. 
+Thanks to team members Kian Milani and Ewan Douglas (University of Arizona), poppy now 
+includes a high performance option using NVidia GPUs to significantly accelerate optical 
+calculations, in some cases by ~20x to 80x. 
 
-This implementation seeks to perform all calculations on the GPU until the end of propagation. This
-reduces time for calculations as arrays no longer need to be transferred between GPU memory and
-standard memory when performing different calculations. It also allows GPU acceleration of the
-majority of calculations performed during an optical propagation (i.e. creating models of optical
-elements and applying them to wavefronts happens on the GPU, as well as the propagation calculations
-from one plane to another.)
+This implementation seeks to perform all calculations on the GPU until the end of 
+propagation. This reduces time for calculations as arrays no longer need to be transferred 
+between GPU memory and standard memory when performing different calculations. It also 
+allows GPU acceleration of the majority of calculations performed during an optical 
+propagation (i.e. creating models of optical elements and applying them to wavefronts 
+happens on the GPU, as well as the propagation calculations from one plane to another.)
 
-An updated implementation using `CuPy <https://docs.cupy.dev/en/stable/overview.html>` replaces
-initial earlier support for CUDA using pyculib and numba.cuda. (That initial implementation has been
-removed since the CuPy implementation is much better performing.)
-
-Note, because cupy is used as a replacement for numpy at import time, it is a bit tricky to toggle
-between GPU and CPU calculations during the same python session. Doing so is advanced usage, and
-while it can be useful in some cases for debugging or benchmarking, it's not fully supported or
-recommended to try to switch between calculation backends within the same session. 
+An updated implementation using `CuPy <https://docs.cupy.dev/en/stable/overview.html>` 
+replaces initial earlier support for CUDA using pyculib and numba.cuda. (That initial 
+implementation has been removed since the CuPy implementation is much better performing.)
 
+Note, because cupy is used as a replacement for numpy at import time, it is a bit tricky 
+to toggle between GPU and CPU calculations during the same python session. Doing so is 
+advanced usage, and while it can be useful in some cases for debugging or benchmarking, 
+it's not fully supported or recommended to try to switch between calculation backends 
+within the same session. 
 
 **What about AMD GPUs?**
 
-There also exists partial/earlier support for OpenCL for AMD GPUs, using the `pyopencl` and `gpyfft`
-packages. This provides much less performance gains than the CuPy version, however, since only 
-FFTs are performed on-GPU, not other parts of the optical propagation calculations.
+There also exists partial/earlier support for OpenCL for AMD GPUs, using the `pyopencl` 
+and `gpyfft` packages. This provides much less performance gains than the CuPy version, 
+however, since only  FFTs are performed on-GPU, not other parts of the optical propagation 
+calculations.
 
 **What about Apple Silicon GPUs?**
 
-Poppy does not yet have support for the specialized GPU hardware in Apple Silicon M1/M2 and similar.
-For these machines, plain numpy is the best option.
+Poppy does not yet have support for the specialized GPU hardware in Apple Silicon M1/M2 
+and similar. For these machines, plain numpy is the best option.
+
 
 Requirements and Setup
 ----------------------
 
-
 Requires NVidia GPU hardware
 
-Requires CuPy > 10.0. Install from https://cupy.dev following the `CuPy installation docs <https://docs.cupy.dev/en/stable/install.html#>`_
+Requires CuPy > 10.0. Install from https://cupy.dev following the `CuPy installation docs 
+<https://docs.cupy.dev/en/stable/install.html#>`_
 
 Also requires the cupyx GPU-accelerated version of scipy.
 
 
 Performance Comparisons
 -----------------------
 
-
-
-Computation comparisons have been performed to illustrate the benefit of this accelerated computing
-feature. Below are comparisons of the times required for a PSF to be calculated for varying array
-sizes using the MKL FFT option versus the CuPy calculations. The optical systems tested had 5
-different surfaces/optics. 
-
-Performances will naturally vary depending on the compute hardware used. The system used for these
-comparisons was the University of Arizona’s HPC Puma nodes. The node utilized 32 AMD EPYC 7642 CPUs
-and the NVIDIA Tesla V100S GPU.
-
-+-------------------+--------------+------------------------+-------------------------+----------------------+
-|  Propagation Type |	Array Size |	MKL Method Times [s] |	CuPy Method Times [s] |	Speed Up Factor      |
-+===============+=======+=======+===============+=======+
-| Fraunhofer	| 1024	| 0.218	| 0.0261	| 8.35  |
-| Fraunhofer	| 2048	| 0.755	| 0.0294	| 25.7  |
-| Fraunhofer	| 4096	| 3.36	| 0.0423	| 79.4  |
-| Fresnel	| 1024	| 0.714	| 0.0438	| 16.3  |
-| Fresnel	| 2048	| 4.16	| 0.0845	| 49.2  |
-| Fresnel	| 4096	| 17.5	| 0.225	        | 77.8  |
-+---------------+-------+-------+---------------+-------+
+Computation comparisons have been performed to illustrate the benefit of this accelerated 
+computing feature. Below are comparisons of the times required for a PSF to be calculated 
+for varying array sizes using the MKL FFT option versus the CuPy calculations. The optical 
+systems tested had 5 different surfaces/optics. 
+
+Performances will naturally vary depending on the compute hardware used. The system used 
+for these comparisons was the University of Arizona’s HPC Puma nodes. The node utilized 
+32 AMD EPYC 7642 CPUs and the NVIDIA Tesla V100S GPU.
+
+================== ============ ====================== ======================= =================
+ Propagation Type   Array Size   MKL Method Times [s]   CuPy Method Times [s]   Speed Up Factor 
+================== ============ ====================== ======================= =================
+ Fraunhofer         1024         0.218                  0.0261                  8.35            
+ Fraunhofer         2048         0.755                  0.0294                  25.7            
+ Fraunhofer         4096         3.36                   0.0423                  79.4            
+ Fresnel            1024         0.714                  0.0438                  16.3            
+ Fresnel            2048         4.16                   0.0845                  49.2            
+ Fresnel            4096         17.5                   0.225                   77.8            
+================== ============ ====================== ======================= =================
 

docs/index.rst

@@ -69,6 +69,7 @@ Contents
   fft_optimization.rst
   gpu_acceleration.rst
   dev_notes.rst
+  fitsheaders.rst
 
 
 Getting Help