pantr 0.6.0__tar.gz

pantr-0.6.0/.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(conda run:*)",
+      "Bash(conda activate:*)",
+      "Bash(pytest:*)",
+      "Bash(ruff:*)",
+      "Bash(mypy:*)",
+      "Bash(sphinx-build:*)",
+      "Bash(make:*)",
+      "Bash(lint-imports:*)"
+    ]
+  }
+}

pantr-0.6.0/.claude/skills/new-feature/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: new-feature
+description: End-to-end workflow for implementing a new feature, bug fix, or refactor — from creating a worktree and branch through implementation, testing, validation, PR creation, and user notification. Use this skill whenever the user asks you to implement, add, build, create, or fix something that will result in a PR. Trigger on requests like "add support for X", "implement Y", "fix bug Z", "refactor W", or any task that involves writing code that should be merged. Even if the user doesn't mention PRs or branches, if the task involves code changes that need review, use this skill.
+---
+
+# New Feature Workflow
+
+This skill orchestrates the full lifecycle of a code change — from branch creation to PR. Follow these phases in order.
+
+## Phase 1: Worktree and branch
+
+Create an isolated worktree to work in. Use the `EnterWorktree` tool — it will create a new worktree under `.claude/worktrees/` with a fresh branch based on HEAD.
+
+After entering the worktree, rename the branch to follow the convention:
+
+```bash
+git branch -m <type>/<short-description>
+```
+
+Where `<type>` matches the conventional commit type (`feat`, `fix`, `refactor`, etc.) and `<short-description>` is a kebab-case summary (e.g., `feat/periodic-bspline-product`, `fix/bernstein-derivative-at-boundary`).
+
+## Phase 2: Plan
+
+Before writing code, understand the task and form a plan:
+
+1. Read the relevant existing code to understand the architecture and conventions
+2. Identify which layer(s) the change touches (Layer 1 / 2 / 3 — see CLAUDE.md)
+3. Outline the approach — what files to create or modify, what the public API looks like
+4. Share the plan with the user and get confirmation before proceeding
+
+For non-trivial features, use `EnterPlanMode` to align on the approach.
+
+## Phase 3: Implement
+
+Write the code following the project's architecture and conventions:
+
+- **Layer 3 (kernels)**: Pure Numba computation, no validation, `@nb_jit(nopython=True, cache=True)`
+- **Layer 2 (helpers)**: Input validation, array allocation, calls Layer 3
+- **Layer 1 (public API)**: Lightweight validation, delegates to Layer 2
+- Follow strict mypy typing, Google-style docstrings, and all conventions in CLAUDE.md
+
+### Commit conventions
+
+Commit regularly as you complete logical units of work. Use **conventional commits**:
+
+```
+<type>(<scope>): <imperative summary>
+
+Optional body explaining why, not what.
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+```
+
+**Types**: `feat`, `fix`, `refactor`, `test`, `docs`, `style`, `perf`, `chore`
+**Scope**: the module or area affected (e.g., `bspline`, `basis`, `quad`, `docs`)
+
+Examples:
+- `feat(bspline): add exact 1D B-spline product via Bezier multiplication`
+- `fix(basis): correct off-by-one in Cox-de Boor recursion`
+- `refactor(bspline): move to_open_bspline to Layer 2`
+- `test(bspline): add boundary case tests for derivative evaluation`
+
+Keep commits focused — one logical change per commit. Do not bundle unrelated changes.
+
+## Phase 4: Test
+
+Write tests for the new code:
+
+- Place tests in the appropriate file under `tests/` (follow existing naming: `test_<module>.py`)
+- Cover normal cases, edge cases, and error cases
+- Test public API (Layer 1) primarily; test Layer 2 directly only if it has complex validation logic
+- Use `pytest --no-cov -v` to run tests during development
+- Commit tests in a dedicated commit (e.g., `test(bspline): add tests for exact product`)
+
+## Phase 5: Pre-PR validation
+
+Before creating the PR, run the full check suite. Invoke the `pre-pr-checks` skill (or run the checks manually):
+
+1. `ruff check .` — lint
+2. `ruff format --check .` — formatting
+3. `mypy --config-file mypy.ini src tests` — type checking
+4. `pytest --no-cov -v` — tests
+5. `NUMBA_DISABLE_JIT=1 sphinx-build -M html docs/ docs/_build -W --keep-going -j auto` — docs
+
+Fix any issues and commit the fixes before proceeding. All checks must pass.
+
+**Always run every check on the whole repo, not single files.** Running
+`ruff check <one_file>` while skipping `ruff format --check .` (or vice versa) has
+let real failures through. Run all five commands, every push — no shortcuts.
+
+**Local green ≠ CI green.** The local environment can differ from CI in ways that
+hide failures; the local suite passing is necessary but not sufficient. Known traps:
+
+- **mypy runs on a Python matrix (3.11–3.14).** `mypy.ini` pins `python_version = 3.11`,
+  but the *numpy stub version* is whatever is installed locally. Be defensive with numpy
+  typing: no bare `np.ndarray`; `np.einsum` still returns `Any` in current stubs, so wrap
+  its result with `np.asarray(..., dtype=np.float64)` where the dtype matters.
+- **Headless GL.** The CI test job runs without a display. pyvista/VTK tests must not
+  call `.show()` or `pantr.viz.plot()` (they force a render and segfault headless) —
+  build the scene with `to_plotter()` instead. The full suite runs under coverage with
+  `NUMBA_DISABLE_JIT=1`; a segfault there crashes the whole run.
+- If a dependency the suite needs (e.g. `pyvista`, `mpi4py`) is missing locally, the
+  relevant tests silently skip — install it so they actually run before you rely on a
+  green local result.
+
+## Phase 5.5: Automated review (fresh Sonnet reviewers)
+
+After checks pass and before pushing, run a fresh-context review of the branch diff.
+
+**Carve-out — skip this phase entirely** if the diff is trivial: docs-only,
+formatting-only, or comment-only changes (`git diff main...HEAD` touches no
+executable logic). For these, proceed straight to Phase 6.
+
+Otherwise, launch the pr-review-toolkit agents **in parallel** via the Task tool,
+each with **`model: sonnet`** (the orchestrator stays on Opus; reviewers get clean,
+uncontaminated context):
+
+- `pr-review-toolkit:code-reviewer` — always
+- `pr-review-toolkit:pr-test-analyzer` — if test files changed
+- `pr-review-toolkit:comment-analyzer` — if comments/docstrings changed
+- `pr-review-toolkit:silent-failure-hunter` — if error handling changed
+- `pr-review-toolkit:type-design-analyzer` — if new types added
+
+Tell each agent to review the branch diff against `main` (`git diff main...HEAD`).
+
+Aggregate findings into **Critical / Important / Suggestion** buckets, then:
+
+1. Fix every **Critical** and **Important** finding. Commit the fixes
+   (`fix(<scope>): address review findings`).
+2. Re-run Phase 5 checks — they must pass.
+3. Re-run the review on the new diff. Repeat until no Critical/Important findings
+   remain, or two consecutive rounds surface nothing new (**hard cap: 3 rounds**).
+4. List any unaddressed **Suggestions** in the PR body under a "Review notes"
+   heading — do not silently drop them.
+
+This phase is **unattended** — do not pause for approval. Proceed to Phase 6 when clean.
+
+> Note: findings come from fresh Sonnet reviewers, but fixes are applied by this
+> (Opus) orchestrator, which carries implementation context. The re-review in
+> step 3 is what guards against the implementer rationalizing away a real finding.
+
+## Phase 6: PR and notify
+
+Once all checks pass:
+
+1. Push the branch:
+   ```bash
+   git push -u origin HEAD
+   ```
+
+2. Create the PR using `gh pr create`:
+   - Title: concise, under 70 characters
+   - Body: summary of changes, test plan, and the generated-by footer
+   - Target the `main` branch
+
+   ```bash
+   gh pr create --title "<type>(<scope>): <summary>" --body "$(cat <<'EOF'
+   ## Summary
+   <bullet points describing the changes>
+
+   ## Test plan
+   - [ ] All existing tests pass
+   - [ ] New tests added for <feature>
+   - [ ] Pre-PR checks pass (ruff, mypy, pytest, docs)
+
+   Generated with [Claude Code](https://claude.com/claude-code)
+   EOF
+   )"
+   ```
+
+3. **Verify CI is green before declaring done.** Pushing is not the finish line —
+   local checks can pass while CI fails (see the local-vs-CI traps in Phase 5). After
+   creating the PR, watch the checks to completion:
+
+   ```bash
+   gh pr checks <pr-number> --watch    # or poll `gh pr checks <pr-number>`
+   ```
+
+   If any job fails, read its log (`gh run view --job <id> --log`), fix the cause,
+   commit, and push again — then re-watch. Do not report the PR as ready until every
+   required check passes. Avoid pushing twice in quick succession: a second push can
+   cancel the first run's in-progress jobs (showing a spurious "failure"); wait for the
+   run to settle, or confirm a job was *canceled* (not a real failure) before reacting.
+
+4. **Notify the user**: Tell them the PR is ready *and CI is green*, provide the URL,
+   and give a brief summary of what was done.
+
+## Important notes
+
+- If the user asks you to **plan only** (not implement), stop after Phase 2 and present the plan.
+- If at any point you're unsure about a design decision, ask the user rather than guessing.
+- Do not push or create a PR without running all checks first (every command, whole repo).
+- Do not push or create a PR without running Phase 5.5 review first (unless the diff hit the trivial carve-out).
+- The work is not done until **CI is green**, not merely when local checks pass — always confirm with `gh pr checks` before declaring the PR ready.
+- Keep the user informed at natural milestones (plan ready, implementation done, tests passing, PR created, CI green).

