Update README, docs, and CLAUDE.md for v0.5.0 completeness

0xC000005 · claude · 0xC000005 · commit 1551bbd3b8a2 · 2026-02-12T16:11:37.000-05:00
Add ChebyshevTT to README features list and code examples, docs landing
page, getting-started class selection guide, API reference, and error
estimation page. Update CLAUDE.md with tensor_train.py architecture,
current test counts, and comparison script.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PyChebyshev is a pip-installable Python library for multi-dimensional Chebyshev tensor interpolation with analytical derivatives. It uses barycentric interpolation with full weight pre-computation and BLAS GEMV for fast evaluation. Originally developed as a research project comparing numerical methods for Black-Scholes option pricing against the MoCaX C++ library.
+
+## Commands
+
+```bash
+# Setup
+uv sync
+
+# Run tests (~100 tests, ~120s due to 5D Black-Scholes builds)
+uv run pytest tests/ -v
+
+# Run a single test
+uv run pytest tests/test_barycentric.py::TestSimple3D::test_price_accuracy -v
+
+# Build package
+uv build
+
+# Build and preview docs locally
+uv run mkdocs serve          # http://127.0.0.1:8000
+uv run mkdocs build --strict # Verify docs build
+
+# Deploy docs to GitHub Pages
+uv run mkdocs gh-deploy --force
+
+# Run benchmark scripts (not part of library)
+uv run python chebyshev_barycentric.py
+uv run python compare_methods_time_accuracy.py
+```
+
+## Architecture
+
+### Library (`src/pychebyshev/`)
+
+The installable package. Public classes: `ChebyshevApproximation`, `ChebyshevSlider`, and `ChebyshevTT`.
+
+- **`barycentric.py`** — Core implementation. `ChebyshevApproximation` class with `build()`, `eval()`, `vectorized_eval()`, `vectorized_eval_multi()`. Key insight: barycentric weights depend only on node positions (not function values), enabling full pre-computation. `vectorized_eval()` uses a reshape trick to route N-D tensor contractions through BLAS GEMV (~0.065ms/query). `vectorized_eval_multi()` shares barycentric weight computation across price + derivatives (~0.29ms for 6 outputs). `fast_eval()` exists but is deprecated (JIT path, ~150x slower than BLAS).
+- **`slider.py`** — `ChebyshevSlider` class for high-dimensional approximation via the Sliding Technique.
+- **`tensor_train.py`** — `ChebyshevTT` class for Tensor Train Chebyshev interpolation. TT-Cross builds from O(d·n·r²) evaluations with maxvol pivoting, eval caching, and SVD-based adaptive rank. Vectorized batch eval via numpy einsum. FD derivatives.
+- **`_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.
+
+### Benchmark Scripts (project root)
+
+Not part of the library. Compare Chebyshev barycentric against alternative methods:
+
+- `chebyshev_barycentric.py` — Standalone version with embedded test suite
+- `chebyshev_baseline.py` — NumPy polynomial coefficient approach
+- `fdm_baseline.py` — Finite difference PDE solver
+- `mocax_baseline.py`, `mocax_tt.py`, `mocax_sliding.py` — MoCaX C++ library tests (require `mocaxextend_lib/`)
+- `compare_methods_time_accuracy.py` — Fair time/accuracy comparison across all methods
+- `compare_tensor_train.py` — PyChebyshev TT vs MoCaX TT comparison (requires `mocaxextend_lib/`)
+
+### Tests (`tests/`)
+
+- `conftest.py` — Shared fixtures (`cheb_sin_3d`, `cheb_bs_3d`, `cheb_bs_5d`, `tt_sin_3d`, `tt_bs_5d`) and analytical Black-Scholes functions (reimplemented via `scipy.stats.norm` to avoid external deps). Helper functions are imported as `from conftest import ...` (pytest auto-import, NOT `from tests.conftest`).
+- `test_barycentric.py` — 35 tests: accuracy, derivatives, eval method consistency, node coincidence, error estimation, build-required guard.
+- `test_slider.py` — 36 tests: additive/coupled functions, 5D, cross-group derivatives, error estimation, serialization.
+- `test_tensor_train.py` — 23 tests: TT-Cross/TT-SVD accuracy, batch eval, FD derivatives, rank control, serialization, error estimation.
+
+### CI/CD (`.github/workflows/`)
+
+- `test.yml` — pytest on Python 3.10-3.13 (triggers on push/PR to main)
+- `publish.yml` — `uv build && uv publish` via OIDC trusted publishing (triggers on GitHub release creation)
+
+### Docs (`docs/`)
+
+MkDocs + Material theme, deployed to GitHub Pages. KaTeX for math rendering, mkdocstrings for API autodoc from NumPy-style docstrings.
+
+## Key Technical Constraints
+
+- **Numba/JIT is deprecated**: `fast_eval()` and `_jit.py` are deprecated. `vectorized_eval()` via BLAS GEMV is ~150x faster and needs no optional deps.
+- **Python >=3.10**: Uses `from __future__ import annotations` for modern type hints.
+- **Core deps are only numpy and scipy**: pytest, matplotlib, blackscholes etc. belong in dev/optional groups only.
+- **README images must use absolute GitHub URLs**: PyPI renders README but can't serve local files. Use `https://raw.githubusercontent.com/0xC000005/PyChebyshev/main/...` for all `<img src>`.
+- **Version in two places**: `pyproject.toml` and `src/pychebyshev/_version.py` must stay in sync.
+
+## Release Process
+
+1. Bump version in `pyproject.toml` and `src/pychebyshev/_version.py`
+2. Update `CHANGELOG.md`
+3. Commit, push to main
+4. `gh release create vX.Y.Z` — triggers publish workflow → PyPI
+5. `uv run mkdocs gh-deploy --force` — updates docs site
diff --git a/README.md b/README.md
@@ -63,8 +63,9 @@ The convergence plots demonstrate exponential error decay as node count increase
 
 ## Features
 
