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, astropy, scipy, numpy, matplotlib, dask, wget, gdown, plus hip-cargo[s3] for s3:// paths). Use plain meerkat-beams only if you need the CLI metadata for Stimela without running the implementations locally. Every store the package writes is zarr format 2, whether zarr-python 2 or 3 is installed, so its output stays readable by either.

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.