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

lme_python-0.2.3/.github/FUNDING.yml

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

{lme_python-0.2.2 → lme_python-0.2.3}/.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.3}/.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.3}/.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.3}/.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.3}/.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.3/.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.3}/.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.2 → lme_python-0.2.3}/AGENTS.md

@@ -10,7 +10,7 @@ Use the smallest validation tier that proves the change is sound, then run the e
 | 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 the formatters are installed |
-| Documentation or portable examples | `task docs:check`; use `task consumer:smoke` when install or example behavior changes |
+| Documentation or portable examples | `task docs:check` (includes dashboard JSON drift); use `task consumer:smoke` when install or example behavior changes |
 | LMM throughput paths (`src/math.rs`, `src/optimizer.rs`) | Read [OPTIMIZATION.md](OPTIMIZATION.md) and run the applicable fair-harness cases |
 | Completion score files: `README.md`, `REPO_COMPLETION_BY_AREA.md`, `completion_manifest.json`, or `scripts/ci/check_completion_score.py` | `task completion:check` |
 
@@ -20,10 +20,10 @@ For a change that crosses several rows, run every applicable check. Full Rust in
 
 The completion headline in [README.md](README.md) and every percentage in [REPO_COMPLETION_BY_AREA.md](REPO_COMPLETION_BY_AREA.md) are generated claims, not values to edit by hand.
 
-- [completion_manifest.json](completion_manifest.json) is the source of truth: it declares binary scope commitments, their weights, and evidence paths.
-- `task completion:check` validates evidence-path existence, score arithmetic, report rows, and the README headline.
-- A completion item may be marked complete only when its stated evidence is current. Partial or stale evidence earns zero.
-- Do not raise a score merely because an API exists, a focused benchmark passes, or the stated scope has been narrowed. Update the manifest and supporting evidence in the same change.
+- [completion_manifest.json](completion_manifest.json) is the source of truth: it declares binary scope commitments, their weights, locked `scope` strings, evidence paths, and a `gap` for every incomplete criterion.
+- `task completion:check` validates schema version 2 (names, scopes, gaps), evidence-path existence, score arithmetic, report rows, and the README headline.
+- A completion item may be marked complete only when its **locked scope** is met and its stated evidence is current. Partial, stale, or substituted evidence earns zero.
+- Do not raise a score merely because an API exists, a focused benchmark passes, or the stated scope has been narrowed or replaced. Do not edit `scope` to make an existing artifact pass. Update the manifest and supporting evidence in the same change.
 
 `task ci` runs this check automatically. Run it directly whenever a completion-related file changes.
 
@@ -95,6 +95,7 @@ For repository-metadata token issues, set `REPO_ADMIN_TOKEN` locally and run `ta
 | `task audit` / `task legal` | Security audit / provenance and license checks |
 | `task completion:check` | Verify the manifest-derived completion score and published markers |
 | `task docs:check` / `task consumer:smoke` | Validate docs/links/API examples / run clean-install Rust and Python workflows |
+| `task benchmarks:site` | Regenerate `docs/benchmarks/data/latest.json` from checked-in reference JSON |
 | `task benchmarks:fair-rust-julia` | Fair fit-only Rust vs MixedModels.jl timing when Julia packages are installed |
 | `task benchmarks:perf-breakdown` | Rust phase timings against Julia optimizer evaluation counts |
 | `task benchmarks:external-timings` | Fair-ish `nlmer`, post-fit inference, and Python FFI timings vs R when available |

{lme_python-0.2.2 → lme_python-0.2.3}/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.

{lme_python-0.2.2 → lme_python-0.2.3}/BENCHMARK_COVERAGE.md

@@ -1,8 +1,14 @@
 # Benchmark coverage map
 
+[Documentation](docs/README.md) · [Benchmark guide](BENCHMARKS.md) · [Optimization notes](OPTIMIZATION.md)
+
 This file maps **which parts of `lme-rs` have external performance references** (not just Rust-only Criterion benches). Use it to ground [REPO_COMPLETION_BY_AREA.md](REPO_COMPLETION_BY_AREA.md) axis (3) and [USABILITY.md](USABILITY.md) performance posture.
 
-**Last assessed:** 2026-08-14
+**Evidence assessment:** 2026-08-15. The catalog below reports dated artifacts,
+not measurements rerun during documentation maintenance.
+
+**Jump to:** [Harness tiers](#harness-tiers) · [Case catalog](#tier-a-case-catalog) ·
+[Commands](#running-benchmarks) · [Claim policy](#what-each-completion-row-may-claim)
 
 ---
 
@@ -23,7 +29,7 @@ This file maps **which parts of `lme-rs` have external performance references**
 
 Default target: **Rust median < 1.0× Julia median** on `cold_fit` for tier-A LMM cases on the reference workstation (strictly faster than MixedModels.jl).
 
-Prior milestones: **≤ 2×** (through 2026-07-08) while crossed/nested were multi× slower; **≤ 1.5×** (2026-07-09–15); selected crossed/nested strict passes on 2026-07-16. The [2026-07-22 full tier-A reference](benchmarks/fair-rust-julia-reference-2026-07-22-full-tier-a.json) records all 12 cases at the current **1.0×** gate with no failures.
+Prior milestones: **≤ 2×** (through 2026-07-08) while crossed/nested were multi× slower; **≤ 1.5×** (2026-07-09–15); selected crossed/nested strict passes on 2026-07-16. The [2026-07-22 full tier-A reference](benchmarks/fair-rust-julia-reference-2026-07-22-full-tier-a.json) records all 12 cases at the **1.0×** gate on that revision. LMM rows remain the current LMM evidence (`math.rs` / `optimizer.rs` unchanged); the two GLMM rows predate Gamma PIRLS phi profiling and multivariate AGQ-in-θ.
 
 ```powershell
 python scripts/run_fair_rust_julia_benchmark.py --implementations rust,julia --with-phases --repeats 10
