Merge pull request #14 from 0xC000005/v0.17-integrate

v0.17.0: Integrate Everywhere — Slider + TT integrate()

Author: 0xC000005

CHANGELOG.md

@@ -5,6 +5,19 @@ 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.17.0] - 2026-04-25
+
+### Added — Integrate Everywhere
+
+- `ChebyshevSlider.integrate(dims=None, bounds=None)` — full and partial integration via the sliding-decomposition closed form. Returns a scalar on full integration; a `ChebyshevSlider` over surviving dims on partial.
+- `ChebyshevTT.integrate(dims=None, bounds=None)` — full and partial integration via Fejér-1 quadrature contraction into each integrated core's node axis. Returns a scalar on full integration; a `ChebyshevTT` over surviving dims on partial. Works on TT objects built via Cross, SVD, and ALS methods.
+- New private helpers in `_calculus.py`: `_slider_partition_intersect()`, `_integrate_tt_along_dim()`.
+- Extended user-guide page `docs/user-guide/calculus.md` with v0.17 Slider/TT integration sections.
+
+After v0.17, all four PyChebyshev classes support integration. Roots/min/max on Slider/TT remain deferred to v0.21.
+
+**Beyond MoCaX:** MoCaX 4.3.1 has no `integrate()` API on any class.
+
 ## [0.16.0] - 2026-04-25
 
 ### Added — Polish Bundle (final MoCaX 4.3.1 cosmetic mirror)

CLAUDE.md

@@ -12,7 +12,7 @@ PyChebyshev is a pip-installable Python library for multi-dimensional Chebyshev
 # Setup
 uv sync
 
-# Run tests (~838 tests, ~110s due to 5D Black-Scholes builds)
+# Run tests (~890 tests, ~110s due to 5D Black-Scholes builds)
 uv run pytest tests/ -v
 
 # Run a single test
@@ -59,6 +59,9 @@ The installable package. Public classes: `ChebyshevApproximation`, `ChebyshevSpl
   `is_dimensionality_allowed()` static, `defer_build=True` +
   `set_original_function_values()`, and optional `Domain`/`Ns`/`SpecialPoints`
   typed helpers (constructors accept both forms).
+- v0.17 adds `integrate()` on `ChebyshevSlider` and `ChebyshevTT` (full +
+  partial integration). After v0.17, every PyChebyshev class supports
+  integration. Roots/min/max on Slider/TT remain deferred to v0.21.
 
 ### Benchmark Scripts (project root)
 
@@ -77,6 +80,7 @@ Not part of the library. Compare Chebyshev barycentric against alternative metho
 - `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)
+- `compare_calculus_completion.py` — PyChebyshev v0.17 Slider/TT integrate vs MoCaX 4.3.1 (no equivalent — beyond-MoCaX feature)
 
 ### Tests (`tests/`)
 
@@ -101,6 +105,9 @@ Not part of the library. Compare Chebyshev barycentric against alternative metho
   `get_evaluation_points`, `get_num_evaluation_points`), `peek_format_version`,
   `is_dimensionality_allowed`, `defer_build` + `set_original_function_values`,
   `Domain`/`Ns`/`SpecialPoints` typed helpers.
+- `test_calculus_completion.py` — ~37 tests: `ChebyshevSlider.integrate()` (full
+  and partial), `ChebyshevTT.integrate()` (full and partial), cross-class
+  consistency checks, bounds validation.
 
 ### CI/CD (`.github/workflows/`)
 

compare_calculus_completion.py

@@ -0,0 +1,47 @@
+"""Side-by-side comparison: PyChebyshev v0.17 integrate() on Slider/TT vs MoCaX 4.3.1.
+
+MoCaX has no integrate() API on any class. This script demonstrates
+PyChebyshev's spectral integration as a beyond-MoCaX feature.
+
+    uv run python compare_calculus_completion.py
+"""
+
+from __future__ import annotations
+
+import math
+
+from pychebyshev import ChebyshevSlider, ChebyshevTT
+
+
+def f(x, _):
+    return math.sin(x[0]) + math.cos(x[1])
+
+
+def main():
+    domain = [[-1.0, 1.0], [-1.0, 1.0]]
+
+    # PyChebyshev Slider integrate
+    slider = ChebyshevSlider(
+        f, 2, domain, [10, 10],
+        partition=[[0], [1]], pivot_point=[0.0, 0.0],
+    )
+    slider.build(verbose=False)
+    print("PyChebyshev v0.17 — integrate() on all four classes:")
+    print(f"  Slider full integrate           → {slider.integrate():.6f}")
+    print(f"  Slider partial (dims=[0])       → {type(slider.integrate(dims=[0])).__name__}")
+
+    # PyChebyshev TT integrate
+    tt = ChebyshevTT(f, 2, domain, [10, 10])
+    tt.build(verbose=False)
+    print(f"  TT full integrate               → {tt.integrate():.6f}")
+    print(f"  TT partial (dims=[0])           → {type(tt.integrate(dims=[0])).__name__}")
+
+    # Analytical answer for sin(x) + cos(y) over [-1,1]^2 = 4*sin(1)
+    print(f"\n  Analytical: 4 * sin(1)         → {4.0 * math.sin(1.0):.6f}")
+
+    # MoCaX equivalent: none. Document this clearly.
+    print("\nMoCaX 4.3.1: no integrate() API on any class — PyChebyshev is unique here.")
+
+
+if __name__ == "__main__":
+    main()

