FastLSQ 0.4.1__tar.gz → 0.4.2__tar.gz

{fastlsq-0.4.1 → fastlsq-0.4.2}/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to FastLSQ will be documented in this file.
 
+## [0.4.2] - 2026-07-20
+
+### Fixed
+
+- **`IntegralOperator` with `order >= 2` returned wrong values.** The higher-order
+  branch evaluated `F_n(hi) − F_n(lo)`, the difference of n-th antiderivatives, which
+  is *not* the n-fold iterated (Volterra) integral: it drops the polynomial terms
+  `Σ_{j=1}^{n-1} F_j(lo)·Δ^{n−j}/(n−j)!`. For `order=2` on `[0,1]` this was ~380%
+  off against a double cumulative-trapezoid reference. `order=1` was always correct
+  and is unchanged. The higher-order path now goes through the new
+  `SinusoidalBasis.iterated_integral(..., order=n)`, which implements the Cauchy
+  repeated-integration formula `∫_lo^x (x−t)^{n−1}/(n−1)! φ(t) dt` and agrees with
+  n-fold quadrature to ~1e-9 (grid-limited) and with 60-digit `mpmath` to ~1e-15.
+- **Near-DC features are now consistent across orders.** The `order >= 2` path went
+  through the DC-guarded `derivative`, which *zeroes* any feature with
+  `|W_dim| <= dc_eps`, while `order=1` handled it exactly via the `sinc` identity. A
+  near-DC feature is constant along the integrated axis, so its iterated integral is
+  the finite ramp `φ·Δ^n/n!` — the limit-bearing integral does not diverge, unlike the
+  standalone `1/W` antiderivative that `dc_eps` exists to guard. `iterated_integral`
+  therefore applies **no DC guard** and is exact as `W_dim → 0` at every order, while
+  `derivative` with negative `alpha` keeps its guard because that primitive genuinely
+  blows up. Documented in both docstrings.
+
+### Added
+
+- **`SinusoidalBasis.iterated_integral(x, dim, lower, upper=None, order=n)`** — the
+  n-fold iterated integral in closed form. Evaluated by a cancellation-free Taylor-tail
+  series `Δ^n Σ_p θ^p/(n+p)!·Φ_p(Z_lo)` for small `|θ| = |W_dim·Δ|` and by the
+  equivalent antiderivative form above it, since the latter's rounding error grows like
+  `n!/θ^n`. Holds ~1e-15 (relative to `Δ^n/n!`) for `n ≤ 10`, ~4e-14 by `n = 12`.
+- **`order >= 2` test coverage** in `tests/test_integral.py` (previously every test used
+  the default `order=1`): n-fold cumulative-trapezoid and Cauchy-kernel references for
+  Volterra and definite integrals, `order=1` agreement between the two code paths,
+  near-DC exactness at every order, and an explicit guard that the result is *not* the
+  naive difference of n-th antiderivatives.
+
 ## [0.4.1] - 2026-06-23
 
 ### Added

{fastlsq-0.4.1 → fastlsq-0.4.2}/FastLSQ.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.4.1
+Version: 0.4.2
 Summary: One-shot PDE solving via Fourier features with exact analytical derivatives; rank-revealing solvers, learnable anisotropic bandwidth, and CPU/CUDA/MPS support
 Author: Antonin Sulc
 License-Expression: MIT
@@ -278,7 +278,7 @@ derivative engine:
 | `SinusoidalBasis` | Evaluates basis functions and arbitrary-order derivatives in O(1) via the cyclic identity |
 | `BasisCache` | Pre-computes sin(Z)/cos(Z) once, reuses across multiple derivative evaluations |
 | `DiffOperator` / `Op` | Symbolic linear differential operators that compose via +, -, scalar *; coefficients can be `nn.Parameter` for learnable PDEs |
-| `IntegralOperator` / `IntegroDifferentialOperator` | Closed-form **single-axis** definite / running (Volterra) integrals; compose with `Op` into one integro-differential design matrix |
+| `IntegralOperator` / `IntegroDifferentialOperator` | Closed-form **single-axis** definite / running (Volterra) integrals, including `order=n` **iterated** integrals `∫_lo^x (x−t)^{n−1}/(n−1)! φ dt`; compose with `Op` into one integro-differential design matrix |
 | `GaussianWindowedBasis` / `ProjectionOperator` | Windowed-Fourier (Gabor) basis + closed-form **projection (Radon)** operator `∫ f δ(c·z−u) dz` for tomographic / line-integral inverse problems; quadrature-free and differentiable in the optics `c` |
 | `FeatureBasis` | Adapter for non-sinusoidal solvers (e.g. PIELM with tanh) |
 | `FastLSQSolver` | Manages feature blocks; exposes `.basis` for all derivative computations |