pantr-0.6.0/.claude/skills/pre-pr-checks/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: pre-pr-checks
+description: Run the full pre-PR validation suite (ruff lint, ruff format check, mypy type checking, pytest tests, and Sphinx documentation build). Use this skill whenever you need to verify code quality before pushing, creating a PR, or when the user asks to "run checks", "validate", "run CI locally", or "make sure everything passes". Also trigger when about to push code or create a pull request — always validate first.
+---
+
+# Pre-PR Checks
+
+Run all quality checks that CI would run, and report results. The goal is to catch issues before they reach the remote, saving CI time and avoiding back-and-forth.
+
+## Environment setup
+
+Activate the conda environment first:
+
+```bash
+conda activate pantr
+```
+
+## Checks to run
+
+Run these checks **sequentially** in this order — later checks are pointless if earlier ones fail on syntax or type errors.
+
+### 1. Ruff lint
+
+```bash
+ruff check .
+```
+
+If there are auto-fixable issues, fix them with `ruff check --fix .` and re-run to confirm. Stage the fixes.
+
+### 2. Ruff format check
+
+```bash
+ruff format --check .
+```
+
+If formatting issues are found, run `ruff format .` to fix them and stage the changes.
+
+### 3. mypy type checking
+
+```bash
+mypy --config-file mypy.ini src tests
+```
+
+If there are type errors, fix them before proceeding. Type errors often indicate real bugs.
+
+### 4. Pytest (without coverage)
+
+```bash
+pytest --no-cov -v
+```
+
+Use `--no-cov` to keep things fast. All tests must pass.
+
+### 5. Documentation build
+
+```bash
+NUMBA_DISABLE_JIT=1 sphinx-build -M html docs/ docs/_build -W --keep-going -j auto
+```
+
+The `-W` flag treats warnings as errors (matching CI). `NUMBA_DISABLE_JIT=1` avoids Numba compilation during doc build.
+
+## Reporting
+
+After running all checks, present a clear summary:
+
+```
+Pre-PR Checks Summary
+---------------------
+Ruff lint:    PASS / FAIL (N issues)
+Ruff format:  PASS / FAIL (N files)
+mypy:         PASS / FAIL (N errors)
+pytest:       PASS / FAIL (N passed, M failed)
+docs build:   PASS / FAIL (N warnings)
+```
+
+If any check failed and you were unable to fix it, explain what went wrong and suggest next steps. If all checks pass, say so clearly — the code is ready to push.
+
+## When auto-fixing
+
+If you fix lint, format, or type issues during this process, commit those fixes in a dedicated commit:
+
+```
+style: fix lint and formatting issues
+```
+
+Keep these commits separate from feature work so the git history stays clean.

