cholops 0.1.0__tar.gz

cholops-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- First release

cholops-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+## Setup and checks
+
+Use Python 3.12 or newer and the locked environment:
+
+```sh
+uv sync --locked --all-groups
+uv lock --check
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+JAX_PLATFORMS=cpu JAX_ENABLE_X64=0 uv run --locked python -m pytest
+JAX_PLATFORMS=cpu JAX_ENABLE_X64=1 uv run --locked python -m pytest
+```
+
+Run each precision in a separate process, selecting x64 before collection.
+Examples inherit that setting:
+
+```sh
+JAX_ENABLE_X64=1 uv run --locked python examples/basic_factor.py
+JAX_ENABLE_X64=1 uv run --locked python examples/streaming_gp.py
+JAX_ENABLE_X64=1 uv run --locked python examples/online_least_squares.py
+JAX_ENABLE_X64=1 uv run --locked python examples/tensor_operations.py
+```
+
+The default suite is the small CI layer. Keep each case within a few seconds,
+including compilation. Small numerical and gradient regressions belong here.
+The manual release suite adds larger matrices, long sequences, high-precision
+references and benchmark comparisons:
+
+```sh
+JAX_PLATFORMS=cpu JAX_ENABLE_X64=0 uv run --locked python -m pytest --full
+JAX_PLATFORMS=cpu JAX_ENABLE_X64=1 uv run --locked python -m pytest --full
+JAX_PLATFORMS=cuda JAX_ENABLE_X64=0 uv run --locked python -m pytest --full --require-gpu
+JAX_PLATFORMS=cuda JAX_ENABLE_X64=1 uv run --locked python -m pytest --full --require-gpu
+```
+
+CUDA requires the configured GPU environment (`uv sync --locked --all-groups
+--extra cuda13` on supported Linux hosts). CPU full runs explicitly skip the
+GPU-only storage check. `--require-gpu` prevents accidental CPU validation.
+Use `--full -m full` to run only additional release tests. See
+[testing guide](TESTING.md) and the [benchmark guide](benchmarks/README.md).
+
+## Design
+
+The public API is exported from `cholops` and grouped into `cholops.factors`
+and `cholops.tensors`. Leading-underscore modules are private.
+
+`factors/` contains the two factor classes and their shared matrix calculations.
+The classes own factor storage and, for `PermutedCholesky`, permutation state.
+`tensors/` contains factorization, append, rank-one updates, deletion and
+replacement. Each algorithm stays with its derivative rules. Private modules
+provide shared validation, indexing and JAX differentiation support.
+
+Dependencies run from factor objects to tensor operations. Tensor code does not
+import the factor classes. Reuse the tensor implementations rather than
+duplicating them in containers.
+
+State is immutable. No hidden precision changes, jitter, clipping, retry,
+occupancy tracking, memory pool or buffer donation. Test meaningful numerical
+behavior against independent dense or high-precision references. A small factor
+residual alone does not establish accurate gradients. Preserve signed
+zero-weight derivatives and visible numerical failures.
+
+Keep supported transformations and shape/order explicit in docstrings
+and the [API guides](docs/tensors.md). Any new numerical algorithm needs both
+correctness evidence and representative measurements before performance claims.