{fastlsq-0.4.1 → fastlsq-0.4.2}/FastLSQ.egg-info/SOURCES.txt

@@ -35,17 +35,6 @@ examples/run_nonlinear.py
 examples/tutorial_basic.py
 examples/tutorial_nonlinear.py
 examples/vector_basis_stream_vorticity.py
-examples/digital_twins/darcy_heat.py
-examples/digital_twins/pendulum.py
-examples/digital_twins/pendulum_benchmark.py
-examples/digital_twins/plasma_wakefield.py
-examples/digital_twins/plasma_wakefield_2D_1.py
-examples/digital_twins/plasma_wakefield_2D_2.py
-examples/digital_twins/plasma_wakefield_2d_3.py
-examples/digital_twins/plasma_wakefield_parameteric.py
-examples/digital_twins/plot_utils.py
-examples/digital_twins/structural_health_simple.py
-examples/digital_twins/turbulence_gravity_cooling.py
 examples/extras/fred_sde.py
 examples/extras/fred_sde_fastlsq.py
 examples/extras/gaia_potential.py
@@ -87,22 +76,6 @@ examples/extras/scenarios/s12_mems_resonator.py
 examples/extras/scenarios/s13_variable_stars_kepler.py
 examples/extras/scenarios/s14_eeg.py
 examples/extras/scenarios/s15_circadian.py
-examples/inverse/aero_.py
-examples/inverse/denoising_parameter_estimation.py
-examples/inverse/elastic_wave_animation.py
-examples/inverse/heat_from_video.py
-examples/inverse/inverse_memory_kernel.py
-examples/inverse/inverse_source_integral_sensors.py
-examples/inverse/inverse_turbulence.py
-examples/inverse/rlc_system_id.py
-examples/inverse/shape_ns.py
-examples/inverse/subsurface_imaging.py
-examples/inverse/tomography_projection.py
-examples/inverse/wing_optimize_simple.py
-examples/sindy/compare_sindy_methods.py
-examples/sindy/sindy_benchmarks.py
-examples/sindy/sindy_differentiable.py
-examples/sindy/sindy_minimal_diff.py
 fastlsq/__init__.py
 fastlsq/api.py
 fastlsq/basis.py
@@ -126,16 +99,6 @@ fastlsq/problems/__init__.py
 fastlsq/problems/linear.py
 fastlsq/problems/nonlinear.py
 fastlsq/problems/regression.py
-misc/fastlsq_teaser.png
-misc/ideal_quadrupole.png
-misc/inverse_heat_source.gif
-misc/inverse_heat_source.png
-misc/inverse_magnetostatics.png
-misc/inverse_magnetostatics_convergence.png
-misc/quadrupole_convergence.png
-misc/quadrupole_optimization.png
-misc/tutorial_nlpoisson_convergence.png
-misc/tutorial_nlpoisson_solution.png
 tests/test_basic.py
 tests/test_benchmarks_inverse.py
 tests/test_block.py

