Merge pull request #915 from spacetelescope/develop

Release V1.4.0 to stable

.github/workflows/ci_workflows.yml

@@ -3,7 +3,12 @@ name: CI
 on: [push, pull_request]
 
 jobs:
+  retrieve_cache:
+    uses: spacetelescope/webbpsf/.github/workflows/retrieve_cache.yml@develop
+    with:
+      minimal: true
   tests:
+    needs: [ retrieve_cache ]
     name: ${{ matrix.name }}
     runs-on: ${{ matrix.os }}
     strategy:
@@ -57,18 +62,21 @@ jobs:
       run: pip install tox tox-conda>=0.2
 
     - name: Get WebbPSF Data
-      run: | # Get WebbPSF data files (just a subset of the full dataset!) and set up environment variable
-           wget https://stsci.box.com/shared/static/gkbnn3jwcootr9riwv0rv1t8rpvxl3vr.gz -O /tmp/minimal-webbpsf-data.tar.gz
-           tar -xzvf /tmp/minimal-webbpsf-data.tar.gz
-           echo "WEBBPSF_PATH=${{github.workspace}}/webbpsf-data" >> $GITHUB_ENV
+      uses: actions/cache/restore@v4
+      with:
+        path: ${{ needs.retrieve_cache.outputs.cache_path }}
+        key: ${{ needs.retrieve_cache.outputs.cache_key }}
+
+    - name: Set WebbPSF data path
+      run: echo "WEBBPSF_PATH=${{ needs.retrieve_cache.outputs.cache_path }}/webbpsf-data/" >> $GITHUB_ENV
 
     - name: Check conda info
       run: conda info
 
     - name: Run tests with requirements file
       if: ${{ contains(matrix.toxenv,'-latest') }}
       run: |
-        cp $RUNNER_WORKSPACE/webbpsf/requirements.txt /tmp/
+        cp requirements.txt ${{ runner.temp }}
         tox -e ${{ matrix.toxenv }}
 
     - name: Run tests

.github/workflows/download_data.yml

@@ -0,0 +1,79 @@
+# downloads WebbPSF dataset and caches it to GitHub cache,
+# making a new cache for a new data version
+# the cache key is in the form `webbpsf-data-mini-1.3.0`,
+# `webbpsf-data-full-1.2.6`, etc.
+#
+# To provide your own test workflow with the WebbPSF dataset,
+# you should use this workflow to set up a cache in your repository,
+# and then use `retrieve_cache.yml` to retrieve that cache so you
+# don't have to download the entire dataset every time.
+#
+# to set up a cache of WebbPSF data in your own repository,
+# create a workflow like the following:
+#
+# # .github/workflows/download_webbpsf.yml
+# name: download and cache WebbPSF data
+# on:
+#   schedule:
+#     - cron: "0 0 * * 0"
+# jobs:
+#   download_webbpsf:
+#     uses: spacetelescope/webbpsf/.github/workflows/download_data.yml@develop
+#     with:
+#       minimal: true
+
+name: download and cache data
+
+on:
+  workflow_call:
+    inputs:
+      minimal:
+        description: minimal dataset
+        type: boolean
+        required: false
+        default: true
+    outputs:
+      version:
+        value: ${{ jobs.download.outputs.version }}
+      cache_path:
+        value: ${{ jobs.download.outputs.cache_path }}
+      cache_key:
+        value: ${{ jobs.download.outputs.cache_key }}
+  workflow_dispatch:
+    inputs:
+      minimal:
+        description: minimal dataset
+        type: boolean
+        required: false
+        default: true
+  schedule:
+    - cron: "0 0 * * 0"
+  release:
+
+env:
+  DATA_URL: https://stsci.box.com/shared/static/qxpiaxsjwo15ml6m4pkhtk36c9jgj70k.gz
+  MINIMAL_DATA_URL: https://stsci.box.com/shared/static/0dt9z6b927iqgtify2a4cvls9hvapi6k.gz
+
+jobs:
+  download:
+    name: download and cache WebbPSF data
+    runs-on: ubuntu-latest
+    steps:
+      - run: wget ${{ (github.event_name == 'schedule' || github.event_name == 'release') && env.MINIMAL_DATA_URL || inputs.minimal && env.MINIMAL_DATA_URL || env.DATA_URL }} -O ${{ runner.temp }}/webbpsf-data.tar.gz
+      - run: mkdir ${{ runner.temp }}/data/
+      - run: tar -xzvf ${{ runner.temp }}/webbpsf-data.tar.gz -C ${{ runner.temp }}/data/
+      - id: cache_path
+        run: echo cache_path=${{ runner.temp }}/data/ >> $GITHUB_OUTPUT
+      - id: version
+        run: echo "version=$(cat ${{ steps.cache_path.outputs.cache_path }}/webbpsf-data/version.txt)" >> $GITHUB_OUTPUT
+      - id: cache_key
+        run: echo "cache_key=webbpsf-data-${{ (github.event_name == 'schedule' || github.event_name == 'release') && 'mini' || inputs.minimal && 'mini' || 'full' }}-${{ steps.version.outputs.version }}" >> $GITHUB_OUTPUT
+      - uses: actions/cache/save@v4
+        with:
+          path: ${{ runner.temp }}/data/
+          key: ${{ steps.cache_key.outputs.cache_key }}
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      cache_path: ${{ steps.cache_path.outputs.cache_path }}
+      cache_key: ${{ steps.cache_key.outputs.cache_key }}
+

