convolve-rs

Documentation for the Python API, CLI and algorithms is at convolve-rs.readthedocs.io. The Rust API is at docs.rs/convolve-rs.

A Rust port of beamcon from RACS-tools. It smooths FITS images and spectral cubes to a common beam. The convolution is done in the UV plane (FFT), which avoids numerical problems with undersampled kernels.

Note: this is an experiment in LLM-assisted coding with Claude. Do not trust this software as far as you can throw it.

Installation

Python library

pip install convolve-rs

CLI binary

Requires Rust 1.85+.

cargo install convolve-rs

Usage

• Python API and quickstart: convolve-rs.readthedocs.io/en/latest/quickstart.html
• CLI reference: convolve-rs.readthedocs.io/en/latest/cli.html
• Rust API: docs.rs/convolve-rs

Development

Install in editable mode:

uv pip install -e .

After changing the Python-facing Rust API in src/python.rs, rebuild with the stubgen feature (the default build omits _generate_stubs) and regenerate the type stubs:

uv run maturin develop --features stubgen
uv run --no-sync python -c "from convolve_rs._convolve_rs import _generate_stubs; _generate_stubs()"

This overwrites convolve_rs/_convolve_rs.pyi from the Rust annotations and docstrings. Commit it with the API change.

Running tests

Python tests need the compiled extension and the test extra (pytest, radio-beam, astropy). uv sync builds the extension into .venv. uvx pytest does not work, because it runs in an isolated environment without the module or its dependencies.

uv sync --extra test       # builds the extension + installs test deps
uv run --no-sync pytest

Rust tests run with cargo test. One integration test compares output with MIRIAD. Set MIRIAD_BIN to a MIRIAD bin directory to run it; it is skipped otherwise.

cargo test
MIRIAD_BIN=/path/to/miriad/bin cargo test   # include the MIRIAD comparison

Pre-commit hooks

Formatters and linters run with prek, a reimplementation of pre-commit. The hooks in .pre-commit-config.yaml are the checks CI runs: ruff lint and format, ty type checking, cargo fmt and cargo clippy.

uv sync --extra dev   # installs prek + ty into the venv
uvx prek install      # install the git hook (runs on every commit)
uvx prek run --all-files   # run all hooks manually

License

convolve-rs is released under the BSD 3-Clause License.

The UV-plane convolution and cube handling are ported from RACS-tools. The common-beam computation follows radio_beam. Both are BSD licensed. The beam algebra uses the formulae of Wild (1970). MIRIAD (GPL) is used as a reference in the tests. See NOTICE.md for full attributions.