Metadata-Version: 2.4
Name: meerkat-beams
Version: 0.0.1
Summary: MeerKAT beam interpolator
Author: landmanbester
Author-email: landmanbester <lbester@sarao.ac.za>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: hip-cargo>=0.3.0
Requires-Dist: xarray ; extra == 'full'
Requires-Dist: xarray-fits ; extra == 'full'
Requires-Dist: zarr<3 ; extra == 'full'
Requires-Dist: numcodecs ; extra == 'full'
Requires-Dist: astropy ; extra == 'full'
Requires-Dist: numpy ; extra == 'full'
Requires-Dist: scipy ; extra == 'full'
Requires-Dist: matplotlib ; extra == 'full'
Requires-Dist: wget ; extra == 'full'
Requires-Dist: gdown>=5.0.0 ; extra == 'full'
Requires-Dist: requests>=2.33.1 ; extra == 'full'
Requires-Dist: dask-ms[s3,xarray,zarr]>=0.2.23 ; extra == 'full'
Requires-Python: >=3.10, <3.14
Project-URL: Homepage, https://github.com/landmanbester/meerkat-beams
Project-URL: Repository, https://github.com/landmanbester/meerkat-beams
Project-URL: Bug Tracker, https://github.com/landmanbester/meerkat-beams/issues
Provides-Extra: full
Description-Content-Type: text/markdown

# 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

```bash
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

| Python | Support |
|---|---|
| 3.11 – 3.13 | Full: `[full]` scientific stack, tested in CI |
| 3.10 | Lightweight only: base install (CLI + hip-cargo container dispatch via `--backend docker/podman/...`). The `[full]` stack is neither tested nor supported on 3.10. |

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:

```python
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`](https://github.com/caracal-pipeline/hip-cargo) and supports both native execution and container dispatch (`--backend apptainer|singularity|docker|podman`).

```bash
# 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

```bash
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.