docs/roadmap.md

@@ -132,7 +132,7 @@ breaking changes.
 
 **Closes MoCaX gaps:** the last cosmetic surface methods.
 
-## v0.17 — Integrate Everywhere :material-clock-outline:
+## v0.17 — Integrate Everywhere :material-check:
 
 Extend the v0.9 calculus toolkit so every class supports integration.
 

docs/user-guide/calculus.md

@@ -24,14 +24,20 @@ all from a single pre-built proxy, without calling the pricing engine again.
     See [Chebyshev Algebra](algebra.md) for combining interpolants and
     [Extrusion & Slicing](extrude-slice.md) for dimension manipulation.
 
+!!! info "v0.17"
+    `integrate()` now works on all four classes.  `ChebyshevSlider` and
+    `ChebyshevTT` support full and partial integration (see
+    [Slider integration](#slider-integration-v017) and
+    [TT integration](#tt-integration-v017)).
+
 ## Supported Classes
 
 | Class | `integrate()` | `roots()` | `minimize()` / `maximize()` |
 |-------|:---:|:---:|:---:|
 | `ChebyshevApproximation` | Yes | Yes | Yes |
 | `ChebyshevSpline` | Yes | Yes | Yes |
-| `ChebyshevSlider` | No | No | No |
-| `ChebyshevTT` | No | No | No |
+| `ChebyshevSlider` | Yes (v0.17) | No | No |
+| `ChebyshevTT` | Yes (v0.17) | No | No |
 
 ## Integration
 
@@ -200,6 +206,83 @@ cheb_2d.build()
 result = cheb_2d.integrate(dims=[0, 1], bounds=[(0.0, 1.0), None])
 ```
 
+### Slider Integration (v0.17)
+
+`ChebyshevSlider` uses the closed-form structure of the sliding decomposition.
+For a slider with pivot value $pv$ and slides $s_i$ over groups $G_i$:
+
+$$
+f(x) \approx pv + \sum_i \bigl[s_i(x_{G_i}) - pv\bigr]
+$$
+
+Integrating over a region $T = \prod_d [a'_d, b'_d]$ gives:
+
+$$
+\int_T f \, dx = pv \cdot \mathrm{vol}(T) \cdot (1 - k)
+  + \sum_i \mathrm{vol}(T \setminus G_i) \cdot \int_{T \cap G_i} s_i
+$$
+
+where $k$ is the number of slides.  Each slide integral is delegated to
+`ChebyshevApproximation.integrate()`.
+
+Full integration returns a scalar.  Partial integration (some dims surviving)
+returns a new `ChebyshevSlider` over the surviving dimensions.  Slides whose
+groups are fully integrated out are absorbed into an updated pivot value;
+slides with partially surviving groups are reduced by integrating the consumed
+dimensions of their underlying approximation.
+
+```python
+from pychebyshev import ChebyshevSlider
+import math
+
+slider = ChebyshevSlider(
+    lambda x, _: math.sin(x[0]) + math.cos(x[1]),
+    2, [[-1.0, 1.0], [-1.0, 1.0]], [12, 12],
+    partition=[[0], [1]], pivot_point=[0.0, 0.0],
+)
+slider.build()
+
+total = slider.integrate()                        # → scalar
+reduced = slider.integrate(dims=[0])              # → 1-D ChebyshevSlider
+```
+
+Sub-interval bounds work the same as for `ChebyshevApproximation`:
+
+```python
+# Integrate dim 0 over [0, 1], return 1-D slider in dim 1
+partial = slider.integrate(dims=[0], bounds=[(0.0, 1.0)])
+```
+
+### TT Integration (v0.17)
+
+`ChebyshevTT` cores are stored in Chebyshev coefficient space.  For each
+integrated dimension $d$, the algorithm:
+
+1. Converts core $d$ from coefficient to value space (type-I DCT).
+2. Contracts the Fejér-1 quadrature weights (or sub-interval weights for
+   bounded integration) into the node axis, producing a rank-2 matrix.
+3. Absorbs that matrix into the nearest surviving core to maintain the TT chain.
+
+Full integration contracts all cores to a scalar.  Partial integration
+returns a new `ChebyshevTT` over the surviving dimensions.  The method works
+for TT objects built with any build strategy (`'cross'`, `'svd'`, `'als'`).
+
+```python
+from pychebyshev import ChebyshevTT
+import math
+
+tt = ChebyshevTT(
+    lambda x, _: math.sin(x[0]) + math.cos(x[1]),
+    2, [[-1.0, 1.0], [-1.0, 1.0]], [12, 12],
+)
+tt.build()
+
+total = tt.integrate()                            # → scalar
+reduced = tt.integrate(dims=[0])                  # → 1-D ChebyshevTT
+```
+
+Sub-interval bounds are supported identically to `ChebyshevApproximation`.
+
 ### `integrate()` API
 
 | Parameter | Type | Description |
@@ -208,8 +291,8 @@ result = cheb_2d.integrate(dims=[0, 1], bounds=[(0.0, 1.0), None])
 | `bounds` | `tuple`, `list[tuple/None]`, or `None` | Sub-interval bounds. `None` = full domain. Single `(lo, hi)` for one dim, or list with positional correspondence to `dims`. |
 
 **Returns**: `float` if all dimensions are integrated; otherwise a
-lower-dimensional interpolant of the same type (`ChebyshevApproximation` or
-`ChebyshevSpline`).
+lower-dimensional interpolant of the **same type** (`ChebyshevApproximation`,
+`ChebyshevSpline`, `ChebyshevSlider`, or `ChebyshevTT`).
 
 **Errors**:
 
@@ -357,9 +440,10 @@ Partial integration on a spline returns a lower-dimensional `ChebyshevSpline`.
 
 ## Derivatives, Error Estimation, and Serialization
 
-**Partial integration** returns a fully functional interpolant (either
-`ChebyshevApproximation` or `ChebyshevSpline`).  All existing features
-work on the result:
+**Partial integration** returns a fully functional interpolant of the same
+type (`ChebyshevApproximation`, `ChebyshevSpline`, `ChebyshevSlider`, or
+`ChebyshevTT`).  For `ChebyshevApproximation` and `ChebyshevSpline`, all
+existing features work on the result:
 
 - **Derivatives**: `vectorized_eval(point, [1])` computes derivatives in
   the surviving dimensions via the spectral differentiation matrices.
@@ -400,10 +484,10 @@ matrices, and barycentric evaluation.
 
 ## Limitations
 
-- **Not yet supported on `ChebyshevSlider` or `ChebyshevTT`.**
-  Calculus on Tensor Train interpolants would require TT-specific
-  coefficient extraction; slider calculus would need per-slide integration
-  with additive recombination.
+- **`roots()`, `minimize()`, and `maximize()` are not yet supported on
+  `ChebyshevSlider` or `ChebyshevTT`.**  These operations require
+  1-D polynomial coefficient extraction; generalising to the sliding
+  decomposition or TT format is deferred.
 - **Multi-D rootfinding** (2D Bezout resultants) is not implemented. Only
   1-D slices are supported via the `dim` + `fixed` interface.
 - **Result has `function=None`** -- partial integration results cannot call

pyproject.toml

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

src/pychebyshev/_calculus.py

@@ -337,3 +337,52 @@ def _validate_calculus_args(ndim, dim, fixed, domain):
         slice_params.append((d, v))
 
     return dim, slice_params
+
+
+def _slider_partition_intersect(
+    group_dims: list[int], integrate_dims: list[int]
+) -> tuple[str, list[int]]:
+    """Classify a slide group against an integration set.
+
+    Parameters
+    ----------
+    group_dims : list[int]
+        Dimensions covered by the slide group.
+    integrate_dims : list[int]
+        Dimensions being integrated over.
+
+    Returns
+    -------
+    kind : str
+        One of: "full" (entire group integrated), "partial" (some dims
+        integrated), "none" (no group dims integrated).
+    kept : list[int]
+        Dimensions of the group NOT being integrated. Empty for "full".
+    """
+    group_set = set(group_dims)
+    integrate_set = set(integrate_dims)
+    overlap = group_set & integrate_set
+    if not overlap:
+        return "none", list(group_dims)
+    if overlap == group_set:
+        return "full", []
+    return "partial", [d for d in group_dims if d not in integrate_set]
+
+
+def _integrate_tt_along_dim(core: np.ndarray, weights: np.ndarray) -> np.ndarray:
+    """Contract a single TT core along its node axis with quadrature weights.
+
+    Parameters
+    ----------
+    core : np.ndarray
+        Shape ``(r_left, n, r_right)``.
+    weights : np.ndarray
+        Shape ``(n,)`` — quadrature weights scaled to the dim's domain.
+
+    Returns
+    -------
+    np.ndarray
+        Shape ``(r_left, r_right)`` — the contracted matrix
+        ``M = sum_j core[:, j, :] * weights[j]``.
+    """
+    return np.einsum("rjs,j->rs", core, weights)

src/pychebyshev/_version.py

@@ -1 +1 @@
-__version__ = "0.16.0"
+__version__ = "0.17.0"