-- **Full tensor interpolation** via `ChebyshevApproximation` — spectral accuracy for up to ~5-6 dimensions
-- **Sliding technique** via `ChebyshevSlider` — additive decomposition for high-dimensional functions (10+ dims)
+- **Full tensor interpolation** via `ChebyshevApproximation` — spectral accuracy for up to ~5 dimensions
+- **Tensor Train decomposition** via `ChebyshevTT` — TT-Cross builds from O(d·n·r²) evaluations for 5+ dimensions
+- **Sliding technique** via `ChebyshevSlider` — additive decomposition for separable high-dimensional functions
 - **Analytical derivatives** via spectral differentiation matrices (no finite differences)
 - **Vectorized evaluation** using BLAS matrix-vector products (~0.065ms/query)
 - **Pure Python** — NumPy + SciPy only, no compiled extensions needed
@@ -114,9 +115,31 @@ results = cheb.vectorized_eval_multi(
 )
 ```
 
-### High-Dimensional Functions (Sliding Technique)
+### High-Dimensional Functions (Tensor Train)
 
-For functions with more than ~6 dimensions, use `ChebyshevSlider` to decompose into low-dimensional slides:
+For 5+ dimensional functions where full tensor grids are too expensive, use `ChebyshevTT` with TT-Cross:
+
+```python
+from pychebyshev import ChebyshevTT
+
+tt = ChebyshevTT(
+    my_func, num_dimensions=5,
+    domain=[[-1, 1]] * 5,
+    n_nodes=[11] * 5,
+    max_rank=10,
+)
+tt.build()
+val = tt.eval([0.5] * 5)
+
+# Batch evaluation (much faster per point)
+import numpy as np
+points = np.random.uniform(-1, 1, (1000, 5))
+vals = tt.eval_batch(points)
+```
+
+### Separable Functions (Sliding Technique)
+
+For functions that decompose additively, use `ChebyshevSlider`:
 
 ```python
 from pychebyshev import ChebyshevSlider
diff --git a/docs/api/reference.md b/docs/api/reference.md
@@ -8,6 +8,10 @@
 
 ::: pychebyshev.ChebyshevSlider
 
