limTOD 1.3.0__tar.gz

limtod-1.3.0/CHANGELOG.md

@@ -0,0 +1,215 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.3.0] - 2026-07-25
+
+### Added
+
+- 🚀 **`limtod_jax` package**: pure-JAX, differentiable port of the sky→TOD
+  chain (pointing → ZYZ Euler angles → Wigner rotation of beam alms →
+  beam-weighted harmonic dot), implementing the e-RHINO
+  `docs/limtod-port-contract.md`. Ships `zyz_of_pointing`, `rotate_alm`,
+  `beam_weighted_sum`, `generate_tod_sky` (+ exact adjoint),
+  `generate_projection_rows`, and JAX-side HEALPix map↔alm wrappers.
+  Matches `limTOD.simulator.generate_TOD_sky(..., truncate_frac_thres=0.0)`
+  to ~1e-12 relative in float64 (oracle-tested at extreme pointing corners);
+  jit/vmap/grad-safe. Install with `pip install -e ".[jax]"` (Python ≥ 3.11).
+- 📦 **Dependency extras**: `[mpi]` (mpi4py), `[gdsm]` (pygdsm), `[jax]`
+  (jax + s2fft), and `[full]` (all of the above).
+- 🛡️ **MPI launcher guard**: importing limTOD under `mpirun`/`srun`
+  *without* mpi4py now raises a clear `RuntimeError` instead of silently
+  running N duplicated serial copies (each process believing it is rank 0).
+  Escape hatch for intentionally independent serial copies:
+  `LIMTOD_FORCE_SERIAL=1`.
+- 🚢 **First PyPI release**: `pip install limTOD`.
+
+### Code quality (post-review polish)
+
+- ✅ **New test suites**: full-Stokes physical invariants (spin structure,
+  1D/3-row/4-row consistency, linearity, normalization) pin the polarized
+  chain the Stokes-I oracle never covered; a flicker-noise boundary sweep
+  over (alpha, fc, tau) corners; and an independent end-to-end
+  `HPW_mapmaking` oracle that rebuilds the regularized normal equations in
+  the test (unfiltered, priors, per-TOD noise variance, high-pass
+  consistency, gain/injection calibration).
+- 🧾 **Type annotations** across the numpy package (`mypy
+  --disallow-untyped-defs` clean); the previously dead ArrayLike aliases
+  are now used.
+- 🪵 **Logging**: all library `print()` calls migrated to module loggers
+  (`logging.getLogger`); informational output is now opt-in via standard
+  logging configuration instead of unconditional stdout, and MPI ranks no
+  longer duplicate messages.
+- 🧩 **`HPW_mapmaking.__call__` decomposed** into `_filter_and_stack`,
+  `_build_priors`, and `_normalize_noise_variance` (behavior pinned
+  bit-exact by the new oracle tests before refactoring).
+- 📓 Notebooks that require external, non-shipped data
+  (`demonstration.ipynb`, `RotatingBeam/baseSim*.ipynb`) now carry a
+  warning cell up top instead of failing with a bare `FileNotFoundError`.
+
+### Documentation
+
+- 📚 **Restructured**: README is now a concise landing page (install,
+  quick starts, citation); detailed guides moved to `docs/`
+  (tod-simulation, mapmaking, theory & conventions, api-reference,
+  limtod-jax). Fixed duplicated/garbled parameter listings, broken
+  fences, and case-mismatched notebook links from the old monolithic
+  README.
+
+### Packaging
+
+- Version is single-sourced from `pyproject.toml`: both
+  `limTOD.__version__` and `limtod_jax.__version__` read the installed
+  distribution metadata (the hardcoded copies had drifted once).
+- Modernized metadata (SPDX license expression + `license-files`,
+  Python 3.12/3.13 classifiers, Documentation/Changelog URLs) and a lean
+  sdist (packages + docs + CHANGELOG; notebooks/data stay on GitHub).
+
+### Changed
+
+- **Fresh-install default changed**: `mpi4py` and `pygdsm` are no longer
+  required dependencies — a plain `pip install -e .` now installs a lighter,
+  wheel-only stack (numpy, healpy, astropy, scipy, tqdm, mpmath). Rationale:
+  mpi4py needs a system MPI toolchain and pygdsm downloads sky-model data,
+  both an unnecessary burden for downstream users (e.g. e-RHINO) who only
+  consume the JAX port. **Existing environments are unaffected** (already-
+  installed packages stay); for a fresh full setup use
+  `pip install -e ".[full]"`, for MPI runs `.[mpi]`, for GDSM skies `.[gdsm]`.
+- `limTOD.mpiutil` falls back to serial mode (`rank=0, size=1, world=None`)
+  when mpi4py is absent — restoring the graceful-degradation behavior of the
+  upstream caput `mpiutil` it is adapted from. With mpi4py installed,
+  behavior is unchanged.
+- `GDSM_sky_model` imports pygdsm lazily and raises a clear `ImportError`
+  pointing at `pip install "limTOD[gdsm]"` when it is missing. All other
+  functionality works without pygdsm.
+
+### Fixed
+
+Pre-release full-code review (independent numpy-side and JAX-side passes)
+caught and fixed, with regression tests for each:
+
+- 🐛 **`horizontal_mask` orientation**: the horizontal-frame mask was
+  rotated with `elevation=0` instead of the zenith pointing
+  (`elevation=90`), tipping it 90° onto the horizon — every masked
+  simulation placed the mask at the wrong sky location. Fixed; a
+  regression test pins the mask cap to (RA = LST, Dec = latitude).
+- 🐛 **Silent NaN from zero-sum beams**: `normalize_beam`/`normalize=True`
+  divided by the beam's pixel sum unguarded; a fully-truncated or
+  fully-masked pointing silently poisoned the TOD with NaN. Now raises a
+  clear `ValueError` naming the pointing conditions; negative beam sums
+  scale all Stokes rows consistently (previously Q/U/V were left
+  unscaled).
+- 🐛 **Flicker-noise error handling**: `aux_int` no longer swallows
+  mpmath errors into a printed message plus a fabricated `inf`
+  (it raises with context); `flicker_corr`/`sim_noise` explicitly reject
+  the singular `alpha=1` exponent instead of failing type-dependently.
+- 🐛 **`wiener_filter_map` short TODs**: the default rolling-variance
+  estimator crashed with an opaque matmul error for TODs shorter than its
+  100-sample window; the window now caps at the TOD length and mismatched
+  `noise_variance` lengths raise a clear error.
+- 🐛 **`HPW_mapmaking` prior routing**: mixed 1D/2D
+  `Tsys_other_prior_inv_cov_group` elements were all routed by the FIRST
+  element's dimensionality, silently discarding off-diagonal covariance
+  entries; each element now routes by its own shape.
+- 🐛 **`generate_gaussian_field(seed=None)`** no longer reseeds the global
+  NumPy RNG from OS entropy (which clobbered callers' reproducibility
+  seeding); it only seeds when a seed is given.
+- 🐛 **Bugs surfaced by the typing pass** (all regression-tested):
+  `HPW_mapmaking(return_full_cov=True)` crashed unpacking
+  `wiener_filter_map`'s 3-tuple — the posterior covariance is now returned
+  as the final element; `wiener_filter_map` no longer hits a `NameError`
+  when the covariance is uncomputable (clear `LinAlgError` instead);
+  `Tsys_others_operator_group` accepts the documented bare-2D-array form
+  (and validates its length against the number of TODs);
+  `sim_noise` accepts a plain Python list `time_list` as documented.
+- Pointing-array length mismatches now raise upfront (zip previously
+  truncated silently); MPI-unsafe unconditional prints are rank-0-gated;
+  `HPW_mapmaking` argument validation raises `ValueError` instead of
+  `assert` (which `python -O` strips); example scripts' obfuscated
+  serializer imports (written to dodge a security hook) were replaced with
+  plain, warning-commented imports.
+- Aligned `pyproject.toml`/`limTOD.__version__` (stuck at 1.1.0) with the
+  changelog version history.
+
+## [1.2.0] - 2025-10-06
+
+### Added
+
+- Add `CHANGELOG.md`
+
+### Changed
+
+- **BREAKING**: Renamed `TODsim` class to `TODSim` for better Python naming conventions
+- Renamed old `limTODsim` class references to `TODSim` throughout codebase
+- Updated all import statements and class instantiations to use `TODSim`
+- Updated `__init__.py` and `__all__` exports to reflect new class name
+
+### Improved
+
+- 📝 **Documentation**:
+  - **Structure**: Moved "Latest Updates" section from README.md to dedicated CHANGELOG.md file
+  - 📋 **Table of Contents**: Updated README.md Table of Contents to accurately reflect document structure
+  - **Examples**: Removed in flavour of example notebooks to simplify maintainace
+- 🔧 **Code Organization**:
+  - Move example notebooks to `examples/`
+  - Improved consistency in class naming across all files including:
+    - Source code (`simulator.py`)
+    - Package exports (`__init__.py`)
+    - Documentation (`README.md`)
+    - Example notebooks (`examples.ipynb`, `mm_example.ipynb`)
+    - Change Log (`CHANGELOG.md`)
+
+### Fixed
+
+- Corrected all references to use consistent `TODSim` class name
+- Fixed import statements in example notebooks and documentation
+
+## [1.1.0] - 2025-10-05
+
+### Added
+
+- 🎯 **Full Stokes Support**: Added complete polarization handling (I, Q, U, V) for both TOD simulation and map-making
+- 🗺️ **Map-Making Pipeline**: Implemented `HPW_mapmaking` class combining high-pass filtering and Wiener filtering for sky reconstruction from TOD
+- 🎲 **Gaussian Random Field Generator**: Added generator for correlated sky realizations from frequency-frequency angular power spectra C_ℓ(ν,ν'), enabling realistic simulation of line intensity mapping signals with spectral correlations (credit: Katrine Alice Glasscock, Philip Bull)
+- 📓 **Example Notebooks**: Added comprehensive Jupyter notebook demonstrating the full map-making workflow ([examples/mm_example.ipynb](examples/mm_example.ipynb))
+
+### Changed
+
+- **BREAKING**: `beam_func` and `sky_func` now require keyword-only arguments, two of which must be `freq` and `nside`:
+
+  ```python
+  # Old: beam_func(freq, nside) and sky_func(freq, nside)
+  # New: beam_func(freq=xx, nside=xx) and sky_func(freq=xx, nside=xx)
+  ```
+
+- **BREAKING**: Function outputs must be HEALPix maps with specific shapes:
+  - 1D array of length npix for unpolarized (**I**) beam/sky
+  - 2D array of shape (3, npix) for polarized (**I, Q, U**) beam/sky
+  - 2D array of shape (4, npix) for polarized (**I, Q, U, V**) beam/sky
+
+### Fixed
+
+- 🐛 **Bug Fix**: Corrected a critical sign error in coordinate rotation transformations
+
+## [1.0.0] - 2025-09-01
+
+### Initial Release
+
+- Initial release of limTOD: Time-Ordered Data simulation for single-dish radio telescopes
+
+### Key Features
+
+- TOD simulation with realistic noise models (1/f noise, white noise, gain variations)
+- Support for asymmetric beam patterns
+- Direct beam convolution using HEALPix spherical harmonics rotation and sum to calculate Tsky
+- Flexible beam and sky model functions
+- Global Sky Model (GDSM) integration
+- MPI parallelization support
+- Example scanning patterns and beam models
+- Example notebooks for getting started
+- Documentation and examples

limtod-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zheng Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

limtod-1.3.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# sdist contents beyond the packages themselves. Deliberately lean: the big
+# example notebooks/data and conventions.pdf stay on GitHub (linked from docs).
+include CHANGELOG.md
+recursive-include docs *.md
+prune examples
+prune scripts
+prune tests

limtod-1.3.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: limTOD
+Version: 1.3.0
+Summary: Time-Ordered Data simulator for single-dish radio intensity mapping, with a differentiable JAX port (limtod_jax)
+Author-email: Zheng Zhang <zheng.zhang@manchester.ac.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zzhang0123/limTOD
+Project-URL: Documentation, https://github.com/zzhang0123/limTOD/tree/main/docs
+Project-URL: Changelog, https://github.com/zzhang0123/limTOD/blob/main/CHANGELOG.md
+Project-URL: Bug Reports, https://github.com/zzhang0123/limTOD/issues
+Project-URL: Source Code, https://github.com/zzhang0123/limTOD
+Keywords: time-ordered data,simulation,MeerKAT,HEALPix,beam patterns,sky models,noise modeling,map making
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: healpy>=1.14.0
+Requires-Dist: astropy>=4.0.0
+Requires-Dist: scipy>=1.5.0
+Requires-Dist: tqdm>=4.60.0
+Requires-Dist: mpmath>=1.2.0
+Provides-Extra: mpi
+Requires-Dist: mpi4py>=3.0.0; extra == "mpi"
+Provides-Extra: gdsm
+Requires-Dist: pygdsm>=1.2.0; extra == "gdsm"
+Provides-Extra: full
+Requires-Dist: mpi4py>=3.0.0; extra == "full"
+Requires-Dist: pygdsm>=1.2.0; extra == "full"
+Requires-Dist: jax>=0.5; extra == "full"
+Requires-Dist: s2fft>=1.4.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8; extra == "dev"
+Requires-Dist: mypy>=0.800; extra == "dev"
+Requires-Dist: sphinx>=4.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == "dev"
+Requires-Dist: jupyter>=1.0; extra == "dev"
+Requires-Dist: matplotlib>=3.3.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
+Requires-Dist: jupyter>=1.0; extra == "docs"
+Requires-Dist: matplotlib>=3.3.0; extra == "docs"
+Provides-Extra: notebooks
+Requires-Dist: jupyter>=1.0; extra == "notebooks"
+Requires-Dist: matplotlib>=3.3.0; extra == "notebooks"
+Requires-Dist: seaborn>=0.11.0; extra == "notebooks"
+Provides-Extra: jax
+Requires-Dist: jax>=0.5; extra == "jax"
+Requires-Dist: s2fft>=1.4.0; extra == "jax"
+Dynamic: license-file
+
+# limTOD
+
+**Time-Ordered Data simulator for single-dish (autocorrelation) radio
+intensity mapping — with a differentiable pure-JAX port.**
+
+limTOD simulates the time-ordered data (TOD) of a single-dish telescope
+scanning a HEALPix sky with an arbitrary (asymmetric) beam: the beam is
+rotated to each pointing in spherical-harmonic space and dotted with the
+sky, then combined with 1/f gain noise and white noise. The package also
+ships:
+
+- **`HPW_mapmaking`** — high-pass + Wiener-filter map-making from TOD back
+  to sky maps;
+- **`limtod_jax`** — a pure-JAX, jit/vmap/grad-safe port of the sky→TOD
+  chain, verified against the numpy implementation to ~1e-12 in float64.
+  It powers the differentiable pipeline of
+  [e-RHINO](https://github.com/zzhang0123/e-RHINO).
+
+Latest changes:
+[CHANGELOG](https://github.com/zzhang0123/limTOD/blob/main/CHANGELOG.md).
+
+## Installation
+
+```bash
+pip install limTOD
+```
+
+The base install is deliberately lightweight (wheel-only: numpy, healpy,
+astropy, scipy, tqdm, mpmath — no compiler needed). Heavier dependencies
+are opt-in extras:
+
+| Extra | Installs | When you need it |
+|-------|----------|------------------|
+| `[mpi]` | mpi4py | MPI-parallel simulation (`mpirun -n N ...`). Without it limTOD runs serially; launching under `mpirun` *without* mpi4py fails loudly instead of silently duplicating work. |
+| `[gdsm]` | pygdsm | The `GDSM_sky_model` sky function (Global Sky Model). Everything else works without it. |
+| `[jax]` | jax, s2fft | The `limtod_jax` package (Python ≥ 3.11). |
+| `[full]` | all of the above | The complete setup. |
+
+```bash
+pip install "limTOD[full]"
+```
+
+From source: clone the
+[repository](https://github.com/zzhang0123/limTOD) and
+`pip install -e ".[dev,full]"` (runs the test suite over both the
+MPI-present and serial-fallback paths).
+
+## Quick start
+
+Simulate multi-frequency TOD for a MeerKAT-like scan
+(sky model here needs `[gdsm]`; pass your own `sky_func` to go without):
+
+```python
+from limTOD import TODSim, example_scan
+
+simulator = TODSim(
+    ant_latitude_deg=-30.7130, ant_longitude_deg=21.4430, ant_height_m=1054,
+    beam_nside=256, sky_nside=256,
+)
+time_list, azimuth_list = example_scan()
+tod, sky_tod, gain_noise = simulator.generate_TOD(
+    freq_list=[950, 1000, 1050],          # MHz
+    time_list=time_list,
+    azimuth_deg_list=azimuth_list,
+    elevation_deg=41.5,
+)                                          # each (n_freq, n_time)
+```
+
+The same sky→TOD chain, differentiable in JAX (`[jax]` extra):
+
+```python
+import jax; jax.config.update("jax_enable_x64", True)
+import jax.numpy as jnp
+import limtod_jax as ltj
+
+sky_alm = ltj.map2alm_quad(sky_map, nside=nside, lmax=lmax)
+psi, theta, phi = ltj.zyz_of_pointing(lst_deg, lat_deg, az_deg, el_deg, 0.0)
+tod = ltj.generate_tod_sky(
+    beam_alm, sky_alm, jnp.stack([psi, theta, phi], axis=-1), lmax=lmax,
+)
+grad = jax.grad(lambda b: ltj.generate_tod_sky(
+    b, sky_alm, jnp.stack([psi, theta, phi], axis=-1), lmax=lmax).sum().real
+)(beam_alm)                                # d(TOD sum)/d(beam alms)
+```
+
+## Documentation
+
+| Page | Contents |
+|------|----------|
+| [TOD simulation](https://github.com/zzhang0123/limTOD/blob/main/docs/tod-simulation.md) | `TODSim` guide: inputs, outputs, noise model, MPI, troubleshooting |
+| [Map-making](https://github.com/zzhang0123/limTOD/blob/main/docs/mapmaking.md) | `HPW_mapmaking`: high-pass + Wiener filtering |
+| [Theory & conventions](https://github.com/zzhang0123/limTOD/blob/main/docs/theory.md) | Signal model, coordinate chain, Euler-angle conventions |
+| [API reference](https://github.com/zzhang0123/limTOD/blob/main/docs/api-reference.md) | Public numpy API signatures |
+| [limtod_jax](https://github.com/zzhang0123/limTOD/blob/main/docs/limtod-jax.md) | The JAX port: usage, exactness contract, precision requirements |
+
+Worked notebooks:
+[TOD simulation](https://github.com/zzhang0123/limTOD/blob/main/examples/TODsim_examples.ipynb)
+and
+[map-making](https://github.com/zzhang0123/limTOD/blob/main/examples/mm_example.ipynb).
+Mathematical derivations:
+[conventions.pdf](https://github.com/zzhang0123/limTOD/blob/main/conventions.pdf).
+
+## Citation
+
+If you use limTOD in your research, please cite:
+
+```bibtex
+@ARTICLE{2026RASTI...5ag024Z,
+       author = {{Zhang}, Zheng and {Bull}, Philip and {Santos}, Mario G. and {Nasirudin}, Ainulnabilah},
+        title = "{Joint Bayesian calibration and map-making for intensity mapping experiments}",
+      journal = {RAS Techniques and Instruments},
+     keywords = {Data Methods, methods: data analysis, techniques: spectroscopic, radio lines: general, Instrumentation and Methods for Astrophysics},
+         year = 2026,
+        month = jan,
+       volume = {5},
+          eid = {rzag024},
+        pages = {rzag024},
+          doi = {10.1093/rasti/rzag024},
+archivePrefix = {arXiv},
+       eprint = {2509.10992},
+ primaryClass = {astro-ph.IM},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2026RASTI...5ag024Z},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+```
+
+## License and authorship
+
+MIT License — see
+[LICENSE](https://github.com/zzhang0123/limTOD/blob/main/LICENSE).
+
+limTOD is developed and maintained by Zheng Zhang (University of
+Manchester), with help and advice from members of the MeerKLASS
+and RHINO collaborations — including Phil Bull, Piyanat Kittiwisit,
+Geoff Murphy, and Mario Santos.

limtod-1.3.0/README.md

@@ -0,0 +1,135 @@
+# limTOD
+
+**Time-Ordered Data simulator for single-dish (autocorrelation) radio
+intensity mapping — with a differentiable pure-JAX port.**
+
+limTOD simulates the time-ordered data (TOD) of a single-dish telescope
+scanning a HEALPix sky with an arbitrary (asymmetric) beam: the beam is
+rotated to each pointing in spherical-harmonic space and dotted with the
+sky, then combined with 1/f gain noise and white noise. The package also
+ships:
+
+- **`HPW_mapmaking`** — high-pass + Wiener-filter map-making from TOD back
+  to sky maps;
+- **`limtod_jax`** — a pure-JAX, jit/vmap/grad-safe port of the sky→TOD
+  chain, verified against the numpy implementation to ~1e-12 in float64.
+  It powers the differentiable pipeline of
+  [e-RHINO](https://github.com/zzhang0123/e-RHINO).
+
+Latest changes:
+[CHANGELOG](https://github.com/zzhang0123/limTOD/blob/main/CHANGELOG.md).
+
+## Installation
+
+```bash
+pip install limTOD
+```
+
+The base install is deliberately lightweight (wheel-only: numpy, healpy,
+astropy, scipy, tqdm, mpmath — no compiler needed). Heavier dependencies
+are opt-in extras:
+
+| Extra | Installs | When you need it |
+|-------|----------|------------------|
+| `[mpi]` | mpi4py | MPI-parallel simulation (`mpirun -n N ...`). Without it limTOD runs serially; launching under `mpirun` *without* mpi4py fails loudly instead of silently duplicating work. |
+| `[gdsm]` | pygdsm | The `GDSM_sky_model` sky function (Global Sky Model). Everything else works without it. |
+| `[jax]` | jax, s2fft | The `limtod_jax` package (Python ≥ 3.11). |
+| `[full]` | all of the above | The complete setup. |
+
+```bash
+pip install "limTOD[full]"
+```
+
+From source: clone the
+[repository](https://github.com/zzhang0123/limTOD) and
+`pip install -e ".[dev,full]"` (runs the test suite over both the
+MPI-present and serial-fallback paths).
+
+## Quick start
+
+Simulate multi-frequency TOD for a MeerKAT-like scan
+(sky model here needs `[gdsm]`; pass your own `sky_func` to go without):
+
+```python
+from limTOD import TODSim, example_scan
+
+simulator = TODSim(
+    ant_latitude_deg=-30.7130, ant_longitude_deg=21.4430, ant_height_m=1054,
+    beam_nside=256, sky_nside=256,
+)
+time_list, azimuth_list = example_scan()
+tod, sky_tod, gain_noise = simulator.generate_TOD(
+    freq_list=[950, 1000, 1050],          # MHz
+    time_list=time_list,
+    azimuth_deg_list=azimuth_list,
+    elevation_deg=41.5,
+)                                          # each (n_freq, n_time)
+```
+
+The same sky→TOD chain, differentiable in JAX (`[jax]` extra):
+
+```python
+import jax; jax.config.update("jax_enable_x64", True)
+import jax.numpy as jnp
+import limtod_jax as ltj
+
+sky_alm = ltj.map2alm_quad(sky_map, nside=nside, lmax=lmax)
+psi, theta, phi = ltj.zyz_of_pointing(lst_deg, lat_deg, az_deg, el_deg, 0.0)
+tod = ltj.generate_tod_sky(
+    beam_alm, sky_alm, jnp.stack([psi, theta, phi], axis=-1), lmax=lmax,
+)
+grad = jax.grad(lambda b: ltj.generate_tod_sky(
+    b, sky_alm, jnp.stack([psi, theta, phi], axis=-1), lmax=lmax).sum().real
+)(beam_alm)                                # d(TOD sum)/d(beam alms)
+```
+
+## Documentation
+
+| Page | Contents |
+|------|----------|
+| [TOD simulation](https://github.com/zzhang0123/limTOD/blob/main/docs/tod-simulation.md) | `TODSim` guide: inputs, outputs, noise model, MPI, troubleshooting |
+| [Map-making](https://github.com/zzhang0123/limTOD/blob/main/docs/mapmaking.md) | `HPW_mapmaking`: high-pass + Wiener filtering |
+| [Theory & conventions](https://github.com/zzhang0123/limTOD/blob/main/docs/theory.md) | Signal model, coordinate chain, Euler-angle conventions |
+| [API reference](https://github.com/zzhang0123/limTOD/blob/main/docs/api-reference.md) | Public numpy API signatures |
+| [limtod_jax](https://github.com/zzhang0123/limTOD/blob/main/docs/limtod-jax.md) | The JAX port: usage, exactness contract, precision requirements |
+
+Worked notebooks:
+[TOD simulation](https://github.com/zzhang0123/limTOD/blob/main/examples/TODsim_examples.ipynb)
+and
+[map-making](https://github.com/zzhang0123/limTOD/blob/main/examples/mm_example.ipynb).
+Mathematical derivations:
+[conventions.pdf](https://github.com/zzhang0123/limTOD/blob/main/conventions.pdf).
+
+## Citation
+
+If you use limTOD in your research, please cite:
+
+```bibtex
+@ARTICLE{2026RASTI...5ag024Z,
+       author = {{Zhang}, Zheng and {Bull}, Philip and {Santos}, Mario G. and {Nasirudin}, Ainulnabilah},
+        title = "{Joint Bayesian calibration and map-making for intensity mapping experiments}",
+      journal = {RAS Techniques and Instruments},
+     keywords = {Data Methods, methods: data analysis, techniques: spectroscopic, radio lines: general, Instrumentation and Methods for Astrophysics},
+         year = 2026,
+        month = jan,
+       volume = {5},
+          eid = {rzag024},
+        pages = {rzag024},
+          doi = {10.1093/rasti/rzag024},
+archivePrefix = {arXiv},
+       eprint = {2509.10992},
+ primaryClass = {astro-ph.IM},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2026RASTI...5ag024Z},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+```
+
+## License and authorship
+
+MIT License — see
+[LICENSE](https://github.com/zzhang0123/limTOD/blob/main/LICENSE).
+
+limTOD is developed and maintained by Zheng Zhang (University of
+Manchester), with help and advice from members of the MeerKLASS
+and RHINO collaborations — including Phil Bull, Piyanat Kittiwisit,
+Geoff Murphy, and Mario Santos.

limtod-1.3.0/docs/README.md

@@ -0,0 +1,12 @@
+# limTOD documentation
+
+| Page | Contents |
+|------|----------|
+| [TOD simulation](tod-simulation.md) | `TODSim` user guide: inputs, outputs, noise model, examples, troubleshooting |
+| [Map-making](mapmaking.md) | `HPW_mapmaking`: high-pass + Wiener filtering from TOD to sky maps |
+| [Theory & conventions](theory.md) | Signal model, coordinate transformations, Euler-angle conventions, workflow |
+| [API reference](api-reference.md) | Signatures and parameters of the public numpy API |
+| [limtod_jax](limtod-jax.md) | The pure-JAX differentiable port: usage, conventions, exactness contract, precision |
+
+Release notes live in [CHANGELOG.md](../CHANGELOG.md); mathematical
+derivations in [conventions.pdf](../conventions.pdf).