gmat-sweep 0.1.0__tar.gz

gmat_sweep-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default reviewer for everything in this repo.
+*   @djankov

gmat_sweep-0.1.0/.github/ISSUE_TEMPLATE/backend-request.yml

@@ -0,0 +1,41 @@
+name: Backend request
+description: Request a new execution backend behind the Pool abstraction.
+title: "Backend: <name>"
+labels: ["type:backend-request"]
+body:
+  - type: input
+    id: backend_name
+    attributes:
+      label: Backend
+      description: Name of the execution surface (e.g. Slurm, Kubernetes, MPI, AWS Batch).
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Why this backend
+      description: What can't you do with the shipped backends (LocalJoblibPool, DaskPool, RayPool)? Cluster you already have? Org policy? Scale ceiling?
+    validations:
+      required: true
+  - type: textarea
+    id: subprocess_isolation
+    attributes:
+      label: Subprocess-isolation contract
+      description: |
+        gmat-sweep guarantees one fresh Python interpreter per run (gmatpy cannot
+        be cleanly re-initialised in-process). Any backend that doesn't honour
+        this contract is rejected at import time. Briefly describe how the
+        proposed backend would satisfy it (one task per pod / one srun job per
+        run / etc.).
+    validations:
+      required: true
+  - type: textarea
+    id: prior_art
+    attributes:
+      label: Prior art
+      description: Existing Python wrappers, recipes, libraries you'd want us to consider.
+  - type: textarea
+    id: willingness
+    attributes:
+      label: Willingness to contribute
+      description: Are you offering a PR, an evaluation environment, sample workloads, or just flagging the need?

gmat_sweep-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,82 @@
+name: Bug
+description: Report a defect in gmat-sweep.
+title: "<short summary>"
+labels: ["type:bug"]
+body:
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: Observed behavior. Include error messages and tracebacks verbatim.
+    validations:
+      required: true
+  - type: textarea
+    id: what_expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest snippet that triggers the bug. A `.script` fragment plus the Python that drives the sweep is ideal.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: gmat_sweep_version
+    attributes:
+      label: gmat-sweep version
+      placeholder: "e.g. 0.1.0, or git sha"
+    validations:
+      required: true
+  - type: input
+    id: gmat_run_version
+    attributes:
+      label: gmat-run version
+      placeholder: "e.g. 0.4.0"
+    validations:
+      required: true
+  - type: input
+    id: gmat_version
+    attributes:
+      label: GMAT version
+      placeholder: "e.g. R2026a"
+    validations:
+      required: true
+  - type: input
+    id: python_version
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.12.3"
+    validations:
+      required: true
+  - type: dropdown
+    id: backend
+    attributes:
+      label: Backend
+      options:
+        - LocalJoblibPool (default)
+        - DaskPool
+        - RayPool
+        - Other / unsure
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - Windows
+        - macOS
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Relevant per-worker logs, the sweep manifest, captured stderr, pytest output.
+      render: shell

gmat_sweep-0.1.0/.github/ISSUE_TEMPLATE/chore.yml

