Merge pull request #10 from 0xC000005/v0.14-binary-serialization

v0.14: Portable .pcb binary serialization format

Author: 0xC000005

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to PyChebyshev 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).
 
+## [0.14.0] - 2026-04-24
+
+### Added
+- Portable `.pcb` binary serialization format for `ChebyshevApproximation`
+  and `ChebyshevSpline`. Closes the MoCaX cross-language serialization gap
+  in PyChebyshev's specific way.
+  - New `format=` kwarg on `save()` (default `'pickle'`, opt in to `'binary'`).
+  - `load()` auto-detects via 4-byte magic header `b"PCB\x00"`. No
+    behaviour change for existing pickle files.
+  - C reference reader at `examples/binary_reader/` (not in CI).
+  - Format spec at `docs/user-guide/binary-format.md`.
+  - Stdlib `struct` + NumPy only — no new runtime dependencies.
+
+### Restrictions
+- `format='binary'` requires flat `n_nodes` for `ChebyshevSpline`. Splines
+  built with nested per-piece `n_nodes` raise `NotImplementedError` and
+  fall back to pickle.
+- `ChebyshevSlider` and `ChebyshevTT` remain pickle-only in v0.14.
+
 ## [0.13.1] - 2026-04-24
 
 ### Changed

CLAUDE.md

@@ -12,7 +12,7 @@ PyChebyshev is a pip-installable Python library for multi-dimensional Chebyshev
 # Setup
 uv sync
 
-# Run tests (~586 tests, ~110s due to 5D Black-Scholes builds)
+# Run tests (~662 tests, ~110s due to 5D Black-Scholes builds)
 uv run pytest tests/ -v
 
 # Run a single test
