gmat-sweep v0.3 — DaskPool, RayPool, cluster recipes, 1000-run benchmark

[djankov]

gmat-sweep v0.3 is on PyPI. This one is the cluster-backends release: DaskPool and RayPool join LocalJoblibPool behind a single Pool ABC, the CLI grows a --backend {local,dask,ray} flag and a rich gmat-sweep show --detail / --run mode, three cluster-recipe pages (Slurm, Kubernetes, Ray autoscaling) document the multi-host story end-to-end, and a 1000-run reference benchmark with a per-backend throughput floor lands in CI. Trove classifier moves from Development Status :: 3 - Alpha to 4 - Beta.

from gmat_sweep import sweep
from gmat_sweep.backends import DaskPool

# Same call shape as v0.2 — only the backend changes.
with DaskPool(n_workers=8) as pool:
    df = sweep(
        "mission.script",
        grid={"Sat.SMA": [7000, 7100, 7200, 7300]},
        backend=pool,
    )

What's new in v0.3

• DaskPool and RayPool cluster backends. DaskPool (pip install gmat-sweep[dask]) wraps dask.distributed — auto-spawns a LocalCluster by default, accepts an existing Client for shared-cluster setups. RayPool (pip install gmat-sweep[ray]) wraps Ray — calls ray.init for you, or connects to a pre-existing cluster via address=. Both are imported lazily (a minimal install never imports distributed or ray) and ship with a uniform reuse_gmat_context flag controlling how the GMAT bootstrap is amortised across runs (#57, #58, #78).
• Three cluster-recipe pages. Slurm with srun, Kubernetes pod-per-worker, and Ray autoscaling — each pairing the cluster-side configuration with the matching sweep() driver, plus the gotchas (shared-filesystem requirements, image-discipline constraints, Ray's runtime_env quirk) that land most users on a forum thread (#63).
• CLI --backend and gmat-sweep show --detail / --run. Every sweep-running subcommand and resume accept --backend {local,dask,ray}; --backend-arg KEY=VALUE is the escape hatch for less-common pool kwargs. Missing extras exit with code 4 and a pip install gmat-sweep[…] message. gmat-sweep show --detail prints a per-run table sorted with failed first, then skipped, then ok; --run N prints a single run's full record including the captured stderr. --filter STATUS narrows the table; --detail and --run are mutually exclusive (#59, #60).
• 1000-run reference benchmark + CI throughput floor. docs/benchmarks.md reports wall-clock and throughput for all three backends on a 1000-run Sat.SMA sweep against the LEO basic mission fixture. A 50-run scaled variant runs on every PR and asserts measured throughput meets the per-backend floor in tests/data/throughput_floor.json — slowdowns surface as a CI failure naming the backend, the measured rate, and the floor (#61).
• Backend-equivalence validation. A new gated CI cell runs three reference sweeps (16-run grid, 32-run Monte Carlo, 16-run Latin hypercube) on each backend and asserts pairwise bit-equality on the aggregated DataFrame and the manifest's reproducibility-bearing fields. Cross-process determinism is pinned on Dask and Ray — a fresh driver-process re-running the same Monte Carlo sweep must produce a bit-equal result (#62).
• Two new example notebooks. Dask cluster recipe — 100-run grid sweep through a distributed.LocalCluster with DaskPool. Ray autoscaling recipe — 100-run Monte Carlo through RayPool against a local ray.init(). Both notebooks run end-to-end on a laptop and exercise the same APIs the cluster recipes scale up (#64).

Behaviour changes worth knowing about

• workers=N keyword retired. The shorthand on sweep / monte_carlo / latin_hypercube is replaced by backend=. A v0.2 caller passing workers=8 must now pass backend=LocalJoblibPool(workers=8) — one-line migration at every call site (#56).
• DaskPool and RayPool default to per-worker GMAT-bootstrap reuse. reuse_gmat_context=True is the new default — a worker process imports gmat_run once and reuses the loaded state across many tasks. Safe only when every spec dispatched through the pool loads the same script (the common case). If you compose one Dask or Ray pool across calls that load different .script files, pass reuse_gmat_context=False (#78).

Full notes: https://github.com/astro-tools/gmat-sweep/blob/main/CHANGELOG.md#030--2026-05-07

Install

pip install -U gmat-sweep                 # core (LocalJoblibPool)
pip install -U "gmat-sweep[dask]"         # adds DaskPool
pip install -U "gmat-sweep[ray]"          # adds RayPool
pip install -U "gmat-sweep[examples]"     # matplotlib + dask + ray for the example notebooks

Same baseline: Python 3.10–3.12 and a local GMAT install. R2025a and R2026a are exercised on every PR (Ubuntu / Windows / macOS × Py 3.10 / 3.11 / 3.12 × R2025a / R2026a — 18 cells, plus the dedicated backend-equivalence and throughput-regression cells).

Links

• PyPI: https://pypi.org/project/gmat-sweep/
• Docs: https://astro-tools.github.io/gmat-sweep/
• Source: https://github.com/astro-tools/gmat-sweep
• Release notes: https://github.com/astro-tools/gmat-sweep/releases/tag/v0.3.0

Feedback wanted

• Wired one of the three recipe pages into a real cluster — Slurm via dask-jobqueue, Kubernetes via the Dask Operator, or Ray autoscaling? Comment or open an issue with the diff and any gotcha that wasn't covered. The recipes are designed to be drop-in; "I had to add X to make this work" is exactly the feedback that improves them.
• Composing a single pool across calls that load different scripts? You're the user reuse_gmat_context=False is for — flag if the docs around it (FAQ, backends page) read clearly or leave a foot-gun.
• Hitting the throughput floor on a backend? tests/data/throughput_floor.json is the source of truth; if your hardware reproducibly outpaces it, a PR raising the floor (with the measured numbers) is welcome — likewise if it can't reach it on a representative box.