@@ -0,0 +1,25 @@
+name: Chore
+description: Tooling, infra, hygiene, or other non-feature work.
+title: "<short summary>"
+labels: ["type:chore"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What
+      description: What needs to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: Why
+      description: Why now. What's blocked or painful without it.
+    validations:
+      required: true
+  - type: textarea
+    id: done
+    attributes:
+      label: Definition of done
+      value: |
+        - [ ]

gmat_sweep-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/orgs/astro-tools/discussions
+    about: Open a discussion in the org-wide space for usage questions, ideas, or general chat.

gmat_sweep-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,39 @@
+name: Feature
+description: Propose a new capability or a non-trivial change.
+title: "<short summary>"
+labels: ["type:feature"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One or two sentences describing what this feature is.
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: Why this matters. What can't users do today that they should be able to do?
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Concrete, testable checkboxes. An outside reviewer should be able to read these and tell whether the feature is done.
+      value: |
+        - [ ]
+        - [ ]
+    validations:
+      required: true
+  - type: textarea
+    id: out_of_scope
+    attributes:
+      label: Out of scope / non-goals
+      description: What this issue deliberately does not cover. Helps keep scope honest.
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Design notes, links to charter sections, references to prior art, open questions.

gmat_sweep-0.1.0/.github/ISSUE_TEMPLATE/use-case-fit.yml

@@ -0,0 +1,41 @@
+name: Use-case fit
+description: I want to use gmat-sweep for X — does it fit?
+title: "<short summary of the use case>"
+labels: ["type:use-case-fit"]
+body:
+  - type: textarea
+    id: use_case
+    attributes:
+      label: What you want to do
+      description: Describe the analysis or workflow you have in mind. A launch-window scan? A dispersion study? Something else?
+    validations:
+      required: true
+  - type: textarea
+    id: parameters
+    attributes:
+      label: What you'd be sweeping
+      description: Which fields would vary, and roughly how (grid? Monte Carlo? Latin hypercube? something else)? Order-of-magnitude run count.
+    validations:
+      required: true
+  - type: textarea
+    id: existing_workflow
+    attributes:
+      label: How you do this today
+      description: Hand-rolled multiprocessing? A spreadsheet? Paramat? Nothing yet? Helps us understand the pain point.
+  - type: textarea
+    id: blockers
+    attributes:
+      label: What's stopping you from just trying it
+      description: Missing feature, unclear docs, uncertainty about scale, license concern, scope question?
+    validations:
+      required: true
+  - type: input
+    id: gmat_version
+    attributes:
+      label: GMAT version
+      placeholder: "e.g. R2026a"
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Links to a paper, prior project, GMAT script — anything that helps us understand the use case.

gmat_sweep-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,140 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }}, ${{ matrix.gmat-version }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      # 2 OSes × 3 Python minors × 2 GMAT releases = 12 cells. macOS is
+      # deferred to v0.2 per the charter; R2026a is the primary target,
+      # R2025a is the previous release we still support.
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ['3.10', '3.11', '3.12']
+        gmat-version: [R2025a, R2026a]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - uses: astro-tools/setup-gmat@v0
+        with:
+          version: ${{ matrix.gmat-version }}
+          cache: true
+
+      - name: Install project
+        run: uv sync --all-groups
+
+      - name: Run pytest
+        # `-m "integration or not integration"` overrides the default
+        # marker filter in pyproject.toml so CI runs both unit and
+        # integration suites in a single invocation.
+        run: uv run pytest -m "integration or not integration" --cov --cov-report=term-missing
+
+      # Coverage gates run on a single matrix combination — the .coverage
+      # data is identical across runners. Overall floor matches the v0.1
+      # charter DoD; the four per-file gates match CONTRIBUTING.md.
+
+      - name: Enforce overall coverage (>=80%)
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' && matrix.gmat-version == 'R2026a'
+        run: uv run coverage report --fail-under=80
+
+      - name: Enforce grids.py coverage (>=95%)
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' && matrix.gmat-version == 'R2026a'
+        run: uv run coverage report --include='src/gmat_sweep/grids.py' --fail-under=95
+
+      - name: Enforce distributions.py coverage (>=95%)
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' && matrix.gmat-version == 'R2026a'
+        run: uv run coverage report --include='src/gmat_sweep/distributions.py' --fail-under=95
+
+      - name: Enforce manifest.py coverage (>=95%)
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' && matrix.gmat-version == 'R2026a'
+        run: uv run coverage report --include='src/gmat_sweep/manifest.py' --fail-under=95
+
+      - name: Enforce aggregate.py coverage (>=95%)
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' && matrix.gmat-version == 'R2026a'
+        run: uv run coverage report --include='src/gmat_sweep/aggregate.py' --fail-under=95
+
+      # Smoke-execute the example notebooks end-to-end. Catches "someone changed
+      # the public surface and forgot to refresh the committed notebook"
+      # regressions without paying the cost of nbval-style strict comparison
+      # (notebooks are committed with cleared outputs). One matrix combo is
+      # enough — the underlying surface is covered cross-platform by the rest
+      # of the test job. Notebook 03 uses signal.SIGINT against a child
+      # process, so it is Linux-only (Windows lacks the matching semantics).
+      - name: Smoke-execute example notebooks
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' && matrix.gmat-version == 'R2026a'
+        working-directory: docs/examples
+        run: |
+          uv sync --all-groups --extra examples
+          uv run jupyter execute 01_sma_scan.ipynb
+          uv run jupyter execute 02_epoch_arrival_grid.ipynb
+          uv run jupyter execute 03_killed_sweep_recovery.ipynb
+
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  typecheck:
+    name: typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run mypy
+
+  # Smoke-check that `pip install gmat-sweep` (no extras, no dev group)
+  # imports cleanly. Catches an extras-only or dev-only dependency leaking
+  # into the default install path.
+  minimal-install:
+    name: minimal install smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install .
+      - run: python -c "import gmat_sweep"

gmat_sweep-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run mkdocs build --strict
+
+  deploy:
+    name: deploy
+    needs: build
+    if: |
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) ||
+      github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - run: uv run mkdocs gh-deploy --force --no-history

