Merge pull request #209 from punch-mission/rework

Full rewrite for speed and logical simplicity

Author: jmbhughes

.codespellignore

@@ -35,6 +35,18 @@ jobs:
     - name: Lint with ruff
       run: |
         ruff check .
+    - name: Run codespell on source code
+      uses: codespell-project/actions-codespell@v2
+      with:
+        skip: '*.fits,*.ipynb'
+        ignore_words_file: .codespellignore
+        path: punchbowl
+    - name: Run codespell on documentation
+      uses: codespell-project/actions-codespell@v2
+      with:
+        skip: '*.fits,*.ipynb'
+        ignore_words_file: .codespellignore
+        path: docs/source
     - name: Test with pytest
       run: |
         coverage run -m pytest

.github/workflows/ci.yml

@@ -1,66 +1,36 @@
-name: Build and upload to PyPI
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
 
-on:
-  workflow_dispatch:
-#  pull_request:
-#  push:
-#    branches:
-#      - main
-  release:
-    types:
-      - published
-
-jobs:
-  build_wheels:
-    name: Build wheels on ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        # macos-13 is an intel runner, macos-14 is apple silicon
-        os: [ubuntu-latest, macos-13, macos-14]
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Build wheels
-        uses: pypa/[email protected]
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
 
-      - uses: actions/upload-artifact@v4
-        with:
-          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
-          path: ./wheelhouse/*.whl
+name: Upload Python Package
 
-  build_sdist:
-    name: Build source distribution
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Build sdist
-        run: pipx run build --sdist
+on:
+  release:
+    types: [published]
 
-      - uses: actions/upload-artifact@v4
-        with:
-          name: cibw-sdist
-          path: dist/*.tar.gz
+permissions:
+  contents: read
 
-  upload_pypi:
-    needs: [build_wheels, build_sdist]
+jobs:
+  deploy:
     runs-on: ubuntu-latest
-    environment: pypi
     permissions:
-      id-token: write
-    if: github.event_name == 'release' && github.event.action == 'published'
-    # or, alternatively, upload to PyPI on every tag starting with 'v' (remove on: release above to use this)
-    # if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
     steps:
-      - uses: actions/download-artifact@v4
-        with:
-          # unpacks all CIBW artifacts into dist/
-          pattern: cibw-*
-          path: dist
-          merge-multiple: true
-
-      - uses: pypa/gh-action-pypi-publish@release/v1
-#        with:
-          # To test: repository-url: https://test.pypi.org/legacy/
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build -s
+    - name: Publish package distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/python-publish.yml

@@ -11,6 +11,12 @@ repos:
     hooks:
       - id: isort
         exclude: ".*(.fits|.fts|.fit|.header|.txt|tca.*|extern.*|sunpy/extern)$"
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.1.0
+    hooks:
+      - id: codespell
+        files: ^.*\.(py|c|h|md|rst|yml)$
+        args: [ "--ignore-words", ".codespellignore" ]
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ authors:
   given-names: "Daniel"
   orcid: "https://orcid.org/0000-0002-0494-2025"
 title: "regularizepsf"
-version: 0.4.0
+version: 1.0.0
 doi: 10.5281/zenodo.7392170
-date-released: 2024-08-18
+date-released: 2024-09-09
 url: "https://github.com/punch-mission/regularizepsf"

CITATION.cff

@@ -19,4 +19,4 @@ To cite `the associated paper <https://iopscience.iop.org/article/10.3847/1538-3
 
 
 If you use this software, please also cite the package with the specific version used.
-`Zenodo always has the most up-to-date citation. <https://zenodo.org/records/10066960>`
+`Zenodo always has the most up-to-date citation. <https://zenodo.org/records/10066960>`_

docs/source/cite.rst

@@ -9,32 +9,24 @@ A point spread function (PSF) describes how the optical system spreads light fro
 The basic premise of this technique is to model the point spread function of an imager using stars as our point sources.
 Then, we calculate the inverse PSF and apply it. We could directly convolve the inverse PSF but convolutions are slow.
 A convolution in the image is the same as multiplying in Fourier space, a much faster operation, so we do that instead.
-Instead of simply calculating the inverse PSF directly, we also include a *target PSF* model to make the resulting corrected
-stars uniform. This target is typically a Gaussian as shown below in the :doc:`examples`.
+This package supports defining a PSF transformation from any input PSF to any target PSF.
 
 Since the PSF can vary across the image, we create many local models that apply only in smaller regions of the image.
 These regions overlap so the correction is smooth without hard transition edges.
 
-Purpose of the target PSF
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-We need a target PSF because we not only correct the PSF but homogenize to a standard PSF.
-This is necessary because a correction without applying a target could result in different PSFs across the image,
-e.g. you might correct the center of the image much better than the edges because the center was more well behaved to begin with.
-For our purposes on the PUNCH mission, we need the resulting PSF to be the same everywhere.
-Thus, we apply a standardized target PSF as well as inverting the observed PSF.
-
 Overview of the package
 ------------------------
 The package has a few main components:
 
-1. Fitting routines in ``regularizepsf.fitter``
-2. PSF correction tools in ``regularizepsf.corrector``
-3. Visualization utilities in ``regularizepsf.visualize``
+1. Representations of PSFs in ``regularizepsf.psf``
+2. A method of transforming a PSF from one to another in ``regularizepsf.transform``
+3. Routines to model a PSF from data in ``regularizepsf.builder``
+4. Extra visualization tools in ``regularizepsf.visualize``
+
+PSFs can be represented in three ways:
 
-The most commonly used fitting routine is ``CoordinatePatchCollection.find_stars_and_average`` as demonstrated in :doc:`examples`.
-This can then be converted to an ``ArrayCorrector``, the most commonly used PSF correction tool, by adding the target PSF.
-This ``ArrayCorrector`` then can be applied to any new image using the associated ``correct_image`` method on it.
-Finally, there are many visualizations to assist in understanding the results and derived PSF models. These are
-outlined in :doc:`visualization`.
+1. `simple_functional_psf`: the PSF is described as a mathematical function that doesn't vary across an image
+2. `varied_functional_psf`: the PSF is described as a mathematical function that varies across the image
+3. `ArrayPSF`: the PSF is described using many small arrays, avoiding the need to find an expressive functional model
 
-To speed up computation of the many FFTs, the correction is done in Cython in the ``helper.pyx`` file.
+Using a set of images, we can extract `ArrayPSF`s directly and quickly correct an image.

docs/source/concepts.rst

@@ -27,7 +27,9 @@
 
 extensions = ["autoapi.extension",
               "sphinx.ext.autodoc",
-              "sphinx.ext.napoleon"]
+              "sphinx.ext.napoleon",
+              "nbsphinx",
+              "IPython.sphinxext.ipython_console_highlighting"]
 
 templates_path = ["_templates"]
 exclude_patterns = []

docs/source/conf.py

@@ -4,36 +4,30 @@ We encourage all contributions. Please see our `contribution guide first <https:
 
 We recommend working in a virtual environment.
 This can be created by running ``python -m venv venv``. Then, activate the environment with ``source venv/bin/activate``.
-You can then install the required packages with ``pip install ".[test]"``.
+You can then install the required packages with ``pip install ".[dev]"``.
 
 If at any time you run into issues, please contact us by :doc:`following the guidelines here <help>`.
 
 Setting up pre-commit
 ----------------------
 
 The first time you develop code, you'll need to install the pre-commit. This checks that our style is consistent.
-It gets installed when you do ``pip install ".[test]"`` but then requires you to activate them by
-running ``pre-commit install``. Now everytime you commit, our checks will run first.
+It gets installed when you do ``pip install ".[dev]"`` but then requires you to activate them by
+running ``pre-commit install``. Now every time you commit, our checks will run first.
 
 Building the docs
 ------------------
 The docs are built using ``sphinx``. First, you must install it and the other documentation requirements with ::
 
-    pip install -r ./docs/requirements.txt
-    pip install ".[test]"
-    python setup.py build_ext --inplace
+    pip install ".[docs]"
 
 Then, navigate to the ``docs`` directory and run ``make html`` to build the docs.
 
+We use ReadTheDocs, so a preview of the docs are built with each PR.
+That makes it easier to check updates without manually building.
+
 Running tests
 -------------
 To run the tests for this package, run ``pytest`` in the repository base directory.
 
-This repository includes tests for the plotting utilities which compare generated plots to reference images saved in
-``tests/baseline``.
-To include these image-comparison tests, run ``pytest --mpl``.
-To update these reference images, run ``pytest --mpl --mpl-generate-path=tests/baseline``.
-
-If the image-comparison tests are failing,
-run ``pytest --mpl --mpl-generate-summary=html`` to generate a summary page showing the generated and reference images.
-The location of the generated file will be shown at the end of ``pytest``'s command-line output.
+Tests are automatically run for pull requests.