Merge pull request #12 from 0xC000005/v0.16-polish

v0.16.0: Polish Bundle (final MoCaX 4.3.1 cosmetic mirror)

Author: 0xC000005

CHANGELOG.md

@@ -5,6 +5,20 @@ 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.16.0] - 2026-04-25
+
+### Added — Polish Bundle (final MoCaX 4.3.1 cosmetic mirror)
+
+- `clone()` deep copy method on all four classes (`ChebyshevApproximation`, `ChebyshevSpline`, `ChebyshevSlider`, `ChebyshevTT`). Like save/load, the source `function` callable is not duplicated; clone has `function = None`.
+- Instance getters: `get_max_derivative_order()` (all four), `get_error_threshold()` (Approximation/Spline), `get_special_points()` (Approximation/Spline; Approximation now stores `special_points` with `__setstate__` backfill), `get_evaluation_points()` and `get_num_evaluation_points()` (all four; eval grid size semantics, matching `len(get_evaluation_points()) == get_num_evaluation_points()`).
+- `peek_format_version(filename)` static on `ChebyshevApproximation` — read `.pcb` major version without deserializing.
+- `is_dimensionality_allowed(num_dim)` static on all four classes (returns True for any positive int; hook for future per-class capability caps).
+- `defer_build=True` keyword-only ctor flag + `set_original_function_values(values)` instance mutator on `ChebyshevApproximation` and `ChebyshevSpline` — in-place deferred construction. Bit-identical to the `from_values()` factory. Spline path threads `additional_data` to pieces; atomic per-piece validation.
+- Optional typed helpers `Domain`, `Ns`, `SpecialPoints` (frozen dataclasses) exported from the package; constructors of all four classes accept raw lists or these dataclasses.
+- `ChebyshevTT` ctor now accepts `max_derivative_order: int = 2` keyword-only kwarg; `__setstate__` backfill for backward-compat pickles.
+
+All additions are strictly additive — no breaking changes.
+
 ## [0.15.0] - 2026-04-25
 
 ### Added

CLAUDE.md

@@ -12,7 +12,7 @@ PyChebyshev is a pip-installable Python library for multi-dimensional Chebyshev
 # Setup
 uv sync
 
-# Run tests (~733 tests, ~110s due to 5D Black-Scholes builds)
+# Run tests (~838 tests, ~110s due to 5D Black-Scholes builds)
 uv run pytest tests/ -v
 
 # Run a single test