{fastlsq-0.4.1 → fastlsq-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.4.1
+Version: 0.4.2
 Summary: One-shot PDE solving via Fourier features with exact analytical derivatives; rank-revealing solvers, learnable anisotropic bandwidth, and CPU/CUDA/MPS support
 Author: Antonin Sulc
 License-Expression: MIT
@@ -278,7 +278,7 @@ derivative engine:
 | `SinusoidalBasis` | Evaluates basis functions and arbitrary-order derivatives in O(1) via the cyclic identity |
 | `BasisCache` | Pre-computes sin(Z)/cos(Z) once, reuses across multiple derivative evaluations |
 | `DiffOperator` / `Op` | Symbolic linear differential operators that compose via +, -, scalar *; coefficients can be `nn.Parameter` for learnable PDEs |
-| `IntegralOperator` / `IntegroDifferentialOperator` | Closed-form **single-axis** definite / running (Volterra) integrals; compose with `Op` into one integro-differential design matrix |
+| `IntegralOperator` / `IntegroDifferentialOperator` | Closed-form **single-axis** definite / running (Volterra) integrals, including `order=n` **iterated** integrals `∫_lo^x (x−t)^{n−1}/(n−1)! φ dt`; compose with `Op` into one integro-differential design matrix |
 | `GaussianWindowedBasis` / `ProjectionOperator` | Windowed-Fourier (Gabor) basis + closed-form **projection (Radon)** operator `∫ f δ(c·z−u) dz` for tomographic / line-integral inverse problems; quadrature-free and differentiable in the optics `c` |
 | `FeatureBasis` | Adapter for non-sinusoidal solvers (e.g. PIELM with tanh) |
 | `FastLSQSolver` | Manages feature blocks; exposes `.basis` for all derivative computations |

{fastlsq-0.4.1 → fastlsq-0.4.2}/README.md

@@ -237,7 +237,7 @@ derivative engine:
 | `SinusoidalBasis` | Evaluates basis functions and arbitrary-order derivatives in O(1) via the cyclic identity |
 | `BasisCache` | Pre-computes sin(Z)/cos(Z) once, reuses across multiple derivative evaluations |
 | `DiffOperator` / `Op` | Symbolic linear differential operators that compose via +, -, scalar *; coefficients can be `nn.Parameter` for learnable PDEs |
-| `IntegralOperator` / `IntegroDifferentialOperator` | Closed-form **single-axis** definite / running (Volterra) integrals; compose with `Op` into one integro-differential design matrix |
+| `IntegralOperator` / `IntegroDifferentialOperator` | Closed-form **single-axis** definite / running (Volterra) integrals, including `order=n` **iterated** integrals `∫_lo^x (x−t)^{n−1}/(n−1)! φ dt`; compose with `Op` into one integro-differential design matrix |
 | `GaussianWindowedBasis` / `ProjectionOperator` | Windowed-Fourier (Gabor) basis + closed-form **projection (Radon)** operator `∫ f δ(c·z−u) dz` for tomographic / line-integral inverse problems; quadrature-free and differentiable in the optics `c` |
 | `FeatureBasis` | Adapter for non-sinusoidal solvers (e.g. PIELM with tanh) |
 | `FastLSQSolver` | Manages feature blocks; exposes `.basis` for all derivative computations |

{fastlsq-0.4.1 → fastlsq-0.4.2}/fastlsq/__init__.py

@@ -55,7 +55,7 @@ from fastlsq.export import (
 from fastlsq import viz
 from fastlsq import benchmark
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 __all__ = [
     # Device selection (CPU / CUDA / Apple-MPS, dtype-aware)
     "resolve_device",

{fastlsq-0.4.1 → fastlsq-0.4.2}/fastlsq/basis.py

@@ -61,6 +61,8 @@ Example
 
 from __future__ import annotations
 
+import math
+
 import torch
 import numpy as np
 from typing import Optional, Sequence, Union
@@ -141,8 +143,22 @@ class SinusoidalBasis:
         sinusoidal antiderivative (its primitive is a ramp that leaves the basis),
         so its column is zeroed instead of dividing by ~0.  Only affects negative
         orders; ordinary derivatives are untouched.
+
+        It also does **not** affect the limit-bearing integrals
+        (:meth:`definite_integral`, :meth:`iterated_integral`): over a finite interval
+        the ramp is perfectly well defined -- a DC feature integrates to ``φ·Δ^n/n!``
+        -- so those are computed exactly, with no guard, at every order.  Only the
+        *standalone* primitive genuinely diverges as ``1/W``, and only it is guarded.
     """
 
+    # Branch point for :meth:`iterated_integral`.  Below |θ| = W_dim·Δ the closed form
+    # suffers catastrophic cancellation (its rounding error grows like n!/θ^n), so the
+    # equivalent Taylor-tail series is used; above it the series would need many more
+    # terms.  40 terms hold both branches to ~1e-15 (relative to Δ^n/n!) for n ≤ 10,
+    # degrading gracefully to ~4e-14 by n = 12; verified against 60-digit mpmath.
+    _ITER_THETA_MAX = 4.0
+    _ITER_TERMS = 40
+
     def __init__(
         self,
         W: torch.Tensor,
@@ -358,6 +374,99 @@ class SinusoidalBasis:
         out = delta * torch.sin(half_sum) * torch.sinc(sinc_arg)
         return out * self._inv_norm
 
+    def iterated_integral(
+        self,
+        x: torch.Tensor,
+        dim: int,
+        lower: float,
+        upper: Optional[float] = None,
+        order: int = 1,
+        cache: Optional[BasisCache] = None,
+    ) -> torch.Tensor:
+        """``order``-fold *iterated* (Cauchy) integral along one axis, shape (M, N).
+
+        This is the repeated integral with all ``order`` lower limits pinned at
+        ``lower`` -- the operator a Volterra integral equation actually applies --
+
+            (I^n φ)(x) = ∫_lo^x ∫_lo^{s_1} … ∫_lo^{s_{n-1}} φ dt … ds_1
+                       = ∫_lo^x (x − t)^{n−1}/(n−1)! · φ(t) dt,
+
+        **not** the difference of n-th antiderivatives ``F_n(hi) − F_n(lo)``, which
+        omits the polynomial terms ``Σ_{j=1}^{n-1} F_j(lo)·Δ^{n−j}/(n−j)!``.
+
+        Evaluated by a *cancellation-free* series in the small-``|W·Δ|`` regime and by
+        the equivalent closed form otherwise.  Writing Δ = hi − lo, θ = W_dim·Δ and
+        Φ_k(Z) = sin(Z + kπ/2), the two branches are
+
+            θ small:  (I^n φ)(x) = Δ^n · Σ_{p≥0} θ^p/(n+p)! · Φ_p(Z_lo)
+            θ large:  (I^n φ)(x) = F_n(Z_hi) − Σ_{j=1}^{n} F_j(Z_lo)·Δ^{n−j}/(n−j)!,
+                      with F_j(Z) = Φ_{−j}(Z) / W_dim^j.
+
+        The series is the exact Taylor tail left over after that cancellation, so it is
+        finite and exact as ``W_dim → 0`` -- **no DC guard is applied or needed here**.
+        A near-DC feature is constant along ``dim`` and correctly integrates to
+        ``φ · Δ^n/n!``, matching the ``order=1`` sinc identity in
+        :meth:`definite_integral`.  (This is deliberately unlike :meth:`derivative`
+        with negative ``alpha``, whose standalone antiderivative genuinely diverges as
+        ``1/W`` and so is DC-guarded to zero.)
+
+        ``upper=None`` gives the running (Volterra) integral with variable upper limit
+        ``x[:, dim]``; a numeric ``upper`` pins it.  ``order=1`` reproduces
+        :meth:`definite_integral` to machine precision.
+        """
+        if order < 1:
+            raise ValueError("integration order must be a positive integer")
+        if x.dtype != self.W.dtype or x.device != self.W.device:
+            x = x.to(dtype=self.W.dtype, device=self.W.device)
+
+        n = int(order)
+        Wd = self.W[dim : dim + 1, :]  # (1, N)
+
+        x_lo = x.clone()
+        x_lo[:, dim] = lower
+        cache_lo = self.cache(x_lo)  # phases at the (common) lower limit
+
+        if upper is None:  # Volterra: upper limit is x_dim itself
+            cache_hi = cache if cache is not None else self.cache(x)
+            t_hi = x[:, dim : dim + 1]  # (M, 1)
+        else:
+            x_hi = x.clone()
+            x_hi[:, dim] = upper
+            cache_hi = self.cache(x_hi)
+            t_hi = torch.full(
+                (x.shape[0], 1), float(upper), device=self.W.device, dtype=self.W.dtype
+            )
+
+        delta = t_hi - float(lower)  # (M, 1)
+        theta = Wd * delta  # (M, N)
+        small = theta.abs() <= self._ITER_THETA_MAX
+
+        # 1/k! as plain floats: torch cannot divide a tensor by math.factorial's
+        # arbitrary-precision int, and float() keeps it to a single correct rounding.
+        inv_fact = [1.0 / float(math.factorial(k)) for k in range(n + self._ITER_TERMS)]
+
+        # --- Series branch: Δ^n Σ_p θ^p/(n+p)! Φ_p(Z_lo).  θ is zeroed outside the
+        # small-|θ| set so the powers cannot overflow (matters in float32).
+        th_s = torch.where(small, theta, torch.zeros_like(theta))
+        series = torch.zeros_like(theta)
+        th_pow = torch.ones_like(theta)  # θ^p
+        for p in range(self._ITER_TERMS):
+            series = series + (th_pow * inv_fact[n + p]) * cache_lo.phase(p)
+            th_pow = th_pow * th_s
+        series = series * (delta ** n)
+
+        # --- Closed branch: F_n(Z_hi) − Σ_j F_j(Z_lo) Δ^{n-j}/(n-j)!.  W is forced to
+        # 1 on the small-|θ| set so the unselected branch cannot produce inf/NaN (which
+        # would otherwise poison gradients through torch.where).
+        Wd_safe = torch.where(small, torch.ones_like(theta), Wd.expand_as(theta))
+        closed = cache_hi.phase(-n) / Wd_safe ** n
+        for j in range(1, n + 1):
+            closed = closed - (cache_lo.phase(-j) / Wd_safe ** j) * (
+                delta ** (n - j) * inv_fact[n - j]
+            )
+
+        return torch.where(small, series, closed) * self._inv_norm
+
     # ------------------------------------------------------------------
     # Convenience: 0th order (basis values)
     # ------------------------------------------------------------------
@@ -874,7 +983,14 @@ class IntegralOperator:
 
     ``apply(basis, x)`` returns an (M, N) design matrix: for Volterra, the running
     integral up to each ``x``; for a partial definite integral in d>1, the matrix
-    marginalised along ``dim`` (other coordinates held at ``x``).  Composes with
+    marginalised along ``dim`` (other coordinates held at ``x``).
+
+    ``order=n > 1`` is the n-fold **iterated** integral with every lower limit pinned
+    at ``lower`` -- ∫_lo^x ∫_lo^{s_1} … φ, equivalently the Cauchy form
+    ∫_lo^x (x−t)^{n−1}/(n−1)! φ(t) dt -- which is what a higher-order Volterra equation
+    applies.  It is *not* the difference of n-th antiderivatives F_n(hi) − F_n(lo);
+    see :meth:`SinusoidalBasis.iterated_integral`.  Near-DC features are exact and
+    finite at every order (no DC guard).  Composes with
     :class:`DiffOperator` via ``+ - *`` into an :class:`IntegroDifferentialOperator`,
     so an integro-differential / integral equation is one linear-least-squares block:
 
@@ -931,20 +1047,13 @@ class IntegralOperator:
             return basis.definite_integral(
                 x, self.dim, self.lower, upper=self.upper, cache=cache
             )
-        # order >= 2: difference of (DC-guarded) higher antiderivatives.
-        alpha = tuple(-self.order if k == self.dim else 0 for k in range(self.d))
-        F_lo = basis.derivative(self._shift(x, self.lower), alpha)
-        if self.upper is None:
-            F_hi = basis.derivative(x, alpha, cache=cache)
-        else:
-            F_hi = basis.derivative(self._shift(x, self.upper), alpha)
-        return F_hi - F_lo
-
-    def _shift(self, x: torch.Tensor, value: float) -> torch.Tensor:
-        """Copy of ``x`` with the integration axis pinned to ``value``."""
-        xs = x.clone()
-        xs[:, self.dim] = value
-        return xs
+        # order >= 2: the n-fold *iterated* (Cauchy) integral, all lower limits pinned
+        # at ``lower``.  Note this is NOT F_n(hi) − F_n(lo): that difference drops the
+        # polynomial terms Σ_{j<n} F_j(lo)·Δ^{n−j}/(n−j)!.  Like the order-1 branch it
+        # is exact and finite for near-DC features (no DC guard).
+        return basis.iterated_integral(
+            x, self.dim, self.lower, upper=self.upper, order=self.order, cache=cache
+        )
 
     # ------------------------------------------------------------------
     # Arithmetic composition -> IntegroDifferentialOperator

{fastlsq-0.4.1 → fastlsq-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "FastLSQ"
-version = "0.4.1"
+version = "0.4.2"
 description = "One-shot PDE solving via Fourier features with exact analytical derivatives; rank-revealing solvers, learnable anisotropic bandwidth, and CPU/CUDA/MPS support"
 readme = "README.md"
 license = "MIT"

{fastlsq-0.4.1 → fastlsq-0.4.2}/tests/test_integral.py

@@ -12,6 +12,11 @@ reciprocal prefactor.  These tests make that a *tested* property:
 * mixed integro-differential multi-indices match the analytic closed form and autodiff;
 * the DC guard keeps near-zero-frequency antiderivatives finite;
 * definite / running (Volterra) integrals agree with high-resolution quadrature;
+* higher-order (n-fold ITERATED) integrals agree with n-fold cumulative trapezoid and
+  with the Cauchy repeated-integration kernel -- and are *not* the naive difference of
+  n-th antiderivatives, which drops the polynomial terms;
+* near-DC features integrate to the exact ramp phi*Delta^n/n! at every order, rather
+  than being zeroed as the standalone (genuinely divergent) antiderivative is;
 * differential and integral terms compose into one (M, N) design matrix, through which
   gradients flow to learnable coefficients;
 * a Volterra integro-differential boundary-value problem is solved in one LSQ to <1e-5.
@@ -19,6 +24,8 @@ reciprocal prefactor.  These tests make that a *tested* property:
 Run with ``pytest`` or directly as a script.
 """
 
+import math
+
 import numpy as np
 import torch
 
@@ -126,6 +133,126 @@ def test_definite_matches_quadrature():
     assert (rows[0].squeeze() - exact).abs() < 1e-6
 
 
+def _iterated_trapz(fg, xs, n):
+    """n-fold cumulative trapezoid of ``fg`` on grid ``xs`` (all lower limits at xs[0])."""
+    cur = fg
+    for _ in range(n):
+        nxt = torch.zeros_like(cur)
+        nxt[1:] = torch.cumulative_trapezoid(cur, xs)
+        cur = nxt
+    return cur
+
+
+def test_iterated_volterra_matches_quadrature():
+    """order>=2 is the n-fold ITERATED (Volterra) integral, matching an n-fold cumulative
+    trapezoid.  Regression guard: the old code returned F_n(hi) - F_n(lo), which drops the
+    polynomial terms sum_j F_j(lo)*(x-lo)^(n-j)/(n-j)! and was ~380% off for n=2."""
+    torch.manual_seed(3)
+    basis = SinusoidalBasis.random(1, 32, sigma=3.0, normalize=False)
+    beta = torch.randn(32, 1)
+
+    xg = torch.linspace(0.0, 1.0, 20001).reshape(-1, 1)
+    xs = xg.squeeze()
+    fg = (basis.evaluate(xg) @ beta).squeeze()
+
+    for n in (1, 2, 3, 4):
+        ref = _iterated_trapz(fg, xs, n)
+        got = (IntegralOperator.volterra(dim=0, lower=0.0, d=1, order=n).apply(basis, xg)
+               @ beta).squeeze()
+        assert torch.isfinite(got).all()
+        rel = (torch.norm(got - ref) / torch.norm(ref)).item()
+        assert rel < 1e-6, f"order {n}: volterra vs {n}x-trapz rel-L2 = {rel:.2e}"
+
+
+def test_iterated_volterra_matches_cauchy_kernel():
+    """Independent reference: the n-fold iterated integral equals the SINGLE integral
+    int_lo^x (x-t)^(n-1)/(n-1)! phi(t) dt (Cauchy formula for repeated integration)."""
+    torch.manual_seed(11)
+    basis = SinusoidalBasis.random(1, 24, sigma=2.5, normalize=False)
+    beta = torch.randn(24, 1)
+
+    lo, x_eval = -0.4, 0.85
+    tg = torch.linspace(lo, x_eval, 40001)
+    fg = (basis.evaluate(tg.reshape(-1, 1)) @ beta).squeeze()
+
+    for n in (2, 3, 5):
+        kernel = (x_eval - tg) ** (n - 1) / float(math.factorial(n - 1))
+        ref = torch.trapz(kernel * fg, tg)
+        got = (IntegralOperator.volterra(dim=0, lower=lo, d=1, order=n)
+               .apply(basis, torch.tensor([[x_eval]])) @ beta).squeeze()
+        rel = ((got - ref).abs() / ref.abs()).item()
+        assert rel < 1e-6, f"order {n}: vs Cauchy kernel rel = {rel:.2e}"
+
+
+def test_iterated_definite_matches_quadrature():
+    """The order-n definite integral over [a, b] equals the n-fold running integral
+    evaluated at b, and is identical for every row in 1D."""
+    torch.manual_seed(4)
+    basis = SinusoidalBasis.random(1, 48, sigma=4.0, normalize=False)
+    beta = torch.randn(48, 1)
+
+    a, b = 0.2, 0.9
+    xg = torch.linspace(a, b, 20001).reshape(-1, 1)
+    fg = (basis.evaluate(xg) @ beta).squeeze()
+
+    for n in (2, 3):
+        ref = _iterated_trapz(fg, xg.squeeze(), n)[-1]
+        I = IntegralOperator.definite(dim=0, lower=a, upper=b, d=1, order=n)
+        rows = I.apply(basis, torch.rand(5, 1)) @ beta  # result independent of x in 1D
+        assert torch.allclose(rows, rows[:1].expand_as(rows), atol=1e-10)
+        rel = ((rows[0].squeeze() - ref).abs() / ref.abs()).item()
+        assert rel < 1e-6, f"order {n}: definite vs {n}x-trapz rel = {rel:.2e}"
+
+
+def test_iterated_order_one_matches_definite_integral():
+    """order=1 of the general iterated form reproduces the sinc closed form exactly, so the
+    two code paths in IntegralOperator.apply cannot drift apart."""
+    torch.manual_seed(12)
+    basis = SinusoidalBasis.random(2, 64, sigma=3.0, normalize=False)
+    x = sample_box(200, 2)
+    for dim, lo, hi in ((0, -0.4, None), (1, 0.1, 0.75)):
+        ref = basis.definite_integral(x, dim, lo, upper=hi)
+        got = basis.iterated_integral(x, dim, lo, upper=hi, order=1)
+        assert torch.allclose(got, ref, atol=1e-14, rtol=1e-11)
+
+
+def test_iterated_near_dc_is_exact_not_zeroed():
+    """Documented semantics: unlike the DC-guarded standalone antiderivative (whose 1/W
+    primitive genuinely diverges), the *limit-bearing* iterated integral of a near-DC
+    feature is finite and exact -- phi * Delta^n / n! -- and must NOT be zeroed.  This keeps
+    order>=2 consistent with the order=1 sinc path (cf. test_dc_guard_no_blowup)."""
+    W = torch.tensor([[0.0, 1e-13, 2.0]])
+    b = torch.tensor([[0.7, 0.7, 0.7]])
+    basis = SinusoidalBasis(W, b, normalize=False)
+
+    delta = 1.3
+    x = torch.tensor([[delta]])
+    for n in (1, 2, 3, 4):
+        got = basis.iterated_integral(x, 0, 0.0, order=n)[0]
+        assert torch.isfinite(got).all()
+        exact_dc = np.sin(0.7) * delta ** n / float(math.factorial(n))
+        # both the exactly-DC and the near-DC column hit the ramp value, not zero
+        assert abs(got[0].item() - exact_dc) < 1e-13, f"order {n}: DC col = {got[0].item()}"
+        assert abs(got[1].item() - exact_dc) < 1e-13
+        assert got[0].abs().item() > 1e-3  # explicitly: not zeroed
+
+
+def test_iterated_differs_from_antiderivative_difference():
+    """Pins the actual bug: for n=2 the correct value is F2(x)-F2(lo)-F1(lo)*(x-lo), so it
+    must differ from the naive difference F2(x)-F2(lo) by exactly that ramp term."""
+    torch.manual_seed(13)
+    basis = SinusoidalBasis.random(1, 16, sigma=2.0, normalize=False)
+    x = torch.linspace(0.1, 1.0, 9).reshape(-1, 1)
+    lo = 0.0
+
+    naive = basis.derivative(x, (-2,)) - basis.derivative(torch.full_like(x, lo), (-2,))
+    got = basis.iterated_integral(x, 0, lo, order=2)
+    ramp = basis.derivative(torch.full_like(x, lo), (-1,)) * (x - lo)
+
+    assert torch.allclose(got, naive - ramp, atol=1e-10, rtol=1e-8)
+    assert not torch.allclose(got, naive, atol=1e-6)  # the dropped term is not negligible
+
+
 def test_integro_differential_compose():
     """Differential + integral terms compose into one (M, N) matrix equal to the sum of parts."""
     torch.manual_seed(5)
@@ -189,6 +316,12 @@ if __name__ == "__main__":
     test_dc_guard_no_blowup()
     test_volterra_matches_quadrature()
     test_definite_matches_quadrature()
+    test_iterated_volterra_matches_quadrature()
+    test_iterated_volterra_matches_cauchy_kernel()
+    test_iterated_definite_matches_quadrature()
+    test_iterated_order_one_matches_definite_integral()
+    test_iterated_near_dc_is_exact_not_zeroed()
+    test_iterated_differs_from_antiderivative_difference()
     test_integro_differential_compose()
     test_learnable_coeff_grad_flows()
     test_volterra_ivp_forward_solve()