PSF Matching

dfpsf is a Python package for performing PSF matching using the Stochastic Gradient Langevin Dynamics (SGLD) algorithm. The primary use-case envisaged is the matching of two point spread functions (PSFs) in astronomical imaging; the code will find the optimal convolutional kernels that minimize the difference between the two PSFs. Mathematically, we can formulate this problem as trying to solve the following equation:

$$PSF_1 \otimes K_1 = PSF_2 \otimes K_2$$

where we are solving for $K_1$ and $K_2$ such that they are as small as possible while minimizing the difference between the convolutions. To do this, we parametrize the solutions as linear combinations of Gaussian basis functions and solve a minimization problem using SGLD. This implementation has been developed using PyTorch in order to reduce computational costs and allow for GPU acceleration. For information on the algorithm behind this code, please see our paper.

Installation

In order to use this code, please do the following after downloading this repo.

1. Create the conda environment

   conda env create -f environment.yml

2. Install the package

   pip install -e .

Simple Usage

Assuming that you have already computed PSFs from two images, you can use dfpsf to find the optimal kernels with the following command:

from dfpsf.doubleKernel.matchingPSF import optimize_psf_langevin

best_params, _ = optimize_psf_langevin(source_psf, target_psf, cen=source_psf.shape[1] / 2, n_steps=2000, device='cuda')

This command will return the parameters of the optimal kernels.

For a more indepth demonstration of the standard dfpsf workflow, please see demo/demo1.ipynb.

Toy Problems

In demo, we have several examples demonstrating how the SGLD algorithm can solve instructive toy problems in both the single kernel and double kernel cases.

Double Kernel

We have the following double kernel examples (see demo/doubleKernel):

1. Both PSFs are identical and simple Gaussians. The convolutional kernels are points.

2. PSF 2 is a puffier version of PSF 1.

3. PSF 2 is a convolution of PSF 1 with an elliptical Gaussian with non-trivial stretching and position angle

4. PSF 1 and PSF 2 are both puffy versions of the original Gaussian source. PSF 2 is still a convolution of PSF 1 with an elliptical Gaussian with non-trivial streching and position angle

5. PSF 1 and and PSF 2 are convolved by different elliptical Gaussian kernels with non-trivial stretching and position angles.

Single Kernel

Similarly, we repeat toy problems 1-3 for the single kernel case (see demo/singleKernel).

PSF Calculation

In order to use the PSF matching tool in real data, we need a method for extracting the PSF from an image (or a tile of an image). To do this, we use the photutils library. The code works as follows:

1. Using DAOStarFinder, find all the stars in the image
2. Use photutils.psf.extract_stars to extract the psfs from the stars
3. Use photutils.psf.EPSFBuilder to create the final ePSF

After running the code ePSF.create_espf.py, you will have a psf for a tiled region.

Please note that we assume a constant background over the tiled region when creating the PSFs.

You can find a demo of this functionality in demo/ePSF-Creation.

Notes

• In case the user is interested in solving the classical single PSF convolution problem, we provide the required functionality in dfpsf.singleKernel. The function can be called with the following:

from dfpsf.singleKernel.matchingPSF_single import optimize_psf_langevin

best_params, _ = optimize_psf_langevin(source_psf, target_psf, cen=source_psf.shape[1] / 2, n_steps=2000, device='cuda')

Testing

The package includes comprehensive unit and integration tests that are automatically run via GitHub Actions on every push and pull request. To run the tests locally:

# Run all tests
pytest

# Run only unit tests
pytest tests/unit

# Run only integration tests
pytest tests/integration

CI Pipeline: Unit tests run first with coverage checking (minimum 80%). If they pass, integration tests are then executed. Integration tests are based on the toy problems in the demo/ directory.

AI Disclaimer

We used Claude.ai to help generate the unit tests. However, all the source code was written by us.