Quickstart

From nothing to a calibrated, deconvolved MeerKAT image in about a minute, on A1 small: rang’s simulated L-band observation (16 antennas, 64 channels, 41 MB, written from seeds; research/a1-simtruth.md), so every number can be checked against the truth. The same chain runs in CI on all five wheels (tools/e2e/run.py).

Note

Use rang-core 0.2.0 or later, because 0.1.0 predates rang-core run and gemclean. The generator examples/a1_simtruth.py and the example configuration are in a source checkout (Installation, “From source”).

1. Install from source

Linux or macOS:

git clone https://github.com/gijzelaerr/rang-core && cd rang-core
python3 -m venv .venv
.venv/bin/python -m pip install --index-url https://pypi.org/simple -e '.[notebook]'
source .venv/bin/activate

Windows (PowerShell):

git clone https://github.com/gijzelaerr/rang-core; cd rang-core
py -3.14 -m venv .venv
.venv\Scripts\python -m pip install --index-url https://pypi.org/simple -e ".[notebook]"
.venv\Scripts\Activate.ps1

This needs Rust 1.93 and cargo on PATH; maturin builds the extension rang._core during the install. Check it:

rang-core -h
gemclean -h

2. Write A1 small

mkdir work && cd work
python ../examples/a1_simtruth.py generate small . --workers 2

This writes a1-small.ms, the truth (truth.json, truth.npz), the RFI mask (a1-small.rfi_mask.npz) and the provenance with seeds and hashes, in about 4 s.

3. Configure and check

cp ../examples/ms-to-image/config.yaml ../examples/ms-to-image/strategy.yaml .
rang-core config check config.yaml a1-small.ms

examples/ms-to-image/config.yaml is CARACal’s continuum chain in Stokes I: the Tricolour port on DATA; K, G, B on the flux calibrator J1939-6342 (PKS 1934−638, Stevens-Reynolds 2016); G and the flux scale F on the gain calibrator; applied to the target; one 1024² GeMClean image at 3″, Briggs 0. config check validates the whole file against the schema and the MS and reports every problem at once, exit 2 if there is one.

4. Run

rang-core run config.yaml a1-small.ms

The MS is written in place (FLAG, MODEL_DATA, CORRECTED_DATA); everything else goes into a1-small.ms.rang-run/:

Path

Contents

state.json

each stage’s status, wall time and configuration hash

calibrate/

the CASA tables K, G, B, Gsec, F

image/SIM-TARGET/

image-image.fits, -model, -residual, -dirty, -psf

receipts/

one rang.receipt (version 5) per command

Beside the MS, a1-small.ms.flagversions/ holds the CASA flag versions: rang_original, saved before the first write, and one per writing stage.

Run the same command again: every finished stage with an unchanged configuration is skipped. A changed one is refused unless you pass --force STAGE.

What CI measures on this run (Windows x86_64, 2026-11-11; research/e4-tutorial.md): flagged fraction 0.364, brightest peak 0.4957 Jy against a true 0.500 Jy, residual rms 0.70 mJy, restoring beam 29.0″ × 4.97″. On other platforms the numbers differ in the last digits; images are not byte-identical across platforms (Known limits).

5. Image directly with gemclean

gemclean takes WSClean-style options and images a Measurement Set without a configuration:

gemclean -name direct -size 1024 1024 -scale 3asec -weight briggs 0 \
    -niter 20000 -auto-threshold 3 -data-column CORRECTED_DATA \
    -no-update-model-required a1-small.ms

-no-update-model-required keeps MODEL_DATA as it is; by default gemclean writes the model column, as WSClean does.

Next