.github/workflows/retrieve_cache.yml

@@ -0,0 +1,69 @@
+# retrieves the latest cache key for WebbPSF data; 
+# the cache key is in the form `webbpsf-data-mini-1.3.0`, 
+# `webbpsf-data-full-1.2.6`, etc.
+#
+# to retrieve the WebbPSF data cache in your test workflow, 
+# first create a cache of the dataset in your repository
+# (see `download_data.yml` for instructions), then
+# call this workflow as a needed job and use `actions/cache/restore`
+# to place the data in your test job:
+#
+# # .github/workflows/tests.yml
+# name: run tests
+# ...
+# jobs:
+#   webbpsf_data_cache_key:
+#     uses: spacetelescope/webbpsf/.github/workflows/retrieve_cache.yml@develop
+#     with:
+#       minimal: true
+#   tests:
+#     needs: [ webbpsf_data_cache_key ]
+#     steps:
+#       ...
+#       - name: retrieve WebbPSF data cache
+#        uses: actions/cache/restore@v4
+#        with:
+#          path: ${{ runner.temp }}/webbpsf-data
+#          key: ${{ needs.webbpsf_data_cache_key.outputs.cache_key }}
+#       ...
+
+name: retrieve latest data cache key
+
+on:
+  workflow_call:
+    inputs:
+      minimal:
+        description: minimal dataset
+        type: boolean
+        required: false
+        default: true
+    outputs:
+      version:
+        value: ${{ jobs.retrieve_latest_cache_key.outputs.version }}
+      cache_path:
+        value: ${{ jobs.retrieve_latest_cache_key.outputs.cache_path }}
+      cache_key:
+        value: ${{ jobs.retrieve_latest_cache_key.outputs.cache_key }}
+
+jobs:
+  retrieve_latest_cache_key:
+    name: retrieve latest WebbPSF data cache key
+    runs-on: ubuntu-latest
+    steps:
+      - name: retrieve latest data cache key
+        id: latest_cache_key
+        run: |
+          # use actions/gh-actions-cache to allow filtering by key
+          gh extension install actions/gh-actions-cache
+          CACHE_KEY=$(gh actions-cache list -R ${{ github.repository }} --key webbpsf-data-${{ inputs.minimal && 'mini' || 'full' }}- --sort created-at | cut -f 1 | head -n 1)
+          if [ "$CACHE_KEY" == '' ]; then exit 1; fi
+          echo cache_key=$CACHE_KEY >> $GITHUB_OUTPUT
+        env:
+          GH_TOKEN: ${{ github.token }}
+      - run: echo ${{ steps.latest_cache_key.outputs.cache_key }}
+      - id: version
+        run: echo "version=$(echo ${{ steps.latest_cache_key.outputs.cache_key }} | awk -F '-' '{print $4}')" >> $GITHUB_OUTPUT
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      cache_path: ${{ runner.temp }}/data/
+      cache_key: ${{ steps.latest_cache_key.outputs.cache_key }}