pantr-0.6.0/.github/workflows/ci.yaml

@@ -0,0 +1,318 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint (Ruff)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          cache-dependency-path: |
+            pyproject.toml
+
+      - name: Cache Ruff cache
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/ruff
+          key: ${{ runner.os }}-ruff-${{ hashFiles('ruff.toml', '.ruff.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-ruff-
+
+      - name: Cache virtualenv
+        id: cache-venv
+        uses: actions/cache@v5
+        with:
+          path: .venv
+          key: ${{ runner.os }}-venv-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-venv-${{ steps.setup-python.outputs.python-version }}-
+
+      - name: Create venv and install dev deps (on cache miss)
+        if: steps.cache-venv.outputs.cache-hit != 'true'
+        run: |
+          python -m venv .venv
+          . .venv/bin/activate
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: |
+          . .venv/bin/activate
+          make ruff-lint
+
+      - name: Ruff formatting check
+        run: |
+          . .venv/bin/activate
+          make ruff-format-check
+
+      - name: Import boundary check (import-linter)
+        run: |
+          . .venv/bin/activate
+          make import-lint
+
+  type-check:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          cache-dependency-path: |
+            pyproject.toml
+
+      - name: Cache mypy cache
+        uses: actions/cache@v5
+        with:
+          path: .mypy_cache
+          key: ${{ runner.os }}-mypy-${{ hashFiles('pyproject.toml', 'mypy.ini') }}
+          restore-keys: |
+            ${{ runner.os }}-mypy-
+
+      - name: Cache virtualenv
+        id: cache-venv
+        uses: actions/cache@v5
+        with:
+          path: .venv
+          key: ${{ runner.os }}-venv-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-venv-${{ steps.setup-python.outputs.python-version }}-
+
+      - name: Create venv and install dev deps (on cache miss)
+        if: steps.cache-venv.outputs.cache-hit != 'true'
+        run: |
+          python -m venv .venv
+          . .venv/bin/activate
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Type check
+        run: |
+          . .venv/bin/activate
+          make type-check
+
+  tests:
+    name: Tests with coverage
+    needs: [lint, type-check]
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          cache-dependency-path: |
+            pyproject.toml
+
+      - name: Cache virtualenv
+        id: cache-venv
+        uses: actions/cache@v5
+        with:
+          path: .venv
+          key: ${{ runner.os }}-venv-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-venv-${{ steps.setup-python.outputs.python-version }}-
+
+      - name: Cache Numba compiled objects
+        uses: actions/cache@v5
+        with:
+          path: |
+            src/pantr/basis/__pycache__
+            src/pantr/bezier/__pycache__
+            src/pantr/bspline/__pycache__
+          key: ${{ runner.os }}-numba-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('src/**/*.py') }}
+          restore-keys: |
+            ${{ runner.os }}-numba-${{ steps.setup-python.outputs.python-version }}-
+
+      - name: Install OpenMPI
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y libopenmpi-dev openmpi-bin
+
+      - name: Create venv and install dev deps (on cache miss)
+        if: steps.cache-venv.outputs.cache-hit != 'true'
+        run: |
+          python -m venv .venv
+          . .venv/bin/activate
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests with JIT (populates Numba cache)
+        run: |
+          . .venv/bin/activate
+          make test
+
+      - name: Run pytest with coverage
+        run: |
+          . .venv/bin/activate
+          make coverage
+
+      - name: Upload coverage xml
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-xml-py${{ matrix.python-version }}-run${{ github.run_attempt }}
+          path: coverage.xml
+          if-no-files-found: error
+
+  docs:
+    name: Build documentation
+    needs: [lint, type-check]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Cache Sphinx doctrees
+        uses: actions/cache@v5
+        with:
+          path: docs/_build/doctrees
+          key: ${{ runner.os }}-sphinx-${{ hashFiles('docs/**/*.md', 'docs/conf.py', 'pyproject.toml', 'src/**/*.py') }}
+
+      - name: Cache intersphinx inventories
+        id: cache-intersphinx
+        uses: actions/cache@v5
+        with:
+          path: docs/_intersphinx
+          key: ${{ runner.os }}-intersphinx-${{ hashFiles('docs/conf.py') }}
+          restore-keys: |
+            ${{ runner.os }}-intersphinx-
+
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: "pip"
+          cache-dependency-path: |
+            pyproject.toml
+
+      - name: Cache virtualenv
+        id: cache-venv
+        uses: actions/cache@v5
+        with:
+          path: .venv
+          key: ${{ runner.os }}-venv-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('pyproject.toml', 'docs/**/*.md', 'docs/conf.py') }}
+          restore-keys: |
+            ${{ runner.os }}-venv-${{ steps.setup-python.outputs.python-version }}-
+
+      - name: Create venv and install docs deps (on cache miss)
+        if: steps.cache-venv.outputs.cache-hit != 'true'
+        run: |
+          python -m venv .venv
+          . .venv/bin/activate
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Download intersphinx inventories (on cache miss)
+        if: steps.cache-intersphinx.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p docs/_intersphinx
+          curl -fsSL --retry 3 --retry-delay 2 https://docs.python.org/3/objects.inv \
+            -o docs/_intersphinx/python.inv || rm -f docs/_intersphinx/python.inv
+          curl -fsSL --retry 3 --retry-delay 2 https://numpy.org/doc/stable/objects.inv \
+            -o docs/_intersphinx/numpy.inv || rm -f docs/_intersphinx/numpy.inv
+          curl -fsSL --retry 3 --retry-delay 2 https://docs.scipy.org/doc/scipy/objects.inv \
+            -o docs/_intersphinx/scipy.inv || rm -f docs/_intersphinx/scipy.inv
+          curl -fsSL --retry 3 --retry-delay 2 https://matplotlib.org/stable/objects.inv \
+            -o docs/_intersphinx/matplotlib.inv || rm -f docs/_intersphinx/matplotlib.inv
+
+      - name: Build docs
+        run: |
+          . .venv/bin/activate
+          make docs SPHINXOPTS="-W --keep-going -j auto"
+
+  mpi-tests:
+    name: MPI tests (mpiexec)
+    needs: [lint, type-check]
+    runs-on: ubuntu-latest
+    # The only job that exercises the real distributed stack under multiple ranks. It
+    # builds mpi4py from source against the system OpenMPI -- the prebuilt wheels are not
+    # guaranteed to match the system launcher's wire protocol. PANTR_RUN_MPI enables the
+    # otherwise-skipped tests under tests/mpi/.
+    env:
+      PANTR_RUN_MPI: "1"
+      PIP_NO_BINARY: "mpi4py"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: "pip"
+          cache-dependency-path: |
+            pyproject.toml
+
+      - name: Install OpenMPI
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y libopenmpi-dev openmpi-bin
+
+      - name: Cache virtualenv
+        id: cache-venv
+        uses: actions/cache@v5
+        with:
+          path: .venv
+          key: ${{ runner.os }}-venv-${{ steps.setup-python.outputs.python-version }}-mpi-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-venv-${{ steps.setup-python.outputs.python-version }}-mpi-
+
+      - name: Create venv and install (with mpi4py built from source, on cache miss)
+        if: steps.cache-venv.outputs.cache-hit != 'true'
+        run: |
+          python -m venv .venv
+          . .venv/bin/activate
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Verify mpi4py matches the launcher
+        run: |
+          . .venv/bin/activate
+          mpiexec --oversubscribe -n 2 python -c "from mpi4py import MPI; assert MPI.COMM_WORLD.size == 2"
+
+      - name: Run MPI smoke tests (2 ranks)
+        run: |
+          . .venv/bin/activate
+          mpiexec --oversubscribe -n 2 python -m pytest tests/mpi/ --no-cov -p no:cacheprovider
+
+      - name: Run MPI smoke tests (3 ranks)
+        run: |
+          . .venv/bin/activate
+          mpiexec --oversubscribe -n 3 python -m pytest tests/mpi/ --no-cov -p no:cacheprovider