@@ -46,6 +46,7 @@ The installable package. Public classes: `ChebyshevApproximation`, `ChebyshevSpl
 - **`_algebra.py`** — Shared helpers for Chebyshev arithmetic operators (compatibility validation, operator dispatch).
 - **`_extrude_slice.py`** — Shared helpers for extrusion and slicing (parameter validation, tensor manipulation, barycentric contraction).
 - **`_calculus.py`** — Shared helpers for Chebyshev calculus (Fejér-1 quadrature weights via DCT-III, sub-interval quadrature weights via Chebyshev antiderivatives, companion-matrix rootfinding, 1-D optimization). References: Waldvogel (2006), Trefethen (2013).
+- **`_binary.py`** — Private. `.pcb` portable binary serialization (v0.14). Reading/writing for `ChebyshevApproximation` and `ChebyshevSpline`. Stdlib `struct` + NumPy only.
 - **`_jit.py`** — Deprecated Numba JIT kernel with pure NumPy fallback. Used only by deprecated `fast_eval()`.
 - **`_version.py`** — Single source of truth for version string.
 
@@ -79,6 +80,7 @@ Not part of the library. Compare Chebyshev barycentric against alternative metho
 - `test_from_values.py` — 65 tests: nodes() and from_values() for ChebyshevApproximation and ChebyshevSpline; bit-identical equivalence with build(); derivatives, calculus, algebra, extrude/slice, save/load; edge cases (NaN/Inf, shape mismatch, 1-node dim, build guard, 4D, boundary eval, negative/wide/tight domains, duplicate knots, algebra chains, domain validation).
 - `test_special_points.py` — 37 tests: `ChebyshevApproximation.__new__` dispatch to `ChebyshevSpline` when `special_points` declares any kink (option A, precedent `pathlib.Path`); validation of special_points shape + nested `n_nodes`; 1D/2D correctness (abs kink recovery to machine precision; plateau control); cross-feature (save/load, algebra, integrate, extrude/slice, from_values); edge cases.
 - `test_error_threshold.py` — 37 tests: v0.11 auto-N doubling loop, max_n cap, get_optimal_n1, semi-auto mixed-N paths, verbose prints, spline per-piece doubling.
+- `test_binary_format.py` — 76 tests: low-level helpers, header parsing, format detection, ChebyshevApproximation round-trip (incl. n=1 dim), ChebyshevSpline round-trip, save/load integration with `format=` kwarg + autodetect, golden vectors, corruption rejection, cross-feature (from_values, algebra, extrude, slice, 5D BS, min n_nodes).
 
 ### CI/CD (`.github/workflows/`)
 

README.md

@@ -77,6 +77,8 @@ The convergence plots demonstrate exponential error decay as node count increase
 - **Vectorized evaluation** using BLAS matrix-vector products (~0.065ms/query)
 - **Error-driven construction** — pass `error_threshold=ε` and PyChebyshev auto-picks node counts per dimension
 - **Special points in the core API** — declare kinks directly on `ChebyshevApproximation` via `special_points=[[...]]`; auto-dispatches to a piecewise Chebyshev spline.
+- **Portable `.pcb` binary format** for cross-language model sharing (C, Rust,
+  Julia consumers can read PyChebyshev interpolants without Python).
 - **Pure Python** — NumPy + SciPy only, no compiled extensions needed
 
 ## Acknowledgments

docs/roadmap.md

@@ -78,7 +78,7 @@ Adds guidance on when to choose **Cross vs SVD vs ALS** as the build method.
 **Closes MoCaX gaps:** rank-adaptive ALS, completion sweep, TT inner
 product, TT orthogonalization.
 
-## v0.14 — Portable Binary Serialization :material-clock-outline:
+## v0.14 — Portable Binary Serialization :material-check:
 
 A language-agnostic `.pcb` binary format alongside the existing pickle-based
 save/load. Consumers in C, Rust, or Julia can read PyChebyshev interpolants

docs/user-guide/binary-format.md

@@ -0,0 +1,210 @@
+# Portable Binary Format (`.pcb`)
+
+PyChebyshev v0.14 introduced a portable binary serialization format alongside
+the default pickle format. The goal: let consumers in **C, Rust, Julia, or
+any other language** read PyChebyshev interpolants without a Python runtime.
+
+The format is intentionally minimal — a fixed header, length-prefixed
+sections, raw little-endian `f64` blobs. A C reference reader at
+`examples/binary_reader/` weighs ~240 lines.
+
+## When to use which format
+
+| Format | Use when |
+|---|---|
+| **Pickle** (default) | Python-only round-trips; need full fidelity (build metadata, error caches) |
+| **Binary** (`.pcb`) | Cross-language consumers; sharing models with C/Rust/Julia code; long-term archival without Python pickle compatibility risk |
+
+Pickle stays the default because every existing user keeps working with no
+change. Opt into binary explicitly:
+
+```python
+cheb.save("model.pcb", format='binary')      # portable
+cheb.save("model.pkl")                       # pickle (default)
+
+ChebyshevApproximation.load("model.pcb")     # auto-detects
+```
+
+`load()` sniffs the first 4 bytes — `b"PCB\x00"` routes to the binary
+reader, anything else to the pickle reader.
+
+## Coverage in v0.14
+
+- **`ChebyshevApproximation`** — full support.
+- **`ChebyshevSpline`** — full support, with one restriction: the spline
+  must use **flat** `n_nodes` (a single `int` per dim, shared across pieces).
+  Splines built with nested per-piece `n_nodes` (the `[[n00, n01], …]` form
+  introduced for special points) cannot be saved as `.pcb` because the
+  underlying `ChebyshevSpline.from_values()` factory does not yet support
+  that shape; use pickle for those.
+- **`ChebyshevSlider`**, **`ChebyshevTT`** — pickle only in v0.14.
+
+## Format specification (v1)
+
+All multi-byte fields are **little-endian**. Numeric arrays are raw `f64`
+blobs in C-order.
+
+### Header (12 bytes)
+
+```
+offset  size  field
+0       4     magic           = b"PCB\x00"
+4       1     major_version   = 1
+5       1     minor_version   = 0
+6       2     class_tag       1 = ChebyshevApproximation, 2 = ChebyshevSpline
+8       4     reserved        = 0x00000000
+```
+
+### `ChebyshevApproximation` body (`class_tag = 1`)
+
+```
+uint32     num_dimensions                            d
+f64[d]     domain_lo                                 [a_0, ..., a_{d-1}]
+f64[d]     domain_hi                                 [b_0, ..., b_{d-1}]
+uint32[d]  n_nodes                                   [n_0, ..., n_{d-1}]
+f64[prod(n_nodes)]  tensor_values                    C-order
+```
+
+`barycentric_weights` and `diff_matrices` are **not** stored; they are
+recomputed from `(domain, n_nodes)` on load (they are pure functions of
+those primitives).
+
+### `ChebyshevSpline` body (`class_tag = 2`)
+
+```
+uint32     num_dimensions                            d
+f64[d]     domain_lo
+f64[d]     domain_hi
+uint32[d]  n_nodes                                   shared across pieces
+uint32[d]  num_knots_per_dim                         [k_0, ..., k_{d-1}]
+f64[k_0 + ... + k_{d-1}]   knots_concatenated        flat, dim-by-dim
+uint32     num_pieces                                P = prod(k_i + 1)
+
+# P piece blocks, in C-order over the piece grid:
+for p in 0..P-1:
+    f64[prod(n_nodes)]     tensor_values_p           C-order
+```
+
+### Versioning policy
+
+- New required fields → bump **major**. v1 readers reject `major != 1`.
+- New optional trailing fields → bump **minor**. v1 readers ignore unknown
+  trailing data.
+- Reserved header bytes MUST be zero in v1.
+
+## Worked example: `f(x,y) = x + y`
+
+Python side:
+
+```python
+from pychebyshev import ChebyshevApproximation
+
+cheb = ChebyshevApproximation(
+    function=lambda pt, _: pt[0] + pt[1],
+    num_dimensions=2,
+    domain=[(-1.0, 1.0), (-1.0, 1.0)],
+    n_nodes=[3, 3],
+)
+cheb.build()
+cheb.save("xy.pcb", format='binary')
+```
+
+The resulting file is exactly **128 bytes**:
+
+```
+12  header
+ 4  num_dimensions = 2
+16  domain_lo  = [-1.0, -1.0]
+16  domain_hi  = [ 1.0,  1.0]
+ 8  n_nodes    = [3, 3]
+72  tensor_values (3 × 3 f64)
+```
+
+C reader:
+
+```bash
+cd examples/binary_reader
+make
+./reader ../../xy.pcb 0.3 0.4
+# 0.69999999999999996
+```
+
+The same IEEE-754 double Python returns (`repr` truncates trailing digits):
+
+```python
+cheb.eval([0.3, 0.4], [0, 0])  # 0.7
+```
+
+The two strings render the same `float64` value `0x3fe6666666666666`. The
+C reader prints with `%.17g`, Python with `repr` — they agree bit-for-bit.
+
+### Spline worked example: `|x|` on `[-1, 1]`
+
+```python
+from pychebyshev import ChebyshevSpline
+
+s = ChebyshevSpline(
+    function=lambda pt, _: abs(pt[0]),
+    num_dimensions=1,
+    domain=[(-1.0, 1.0)],
+    n_nodes=[3],
+    knots=[[0.0]],
+)
+s.build()
+s.save("abs.pcb", format='binary')
+```
+
+The resulting file is exactly **100 bytes**:
+
+```
+12  header
+ 4  num_dimensions = 1
+ 8  domain_lo  = [-1.0]
+ 8  domain_hi  = [ 1.0]
+ 4  n_nodes    = [3]
+ 4  num_knots  = [1]
+ 8  knots      = [0.0]
+ 4  num_pieces = 2
+48  piece tensor values (2 pieces × 3 × f64)
+```
+
+Two pieces because one knot at `0.0` splits the domain `[-1, 1]` into `[-1, 0]`
+and `[0, 1]`. Each piece carries its own 3-node Chebyshev grid.
+
+## Writing a reader in another language
+
+The format is small enough to implement in an afternoon:
+
+1. Read 4 bytes; verify equal to `b"PCB\x00"`.
+2. Read major/minor version; reject unknown major.
+3. Read class tag; dispatch.
+4. For class 1: read `uint32 d`, then `d × f64` for `lo`, `d × f64` for `hi`,
+   `d × uint32` for `n_nodes`, then `prod(n_nodes) × f64` for tensor values.
+5. To evaluate, generate Chebyshev first-kind nodes per dim, compute
+   barycentric weights from node positions, evaluate by dim-by-dim collapse.
+
+`examples/binary_reader/reader.c` is the reference. It is intentionally
+minimal: ~240 lines, stdlib + `libm` only.
+
+## What the format does not store
+
+These fields are dropped on `format='binary'`:
+
+| Field | Replacement |
+|---|---|
+| `function` | always dropped (also dropped by pickle) |
+| `barycentric_weights`, `diff_matrices` | recomputed on load |
+| `_cached_error_estimate` | recomputed lazily |
+| `build_time`, `n_evaluations`, `method` | not preserved (use pickle for full fidelity) |
+| `max_derivative_order` | resets to default `2` on load — re-set manually after `load()` if you need higher orders |
+
+If you need any of those preserved, use pickle.
+
+## Security
+
+The binary reader does no `pickle.loads`-style code execution. It can be
+used to load files from untrusted sources — it will reject malformed
+files with a `ValueError`.
+
+Pickle remains the default and **does** execute arbitrary code from
+loaded files. Treat pickle files like executable code.

examples/binary_reader/.gitignore

@@ -0,0 +1,3 @@
+reader
+*.o
+*.pcb

examples/binary_reader/Makefile

@@ -0,0 +1,10 @@
+CC ?= cc
+CFLAGS ?= -O2 -Wall -Wextra -std=c99
+
+reader: reader.c
+	$(CC) $(CFLAGS) -o reader reader.c -lm
+
+clean:
+	rm -f reader
+
+.PHONY: clean

examples/binary_reader/README.md

@@ -0,0 +1,60 @@
+# PyChebyshev `.pcb` Binary Reader (C Reference)
+
+A ~240-line C program that reads a v1 `.pcb` file (`ChebyshevApproximation`
+class) and evaluates it at a query point. It is the reference proof that
+the format is implementable from scratch in another language. It assumes
+a little-endian host (matches the on-disk format); a port to big-endian
+hardware would need explicit byte-swapping.
+
+`ChebyshevSpline` is **not** supported here — this is a minimal proof,
+not a full port.
+
+## Build
+
+```bash
+cd examples/binary_reader
+make
+```
+
+Requires a C99 compiler (gcc, clang) and `libm`. No third-party deps.
+
+## Usage
+
+First, save a `.pcb` file from Python:
+
+```python
+from pychebyshev import ChebyshevApproximation
+cheb = ChebyshevApproximation(
+    function=lambda pt, _: pt[0] + pt[1],
+    num_dimensions=2,
+    domain=[(-1.0, 1.0), (-1.0, 1.0)],
+    n_nodes=[3, 3],
+)
+cheb.build()
+cheb.save("test.pcb", format='binary')
+print("Python eval:", cheb.eval([0.3, 0.4], [0, 0]))
+```
+
+Then read it from C:
+
+```bash
+./reader test.pcb 0.3 0.4
+```
+
+The two values should agree to at least 1e-12.
+
+## What it covers
+
+- Header parse + validation (magic, major, class tag, reserved bytes)
+- ChebyshevApproximation body (num_dim, domain, n_nodes, tensor)
+- Chebyshev first-kind node reconstruction
+- Barycentric weight computation
+- N-D evaluation by dimension-by-dimension collapse
+
+## What it does not cover
+
+- ChebyshevSpline (pieces, knots) — requires an extra outer routing step
+- Derivatives — requires the differentiation matrix
+- Future format versions
+
+Contributions adding spline support, or porting to Rust/Julia, are welcome.