CITATION.cff

@@ -0,0 +1,59 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: WebbPSF
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Marshall
+    family-names: Perrin
+    affiliation: Space Telescope Science Institute
+    orcid: 'https://orcid.org/0000-0002-3191-8151'
+  - given-names: Marcio
+    family-names: Melendez
+    email: [email protected]
+    affiliation: Space Telescope Science Institute
+    orcid: 'https://orcid.org/0000-0001-8485-0325'
+  - given-names: Shannon
+    family-names: Osborne
+    affiliation: Fred Hutchinson Cancer Center
+    orcid: https://orcid.org/0009-0001-8609-1518'
+  - given-names: Robel
+    family-names: Geda
+    affiliation: Princeton University
+    orcid: 'https://orcid.org/0000-0003-1509-9966'
+  - given-names: Bradley
+    family-names: Sappington
+    email: [email protected]
+    affiliation: Space Telescope Science Institute
+    orcid: 'https://orcid.org/0009-0008-2911-2555'
+  - given-names: Charles-Philippe
+    family-names: Lajoie
+    affiliation: Space Telescope Science Institute
+    orcid: 'https://orcid.org/0009-0003-3993-8338'
+  - given-names: Joseph
+    family-names: Long
+    affiliation: Flatiron Institute
+    orcid: 'https://orcid.org/0000-0003-1905-9443'
+  - given-names: "O. Justin"
+    family-names: "Otor"
+    affiliation: "Otor"
+    orcid: 'https://orcid.org/0000-0002-4679-5692'
+repository-code: 'https://github.com/spacetelescope/webbpsf'
+abstract: >-
+  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, 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.
+license: BSD-3-Clause
+version: 1.4.0

LICENSE.md

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2010-2018, Space Telescope Science Institute, AURA
+Copyright (c) 2010-2024, Space Telescope Science Institute, AURA
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

docs/conf.py

@@ -83,17 +83,18 @@
     "numpydoc",
 ]
 
+
+if on_rtd:
+    extensions.append('sphinx.ext.mathjax')
+
 numpydoc_show_class_members = False
 
 autosummary_generate = True
 graphviz_dot = "dot"
 # 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.
@@ -118,26 +119,53 @@
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+pygments_style = "default"
 
-intersphinx_mapping.update(  # noqa - defined in star import
-    {
-        "poppy": ("http://poppy-optics.readthedocs.io/", None),
-    }
-)
+#intersphinx_mapping.update(  # noqa - defined in star import
+#    {
+#        "poppy": ("http://poppy-optics.readthedocs.io/", None),
+#    }
+#)
 
 
 # -- 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,

docs/index.rst

@@ -15,7 +15,8 @@ WebbPSF is a Python package that computes simulated point spread functions (PSFs
    :align: center
    :alt: Sample PSFs for the filters in the Roman WFI.
 
-   Sample PSFs for the filters in the Roman WFI.
+   Sample PSFs for the filters in the Roman WFI on SCA01. Note that
+   the prism and grism PSFs shown here are monochromatic.
 
 
 **Contributors:**
@@ -24,7 +25,7 @@ WebbPSF has been developed by Marshall Perrin, Marcio Meléndez, Shannon Osborne
 Getting Started with WebbPSF
 ----------------------------
 
-See :ref:`using_api`.
+See `Using WebbPSF <usage.html>`_.
 
 .. admonition:: Quickstart Jupyter Notebook
 
@@ -48,8 +49,8 @@ Contents
    intro.rst
    installation.rst
    relnotes.rst
-   usage.rst
-   psf_grids.rst
+   usage.ipynb
+   psf_grids.ipynb
 
 .. toctree::
    :maxdepth: 1
@@ -60,6 +61,7 @@ Contents
    jwst_measured_opds.ipynb
    jwst_detector_effects.ipynb
    jwst_matching_psfs_to_data.ipynb
+   jwst_large_psf.ipynb
    jwst_optical_budgets.ipynb
    jwst_psf_subtraction.ipynb
    jwst_wavefront_deltas.ipynb