snapshot_imager

snapshot_imager is a Python package for radio interferometric snapshot imaging using Non-Uniform Fast Fourier Transforms (NUFFT). It is designed to efficiently produce dirty image cubes from visibility data, with support for multiple NUFFT strategies (Type 1, Type 3, and multi-frequency synthesis) and optional GPU acceleration via CuPy and cuFINUFFT.

Installation

Install the latest release from PyPI:

pip install snapshot-imager

For GPU support (CUDA 12), install the gpu extra, which pulls in cupy-cuda12x and cufinufft:

pip install "snapshot-imager[gpu]"

For other CUDA versions, install the matching CuPy wheel (e.g. cupy-cuda11x or cupy-cuda13x) and cufinufft yourself.

macOS note: on Apple-silicon Macs, use Python 3.13 or newer. The healpy wheels for Python 3.10–3.12 (installed via hera_cal) bundle their own OpenMP runtime, which conflicts with FINUFFT's and crashes on the first imaging call.

To install from source:

git clone https://github.com/HERA-Team/snapshot_imager.git
cd snapshot_imager
pip install .

Basic Usage

The typical workflow is to unpack HERA DataContainer objects into an ImagingData container, then pass that to dirty_image.

from snapshot_imager import unpack_data_containers, dirty_image

# data, flags, and nsamples are hera_cal DataContainer objects
imaging_data = unpack_data_containers(
    data=data,
    flags=flags,
    nsamples=nsamples,
    pol="ee",
    antpos=antpos,
    freqs=freqs,
)

# One image per channel: a (ntimes, nfreqs, npix, npix) cube
result = dirty_image(imaging_data, npix=256, fov=10.0)

# One multi-frequency synthesis (MFS) image per time: (ntimes, 1, npix, npix)
mfs = dirty_image(imaging_data, npix=256, fov=10.0, mfs=True)

print(result.images.shape)

The returned ImageResult holds the image cube (indexed images[time, freq, m, l]), the pixel direction cosines l_coords and m_coords, and the times and freqs of the images. Per-channel images are normalized so a unit point source has peak 1; MFS images are the unnormalized weighted sum. Pixels below the horizon (only when fov > 90°) are NaN.

dirty_image uses a Type 1 NUFFT by default; pass method="type3" to evaluate the same image with a Type 3 NUFFT (much slower on a regular grid, mainly useful for validation).

The earlier functions snapshot_imager_type1, snapshot_imager_type3, snapshot_imager_mfs_type_1, and snapshot_imager_mfs_type_3 are still available, with their original defaults and outputs; they are thin wrappers around dirty_image.

GPU Acceleration

snapshot_imager supports GPU-accelerated imaging via CuPy and cuFINUFFT. Pass use_gpu=True:

result = dirty_image(imaging_data, npix=256, fov=10.0, use_gpu=True)

If CuPy or cuFINUFFT are not installed, or no CUDA device is available, it falls back to the CPU with a warning.

Development

Set up a development environment with the test and lint tools, and install the git hooks:

pip install -e ".[dev]"
pre-commit install

Run the test suite (GPU tests are skipped automatically when no GPU is available):

pytest --cov

Lint with ruff (this also runs on every commit via pre-commit, and in CI):

pre-commit run --all-files

Benchmark the imagers on synthetic HERA-like data (see --help for sizes and options):

python benchmarks/benchmark_imagers.py

Releasing

Versions are derived from git tags by setuptools-scm, so there is no version string to bump in the code. To publish a release to PyPI:

1. Make sure CI is passing on main.

2. Tag the release commit and push the tag:

   git tag -a v0.2.0 -m "v0.2.0"
   git push origin v0.2.0
   

3. The Publish to PyPI workflow builds the sdist and wheel and uploads them using PyPI trusted publishing. Optionally, create a GitHub release from the tag to record release notes.

License

MIT