lme-python 0.2.2__tar.gz → 0.2.4__tar.gz

lme_python-0.2.4/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: x4g4p3x

{lme_python-0.2.2 → lme_python-0.2.4}/.github/workflows/audit.yml

@@ -28,7 +28,7 @@ jobs:
           toolchain: stable
 
       - name: Install cargo-audit
-        uses: taiki-e/install-action@7f4eb899022d8fe70b20c4f3de697aa85c309026 # v2
+        uses: taiki-e/install-action@84f5ac3124727fb3d284d4d22ee9ab3654fd09a6 # v2
         with:
           tool: cargo-audit@0.22.1
 
@@ -48,7 +48,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.11"
           enable-cache: true

{lme_python-0.2.2 → lme_python-0.2.4}/.github/workflows/benchmarks.yml

@@ -18,6 +18,7 @@ on:
 permissions:
   contents: write
   id-token: write
+  pages: write
 
 env:
   CARGO_TERM_COLOR: always
@@ -200,3 +201,78 @@ jobs:
           echo "Cross-language benchmark script failed with exit code ${{ steps.cross_language_run.outputs.status }}." >&2
           exit 1
 
+  pages:
+    name: Publish Benchmark Dashboard
+    runs-on: ubuntu-latest
+    needs:
+      - criterion
+      - cross-language
+    if: >
+      always() &&
+      needs.criterion.result == 'success' &&
+      needs.cross-language.result == 'success' &&
+      (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/'))
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    concurrency:
+      group: pages
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Download cross-language artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: cross-language-${{ github.sha }}
+          path: site-input
+
+      - name: Resolve release URL
+        id: release_url
+        run: |
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            echo "value=${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/releases/tag/${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build benchmark dashboard
+        run: |
+          set -euo pipefail
+          mkdir -p site
+          cp -R docs/. site/
+          extra=()
+          fair_json="$(find site-input -name 'fair-rust-julia-*.json' -print -quit || true)"
+          cross_json="$(find site-input -name 'cross-language-*.json' -print -quit || true)"
+          if [ -n "${fair_json}" ]; then
+            extra+=(--ci-fair-json "${fair_json}" --fair-asset-name "fair-rust-julia-${GITHUB_SHA}.json")
+          fi
+          if [ -n "${cross_json}" ]; then
+            extra+=(--cross-language-json "${cross_json}" --cross-language-asset-name "cross-language-${GITHUB_SHA}.json")
+          fi
+          python3 scripts/build_benchmark_site.py \
+            --output-dir site/benchmarks/data \
+            --run-url "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}" \
+            --release-url "${{ steps.release_url.outputs.value }}" \
+            --criterion-asset-name "criterion-${GITHUB_SHA}.tar.gz" \
+            --ref-name "${GITHUB_REF_NAME}" \
+            "${extra[@]+"${extra[@]}"}"
+
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+

{lme_python-0.2.2 → lme_python-0.2.4}/.github/workflows/cache-prime.yml

@@ -54,7 +54,7 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: echo "OPENBLAS_TARGET=ARMV8" >> "$GITHUB_ENV"
       - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-test
           cache-workspace-crates: ${{ runner.os != 'Linux' }}
@@ -76,7 +76,7 @@ jobs:
       - name: Install OpenBLAS
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
       - name: Cache production-load Rust dependencies
-        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-release
           cache-workspace-crates: true
@@ -105,7 +105,7 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: echo "OPENBLAS_TARGET=ARMV8" >> "$GITHUB_ENV"
       - name: Cache Python Rust dependencies
-        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-${{ runner.os }}-python
           workspaces: python -> target

{lme_python-0.2.2 → lme_python-0.2.4}/.github/workflows/ci.yml

@@ -36,6 +36,8 @@ jobs:
         run: python3 scripts/ci/lme_ci.py legal
       - name: Validate Markdown links
         run: python3 scripts/ci/lme_ci.py docs-links
+      - name: Validate benchmark dashboard data
+        run: python3 scripts/ci/lme_ci.py benchmark-site --check
       - name: Validate completion score claims
         run: python3 scripts/ci/lme_ci.py completion-check
 
@@ -56,7 +58,7 @@ jobs:
       - name: Install OpenBLAS
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
       - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-test
           save-if: ${{ github.event_name == 'pull_request' || github.ref == 'refs/heads/master' }}
@@ -113,7 +115,7 @@ jobs:
           toolchain: stable
 
       - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-test
           cache-workspace-crates: true
@@ -141,7 +143,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
 
       - name: Restore Rust dependencies
-        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-release
           cache-workspace-crates: true
@@ -169,13 +171,13 @@ jobs:
       - name: Install OpenBLAS
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
       - name: Cache Python Rust dependencies
-        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-${{ runner.os }}-python
           workspaces: python -> target
           save-if: ${{ matrix.python-version == '3.11' && (github.event_name == 'pull_request' || github.ref == 'refs/heads/master') }}
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true
@@ -205,13 +207,13 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: echo "OPENBLAS_TARGET=ARMV8" >> "$GITHUB_ENV"
       - name: Cache Python Rust dependencies
-        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
+        uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           shared-key: ci-${{ runner.os }}-python
           workspaces: python -> target
           save-if: ${{ github.event_name == 'pull_request' || github.ref == 'refs/heads/master' }}
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.11"
           enable-cache: true

{lme_python-0.2.2 → lme_python-0.2.4}/.github/workflows/fuzz-smoke.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Install cargo-fuzz
         run: cargo install cargo-fuzz@0.13.2 --locked
 
-      - uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
+      - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
           workspaces: fuzz
 

lme_python-0.2.4/.github/workflows/pages.yml

@@ -0,0 +1,56 @@
+name: GitHub Pages
+
+# Publishes the static dashboard from checked-in docs/ plus regenerated JSON.
+# Tag/manual benchmark runs can overlay CI artifacts via benchmarks.yml.
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - "docs/**"
+      - "benchmarks/*.json"
+      - "scripts/build_benchmark_site.py"
+      - "scripts/ci/lme_ci.py"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build dashboard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Assemble site
+        run: python3 scripts/ci/lme_ci.py benchmark-site --site-dir site
+
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    name: Deploy
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

{lme_python-0.2.2 → lme_python-0.2.4}/.github/workflows/python-release.yml

@@ -256,7 +256,7 @@ jobs:
         uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
 
       - name: Upload to GitHub Release
-        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
           files: dist/*
           tag_name: ${{ inputs.release_tag }}

lme_python-0.2.4/AGENTS.md

@@ -0,0 +1,148 @@
+# Agent guide
+
+This is a Rust statistical library (`lme-rs`) with PyO3/maturin Python bindings
+(`lme_python`). There is no application server to start. Run commands from the
+repository root unless stated otherwise.
+
+## Start here
+
+1. Inspect `git status --short --branch` and the relevant diff. Preserve unrelated
+   changes; do not reset, stash, switch branches, or update dependencies as routine setup.
+2. Use `rg` and the map below to find the implementation and existing tests. Read
+   relevant guides rather than scanning the whole repository before a focused fix.
+3. Choose required checks before editing. Reproduce bugs with focused tests, fix
+   the cause, and verify both the regression and affected behavior.
+4. Update [CHANGELOG.md](CHANGELOG.md) under `Unreleased` for user-visible fixes,
+   features, and compatibility changes. Instruction-only edits need no entry.
+5. Review the final diff. Report changes, validation, and failures/skips/limitations;
+   do not claim unrun checks.
+
+## Code map
+
+| Area | Start with |
+|---|---|
+| Public API, contracts, reusable fits | `src/lib.rs`, `src/model.rs`, `src/prepared.rs` |
+| Formulas and design matrices | `src/formula.rs`, `src/model_matrix.rs`, `src/basis.rs` |
+| LMM / GLMM / nonlinear fitting | `src/math.rs`, `src/optimizer.rs`, `src/intercept_blocked.rs` / `src/glmm_math.rs`, `src/family.rs` / `src/nlmm/` |
+| Inference and post-fit behavior | `src/contrast.rs`, `src/ddf.rs`, `src/satterthwaite.rs`, `src/kenward_roger.rs`, `src/kr_modcomp.rs`; named modules such as `predict.rs`, `simulate.rs`, `emmeans.rs`, `mcp.rs`, `robust.rs` |
+| Python API and tests | `python/src/lib.rs`, `python/tests/` |
+| Regression tests and reference evidence | `tests/`, `tests/data/`, `comparisons/` |
+| Checks, aliases, hooks, tool versions | [scripts/ci/lme_ci.py](scripts/ci/lme_ci.py), [Taskfile.yml](Taskfile.yml), [lefthook.yml](lefthook.yml), [mise.toml](mise.toml) |
+
+## Required validation
+
+Use the smallest tier covering the change. Requirements from multiple rows combine;
+a successful broader check can satisfy its component checks.
+
+| Change | Minimum checks and escalation |
+|---|---|
+| Rust code | `task lint`, `task test:fast`, and affected integration tests; use `task rust` for cross-module or public-API changes |
+| Python bindings | `task lint:python`, `task python` |
+| CI, manifests, release tooling | `task preflight`; use `task ci` before a release or broad refactor |
+| R / Julia comparison scripts | `task lint:comparisons`; use `task lint:comparisons:required` when formatters are installed |
+| Documentation (including this file) or portable examples | `task docs:check`; add `task consumer:smoke` when install or example behavior changes |
+| LMM throughput paths (`src/math.rs`, `src/optimizer.rs`, related caches/solvers) | Read [OPTIMIZATION.md](OPTIMIZATION.md) and run applicable fair-harness cases in addition to Rust checks |
+| `README.md`, `REPO_COMPLETION_BY_AREA.md`, `completion_manifest.json`, `scripts/ci/check_completion_score.py` | `task completion:check` |
+
+### Avoid redundant work
+
+- Start with `cargo test --locked --test <test_target> <test_filter>` or
+  `cargo test --locked --lib <test_filter>`. Selecting zero tests proves nothing.
+- `task rust` includes Rust lint, all-target compilation, unit/integration tests,
+  doctests, and documentation generation. Add `task lint:python` for the Ruff part
+  of `task lint`; do not separately repeat `task test:fast`.
+- `task test` runs the full Rust suite. On Windows/macOS, `task test:consolidated`
+  runs unit and integration tests with one integration executable, checks examples,
+  and runs doctests. It can replace `task test` when linking is costly. An equivalent
+  Rust validation slice is `task lint:rust`, `task check`, `task test:consolidated`,
+  and `python scripts/ci/lme_ci.py doc`.
+- `task ci` includes Rust, bindings, portable examples, lint, compilation, legal,
+  documentation, and completion checks. It does not replace audits/metadata in
+  `task preflight`, R/Julia checks, or performance harnesses. `task ci:fast` skips
+  the isolated-wheel pass; report that limitation.
+- Reuse passing results for unchanged files/dependencies in the same task. Rerun
+  affected checks after edits; broaden when scope or evidence requires it.
+  Keep hooks enabled even when they repeat earlier checks.
+- Serialize Cargo commands sharing a target directory. Capture verbose logs and
+  inspect exit status and summaries. A timeout or compilation in progress is not a failed test.
+
+## Correctness and evidence
+
+- Add regression coverage for bug fixes. Prefer statistical identities, explicit
+  expected behavior, and independent fixtures over duplicating the implementation.
+- Register new integration test files in [tests/ci_consolidated.rs](tests/ci_consolidated.rs).
+- For R/Julia parity, match rows, formula, family/link, weights, offsets, and ML/REML.
+  Explain tolerances; do not loosen them just to make a failure pass.
+- Tie benchmark claims to the revision, environment, and measured cases. Follow
+  [BENCHMARKS.md](BENCHMARKS.md) and [OPTIMIZATION.md](OPTIMIZATION.md); a focused
+  speedup does not establish general parity or completion.
+
+### Completion scores are generated claims
+
+[completion_manifest.json](completion_manifest.json) governs the README headline
+and all percentages in [REPO_COMPLETION_BY_AREA.md](REPO_COMPLETION_BY_AREA.md).
+It declares weighted binary commitments, locked `scope` strings, evidence paths,
+and a `gap` for every incomplete criterion.
+
+- Complete an item only when its locked scope is met and evidence is current.
+  Partial, stale, or substituted evidence earns zero; an API or focused benchmark is insufficient.
+- Do not narrow/replace `scope` to earn credit or edit generated percentages by hand.
+  Update the manifest and supporting evidence together.
+- `task completion:check` validates schema version 2, names/scopes/gaps, evidence
+  paths, arithmetic, report rows, and the README headline. `task ci` includes it.
+
+## Setup and recovery
+
+- [mise.toml](mise.toml) configures Rust stable, Python 3.11, uv, Task, and Lefthook.
+  Use `task setup` for tools and hooks; run `mise install` first if Task is missing.
+  With tools already installed, use `task hooks:install`. Pre-push audits also
+  require `cargo-audit` (`cargo install cargo-audit`).
+- For missing PATH entries, use `mise exec -- task <name>`. Locate installed tools
+  before reinstalling. Verify subprocess discovery in the actual environment with
+  `python -c "import shutil; print(shutil.which('uv'))"` when necessary.
+- Without Task, use `python scripts/ci/lme_ci.py <subcommand>` (`python3` where
+  appropriate). Mappings are in [Taskfile.yml](Taskfile.yml): `test:fast` → `test-fast`,
+  `rust` → `rust-all`, `lint:python` → `ruff-lint`, `docs:check` → `docs-check`.
+  Use `--help` for all commands. Implement new checks in this runner, not duplicate shell logic.
+- For Git dubious ownership, use `git -c safe.directory=C:/path/to/lme-rs <command>`
+  with this checkout's absolute forward-slash path; do not trust all directories globally.
+- x86_64 builds link static Intel MKL via `ndarray-linalg`; first builds can be slow.
+  Run numerical examples with `--release`, e.g. `cargo run --release --locked --example sleepstudy`.
+  Leave the CI runner's own build profiles unchanged.
+- Windows linker errors `LNK1318`/`LNK1106` can indicate disk exhaustion. Check space
+  and active builds first. Before cleaning, verify the target belongs to this checkout
+  and no build uses it; avoid broad cache deletion.
+- `uv sync` can uninstall the editable Python extension. Restore it from `python/`
+  with `uv run --no-sync maturin develop --release`, or rerun `task python`.
+  Run Python examples there with `uv run --no-sync python examples/<name>.py`.
+
+## Git, hooks, and release boundaries
+
+- Follow the user's commit/push scope; commit authorization alone does not authorize
+  pushing. When already authorized, complete validation and delivery without asking again.
+- For requested updates, fetch before comparing branches; fast-forward only when
+  ancestry and local changes permit it. After pushing, verify HEAD, the tracking ref,
+  and live remote branch SHA agree, and report remaining local changes.
+- Lefthook checks matching staged files: Rust format/Clippy, Python Ruff, comparison
+  formatting, manifests, benchmarks/dashboard, and metadata. Hooks may auto-stage
+  formatting; inspect the result. They do not run full Rust/bindings suites or `pip-audit`.
+- Pre-push runs `task preflight`: lint, all-target compilation, Cargo audits,
+  legal/provenance, and metadata validation. Use `--no-verify` only when explicitly
+  necessary; report the bypass and omitted checks.
+- Hosted validation runs on PRs, `v*` tags, and manual dispatch, not ordinary branch
+  pushes. Cache-prime is not validation. Hosted coverage adds the OS/Python matrix,
+  production-load gates, and `pip-audit`; PRs skip the four heavy ignored cases.
+- Inspect the exact failing CI job/log before changing code. Do not merge with a
+  failing security audit. For metadata authentication, use `REPO_ADMIN_TOKEN` with
+  `task repo-metadata`; a hosted `401` requires checking/rotating the Actions secret.
+- Preserve full-SHA action pins and readable version comments. After BLAS target-table
+  or release-workflow changes, run `task ci` or manually dispatch CI before tagging;
+  Windows/Linux cannot validate macOS Apple Silicon BLAS.
+- Tag CI gates crates.io publishing and dispatches PyPI only after validation succeeds.
+  Keep PyPI top-level for Trusted Publishing attestations; publishing workflows must
+  not independently listen to tags. Read [RELEASING.md](RELEASING.md) before releases.
+- R/Julia benchmark workflow coverage belongs in tag/manual runs. `task benchmarks:preflight`
+  includes Rust smoke and R smoke when R/lme4 is installed. Optional tool skips are not passes.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for extended guidance and
+[Taskfile.yml](Taskfile.yml) for less common commands.

{lme_python-0.2.2 → lme_python-0.2.4}/BENCHMARKS.md

@@ -1,8 +1,38 @@
-# Benchmarks
+# Benchmark guide and measurement history
 
-This repository includes Criterion benchmarks for the Rust crate. Performance is an important selling point of `lme-rs`, but the benchmark suite should be described accurately: it is useful and non-trivial, yet it is not comprehensive enough to support blanket speed claims on its own.
+[Documentation](docs/README.md) · [Coverage map](BENCHMARK_COVERAGE.md) · [Optimization notes](OPTIMIZATION.md) · [Dashboard](https://x4g4p3x.github.io/lme-rs/benchmarks/)
 
-**External reference map:** [BENCHMARK_COVERAGE.md](BENCHMARK_COVERAGE.md) lists which workflows have tier-A (fair) MixedModels.jl timing vs Rust-only Criterion benches. Use it before raising [REPO_COMPLETION_BY_AREA.md](REPO_COMPLETION_BY_AREA.md) axis (3) percentages.
+Choose a harness by the question you want to answer. Numerical parity and
+throughput are separate forms of evidence.
+
+## Choose a benchmark
+
+| Question | Command | What is timed |
+|:---------|:--------|:--------------|
+| Did a Rust operation regress? | `cargo bench --locked --bench bench_math` | Criterion operations, fit paths, and inference |
+| How does matched fitting compare with Julia? | `task benchmarks:fair-rust-julia` | Fit-only medians with shared inputs and warmups |
+| Where is fitting time spent? | `task benchmarks:perf-breakdown` | Rust phases and Julia optimizer evaluations |
+| What do R inference/NLMM and Python overhead cost? | `task benchmarks:external-timings` | Operations supported by the external harness |
+| Do cross-language example scripts run? | `python scripts/run_cross_language_benchmarks.py` | Whole scripts, including runtime startup |
+| Does the dashboard match its source JSON? | `task docs:check` | Data drift validation, not a new measurement |
+
+Run from the repository root. External harnesses require their reference
+runtimes and packages; a skipped implementation is not a measured comparison.
+See [the coverage map](BENCHMARK_COVERAGE.md#running-benchmarks) for setup.
+
+## Reading order
+
+- [Suite coverage](#current-benchmark-coverage) and [remaining gaps](#what-it-does-not-cover-yet)
+- [Methodology](#cross-language-benchmark-methodology)
+- [Commands](#how-to-run-the-benchmarks)
+- [Fair reference results](#fair-rust-vs-julia-reference-results)
+- [Published artifacts](#latest-published-results)
+- [Interpretation](#how-to-interpret-results)
+
+The detailed experiments below are **dated measurement history**. A wording
+update does not rerun them. The July 22 reference contains 10 LMM and 2 GLMM
+cases; later GLMM fitting changes mean its GLMM rows cannot establish current
+performance. Hardware, revision, BLAS, and timing boundaries matter.
 
 ## Native formula parser optimization (2026-08-10)
 
@@ -76,19 +106,24 @@ What the repo still does not provide is a fully normalized cross-ecosystem harne
 It does not yet isolate or compare:
 
 - prediction throughput on large crossed and nested structures
-- weighted GLMM-style workflows if those are added later
+- weighted GLMM throughput across representative model sizes
 - GLMM inference and post-fit helper costs beyond the currently benchmarked paths
 - confidence interval and simulation throughput across multiple model sizes
 
 ### Missing benchmark dimensions
 
-It does not currently sweep over controlled workload dimensions such as:
+The Rust suite already includes parameterized observation/group-count and
+nested/crossed complexity sweeps. It does not provide a complete factorial
+comparison across every combination of:
+
+- response family and link
+- random-effect dimension and correlation structure
+- dense-like versus sparse-like layouts
+- prediction, simulation, and inference workloads
+- reference language and optimizer configuration
 
-- number of observations
-- number of groups
-- random intercept vs random slope structure
-- family and link combinations
-- dense-like vs sparse-like random-effect structure
+Use a named case that represents your workload rather than inferring coverage
+from the existence of one large synthetic benchmark.
 
 ## Cross-language benchmark methodology
 
@@ -230,7 +265,7 @@ Work on [`src/math.rs`](src/math.rs) and [`src/optimizer.rs`](src/optimizer.rs):
 
 ### 2026-07-08 blocked augmented Cholesky (MixedModels-style)
 
-Implemented [`src/intercept_blocked.rs`](src/intercept_blocked.rs): precomputed per-RE Gram blocks, RE ordering by level count, and per-θ **blocked Cholesky** in the layout of MixedModels.jl [`updateL!`](https://github.com/JuliaStats/MixedModels.jl/blob/main/src/linearmixedmodel.jl) — profile deviance from the factored `Xy` block **without** q-dimensional LDL solves or explicit β on the hot path. Full write-up: **[OPTIMIZATION.md § Blocked augmented Cholesky](OPTIMIZATION.md#blocked-augmented-cholesky--what-delivered-the-crossed-speedup-2026-07-08)**.
+Implemented [`src/intercept_blocked.rs`](src/intercept_blocked.rs): precomputed per-RE Gram blocks, RE ordering by level count, and per-θ **blocked Cholesky** in the layout of MixedModels.jl [`updateL!`](https://github.com/JuliaStats/MixedModels.jl/blob/main/src/linearmixedmodel.jl) — profile deviance from the factored `Xy` block **without** q-dimensional LDL solves or explicit β on the hot path. Full write-up: **[OPTIMIZATION.md § Blocked augmented Cholesky](OPTIMIZATION.md#blocked-augmented-cholesky)**.
 
 **Recorded:** 2026-07-08, same Windows AMD64 workstation; `rustc 1.96.0`; 2 warmups + 10 measured fits (`scripts/run_fair_rust_julia_benchmark.py --implementations rust`).
 
@@ -246,7 +281,7 @@ Implemented [`src/intercept_blocked.rs`](src/intercept_blocked.rs): precomputed
 
 ### 2026-07-08 blocked Cholesky hot-path pass
 
-Removed per-θ **clone/alloc** overhead in [`src/intercept_blocked.rs`](src/intercept_blocked.rs) (in-place Schur, fused `assign_scaled`, reused workspaces) and tightened the ML 2D log-grid to **5×5 + 4×4** (~42 evals). Nested sparse crosses remain on reused LDL (`fits_blocked_gate`). Details: **[OPTIMIZATION.md § Closing the crossed_20k gap](OPTIMIZATION.md#closing-the-crossed_20k-gap-vs-julia-14-ms)**.
+Removed per-θ **clone/alloc** overhead in [`src/intercept_blocked.rs`](src/intercept_blocked.rs) (in-place Schur, fused `assign_scaled`, reused workspaces) and tightened the ML 2D log-grid to **5×5 + 4×4** (~42 evals). Nested sparse crosses remain on reused LDL (`fits_blocked_gate`). Details: **[OPTIMIZATION.md § Closing the crossed_20k gap](OPTIMIZATION.md#progress-timeline)**.
 
 **Recorded:** 2026-07-08, same Windows AMD64 workstation; `rustc 1.96.0`; 2 warmups + 10 measured fits (`--implementations rust`).
 
@@ -262,7 +297,7 @@ Removed per-θ **clone/alloc** overhead in [`src/intercept_blocked.rs`](src/inte
 
 ### 2026-07-08 GEMM, batched trisolve, and prepared fit
 
-Further blocked-kernel tuning in [`src/intercept_blocked.rs`](src/intercept_blocked.rs) plus **`prepare_lmer` / `fit_prepared`** in [`src/lib.rs`](src/lib.rs). Full write-up: **[OPTIMIZATION.md § Blocked kernel tuning](OPTIMIZATION.md#blocked-kernel-tuning--gemm-batched-trisolve-prepared-fit-2026-07-08-continued)**.
+Further blocked-kernel tuning in [`src/intercept_blocked.rs`](src/intercept_blocked.rs) plus **`prepare_lmer` / `fit_prepared`** in [`src/lib.rs`](src/lib.rs). Full write-up: **[OPTIMIZATION.md § Blocked kernel tuning](OPTIMIZATION.md#blocked-kernel-tuning)**.
 
 **Recorded:** 2026-07-08, same Windows AMD64 workstation; `rustc 1.96.0`; `bench_perf_breakdown` with 1 warmup + measured `fit_prepared`.
 
@@ -433,9 +468,12 @@ The repository also includes a dedicated workflow in [.github/workflows/benchmar
 - runs the cross-language example-script benchmark
 - uploads the resulting artifacts in CI
 - attaches them to GitHub Releases on tag pushes
+- publishes the fair-harness dashboard to GitHub Pages at [`https://x4g4p3x.github.io/lme-rs/benchmarks/`](https://x4g4p3x.github.io/lme-rs/benchmarks/)
 
 ## Latest published results
 
+The public dashboard at [`https://x4g4p3x.github.io/lme-rs/benchmarks/`](https://x4g4p3x.github.io/lme-rs/benchmarks/) charts the checked-in fair Rust vs MixedModels.jl reference plus the Julia-free external timings. Tag/manual [benchmark workflow](.github/workflows/benchmarks.yml) runs can overlay GitHub-hosted runner JSON. Rebuild the committed payload with `task benchmarks:site` after changing a reference file.
+
 Release-attached Criterion and cross-language JSON artifacts are uploaded by [`.github/workflows/benchmarks.yml`](.github/workflows/benchmarks.yml) on `v*` tags (and manual dispatch). Prefer the [latest GitHub Release](https://github.com/x4g4p3x/lme-rs/releases/latest) for downloadable CI artifacts, and [`CHANGELOG.md`](CHANGELOG.md) for which crate version each tag ships.
 
 **Engineering source of truth for fair Rust vs Julia fit timing** is the checked-in reference JSON under [`benchmarks/`](benchmarks/), especially the full strict-target [2026-07-22 tier-A artifact](benchmarks/fair-rust-julia-reference-2026-07-22-full-tier-a.json). Older tags (for example [v0.1.3](https://github.com/x4g4p3x/lme-rs/releases/tag/v0.1.3)) still carry historical CI tarballs useful for release-to-release comparison, but they are **not** the current performance baseline.
@@ -453,15 +491,24 @@ If you want to cite benchmark results in release notes or external docs, prefer
 
 ## How to interpret results
 
-Use the existing suite primarily for:
+Compare medians from the same machine, model, and measurement boundary.
 
-- detecting regressions after changes to fitting logic
-- tracking the cost of core LMM and GLMM paths over time
-- sanity-checking large synthetic scaling cases
+| Metric | Includes | Appropriate use |
+|:-------|:---------|:----------------|
+| `cold_fit` | One fit including its setup | One-shot API latency |
+| `prepare_lmer` | Reusable design construction | Setup cost |
+| `fit_prepared` | Fitting a cached design | Repeated fixed-design work |
+| Whole-script elapsed time | Startup, I/O, setup, fitting, and printed output | End-to-end script cost |
+| Criterion operation | The operation selected by the benchmark | Within-Rust regression tracking |
 
-Do not use the current suite alone as evidence that `lme-rs` is universally faster than `lme4`, `statsmodels`, or `MixedModels.jl`.
+A Rust/Julia ratio below 1 means Rust was faster for that measured row.
+Do not compare a hot prepared fit to a competitor's full process startup.
 
-The [fair Rust vs Julia harness](#fair-rust-vs-julia-reference-results) on the 2026-07-06 Windows reference showed **MixedModels.jl still faster on every fit-only case**, but the gap **narrowed sharply** on random-intercept workloads (~**2×** vs ~**5–9×** on the 2026-07-04 baseline). Crossed (~**19×**) and nested (~**8×**) were the main gaps on that reference. An [2026-07-07 pass](#fair-rust-julia-2026-07-07-wip) cuts crossed to ~**8×** and nested to ~**2.5×**; [blocked Cholesky](#fair-rust-julia-2026-07-08-blocked-cholesky) and [hot-path tuning](#fair-rust-julia-2026-07-08-blocked-hotpath) cut cold `lmer()` to ~**52 ms**; a [GEMM + prepared-fit pass](#fair-rust-julia-2026-07-08-gemm-prepared) brings **`fit_prepared` to ~13 ms** (~**1×** Julia on `crossed_20k`); a [setup/post-fit pass](#fair-rust-julia-2026-07-08-setup-postfit) cuts cold `lmer()` to **~22 ms** (~**1.4×** Julia on crossed, **~1.1×** on random intercept); a [prepare ownership pass](#fair-rust-julia-2026-07-08-prepare-ownership) brings **`random_intercept_10k` ahead of Julia** and crossed to **~1.3×**; a [nested blocked path + post-fit backsolve pass](#fair-rust-julia-2026-07-08-nested-postfit) brings tier-A cases **within ~2× Julia** on cold `lmer()` (`crossed_20k` **~1.2×**, hot **`fit_prepared` beats Julia** on all three). See [OPTIMIZATION.md](OPTIMIZATION.md) for engineering detail. Treat these as versioned datapoints — re-run the harness on your hardware before citing speed claims.
+The historical sections document how earlier crossed and nested bottlenecks
+were reduced. They are not predictions for every model shape. The
+[July 22 artifact](benchmarks/fair-rust-julia-reference-2026-07-22-full-tier-a.json)
+and [coverage map](BENCHMARK_COVERAGE.md) are the concise entry points to that
+reference set. Re-run after relevant code changes before making a new claim.
 
 ## Recommended next extensions
 
@@ -473,15 +520,12 @@ If performance is going to remain a central public claim, the benchmark suite sh
 4. More explicit GLMM post-fit benchmarks beyond fitting, prediction, and Wald intervals.
 5. Benchmarks that isolate optimizer iteration cost separately from formula parsing and matrix construction.
 
-## Recommendation for this repo today
-
-The current benchmarking is meaningful, but not comprehensive.
+## Maintaining performance claims
 
-That means:
+Use Criterion as a regression guard and the fair harness for external timing.
+Keep raw artifacts, case names, code revision, environment, and methodology
+with each claim. Refresh only the evidence affected by a change.
 
-- yes, keep performance as a **completion criterion** for Rust-native workflows, not only regression tracking (Criterion + fair harness)
-- yes, keep **LMM fit optimization** as a regression guard: axis (3) requires **<1.0×** Julia on tier-A `cold_fit` ([2026-07-22 full reference](benchmarks/fair-rust-julia-reference-2026-07-22-full-tier-a.json))
-- yes, tier-A hot `fit_prepared` and cold `lmer()` both beat MixedModels.jl throughout the current full reference; re-run before citing new speed claims
-- no, Julia bindings to `lme-rs` are not justified by speed — see [fair Rust vs Julia results](BENCHMARKS.md#fair-rust-vs-julia-reference-results)
-- yes, run benchmarks for performance-sensitive changes before release
-- yes, extend the benchmark surface (GLMM fit-only, prediction sweeps) as optimization work proceeds
+Completion thresholds are governed by [the locked manifest](completion_manifest.json)
+and [coverage policy](BENCHMARK_COVERAGE.md). A faster microbenchmark or revised
+description alone does not satisfy a broader completion criterion.