@@ -47,18 +53,18 @@ Hot-path target (batch / CV): **`fit_prepared` ≤ ~1× Julia `fit`** when `--wi
 | `large_random_slopes_100k` | LMM | Synthetic (100k obs; 2k groups) | MixedModels.jl | **0.898×** | **0.646×** | Showcase: correlated intercept/slope, 3 θ; linear cache setup |
 | `crossed_20k` | LMM | Synthetic | MixedModels.jl | **0.879×** | **0.677×** | Direct two-factor Gram + allocation-free blocked gate |
 | `nested_10k` | LMM | Synthetic | MixedModels.jl | **0.961×** | **0.492×** | Direct slash design + membership Gram |
-| `cbpp_binomial_ml` | GLMM | Real binomial | MixedModels.jl GLMM | **0.749×** | N/A | Laplace; not R `nAGQ`-in-θ |
-| `grouseticks_poisson_ml` | GLMM | Real Poisson | MixedModels.jl GLMM | **0.033×** | N/A | Laplace |
+| `cbpp_binomial_ml` | GLMM | Real binomial | MixedModels.jl GLMM | **0.749×** | N/A | Historical Laplace timing; rerun after GLMM changes |
+| `grouseticks_poisson_ml` | GLMM | Real Poisson | MixedModels.jl GLMM | **0.033×** | N/A | Historical Laplace timing; rerun after GLMM changes |
 
 Cases not in tier A (no fair MixedModels.jl fit timing yet):
 
 | Area | Rust bench | Comparable | Status |
 |:-----|:-----------|:-----------|:-------|
-| `nlmer` / Orange | Golden parity + [`scripts/run_external_timings.py`](scripts/run_external_timings.py) | `lme4::nlmer` | **External R timing** (not Julia) |
-| GLMM AGQ (`n_agq > 1`) | Criterion | R semantics differ | **No** apples-to-apples |
+| `nlmer` / Orange | Golden parity + [`scripts/run_external_timings.py`](scripts/run_external_timings.py) | `lme4::nlmer` | **External R timing** (not Julia; inspect the dated artifact) |
+| GLMM AGQ (`n_agq > 1`) | Criterion | Match integration and optimizer settings | **No** matched external timing in this tier |
 | Post-fit inference (KR, ANOVA, predict) | Criterion + external harness | `lmerTest` when installed | **External R timing** for KR / Satterthwaite ANOVA |
 | LMM estimated marginal means / pairs | Criterion (`inference/emmeans_*`) | R `emmeans` correctness fixture | **Rust microbenchmark**; no cross-language speed claim |
-| Python `lme_python` FFI | External harness | Rust `lmer` | **External Python timing** |
+| Python `lme_python` FFI | External harness | Rust `lmer` | **External Python timing** (inspect the dated artifact) |
 | `lm` / `lm_df` | Minimal | R `lm` | **No** (usually negligible) |
 
 The 2026-08-14 Windows Criterion run measured `inference/emmeans_reference_grid` at **42.5–43.1 µs** and `inference/emmeans_pairs_tukey` at **52.9–56.8 µs** on the pastes fixture. These are post-fit operations and do not warrant a specialized cache at the current scale.
@@ -71,7 +77,7 @@ The 2026-08-14 Windows Criterion run measured `inference/emmeans_reference_grid`
 |:------------|:----------------------------|
 | **1 LMM** | Tier-A LMM cases meet `cold_fit` target (or documented exception) |
 | **2 GLMM** | Tier-A GLMM cases measured; do not infer from LMM row 13 alone |
-| **13 Throughput** | Fraction of tier-A cases at target; see case table above |
+| **13 Throughput** | Named LMM cases at target from a **current** artifact; full-suite-including-GLMM needs a rerun after GLMM fit-math changes |
 | **4 Inference** | Correctness / API only unless tier added |
 
 ---
@@ -122,4 +128,6 @@ A dated reference JSON lives under [`benchmarks/`](benchmarks/). Use `--rust-onl
 1. After optimization work on a workflow, add or refresh its tier-A case.
 2. Record medians in [BENCHMARKS.md](BENCHMARKS.md) and/or commit a dated reference JSON under [`benchmarks/`](benchmarks/).
 3. Update **Measured** / **Re-run** cells in the case catalog above.
