meerkat-beams

MeerKAT primary-beam model handling: download MdV beam files from the SARAO archive (https://doi.org/10.48479/wdb0-h061), convert them to a beam dataset (BDS), and render time/frequency-resolved primary beams to xradio-compatible zarr stores.

Installation

pip install meerkat-beams[full]

The [full] extra pulls in the scientific stack (xarray, zarr<3, astropy, scipy, numpy, matplotlib, dask-ms, wget, gdown). Use plain meerkat-beams only if you need the CLI metadata for Stimela without running the implementations locally.

Python support

On 3.10 the base install lets you run every mbeams command by dispatching the actual computation to the container image — nothing scientific runs natively. CI pins this with a dedicated lightweight-install job; the test matrix itself starts at 3.11 (do not add 3.10 to it).

Quick start — auto-downloading cache

The simplest path is to construct a BeamWizard with just the MeerKAT band code; the mean-beam zarr is downloaded from Google Drive on first use and cached locally:

from meerkat_beams.utils import BeamWizard

bw = BeamWizard(band="L", image_name="my_image.fits")
beam_gain = bw.get_time_variable_beamgain(source_coord, times=obs_times)

Supported bands: U, L, S0, S4. (S1, S2, S3 have no published Google Drive ID — pass bds_name= directly for those.)

Cache layout

$MBEAMS_CACHE_DIR/  (or $XDG_CACHE_HOME/meerkat-beams, or ~/.cache/meerkat-beams)
├── inputs/MeerKAT_<BAND>.zarr/    # downloaded mean-beam zarr
└── bds/MeerKAT_<BAND>.bds.zarr/   # locally built compressed BDS

Subsequent constructions of BeamWizard(band=...) reuse the cached BDS. To warm a band ahead of time, just instantiate the wizard once.

Concurrency: the first-time download is not locked. Warm each band from a single process before fanning out.

CLI

The mbeams command wraps each stage of the pipeline. The CLI is generated by hip-cargo and supports both native execution and container dispatch (--backend apptainer|singularity|docker|podman).

# Download an MdV beam from SARAO (band code, filename, or full URL)
mbeams download-mdv-beams --source L

# Convert MdV .npz (or mean-beam zarr) to a BDS
mbeams mdv-beams-to-bds --mdv-beams input.npz --bds output.bds.zarr --compress

# Render a BDS to an xradio-compatible zarr along an image's WCS / time axis
mbeams bds-to-xradio --bds-path beam.bds.zarr --image-path image.zarr --output beam_xradio.zarr

# Shortcut: dump one Jones element / component of an MdV .npz directly to an xradio zarr
mbeams mdv-to-xradio --npz-path input.npz --output beam_xradio.zarr --jones HH --part real

Each command accepts --help. The container-dispatch path is opt-in (--backend defaults to auto → native).

Development

uv sync --group dev --group test
uv run ruff check . && uv run ruff format --check .
uv run pytest -m unit                           # hermetic unit tests
MBEAMS_OFFLINE=1 uv run pytest -m unit          # strict-hermetic (skip L-band warm-up)
uv run pytest                                   # full suite (integration tests may skip)
bash scripts/genfuncs.sh                        # regenerate cli/*.py from cabs/*.yml

See CLAUDE.md for the full architecture, conventions, and test layout.