gmat_sweep-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gmat-sweep
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  github-release:
+    name: github release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes \
+            dist/*

gmat_sweep-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+*.whl
+
+# Environments
+.venv/
+venv/
+env/
+.env
+
+# uv
+.uv-cache/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Docs build
+site/
+.cache/
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+.DS_Store

gmat_sweep-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

gmat_sweep-0.1.0/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to gmat-sweep are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-05-04
+
+Initial public release. The MVP slice of the charter: full-factorial parameter
+sweeps over a `gmat-run` mission, parallelised across subprocess workers,
+aggregated into a `(run_id, time)`-MultiIndexed `pandas.DataFrame`, and backed
+by a durable JSON Lines manifest.
+
+### Added
+
+- `sweep(mission, grid=..., workers=...)` — public entry point for
+  full-factorial parameter grids. Materialises the cartesian product into one
+  [`RunSpec`][gmat_sweep.RunSpec] per cell, dispatches through the default
+  [`LocalJoblibPool`][gmat_sweep.Pool] backend, and returns the aggregated
+  multi-indexed DataFrame (#9).
+- `gmat_sweep.full_factorial` and `gmat_sweep.expand_grid_to_run_specs` —
+  cartesian-product expansion with deterministic, lexicographic key ordering
+  and zero-based `run_id` assignment, the contract every manifest and future
+  resume flow depends on (#4).
+- [`Pool`][gmat_sweep.Pool] ABC with the `subprocess_isolated` invariant
+  enforced at class-definition time, plus the default
+  [`LocalJoblibPool`][gmat_sweep.Pool] implementation backed by joblib's loky
+  executor — every run spawns a fresh Python interpreter that imports
+  `gmatpy` once, sidestepping the well-known reinit limitation (#7).
+- Single-run worker callable that imports `gmat_run`, applies overrides via the
+  dotted-path setter, runs the mission, serialises every `ReportFile` to
+  Parquet, and converts every exception into a `RunOutcome.failed(...)` so a
+  single bad run never aborts the sweep (#6).
+- Lazy `(run_id, time)`-MultiIndex aggregation from per-run Parquet via
+  pyarrow's dataset API. Failed and skipped runs surface as one row with the
+  `__status` column populated (#8).
+- JSON Lines manifest with one header line and one fsync'd
+  [`ManifestEntry`][gmat_sweep.ManifestEntry] per run. `Manifest.load`
+  tolerates a single torn last line (a `Ctrl-C`'d sweep leaves a parseable
+  file). Header captures canonical script SHA-256, `gmat_sweep` /
+  `gmat_run` / GMAT install / Python / OS versions, the materialised parameter
+  spec, and the run count. Includes `find_failed` / `find_missing` lookup
+  helpers for the v0.2 resume flow (#5).
+- Typed exception hierarchy under `gmat_sweep.errors` rooted at
+  [`GmatSweepError`][gmat_sweep.GmatSweepError] —
+  [`SweepConfigError`][gmat_sweep.SweepConfigError],
+  [`RunFailed`][gmat_sweep.RunFailed],
+  [`BackendError`][gmat_sweep.BackendError], and
+  [`ManifestCorruptError`][gmat_sweep.ManifestCorruptError] — alongside
+  JSON-serialisable [`RunSpec`][gmat_sweep.RunSpec] /
+  [`SweepSpec`][gmat_sweep.SweepSpec] / [`RunOutcome`][gmat_sweep.RunOutcome]
+  dataclasses (#3).
+- `gmat-sweep` console script with `run` and `show` subcommands. `run`
+  accepts repeated `--grid name=lo:hi:count` linspace and `--grid
+  name=v1,v2,v3` explicit-list axes; `show` prints a one-line summary of an
+  existing manifest (#10).
+- Validation test suite — per-run round-trip, parameter-spec round-trip
+  (float / int / datetime / vector / str enum), 16-run reference-sweep
+  regression, failure-mode coverage (invalid override, divergent solver, bad
+  script, OOM), and a manifest-replay contract test that pins the v0.1
+  manifest format ahead of v0.2's resume flow (#11).
+- MkDocs-Material documentation site auto-deployed to GitHub Pages on tag
+  pushes, with mkdocstrings-driven API reference, parameter-spec and
+  manifest-schema reference pages, supported-versions table, and FAQ
+  (#12, #28).
+- Three runnable example notebooks rendered into the docs site —
+  single-axis SMA scan, two-axis epoch × time-of-flight grid, and a
+  surviving-a-kill walkthrough demonstrating manifest durability (#13, #29).
+- CI on Ubuntu + Windows × Python 3.10 / 3.11 / 3.12 × R2025a / R2026a (12
+  cells) via `astro-tools/setup-gmat`, with both unit and integration suites
+  enabled. Coverage gates: ≥ 80 % overall and ≥ 95 % each on `grids.py`,
+  `distributions.py`, `manifest.py`, and `aggregate.py` (#2).
+- Release workflow: `uv build` → PyPI trusted publishing →
+  `gh release create --generate-notes` on `v*` tags (#2).
+
+[0.1.0]: https://github.com/astro-tools/gmat-sweep/releases/tag/v0.1.0