Developer guide¶
For algorithm scientists and software engineers who change rang and contribute the change back, with or without an agent. The rules are in AGENTS.md, Part 1; the pull-request route is Contributing; what counts as a gain is Claims: propose, freeze, measure.
Architecture¶
python/rang/ Python: command line, configuration, pipeline, notebooks, research drivers
│ NumPy arrays borrowed in place, GIL released around every kernel
▼
core/py/ (rang-core-py) PyO3 extension rang._core; no kernel code, only bindings
│ C ABI of rang_core::ffi* (#[repr(C)] structs, explicit lengths, status codes)
▼
core/ (rang-core) the kernels: MS reader and table writer, solvers, calibration,
SumThreshold, weights, gridders, GeMClean, predictor, GPU (feature gpu)
src/ (rang-sim) the root crate: the pointing simulation, gain TV, projector, trend;
linked into the extension as rang_core::sim
Rust for kernels, Python for interfaces, orchestration and experiment scripts. A new numerical kernel goes in
core/src/, gets a C-ABI function in anffi_*.rs, a binding incore/py/src/, and a thin wrapper inpython/rang/core_*.pyorcal_*.py. Importingrangnever runs Cargo (research/p7-architecture.md).GPU where it pays, behind the core’s
gpufeature (wgpu). Every GPU path has a CPU path with the same result within a written tolerance; the wheels are CPU only (research/x2-wgpu.md).Telescope specifics stay behind
python/rang/meerkat.pyand the refusals of research/w4-unsupported.md; nothing is generalised before a second telescope’s data and oracle exist (research/meerkat-scope.md).The JAX path of the pointing solver (
rang.pointing, thepointingextra) is a deliberate reference implementation beside the Rust baseline.
Where things are¶
Path |
What |
|---|---|
|
the command line, the configuration schema and refusals, the stages and resume, write-back with flag versions and a journal |
|
the calibration terms, apply, calibrator models |
|
CASA tables, flag versions, QuartiCal stores, sky models, H5parm, killMS |
|
what the notebooks import: data, plots, the frozen rules they quote |
|
CASA-style solves and apply; QuartiCal’s |
|
the casacore table reader and writer |
|
Tricolour, WSClean weights, w-stacking, ducc0’s wgridder |
|
GeMClean and the CLEAN study |
|
the frozen campaigns: recipes, containers and modules, not edited |
|
the notes and compact result archives; |
|
Lean proofs of the CLEAN theory (research/clean-theory.md) |
The Concepts pages give each port with its oracle; the API reference is generated from the docstrings.
Build¶
From a checkout, with Rust 1.93 and cargo on PATH (Installation,
“From source”):
python -m pip install --index-url https://pypi.org/simple \
-e '.[pointing,beam,test,imaging,formats,notebook,docs]' ruff maturin
maturin develop --release # after every Rust change; Python never runs Cargo
A build from a checkout targets x86-64-v3 (.cargo/config.toml); set
RUSTFLAGS="-C target-cpu=x86-64" for a CPU without AVX2 and FMA, as the
wheels do. The GPU paths: cargo test --release --manifest-path core/Cargo.toml --features gpu, and maturin develop --release --features gpu for the
extension.
Test¶
python -m pytest -q # or -n 8 with pytest-xdist
python -m rang.check # every check before a commit: fmt, clippy, cargo test, ruff, pytest, ...
python -m rang.check (also rang-core check, bash tools/check-all.sh)
runs every Rust and Python step and prints PASS or FAIL per step and
overall: PASS; Contributing lists the steps. Some tests read
archived outputs or need an oracle (CASA, QuartiCal, WSClean) and skip
without them; CI has neither, so their gates run only in this local check,
and a pull request reports its result. On a shared host run it under
python tools/heavy_lock.py run --slots N --mem G -- ....
The docs: python docs/execute_notebooks.py (optional; needs the public
fixture), then sphinx-build -W --keep-going -b html docs docs/_build/html,
which must build without a warning. docs/cli.md is generated:
python docs/gen_cli.py after a change to a help text.
Conventions that tests enforce¶
Every source file starts with an SPDX line; a port names the upstream licence too and keeps its notice (tests/test_spdx_headers.py, Licence and acknowledgements).
The version is written once, in
pyproject.toml(tests/test_w4_5_release.py).Every note in
research/is linked fromresearch/README.md; the README stays short, with absolute links (tests/test_w4_8_docs.py).Every repository link on this site names a file that exists (tests/test_d1_docs.py).
Verbatim extracts of frozen modules stay byte-identical (tests/test_p11_extract.py).
With an agent¶
Open any agent in a checkout; AGENTS.md is written for it. The task
procedures are in Task procedures for agents: Propose and measure an algorithm change
for an algorithm change, Image a MeerKAT Measurement Set and
Answer a beginner’s question for the other audiences. Claude Code also
finds them as skills in .claude/skills/.