@@ -53,6 +53,12 @@ The installable package. Public classes: `ChebyshevApproximation`, `ChebyshevSpl
   `is_construction_finished`/`get_constructor_type`/`get_used_ns`, and the
   `get_derivative_id` integer registry + `eval(..., derivative_id=...)` (the
   last one excluding `ChebyshevTT`).
+- v0.16 adds `clone()`, instance getters (`get_max_derivative_order`,
+  `get_error_threshold`, `get_special_points`, `get_evaluation_points`,
+  `get_num_evaluation_points`), `peek_format_version()` static,
+  `is_dimensionality_allowed()` static, `defer_build=True` +
+  `set_original_function_values()`, and optional `Domain`/`Ns`/`SpecialPoints`
+  typed helpers (constructors accept both forms).
 
 ### Benchmark Scripts (project root)
 
@@ -70,6 +76,7 @@ Not part of the library. Compare Chebyshev barycentric against alternative metho
 - `compare_extrude_slice.py` — PyChebyshev extrusion/slicing vs MoCaX comparison (requires `mocaxextend_lib/`)
 - `compare_from_values.py` — PyChebyshev nodes()/from_values() vs MoCaX Extend comparison (requires `mocaxextend_lib/`)
 - `compare_special_points.py` — PyChebyshev special_points vs MoCaX MocaxSpecialPoints + MocaxNs comparison (requires `mocax_lib/`)
+- `compare_v016_polish.py` — PyChebyshev v0.16 polish surface vs MoCaX 4.3.1 cosmetic API (requires `mocaxpy`; gracefully skips MoCaX side if not installed)
 
 ### Tests (`tests/`)
 
@@ -89,6 +96,11 @@ Not part of the library. Compare Chebyshev barycentric against alternative metho
   binary rejection, derivative_id registry on Approximation/Spline/Slider,
   introspection trio (`is_construction_finished`, `get_constructor_type`,
   `get_used_ns`).
+- `test_v016_polish.py` — ~74 tests: clone() on all four classes, instance getters
+  (`get_max_derivative_order`, `get_error_threshold`, `get_special_points`,
+  `get_evaluation_points`, `get_num_evaluation_points`), `peek_format_version`,
+  `is_dimensionality_allowed`, `defer_build` + `set_original_function_values`,
+  `Domain`/`Ns`/`SpecialPoints` typed helpers.
 
 ### CI/CD (`.github/workflows/`)
 

compare_v016_polish.py

@@ -0,0 +1,62 @@
+"""Side-by-side comparison: PyChebyshev v0.16 polish surface vs MoCaX 4.3.1.
+
+Most v0.16 surface methods have direct MoCaX equivalents. This script
+demonstrates the calls side-by-side. Run from the repo root:
+
+    uv run python compare_v016_polish.py
+
+Requires mocax_lib/ at the repo root (gitignored).
+"""
+
+from __future__ import annotations
+
+import math
+
+from pychebyshev import (
+    ChebyshevApproximation,
+    Domain,
+    Ns,
+)
+
+
+def f(x, _):
+    return math.sin(x[0]) + math.cos(x[1])
+
+
+def main():
+    # PyChebyshev: typed-helper construction
+    py_cheb = ChebyshevApproximation(
+        f, 2, Domain([(-1.0, 1.0), (-1.0, 1.0)]), Ns([10, 10]),
+    )
+    py_cheb.build(verbose=False)
+
+    print("PyChebyshev v0.16 polish surface:")
+    print(f"  clone()                         → {type(py_cheb.clone()).__name__}")
+    print(f"  get_max_derivative_order()      → {py_cheb.get_max_derivative_order()}")
+    print(f"  get_error_threshold()           → {py_cheb.get_error_threshold()}")
+    print(f"  get_special_points()            → {py_cheb.get_special_points()}")
+    print(f"  get_num_evaluation_points()     → {py_cheb.get_num_evaluation_points()}")
+    print(f"  get_evaluation_points().shape   → {py_cheb.get_evaluation_points().shape}")
+    print(f"  is_dimensionality_allowed(2)    → {ChebyshevApproximation.is_dimensionality_allowed(2)}")
+
+    try:
+        from mocaxpy import Mocax, MocaxDomain, MocaxNs
+    except ImportError:
+        print("\n(mocaxpy not installed; skipping MoCaX side)")
+        return
+
+    mc = Mocax(
+        f,
+        2,
+        MocaxDomain([(-1.0, 1.0), (-1.0, 1.0)]),
+        MocaxNs([10, 10]),
+        None,  # error_threshold
+    )
+    print("\nMoCaX 4.3.1 equivalent surface:")
+    print(f"  clone()                         → {type(mc.clone()).__name__}")
+    print(f"  get_max_derivative_order()      → {mc.get_max_derivative_order()}")
+    print(f"  get_num_evaluation_points()     → {mc.get_num_evaluation_points()}")
+
+
+if __name__ == "__main__":
+    main()

docs/roadmap.md

@@ -112,14 +112,109 @@ All additive, no breaking changes.
 **Closes MoCaX gaps:** `additional_data`, `get_derivative_id`, descriptor,
 introspection.
 
+## v0.16 — Polish Bundle :material-check:
+
+Final cosmetic mirror of the MoCaX 4.3.1 surface. Strictly additive, no
+breaking changes.
+
+- `clone()` — deep copy on all four classes
+- `get_special_points()`, `get_max_derivative_order()`,
+  `get_error_threshold()` — instance getters
+- `get_evaluation_points()` / `get_num_evaluation_points()` — flat
+  `(N, num_dim)` grid post-construction (MoCaX-style)
+- `set_original_function_values(values)` — in-place deferred
+  construction (alt to the `from_values()` factory)
+- `peek_format_version(filename)` static — read `.pcb` version without
+  deserializing
+- `is_dimensionality_allowed(num_dim)` static — pre-flight capability check
+- Optional typed helpers `Domain`, `Ns`, `SpecialPoints` (constructors
+  accept both raw lists and these dataclasses)
+
+**Closes MoCaX gaps:** the last cosmetic surface methods.
+
+## v0.17 — Integrate Everywhere :material-clock-outline:
+
+Extend the v0.9 calculus toolkit so every class supports integration.
+
+- `ChebyshevSlider.integrate(dims=None, bounds=None)` — full and partial
+  integration via the sliding-decomposition closed form
+- `ChebyshevTT.integrate(dims=None, bounds=None)` — full and partial
+  integration via Fejér-1 weight contraction into TT cores
+
+After v0.17, `integrate()` is available on all four classes. Roots and
+min/max on Slider/TT remain deferred to v0.21.
+
+**Beyond MoCaX:** MoCaX has no `integrate()` API on any class.
+
+## v0.18 — TT Feature Parity :material-clock-outline:
+
+Bring `ChebyshevTT` up to parity with `ChebyshevApproximation` for the
+non-calculus surface.
+
+- TT `extrude()` — add a dim by appending a constant core
+- TT `slice()` — fix a dim by contracting a core via barycentric weights
+- TT `from_values()` classmethod — build from a precomputed full tensor
+  (skip TT-Cross)
+- TT `nodes()` static — generate the Chebyshev grid without function eval
+- TT algebra `+`, `-`, `*` (scalar) — core stacking + rounding
+- `to_dense()` / `from_dense()` — convert between TT and Approximation
+
+**Beyond MoCaX:** richer TT primitives than MoCaXExtend exposes.
+
+## v0.19 — Build & Diagnostics :material-clock-outline:
+
+Ergonomics for users with slow `f` or large grids.
+
+- Parallel function evaluation at build time (`n_workers=` ctor kwarg via
+  `concurrent.futures.ProcessPoolExecutor`)
+- `tqdm`-based progress bars during construction (opt-in, `verbose=2`)
+- `plot_convergence(target_error)` helper — builds at increasing N,
+  plots error decay
+- Visualization helpers: `plot_1d`, `plot_2d_surface`, `plot_2d_contour`
+
+New optional dependency group `pychebyshev[viz]` for matplotlib + tqdm.
+
+**Beyond MoCaX:** MoCaX has neither parallel build nor visualization
+helpers.
+
+## v0.20 — Adaptive Refinement + Interop :material-clock-outline:
+
+Smart node placement plus delivery of the v0.14 `.pcb` portability promise.
+
+- Auto-knot detection for `ChebyshevSpline` — scan for kinks via
+  curvature/derivative discontinuity, place knots automatically
+- Sobol indices computed from spectral coefficients (cheap once the
+  interpolant exists)
+- Auto dimension reordering by importance (helps TT rank growth)
+- Reference `.pcb` reader implementations in **Rust** and **Julia** as
+  separate sub-repos (`0xC000005/pcb-readers`)
+
+**Beyond MoCaX:** MoCaX is closed-source; `.pcb` ecosystem is
+PyChebyshev-unique.
+
+## v0.21 — Advanced Calculus :material-clock-outline:
+
+Research-grade extensions to close the remaining calculus surface.
+
+- N-D rootfinding via Möller–Stetter colleague matrices
+  (Trefethen 2017 ch. 24) on `ChebyshevApproximation` and
+  `ChebyshevSpline`
+- `roots()`, `minimize()`, `maximize()` on `ChebyshevSlider` and
+  `ChebyshevTT` (1-D-at-a-time + Brent's method bracket where no closed
+  form exists)
+- Higher-order partial derivatives on demand (currently capped at
+  construction-time `max_derivative_order`)
+
+**Beyond MoCaX:** spectral N-D rootfinding has no MoCaX analog.
+
 ## v1.0.0 — Parity Announcement :material-clock-outline:
 
-Feature-complete against MoCaX Intelligence 4.3.1. No new code — this release
-is:
+Feature-complete against MoCaX Intelligence 4.3.1, plus the beyond-MoCaX
+extensions from v0.16–v0.21. No new code — this release is:
 
 - Status bump `Beta` → `Production/Stable`
 - API stability commitment going forward
-- Summary CHANGELOG entry covering the parity items
+- Summary CHANGELOG entry covering the parity arc + extensions
 - Refreshed README with the final performance comparison
 
 ---

docs/user-guide/ergonomics.md

@@ -114,3 +114,80 @@ Pickle `load()` is the exception — it preserves the saved object's metadata
 | `getConstructorType()` | `get_constructor_type()` |
 | `getUsedNs()` | `get_used_ns()` |
 | `isConstructionFinished()` | `is_construction_finished()` |
+
+---
+
+## v0.16 polish surface
+
+The v0.16 release adds the final cosmetic mirror of the MoCaX 4.3.1 API.
+All additions are strictly additive.
+
+### `clone()`
+
+Return an independent deep copy of any interpolant:
+
+```python
+cheb2 = cheb1.clone()
+cheb2.set_descriptor("variant")
+# cheb1 is untouched
+```
+
+Available on `ChebyshevApproximation`, `ChebyshevSpline`, `ChebyshevSlider`,
+`ChebyshevTT`. Like `save()`/`load()`, the source `function` callable is not
+duplicated — the clone has `function = None`.
+
+### Instance getters
+
+| Method | Available on | Returns |
+|---|---|---|
+| `get_max_derivative_order()` | all four | `int` |
+| `get_error_threshold()` | Approximation, Spline | `float \| None` |
+| `get_special_points()` | Approximation, Spline | `list[list[float]] \| None` |
+| `get_evaluation_points()` | all four | `np.ndarray` shape `(N, num_dim)` |
+| `get_num_evaluation_points()` | all four | `int` |
+
+`get_evaluation_points()` returns the flat `(N, num_dim)` grid (MoCaX style,
+matches `len(get_evaluation_points()) == get_num_evaluation_points()`).
+
+### Static helpers
+
+```python
+ChebyshevApproximation.peek_format_version("model.pcb")  # → 1
+
+ChebyshevTT.is_dimensionality_allowed(5)  # → True
+```
+
+### Deferred construction (Approximation, Spline)
+
+Construct a grid-only interpolant, then fill its tensor in place:
+
+```python
+cheb = ChebyshevApproximation(None, 2, [[-1,1],[-1,1]], [10,10],
+                               defer_build=True)
+
+# Compute values externally — e.g. on a distributed cluster
+points = cheb.get_evaluation_points()  # (100, 2)
+values = compute_function_on_cluster(points).reshape(10, 10)
+
+cheb.set_original_function_values(values)
+# now evaluable
+result = cheb.eval([0.3, -0.4], [0, 0])
+```
+
+This is the in-place analog of the `from_values()` factory. Bit-identical
+results in both paths.
+
+### Optional typed helpers
+
+```python
+from pychebyshev import Domain, Ns, SpecialPoints, ChebyshevApproximation
+
+cheb = ChebyshevApproximation(
+    f, 2,
+    Domain([(0.0, 1.0), (0.0, 1.0)]),  # equivalent to [[0,1],[0,1]]
+    Ns([15, 15]),                       # equivalent to [15, 15]
+)
+```
+
+Constructors of all four classes accept both raw lists and these frozen
+dataclasses.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pychebyshev"
-version = "0.15.0"
+version = "0.16.0"
 description = "Fast multi-dimensional Chebyshev tensor interpolation with analytical derivatives"
 readme = "README.md"
 license = {text = "MIT"}

src/pychebyshev/__init__.py

@@ -21,10 +21,58 @@
 0.7764
 """
 
+from __future__ import annotations
+
+from dataclasses import dataclass
+
 from pychebyshev._version import __version__
 from pychebyshev.barycentric import ChebyshevApproximation
 from pychebyshev.slider import ChebyshevSlider
 from pychebyshev.spline import ChebyshevSpline
 from pychebyshev.tensor_train import ChebyshevTT
 
-__all__ = ["ChebyshevApproximation", "ChebyshevSlider", "ChebyshevSpline", "ChebyshevTT", "__version__"]
+
+@dataclass(frozen=True)
+class Domain:
+    """Typed container for an interpolant's per-dimension bounds.
+
+    Equivalent to a raw ``list[tuple[float, float]]``. Constructors of
+    all four PyChebyshev classes accept either form.
+    """
+
+    bounds: list[tuple[float, float]]
+
+
+@dataclass(frozen=True)
+class Ns:
+    """Typed container for an interpolant's per-dimension node counts.
+
+    Equivalent to a raw ``list[int]``. Accepted by
+    :class:`ChebyshevApproximation`, :class:`ChebyshevSpline`,
+    :class:`ChebyshevSlider`, and :class:`ChebyshevTT`.
+    """
+
+    counts: list[int]
+
+
+@dataclass(frozen=True)
+class SpecialPoints:
+    """Typed container for per-dimension kink/knot locations.
+
+    Equivalent to a raw ``list[list[float]]``. Accepted by
+    :class:`ChebyshevApproximation` and :class:`ChebyshevSpline`.
+    """
+
+    knots_per_dim: list[list[float]]
+
+
+__all__ = [
+    "ChebyshevApproximation",
+    "ChebyshevSlider",
+    "ChebyshevSpline",
+    "ChebyshevTT",
+    "Domain",
+    "Ns",
+    "SpecialPoints",
+    "__version__",
+]