+## ChebyshevTT
+
+::: pychebyshev.ChebyshevTT
+
 ## Module Functions
 
 ::: pychebyshev.barycentric.compute_barycentric_weights
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -103,3 +103,11 @@ See [Saving & Loading](user-guide/serialization.md) for details.
 - More nodes = higher accuracy but more build-time evaluations ($n_1 \times n_2 \times \cdots$)
 - For 5D with 11 nodes: $11^5 = 161{,}051$ function evaluations at build time
 - Convergence is **exponential** for analytic functions — a few extra nodes can eliminate errors entirely
+
+## Choosing the Right Class
+
+| Class | Dimensions | Build Cost | Derivatives | Best For |
+|-------|-----------|-----------|-------------|----------|
+| [`ChebyshevApproximation`](user-guide/usage.md) | 1–5 | $n^d$ evals | Analytical | Full accuracy with spectral derivatives |
+| [`ChebyshevTT`](user-guide/tensor-train.md) | 5+ | $O(d \cdot n \cdot r^2)$ evals | Finite differences | High-dimensional problems where full grids are infeasible |
+| [`ChebyshevSlider`](user-guide/sliding.md) | 5+ | Sum of slide grids | Analytical (per slide) | Functions with additive/separable structure |
diff --git a/docs/index.md b/docs/index.md
@@ -2,14 +2,18 @@
 
 **Fast multi-dimensional Chebyshev tensor interpolation with analytical derivatives.**
 
-PyChebyshev builds a Chebyshev interpolant of any smooth function in up to N dimensions, then evaluates it and its derivatives in microseconds using vectorized NumPy operations.
+PyChebyshev builds a Chebyshev interpolant of any smooth function in up to N dimensions, then evaluates it and its derivatives in microseconds using vectorized NumPy operations. Three classes cover different use cases:
+
+- **[`ChebyshevApproximation`](user-guide/usage.md)** — full tensor interpolation with analytical derivatives (up to ~5 dimensions)
+- **[`ChebyshevTT`](user-guide/tensor-train.md)** — Tensor Train format via TT-Cross for 5+ dimensions
+- **[`ChebyshevSlider`](user-guide/sliding.md)** — additive decomposition for separable high-dimensional functions
 
 ## Key Features
 
 - **Spectral accuracy** — exponential error decay as node count increases
 - **Analytical derivatives** — via spectral differentiation matrices (no finite differences)
+- **Tensor Train** — TT-Cross builds from O(d·n·r²) evaluations instead of O(n^d)
 - **Fast evaluation** — ~0.065 ms per query (price), ~0.29 ms for price + 5 Greeks
-- **Minimal storage** — 55 floats (440 bytes) for a 5D interpolant with 11 nodes per dimension
 - **Save & load** — persist built interpolants to disk; rebuild-free deployment
 - **Pure Python** — NumPy + SciPy only, no compiled extensions needed
 
diff --git a/docs/user-guide/error-estimation.md b/docs/user-guide/error-estimation.md
@@ -149,9 +149,25 @@ For $\sin(x)$, which is entire (analytic everywhere), the coefficients decay
 exponentially, so you should see the estimate drop by several orders of magnitude as
 $n$ grows.
 
+## Tensor Train Error Estimation
+
+`ChebyshevTT` also supports `error_estimate()`. The estimate is computed from the
+Chebyshev coefficient cores: for each dimension, the last coefficient slice of the
+core is extracted and its norm serves as the per-dimension error proxy. These are
+summed across dimensions, following the same logic as the full tensor case.
+
+```python
+from pychebyshev import ChebyshevTT
+
+tt = ChebyshevTT(my_func, 5, domain, [11]*5, max_rank=10)
+tt.build()
+print(f"TT error estimate: {tt.error_estimate():.2e}")
+```
+
 ## API Reference
 
 For full method signatures and parameter details, see:
 
 - [`ChebyshevApproximation.error_estimate()`](../api/reference.md#pychebyshev.ChebyshevApproximation.error_estimate) -- error estimate for standard tensor interpolation.
 - [`ChebyshevSlider.error_estimate()`](../api/reference.md#pychebyshev.ChebyshevSlider.error_estimate) -- error estimate for sliding approximation (sum of per-slide errors).
+- [`ChebyshevTT.error_estimate()`](../api/reference.md#pychebyshev.ChebyshevTT.error_estimate) -- error estimate for Tensor Train approximation (from coefficient cores).