-4. Adjust [REPO_COMPLETION_BY_AREA.md](REPO_COMPLETION_BY_AREA.md) row **13** only from tier-A evidence.
+4. Update [completion_manifest.json](completion_manifest.json) and its supporting
+   evidence only when the existing locked scope is met. Keep generated report
+   markers aligned and run `task completion:check`; do not edit percentages by hand.

{lme_python-0.2.2 → lme_python-0.2.3}/CHANGELOG.md

@@ -5,7 +5,59 @@ 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.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.3] - 2026-09-09
+
+### Fixed
+
+- Preserve offsets and observation weights throughout Satterthwaite and Kenward-Roger inference.
+- Use one Kenward-Roger covariance adjustment for marginal and joint tests, confidence
+  intervals, estimated marginal means, and multiple comparisons; retain precision
+  for very small p-values and reject nonfinite contrast inputs.
+- Respect precision weights in observation-level and cluster-robust standard errors.
+- Keep nested grouping labels distinct when components contain underscores or backslashes.
+- Honor requested grouped cross-validation fold counts, accept supported numeric
+  response types, and reject missing split labels and invalid responses.
+- Preserve predictors and responses named `intercept` in formula models.
+- Reject nonfinite confidence levels and mismatched or missing robust-inference data.
+- Leave uncertainty unavailable when an OLS fit has no residual degrees of freedom.
+
+
+- Preserve formula offsets in population/conditional predictions and OLS fitting.
+- Preserve precision weights in Gaussian simulation and bootstrap refits; weighted
+  residual resampling uses standardized residuals.
+- Refine two-parameter LMM grid minima before reporting optimizer convergence.
+- Honor nonlinear iteration budgets and expose failed numerical stages. Nonlinear
+  ML fitting now refines covariance and population parameters jointly and includes
+  the full Gaussian likelihood constant; reported likelihood/AIC/BIC may change.
+- Compute OLS coefficients and covariance from one QR decomposition with rank checks.
+
+### Added
+
+- Rust `FitControl`, `FitDiagnostics`, `ModelSpec`, and `ExecutionContext`; Python
+  `FitControl`, `fit.diagnostics`, and `prepared.fit(y=..., control=...)`.
+- Independent response workspaces with shared immutable LMM/GLMM designs, retained
+  GLMM sparse factorization structure, and group-block nonlinear normal equations.
+- Formula-based Python IPC column projection and interpreter release during native
+  fitting, prediction, bootstrap, and profile intervals.
+
+### Compatibility
+
+- Existing fitting functions retain their defaults. Rust consumers constructing
+  `LmeFit` literals must add `diagnostics: None`; numerical design fields exposed
+  through `LmmData`/`GlmmData` are now immutable shared data.
+- A nonconverged fit remains inspectable, but Wald intervals reject it. Set
+  `require_convergence` to reject unsuccessful LMM/GLMM fits immediately.
+- Resampling no longer changes process-wide BLAS/OpenMP environment variables.
+  `n_jobs=None` uses the current Rayon context; callers own backend thread settings.
+
+### Changed
+
+- Reworked documentation navigation, Rust/Python onboarding, example discovery,
+  troubleshooting, workflow scope, and the contributor/release runbooks. Corrected
+  prepared-fit, bootstrap, calibration-bound, and benchmark-evidence descriptions.
+- Reevaluated the repository completion score. The 2026-08-14 **100% (236/236)** headline overstated remaining stretch-item depth, omitted NLMM from the denominator, and could be satisfied by file existence alone. Locked criterion `scope` strings, reopened partial/stale/substituted items, added NLMM as row 14, and published **91% (235/258)**. See [REPO_COMPLETION_BY_AREA.md](REPO_COMPLETION_BY_AREA.md).
+- Reorganized the GitHub README around the existing banner: table of contents, capability and documentation tables, dual Rust/Python install and quick start, an `lme4` mapping, and structured limitation notes.
+- Rebuilt the GitHub Pages [benchmark dashboard](https://x4g4p3x.github.io/lme-rs/benchmarks/) around the fair MixedModels.jl harness and checked-in external timings, and restored Pages deployment.
 
 ## [0.2.2] - 2026-08-14
 

{lme_python-0.2.2 → lme_python-0.2.3}/CI_PERFORMANCE.md

@@ -1,4 +1,10 @@
-# CI performance
+# CI performance history
+
+[Documentation](docs/README.md) · [Current CI behavior](CONTRIBUTING.md#github-actions) · [Runner reference](scripts/ci/README.md)
+
+These are historical measurements from the linked runs, not current duration
+estimates. Use the workflow files and shared runner for the current validation
+contract. Retain both cold and warm runs when adding a new comparison.
 
 This document records hosted-CI timing evidence and the optimizations that are
 safe to depend on. Times are GitHub Actions job timestamps, not local estimates.