cholops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander von Rohr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cholops-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: cholops
+Version: 0.1.0
+Summary: Fast and differentiable Cholesky factor modifications in JAX.
+Keywords: jax,cholesky,linear-algebra,automatic-differentiation
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Dist: jax==0.11.2
+Requires-Dist: jax[cuda13]==0.11.2 ; sys_platform == 'linux' and extra == 'cuda13'
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/avrohr/cholops
+Project-URL: Documentation, https://github.com/avrohr/cholops/tree/main/docs
+Project-URL: Issues, https://github.com/avrohr/cholops/issues
+Provides-Extra: cuda13
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/avrohr/cholops/main/docs/assets/cholops-logo.svg" alt="cholops logo: an eye with three diagonal squares" width="240">
+</p>
+
+# cholops
+
+Cholesky modifications in JAX, with differentiable tensor operations and
+immutable factor objects. cholops provides fast appends, deletions and updates
+of a dense positive-definite matrix's factor, directly or through a factor
+object.
+
+## Install
+
+Install with `pip install cholops`. On Linux with a compatible CUDA 13 driver,
+use `pip install "cholops[cuda13]"`. The initial release targets **JAX 0.11.2** and
+Python 3.12 or newer.
+
+We recommend using float64; see [JAX's precision settings](https://docs.jax.dev/en/latest/101/default_dtypes.html).
+
+Set the `JAX_ENABLE_X64` shell environment variable before starting Python:
+
+```bash
+export JAX_ENABLE_X64=1
+```
+
+Alternatively, enable it in Python before creating arrays:
+
+```python
+import jax
+
+jax.config.update("jax_enable_x64", True)
+```
+
+## Example
+
+```python
+import jax
+import jax.numpy as jnp
+from cholops import Cholesky, PermutedCholesky
+
+A = jnp.array([[2.0, 0.3, 0.1], [0.3, 1.5, 0.2], [0.1, 0.2, 1.2]])
+b = jnp.array([1.0, -0.5, 0.2])
+
+# Create a Cholesky factor from a positive-definite matrix.
+factor = Cholesky.from_matrix(A)
+factor = factor.append(jnp.array([0.2, 0.1, 0.05]), 1.3)
+L = factor.factor
+x = factor.solve(
+    jnp.append(b, 0.4)
+)  # One RHS entry per variable, including the new one.
+
+# PermutedCholesky replaces by deletion and appending,
+# while managing logical ordering transparently.
+managed = PermutedCholesky.from_matrix(A)
+updated = managed.replace(1, jnp.array([0.2, 0.1]), 1.3)
+x_new = updated.solve(b)  # Inputs and outputs remain in logical order.
+
+
+# Zero-mean Gaussian log likelihood and its covariance/data gradients.
+@jax.jit
+def log_likelihood(A, b):
+    state = Cholesky.from_matrix(A)
+    return -0.5 * (state.logdet() + state.quadratic(b) + b.size * jnp.log(2 * jnp.pi))
+
+
+logp, (grad_A, grad_b) = jax.value_and_grad(log_likelihood, argnums=(0, 1))(A, b)
+```
+
+See the [factor guide](https://github.com/avrohr/cholops/blob/main/docs/factors.md) for more information. The executable
+examples explain each step and check their results against dense calculations:
+
+- [Basic factor operations](https://github.com/avrohr/cholops/blob/main/examples/basic_factor.py): add, replace and remove
+  observations, then solve a system and calculate a Gaussian log likelihood.
+- [Streaming Gaussian process](https://github.com/avrohr/cholops/blob/main/examples/streaming_gp.py): maintain a fixed-size
+  observation window with `PermutedCholesky` and differentiate through the
+  replacement sequence with respect to a kernel parameter.
+- [Online least squares](https://github.com/avrohr/cholops/blob/main/examples/online_least_squares.py): update a regression
+  fit with `rank1_positive` as measurements arrive.
+- [Direct tensor operations](https://github.com/avrohr/cholops/blob/main/examples/tensor_operations.py): compare replacement
+  orderings and arrange the right-hand side for each returned factor.
+
+## Tensor operations
+
+The factor objects use the following tensor operations, which can also be
+imported directly from `cholops`:
+
+| Operation | Description |
+| --- | --- |
+| `cholesky` | Factor a positive-definite matrix. |
+| `chol_append` | Append one covariance row and column. |
+| `chol_delete` | Delete one covariance row and column, preserving survivor order. |
+| `chol_replace` | Replace one covariance row and column at the same index. |
+| `chol_delete_append` | Delete one variable and append its replacement last. |
+| `chol_replace_last` | Replace a trailing block of variables. |
+| `chol_diag_update` | Add a signed value to one covariance diagonal entry. |
+| `chol_rank1` | Apply a rank-one update with a signed weight. |
+| `chol_rank1_positive` | Apply a positive rank-one update using the optimized path. |
+
+See the [tensor guide](https://github.com/avrohr/cholops/blob/main/docs/tensors.md) for shapes, ordering and preconditions.
+All operations support `jit`, `vmap` and first-order forward and reverse
+differentiation. Higher-order derivatives have not been validated for general use.
+
+## Performance
+
+We benchmark a single index-preserving `chol_replace` call against a naive JAX
+implementation and full matrix refactorization on an NVIDIA H100. All methods
+receive the existing factor and replacement covariances.
+
+![Single index-preserving replacement: absolute milliseconds on H100](https://raw.githubusercontent.com/avrohr/cholops/main/benchmarks/figures/replacement.svg)
+
+Replacing the first index of a **16,384 × 16,384** matrix gives the following
+speedups after compilation:
+
+| Precision | Forward: vs recompute / naive replacement | Value + gradient: vs recompute / naive replacement |
+| --- | ---: | ---: |
+| float32 | 15.7× / 21.3× | 22.7× / 30.3× |
+| float64 | 10.2× / 16.1× | 15.6× / 22.9× |
+
+[Recomputation](https://github.com/avrohr/cholops/blob/main/benchmarks/_recompute.py) forms `L @ L.T`, changes its row/column
+and calls native JAX Cholesky. The [naive replacement](https://github.com/avrohr/cholops/blob/main/benchmarks/_naive.py)
+baseline uses two signed rank-one scans with standard JAX autodiff.
+
+See [the complete benchmark results](https://github.com/avrohr/cholops/blob/main/benchmarks/README.md) for
+the measurement protocol, additional timings and memory usage.
+
+## Numerical limitations
+
+Near-singular covariances can produce inaccurate factors and gradients.
+See [numerical limits](https://github.com/avrohr/cholops/blob/main/docs/numerics.md).

cholops-0.1.0/README.md

@@ -0,0 +1,129 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/avrohr/cholops/main/docs/assets/cholops-logo.svg" alt="cholops logo: an eye with three diagonal squares" width="240">
+</p>
+
+# cholops
+
+Cholesky modifications in JAX, with differentiable tensor operations and
+immutable factor objects. cholops provides fast appends, deletions and updates
+of a dense positive-definite matrix's factor, directly or through a factor
+object.
+
+## Install
+
+Install with `pip install cholops`. On Linux with a compatible CUDA 13 driver,
+use `pip install "cholops[cuda13]"`. The initial release targets **JAX 0.11.2** and
+Python 3.12 or newer.
+
+We recommend using float64; see [JAX's precision settings](https://docs.jax.dev/en/latest/101/default_dtypes.html).
+
+Set the `JAX_ENABLE_X64` shell environment variable before starting Python:
+
+```bash
+export JAX_ENABLE_X64=1
+```
+
+Alternatively, enable it in Python before creating arrays:
+
+```python
+import jax
+
+jax.config.update("jax_enable_x64", True)
+```
+
+## Example
+
+```python
+import jax
+import jax.numpy as jnp
+from cholops import Cholesky, PermutedCholesky
+
+A = jnp.array([[2.0, 0.3, 0.1], [0.3, 1.5, 0.2], [0.1, 0.2, 1.2]])
+b = jnp.array([1.0, -0.5, 0.2])
+
+# Create a Cholesky factor from a positive-definite matrix.
+factor = Cholesky.from_matrix(A)
+factor = factor.append(jnp.array([0.2, 0.1, 0.05]), 1.3)
+L = factor.factor
+x = factor.solve(
+    jnp.append(b, 0.4)
+)  # One RHS entry per variable, including the new one.
+
+# PermutedCholesky replaces by deletion and appending,
+# while managing logical ordering transparently.
+managed = PermutedCholesky.from_matrix(A)
+updated = managed.replace(1, jnp.array([0.2, 0.1]), 1.3)
+x_new = updated.solve(b)  # Inputs and outputs remain in logical order.
+
+
+# Zero-mean Gaussian log likelihood and its covariance/data gradients.
+@jax.jit
+def log_likelihood(A, b):
+    state = Cholesky.from_matrix(A)
+    return -0.5 * (state.logdet() + state.quadratic(b) + b.size * jnp.log(2 * jnp.pi))
+
+
+logp, (grad_A, grad_b) = jax.value_and_grad(log_likelihood, argnums=(0, 1))(A, b)
+```
+
+See the [factor guide](https://github.com/avrohr/cholops/blob/main/docs/factors.md) for more information. The executable
+examples explain each step and check their results against dense calculations:
+
+- [Basic factor operations](https://github.com/avrohr/cholops/blob/main/examples/basic_factor.py): add, replace and remove
+  observations, then solve a system and calculate a Gaussian log likelihood.
+- [Streaming Gaussian process](https://github.com/avrohr/cholops/blob/main/examples/streaming_gp.py): maintain a fixed-size
+  observation window with `PermutedCholesky` and differentiate through the
+  replacement sequence with respect to a kernel parameter.
+- [Online least squares](https://github.com/avrohr/cholops/blob/main/examples/online_least_squares.py): update a regression
+  fit with `rank1_positive` as measurements arrive.
+- [Direct tensor operations](https://github.com/avrohr/cholops/blob/main/examples/tensor_operations.py): compare replacement
+  orderings and arrange the right-hand side for each returned factor.
+
+## Tensor operations
+
+The factor objects use the following tensor operations, which can also be
+imported directly from `cholops`:
+
+| Operation | Description |
+| --- | --- |
+| `cholesky` | Factor a positive-definite matrix. |
+| `chol_append` | Append one covariance row and column. |
+| `chol_delete` | Delete one covariance row and column, preserving survivor order. |
+| `chol_replace` | Replace one covariance row and column at the same index. |
+| `chol_delete_append` | Delete one variable and append its replacement last. |
+| `chol_replace_last` | Replace a trailing block of variables. |
+| `chol_diag_update` | Add a signed value to one covariance diagonal entry. |
+| `chol_rank1` | Apply a rank-one update with a signed weight. |
+| `chol_rank1_positive` | Apply a positive rank-one update using the optimized path. |
+
+See the [tensor guide](https://github.com/avrohr/cholops/blob/main/docs/tensors.md) for shapes, ordering and preconditions.
+All operations support `jit`, `vmap` and first-order forward and reverse
+differentiation. Higher-order derivatives have not been validated for general use.
+
+## Performance
+
+We benchmark a single index-preserving `chol_replace` call against a naive JAX
+implementation and full matrix refactorization on an NVIDIA H100. All methods
+receive the existing factor and replacement covariances.
+
+![Single index-preserving replacement: absolute milliseconds on H100](https://raw.githubusercontent.com/avrohr/cholops/main/benchmarks/figures/replacement.svg)
+
+Replacing the first index of a **16,384 × 16,384** matrix gives the following
+speedups after compilation:
+
+| Precision | Forward: vs recompute / naive replacement | Value + gradient: vs recompute / naive replacement |
+| --- | ---: | ---: |
+| float32 | 15.7× / 21.3× | 22.7× / 30.3× |
+| float64 | 10.2× / 16.1× | 15.6× / 22.9× |
+
+[Recomputation](https://github.com/avrohr/cholops/blob/main/benchmarks/_recompute.py) forms `L @ L.T`, changes its row/column
+and calls native JAX Cholesky. The [naive replacement](https://github.com/avrohr/cholops/blob/main/benchmarks/_naive.py)
+baseline uses two signed rank-one scans with standard JAX autodiff.
+
+See [the complete benchmark results](https://github.com/avrohr/cholops/blob/main/benchmarks/README.md) for
+the measurement protocol, additional timings and memory usage.
+
+## Numerical limitations
+
+Near-singular covariances can produce inaccurate factors and gradients.
+See [numerical limits](https://github.com/avrohr/cholops/blob/main/docs/numerics.md).

cholops-0.1.0/ROADMAP.md

@@ -0,0 +1,18 @@
+# Roadmap
+
+## Initial release
+
+- [ ] Finish the API and documentation review.
+- [ ] Complete CPU/GPU tests and package checks, then publish the first release.
+
+## Differentiation
+
+- [ ] Add tested support for Hessian-vector products.
+- [ ] Extend to other second-order derivatives while preserving first-order
+  accuracy and performance.
+
+## Possible extensions
+
+- [ ] Block append and deletion.
+- [ ] Rank-k updates.
+- [ ] Faster signed updates and downdates.

cholops-0.1.0/TESTING.md

@@ -0,0 +1,60 @@
+# Testing
+
+The tests check factors, solves and derivatives against dense recomputation and
+independent high-precision references. This guide describes the test groups and
+how to run them. See [contributing](CONTRIBUTING.md) for environment setup.
+
+## Running tests
+
+Run float32 and float64 in separate processes:
+
+```sh
+JAX_PLATFORMS=cpu JAX_ENABLE_X64=0 uv run --locked python -m pytest
+JAX_PLATFORMS=cpu JAX_ENABLE_X64=1 uv run --locked python -m pytest
+```
+
+The default suite runs in CI on Python 3.12 and 3.13. Additional tests are marked
+`full` and run before releases:
+
+| Option | What runs |
+| --- | --- |
+| No option | Small functional, numerical and derivative tests. |
+| `--full` | Default tests plus larger matrices, longer sequences and benchmark checks. |
+| `--full -m full` | Only the additional tests. |
+| `--full --require-gpu` | Full suite, failing immediately if no GPU is active. |
+
+For CUDA, install the `cuda13` extra and set `JAX_PLATFORMS=cuda`. Run both
+precisions as on CPU. GPU storage checks are skipped on CPU; inspect the test
+summary for failures and skips.
+
+## What is checked
+
+- **Operations and factor objects:** reconstruction of the expected covariance,
+  solves, log determinants, quadratic forms and logical ordering after updates.
+- **JAX transformations:** JIT, batching, runtime indices, first-order JVPs and
+  VJPs, and combinations such as differentiation through replacement scans.
+- **Derivative accuracy:** comparison with dense derivatives, JVP/VJP duality,
+  and independent Decimal calculations in [tests/reference](tests/reference).
+- **Sequences and larger matrices:** accumulated factor and gradient errors over
+  repeated replacements, plus scan lengths absent from the small CI cases.
+- **GPU storage:** compiler-reported temporary memory for deletion gradients at
+  several matrix sizes.
+- **Benchmark comparisons:** matching inputs, outputs and derivatives across
+  implementations, including the naive replacement baseline.
+
+Tolerances are chosen per test and precision. Higher-order derivatives are not
+part of the tested API. See [numerical limits](docs/numerics.md) for limitations
+that passing these tests does not remove.
+
+## Writing tests
+
+Each test should establish a desired behavior and have a name that explains
+what a failure means. Compare numerical results with an independent calculation.
+For derivatives, choose an objective that depends on the inputs being tested.
+
+Keep setup and assertions direct. Split unrelated checks into separate tests,
+and use parameter names that identify the failing case. Check logical results
+and documented behavior without requiring a particular internal arrangement.
+Keep numerical regression cases and their precision-specific tolerances when
+consolidating tests.
+

cholops-0.1.0/benchmarks/README.md

@@ -0,0 +1,224 @@
+# Benchmarks
+
+This page presents H100 results for all six operations in the main benchmark:
+append, delete, positive rank-one update, replacement, delete-and-append, and
+trailing-block replacement. Each is measured in float32 and float64, in forward,
+reverse and JVP modes, at matrix sizes 512–16,384.
+
+All six operations were faster than dense JAX recomputation on the measured
+fixtures. The advantage generally grows with matrix size. The plots show the
+full range, and the tables give absolute times at **16,384 × 16,384**.
+
+## What the timings include
+
+Every operation starts from an existing Cholesky factor. The JAX baseline
+reconstructs `L @ L.T`, applies the change and factors the resulting covariance.
+Replacement also includes a naive baseline using two signed rank-one JAX scans
+with standard autodiff. See [_recompute.py](_recompute.py), [_naive.py](_naive.py)
+and the operation references in [workloads.py](workloads.py).
+
+**Forward** returns the updated factor. **Value + gradient** evaluates a fixed
+weighted sum of that factor and differentiates it with respect to every
+continuous input. Both the primal calculation and reverse pass are timed.
+**Directional derivative (JVP)** evaluates the factor and its derivative along
+one input direction.
+Indexed operations modify the first variable. Trailing-block replacement
+changes four variables.
+
+These are warm execution times. Each point is the median of three process
+medians, and shading spans their minimum and maximum. Compilation and cold
+first use are recorded separately in [summary.csv](summary.csv).
+[Speedups](speedups.csv) are calculated within each process before taking their
+median.
+
+## Float32 results
+
+![All six operations in float32, with forward, value-plus-gradient and JVP timings](figures/operations-float32.png)
+
+At **16,384**, times in milliseconds:
+
+| Operation | Forward cholops / JAX (ms) | Value + gradient cholops / JAX (ms) |
+| --- | ---: | ---: |
+| `chol_append` | 5.17 / 242.58 | 8.23 / 1021.03 |
+| `chol_delete` | 7.57 / 241.39 | 20.40 / 1032.96 |
+| `chol_rank1_positive` | 4.65 / 213.10 | 17.55 / 1000.16 |
+| `chol_replace` | 13.31 / 209.73 | 43.30 / 984.93 |
+| `chol_delete_append` | 8.39 / 215.69 | 23.95 / 1012.61 |
+| `chol_replace_last` | 5.87 / 214.33 | 13.62 / 999.27 |
+
+## Float64 results
+
+![All six operations in float64, with forward, value-plus-gradient and JVP timings](figures/operations-float64.png)
+
+At **16,384**, times in milliseconds:
+
+| Operation | Forward cholops / JAX (ms) | Value + gradient cholops / JAX (ms) |
+| --- | ---: | ---: |
+| `chol_append` | 8.39 / 218.90 | 9.75 / 1106.23 |
+| `chol_delete` | 11.51 / 222.41 | 28.78 / 1096.31 |
+| `chol_rank1_positive` | 7.80 / 213.09 | 26.75 / 977.39 |
+| `chol_replace` | 19.84 / 202.27 | 61.60 / 961.97 |
+| `chol_delete_append` | 13.02 / 217.27 | 32.31 / 998.61 |
+| `chol_replace_last` | 10.44 / 211.73 | 20.94 / 979.77 |
+
+The two tables compare cholops with dense recomputation. For single-variable
+replacement, the plots also show the naive baseline. At 16,384, its forward and
+value-plus-gradient times are 283.58 / 1295.88 ms in float32 and
+319.26 / 1413.17 ms in float64. The compact [summary](summary.csv) contains all
+sizes, modes and implementations.
+
+A caller that already stores its covariance can avoid reconstructing `L @ L.T`.
+These factor-input timings therefore describe individual operations, rather
+than a complete GP calculation. The campaign also provides sequence benchmarks
+whose recomputation baseline retains the covariance between steps.
+
+## Memory
+
+Faster execution does not always mean lower memory use. The following compiler
+working-set estimates are for **float64 at 16,384**:
+
+| Operation | Forward cholops / JAX (GiB) | Value + gradient cholops / JAX (GiB) |
+| --- | ---: | ---: |
+| `chol_append` | 6.00 / 8.00 | 4.00 / 12.00 |
+| `chol_delete` | 6.13 / 8.00 | 12.02 / 12.03 |
+| `chol_rank1_positive` | 6.13 / 8.00 | 12.14 / 10.03 |
+| `chol_replace` | 10.13 / 8.00 | 18.25 / 14.50 |
+| `chol_delete_append` | 6.13 / 6.03 | 12.02 / 16.50 |
+| `chol_replace_last` | 6.00 / 8.00 | 6.00 / 12.00 |
+
+The working set is arguments + outputs + temporaries - aliases. These are
+compiler estimates, not measured peak GPU allocations. Values are the largest
+estimate across process repeats. [summary.csv](summary.csv) includes both
+precisions and separates temporary storage from the whole working set. The
+[replacement memory plot](figures/memory.svg) also includes the naive baseline.
+
+## Numerical accuracy
+
+Numerical differences are recorded alongside timings without filtering samples
+or changing outputs. The [numerical tests](../TESTING.md) check factors and
+gradients on specified fixtures.
+
+One float32 delete-and-append case at 8,192 illustrates why disagreement with
+recomputation needs interpretation. Its weighted scalar loss differed by about
+0.00071 relative. Promoting the same inputs and loss weights to float64 showed
+that cancellation in the float32 baseline caused most of the discrepancy:
+
+| Relative error against the same-input float64 reference | cholops float32 | JAX float32 |
+| --- | ---: | ---: |
+| Factor | 1.31e-7 | 1.23e-5 |
+| Weighted scalar value | 1.10e-5 | 6.99e-4 |
+| Largest gradient-leaf error | 3.16e-7 | 1.71e-5 |
+
+This is a diagnostic for that case. Accuracy requirements still depend on the
+application and conditioning of its matrices.
+
+## Reproduce the results
+
+The recorded campaign used an NVIDIA H100 with 95,830 MiB reported memory,
+32 CPU threads per process, JAX/JAXlib 0.11.2, NumPy 2.5.4 and Python 3.13.17.
+Float32 and float64 ran in separate processes with matrix multiplication
+precision set to `highest`. All 720 planned cases completed without skips.
+
+### Run the campaign
+
+From a checkout on a configured Linux GPU host:
+
+```sh
+uv sync --locked --all-groups --extra cuda13
+
+# Write a plan to inspect before running measurements.
+uv run --locked python -m benchmarks.suite --backend gpu \
+  --memory-budget-gib 64 --output results/benchmarks/main-plan
+
+# Create and execute a new plan on this host.
+uv run --locked python -m benchmarks.suite --backend gpu \
+  --memory-budget-gib 64 --output results/benchmarks/main --execute
+
+# Generate figures and summary tables from that campaign.
+uv run --locked python -m benchmarks.plot results/benchmarks/main \
+  --output results/benchmarks/main/plots
+```
+
+The default plan contains 720 cases: 648 for the six operation curves and
+72 for the additional workloads below. It uses six sizes, two precisions,
+forward, reverse and JVP modes, and three process repeats. Output directories
+for plans and cases must be new. Use `--backend cpu` for a CPU campaign and omit
+the CUDA extra when installing its environment. Select `--sizes` and `--dtypes` for smaller runs.
+
+Each case runs in a fresh process. After compilation and the first synchronized
+call, every implementation receives two warmups and fifteen timed calls.
+Implementation order is shuffled within each round and saved. Timing waits for
+the entire output. Inputs are already on the device, and buffers are not donated.
+The seed is fixed, using a dense Gram covariance from at most 16 features plus
+an identity term. Process repeats measure timing variability on the same matrix.
+
+Choose a memory budget below available device RAM. The runner checks memory
+before preparing fixtures and before executing compiled code. Cases that exceed
+the budget appear as explicit skips in `coverage.csv`. Execution errors stop the
+campaign and leave a case log to inspect. Optional sizes 32,768 and 65,536 need
+substantially more memory and are outside the default plan.
+
+### Where results are stored
+
+Raw campaigns belong in the gitignored **`results/benchmarks/`** directory at
+the repository root. Each campaign contains its plan, case directories, logs,
+timing samples, numerical diagnostics and source metadata. The existing H100
+campaign is retained locally as `results/benchmarks/release-reduced-9e03d8b/`.
+
+The repository keeps the report in this README, selected figures in
+[`figures/`](figures/), and the compact `summary.csv` and `speedups.csv` tables.
+Raw measurements are not included in a fresh checkout. To regenerate plots,
+run a campaign or use a retained local campaign as the input to `benchmarks.plot`.
+For example, the saved H100 campaign can be rendered with:
+
+```sh
+uv run --locked python -m benchmarks.plot results/benchmarks/release-reduced-9e03d8b \
+  --output results/benchmarks/release-reduced-9e03d8b/plots
+```
+
+New runs measure the current checkout and record its source hashes and
+environment. The plotter checks that cases match the plan and use consistent
+hardware and JAX versions. Combining source versions requires a source audit
+for each case. Use `--allow-partial` to preview an incomplete campaign.
+
+### Check the setup with one small case
+
+```sh
+uv run --locked python -m benchmarks.run --backend cpu --dtype float64 \
+  --workload operations --operation replace --mode full_vjp \
+  --implementations tensor naive recompute --n 8 --position first \
+  --samples 3 --memory-budget-gib 4 --output results/benchmarks/smoke
+```
+
+This checks execution and output files. Use the declared campaign sizes for
+performance comparisons. Add `--dump-hlo` when profiling an individual case.
+
+## Additional workloads
+
+The campaign also measures:
+
+- Signed rank-one and diagonal updates at size 4,096, using weight `-0.2`.
+  These compare tensor calls with dense recomputation.
+- 16-step replacement sequences at sizes 2,048 and 8,192, comparing `Cholesky`,
+  `PermutedCholesky` and dense recomputation. Each includes initialization and
+  a Gaussian loss at every step. Recomputation retains the covariance between
+  steps. All methods use four-step checkpoint blocks.
+
+Both workloads use float32 and float64, forward, reverse and JVP modes, and
+three process repeats, giving 36 cases each. Indexed updates start at the first
+position. Sequences advance the index after each step. Reverse mode differentiates
+the mean sequence loss with respect to initial features, incoming features and
+scale. Their measurements are included in [summary.csv](summary.csv).
+
+At size 4,096, both signed updates were slower than dense recomputation. In
+float64, their forward times were about 102 ms versus 4.84 ms for recomputation.
+Value + gradient took 481–485 ms versus 18.64–18.83 ms.
+
+## Code layout
+
+`suite.py` defines and launches cases. `workloads.py` builds the computations and
+reference results that `run.py` compiles and times. `plot.py` reads the saved
+campaign and produces summaries and figures. `_support.py` supplies fixtures,
+diagnostics and checkpointing. `_environment.py` records source and environment
+information. The full pytest suite checks the workload calculations against
+their references.