Migrate to stpsf. (#205)

* Migrate to stpsf. * Update scripts/romanisim-make-stack Co-authored-by: Brett Graham <[email protected]> * Update scripts/romanisim-make-image Co-authored-by: Brett Graham <[email protected]> * Update data links and paper link. * Change link text. --------- Co-authored-by: Brett Graham <[email protected]>
spacetelescope · Feb 17, 2025 · f585c3c · f585c3c
1 parent bc586c7
commit f585c3c
Show file tree

Hide file tree

Showing 23 changed files with 161 additions and 147 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -38,7 +38,7 @@ jobs:
           - eigen
           - fftw
       setenv: |
-        WEBBPSF_PATH: ${{ needs.latest_data_cache.outputs.cache_path }}/webbpsf-data/
+        STPSF_PATH: ${{ needs.latest_data_cache.outputs.cache_path }}/stpsf-data/
         GALSIM_CAT_PATH: ${{ needs.latest_data_cache.outputs.cache_path }}/galsim_data/real_galaxy_catalog_23.5_example.fits
         FFTW_DIR: /opt/homebrew/opt/fftw/lib/
       cache-path: ${{ needs.latest_data_cache.outputs.cache_path }}

diff --git a/.github/workflows/ci_cron.yml b/.github/workflows/ci_cron.yml
@@ -25,7 +25,7 @@ jobs:
           - eigen
           - fftw
       setenv: |
-        WEBBPSF_PATH: ${{ needs.latest_data_cache.outputs.cache_path }}/webbpsf-data/
+        STPSF_PATH: ${{ needs.latest_data_cache.outputs.cache_path }}/stpsf-data/
         GALSIM_CAT_PATH: ${{ needs.latest_data_cache.outputs.cache_path }}/galsim_data/real_galaxy_catalog_23.5_example.fits
         FFTW_DIR: /opt/homebrew/opt/fftw/lib/
       cache-path: ${{ needs.latest_data_cache.outputs.cache_path }}

diff --git a/.github/workflows/data.yml b/.github/workflows/data.yml
@@ -5,7 +5,7 @@ on:
     - cron: "42 4 * * 3"
   workflow_call:
     inputs:
-      webbpsf_minimal:
+      stpsf_minimal:
         type: boolean
         required: false
         default: true
@@ -20,8 +20,8 @@ on:
         value: ${{ jobs.combine_data_cache.outputs.cache_path }}
   workflow_dispatch:
     inputs:
-      webbpsf_minimal:
-        description: minimal WebbPSF dataset
+      stpsf_minimal:
+        description: minimal STPSF dataset
         type: boolean
         required: false
         default: true
@@ -32,13 +32,13 @@ on:
         default: "/tmp/data"
 
 jobs:
-  download_webbpsf_data:
+  download_stpsf_data:
     uses: ./.github/workflows/download_data.yml
     with:
-      minimal: ${{ github.event_name != 'workflow_dispatch' && true || inputs.webbpsf_minimal }}
+      minimal: ${{ github.event_name != 'workflow_dispatch' && true || inputs.stpsf_minimal }}
   combine_data_cache:
-    name: combine GalSim and WebbPSF data into single cache
-    needs: [ download_webbpsf_data ]
+    name: combine GalSim and STPSF data into single cache
+    needs: [ download_stpsf_data ]
     runs-on: ubuntu-latest
     env:
       GALSIM_DATA_URL: https://github.com/GalSim-developers/GalSim/raw/releases/2.4/examples/data/
@@ -58,17 +58,17 @@ jobs:
           mkdir -p ${{ env.GALSIM_PATH }}
           mv ./galsim_data/* ${{ env.GALSIM_PATH }}
       - run: echo GALSIM_CAT_PATH=${{ env.GALSIM_PATH }}real_galaxy_catalog_23.5_example.fits >> $GITHUB_ENV
-      - name: retrieve cached WebbPSF data
+      - name: retrieve cached STPSF data
         uses: actions/cache/restore@1bd1e32a3bdc45362d1e726936510720a7c30a57  # v4.2.0
         with:
-          path: ${{ needs.download_webbpsf_data.outputs.cache_path }}
-          key: ${{ needs.download_webbpsf_data.outputs.cache_key }}
-      - run: mv ${{ needs.download_webbpsf_data.outputs.cache_path }}/webbpsf-data/ ${{ steps.cache_path.outputs.cache_path }}
+          path: ${{ needs.download_stpsf_data.outputs.cache_path }}
+          key: ${{ needs.download_stpsf_data.outputs.cache_key }}
+      - run: mv ${{ needs.download_stpsf_data.outputs.cache_path }}/stpsf-data/ ${{ steps.cache_path.outputs.cache_path }}
         continue-on-error: true
       - run: ls ${{ steps.cache_path.outputs.cache_path }}/*
-      - run: echo WEBBPSF_PATH=${{ steps.cache_path.outputs.cache_path }}/webbpsf-data/ >> $GITHUB_ENV
+      - run: echo STPSF_PATH=${{ steps.cache_path.outputs.cache_path }}/stpsf-data/ >> $GITHUB_ENV
       - id: cache_key
-        run: echo cache_key=data-${{ needs.download_webbpsf_data.outputs.cache_key }}-galsim-data-${{ steps.galsim_data.outputs.hash }} >> $GITHUB_OUTPUT
+        run: echo cache_key=data-${{ needs.download_stpsf_data.outputs.cache_key }}-galsim-data-${{ steps.galsim_data.outputs.hash }} >> $GITHUB_OUTPUT
       # save a new cache to the same generalized data directory, combined with extra data
       - name: save a single combined data cache
         uses: actions/cache/save@1bd1e32a3bdc45362d1e726936510720a7c30a57  # v4.2.0

diff --git a/.github/workflows/download_data.yml b/.github/workflows/download_data.yml
@@ -1,24 +1,24 @@
-# downloads WebbPSF dataset and caches it to GitHub cache,
+# downloads STPSF 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.
+# the cache key is in the form `stpsf-data-mini-1.3.0`,
+# `stpsf-data-full-1.2.6`, etc.
 #
-# To provide your own test workflow with the WebbPSF dataset,
+# To provide your own test workflow with the STPSF 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,
+# to set up a cache of STPSF data in your own repository,
 # create a workflow like the following:
 #
-# # .github/workflows/download_webbpsf.yml
-# name: download and cache WebbPSF data
+# # .github/workflows/download_stpsf.yml
+# name: download and cache STPSF data
 # on:
 #   schedule:
 #     - cron: "0 0 * * 0"
 # jobs:
-#   download_webbpsf:
-#     uses: spacetelescope/webbpsf/.github/workflows/download_data.yml@beda656c80a0254e6f80649d9c9c49235634522f  # v1.4.0
+#   download_stpsf:
+#     uses: spacetelescope/stpsf/.github/workflows/download_data.yml@beda656c80a0254e6f80649d9c9c49235634522f  # v1.4.0
 #     with:
 #       minimal: true
 
@@ -64,23 +64,23 @@ on:
       - develop
 
 env:
-  FULL_DATA_URL: https://stsci.box.com/shared/static/qxpiaxsjwo15ml6m4pkhtk36c9jgj70k.gz
-  MINIMAL_DATA_URL: https://stsci.box.com/shared/static/0dt9z6b927iqgtify2a4cvls9hvapi6k.gz
+  FULL_DATA_URL: https://stsci.box.com/shared/static/kqfolg2bfzqc4mjkgmujo06d3iaymahv.gz
+  MINIMAL_DATA_URL: https://stsci.box.com/shared/static/3hzmbarac5yxjt6x7gn17vz02k7c8z1d.gz
 
 jobs:
   download:
-    name: download and cache WebbPSF data
+    name: download and cache STPSF data
     runs-on: ubuntu-latest
     steps:
-      - run: wget ${{ (github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call') && inputs.url || env.MINIMAL_DATA_URL }} -O ${{ runner.temp }}/webbpsf-data.tar.gz
+      - run: wget ${{ (github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call') && inputs.url || env.MINIMAL_DATA_URL }} -O ${{ runner.temp }}/stpsf-data.tar.gz
       - run: mkdir ${{ runner.temp }}/data/
-      - run: tar -xzvf ${{ runner.temp }}/webbpsf-data.tar.gz -C ${{ runner.temp }}/data/
+      - run: tar -xzvf ${{ runner.temp }}/stpsf-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
+        run: echo "version=$(cat ${{ steps.cache_path.outputs.cache_path }}/stpsf-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
+        run: echo "cache_key=stpsf-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/

diff --git a/docs/romanisim/bandpass.rst b/docs/romanisim/bandpass.rst
@@ -3,7 +3,7 @@ Bandpasses
 
 The simulator can render scenes in a number of different bandpasses.  The choice of bandpass affects the point spread function used, the sky backgrounds, the fluxes of sources, and the reference files requested.
 
-At present, romanisim simply passes the choice of bandpass to other packages---to webbpsf for PSF modeling, to galsim.roman for sky background estimation, to CRDS for reference file selection, or to the catalog for the selection of appropriate fluxes.  However, because catalog fluxes are specified in "maggies" (i.e., such that :math:`\mathrm{flux} = 10^{-\mathrm{AB mag} / 2.5}`), the simulator needs to know how to convert between a maggie and the number of electrons Roman receives from a source.  Accordingly, the simulator knows about the AB zero points of the Roman filters, as derived from https://roman.gsfc.nasa.gov/science/WFI_technical.html .  The conversion between electrons received and fluxes in AB "maggies" is determined by integrating a flat 3631 Jy AB reference spectrum over the Roman filters to determine the number of electrons per second corresponding to a zeroth magnitude AB source.
+At present, romanisim simply passes the choice of bandpass to other packages---to stpsf for PSF modeling, to galsim.roman for sky background estimation, to CRDS for reference file selection, or to the catalog for the selection of appropriate fluxes.  However, because catalog fluxes are specified in "maggies" (i.e., such that :math:`\mathrm{flux} = 10^{-\mathrm{AB mag} / 2.5}`), the simulator needs to know how to convert between a maggie and the number of electrons Roman receives from a source.  Accordingly, the simulator knows about the AB zero points of the Roman filters, as derived from https://roman.gsfc.nasa.gov/science/WFI_technical.html .  The conversion between electrons received and fluxes in AB "maggies" is determined by integrating a flat 3631 Jy AB reference spectrum over the Roman filters to determine the number of electrons per second corresponding to a zeroth magnitude AB source.
 
 One technical note: it is unclear what aperture is used for the bandpasses provided by Goddard.  The Roman PSF formally extends to infinity and some light is received by the detector but is so far from the center of the PSF that it is not useful for flux, position, or shape measurements.  Often for the purposes of computing effective area curves only light landing within a fixed aperture is counted.  Presently the simulator assumes that an infinite aperture is used.  This can result in an approximately 10% different flux scale than more reasonable aperture selections.
 

diff --git a/docs/romanisim/install.rst b/docs/romanisim/install.rst
@@ -11,13 +11,13 @@ The most frequently encountered difficulty installing romanisim is
 when GalSim is unable to find FFTW.  If your system does not have the
 FFTW library, these should be installed before romanisim and GalSim.
 
-Another problematic dependency is `WebbPSF
-<https://webbpsf.readthedocs.io>`_, which requires data files to
+Another problematic dependency is `STPSF
+<https://stpsf.readthedocs.io>`_, which requires data files to
 operate.  See the `docs
-<https://webbpsf.readthedocs.io/en/latest/installation.html#installing-the-required-data-files>`_
+<https://stpsf.readthedocs.io/en/latest/installation.html#installing-the-required-data-files>`_
 for instructions on obtaining the relevant data files and pointing the
-``WEBBPSF_PATH`` environment variable to them.  This issue can be
-avoided by not setting the ``--webbpsf`` argument, in which case
+``STPSF_PATH`` environment variable to them.  This issue can be
+avoided by not setting the ``--stpsf`` argument, in which case
 ``romanisim`` uses the GalSim modeling of the Roman PSF.
 
 Additionally, some synthetic scene generation tools use images of galaxies
@@ -44,12 +44,12 @@ In summary, the basic install process looks like this::
     # to be able to run the tests for a specific version, use instead
     # pip install romanisim[test]==0.1
 
-    # get webbpsf data and untar it
-    mkdir -p $HOME/data/webbpsf-data
-    cd $HOME/data/webbpsf-data
-    wget https://stsci.box.com/shared/static/qxpiaxsjwo15ml6m4pkhtk36c9jgj70k.gz -O webbpsf-data.tar.gz
-    tar -xzf webbpsf-data.tar.gz
-    export WEBBPSF_PATH=$PWD/webbpsf-data
+    # get stpsf data and untar it
+    mkdir -p $HOME/data/stpsf-data
+    cd $HOME/data/stpsf-data
+    wget PATH_TO_STPSF_FILES -O stpsf-data.tar.gz
+    tar -xzf stpsf-data.tar.gz
+    export STPSF_PATH=$PWD/stpsf-data
 
     # get galsim galaxy catalogs
     # Note: ~5 GB each, takes a little while to download.
@@ -58,6 +58,8 @@ In summary, the basic install process looks like this::
     galsim_download_cosmos -s 23.5
     galsim_download_cosmos -s 25.2
 
+The path to the STPSF data files may be found in their `documentation <https://stpsf.readthedocs.io/en/latest/installation.html>`_.
+
 You may wish to, for example, set up a new python virtual environment
 before running the above, or choose a different directory for
-WebbPSF's data files.
+STPSF's data files.
diff --git a/docs/romanisim/l2.rst b/docs/romanisim/l2.rst
@@ -9,7 +9,7 @@ The package contains two algorithms for ramp fitting.  The first uses "optimal"
 
 This approach does not handle cosmic rays or saturated pixels well, though for modest sized sets of resultants introducing an additional series of fits for the roughly :math:`2 n_\mathrm{resultant}` sub-ramps would be straightforward.  That approach would also naturally handle saturated ramps.  Even explicitly computing every possible :math:`n_\mathrm{resultant} (n_\mathrm{resultant} - 1) / 2` subramp would likely still be quite inexpensive for modestly sized ramps.
 
-The second approach follows `Casertano (2022) <https://webbpsf.readthedocs.io/en/latest/installation.html#installing-the-required-data-files>`_.  In this approach, a diagonal set of weights is used in place of the full covariance matrix.  The choice of weights depend on the particular pattern of reads assigned to each resultant and the amount of flux in the ramp, allowing them to interpolate from simply differencing the first and last resultants when the flux is very large to weighting the resultants by the number of reads when the flux is zero.  This approach more efficiently handles dealing with ramps that have been split by cosmic rays, and obtaining uncertainties within a few percent of the "optimal" weighting approach.  For these cases, we report final ramp slopes and variances derived from the inverse variance weighted subramp slopes and variances, using the read-noise derived variances.
+The second approach follows `Casertano (2022) <https://www.stsci.edu/files/live/sites/www/files/home/roman/_documents/Roman-STScI-000394_DeterminingTheBestFittingSlope.pdf>`_.  In this approach, a diagonal set of weights is used in place of the full covariance matrix.  The choice of weights depend on the particular pattern of reads assigned to each resultant and the amount of flux in the ramp, allowing them to interpolate from simply differencing the first and last resultants when the flux is very large to weighting the resultants by the number of reads when the flux is zero.  This approach more efficiently handles dealing with ramps that have been split by cosmic rays, and obtaining uncertainties within a few percent of the "optimal" weighting approach.  For these cases, we report final ramp slopes and variances derived from the inverse variance weighted subramp slopes and variances, using the read-noise derived variances.
 
 This is a fairly faithful representation of how level two image construction works, so there are not many additional effects to add here.  But there are some limitations:
 

diff --git a/docs/romanisim/overview.rst b/docs/romanisim/overview.rst
@@ -22,7 +22,7 @@ described by catalogs of sources.  The simulation includes:
 
 The simulator is based on galsim and most of these features directly invoke the
 equivalents in the galsim.roman package.  The chief additions of this package
-on top of the galsim.roman implementation are using "official" webbpsf
+on top of the galsim.roman implementation are using "official" stpsf
 PSFs, and many reference files from the Roman `CRDS <https://roman-crds.stsci.edu>`_ CRDS.  This
 package also implements WFI up-the-ramp sampled and averaged images like those
 that will be downlinked from the telescope, and the official Roman WFI file
@@ -61,7 +61,7 @@ adds an additional top-level branch to the asdf tree with the name
       ├─rng_seed (NoneType): None
       ├─simcatobj (NDArrayType): shape=(496,), dtype=void96
       ├─usecrds (bool): False
-      └─webbpsf (bool): True
+      └─stpsf (bool): True
 
 These fields are simply the arguments to ``romanisim-make-image``,
 plus an additional ``simcatobj`` field which contains the ``x``, ``y``,

diff --git a/docs/romanisim/psf.rst b/docs/romanisim/psf.rst
@@ -1,11 +1,11 @@
 Point Spread Function Modeling
 ==============================
 
-The simulator has two mechanisms for point source modeling.  The first uses the galsim implementation of the Roman point spread function (PSF); for more information, see the galsim Roman documentation.  The second uses the webbpsf package to make a model of the Roman PSF.
+The simulator has two mechanisms for point source modeling.  The first uses the galsim implementation of the Roman point spread function (PSF); for more information, see the galsim Roman documentation.  The second uses the stpsf package to make a model of the Roman PSF.
 
-In the current implementation, the simulator uses a linearly varying, achromatic bandpass for each filter when using webbpsf.  That is, the PSF does not vary depending on the spectrum of the source being rendered.  However, it seems straightforward to implement either of these modes in the context of galsim, albeit at some computational expense.
+In the current implementation, the simulator uses a linearly varying, achromatic bandpass for each filter when using stpsf.  That is, the PSF does not vary depending on the spectrum of the source being rendered.  However, it seems straightforward to implement either of these modes in the context of galsim, albeit at some computational expense.
 
-When using the galsim PSF, galsim's "photon shooting" mode is used for efficient rendering of chromatic sources.  When using webbpsf, FFTs are used to do the convolution of the intrinsic source profile with the PSF and pixel grid of the instrument.
+When using the galsim PSF, galsim's "photon shooting" mode is used for efficient rendering of chromatic sources.  When using stpsf, FFTs are used to do the convolution of the intrinsic source profile with the PSF and pixel grid of the instrument.
 
 .. automodapi:: romanisim.psf