FastLSQ 0.4.0__tar.gz → 0.4.2__tar.gz

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

@@ -2,6 +2,71 @@
 
 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
+
+- **Solve-time diagnostics — `solve_lstsq(..., return_info=True)`.** Returns
+  `(x, info)` with `info = {t_solve, rank_used, residual, cond_estimate}`. `t_solve`
+  is the **device-synced wall-time of the solve step alone** (singular values for
+  the rank/cond diagnostics are computed *outside* the timed region), `rank_used` is
+  the rank-revealing effective numerical rank, and `cond_estimate` is `s_max/s_min`
+  over the retained subspace. The default `return_info=False` path is unchanged.
+- **Phased breakdown in `solve_linear` metrics.** `metrics` now reports
+  `scale_search_s`, `assemble_s`, `solve_s` (plus `rank_used`, `residual`,
+  `cond_estimate`) so the headline time is no longer dominated by the auto-scale
+  search — the reported solve time is a number the library hands you, not one a
+  benchmark reconstructs by hand.
+- **`fastlsq.benchmark.time_solve(fn, reps, warmup, device)`** — a device-correct
+  timing primitive (`synchronize` bracketing + warm-up + min-of-reps) returning the
+  reproducible solve-time *floor* in seconds (`return_all=True` for full stats). Also
+  exposes `fastlsq.benchmark.synchronize`.
+- **`SinusoidalBasis.random_covariance(d, N, Sigma=… | L=…)`** — fixed full-`Sigma`
+  constructor (`W = L @ W_hat`, `Sigma = L Lᵀ`), the symmetric counterpart to
+  `random` / `random_anisotropic`.
+- **`LearnableFastLSQ.freeze() -> SinusoidalBasis`** — freezes the learned bandwidth
+  into a plain, detached basis for one clean, timed one-shot deployment solve (the
+  `.basis` property still reconstructs-with-grad each access).
+- **Checkpoint provenance.** `save_checkpoint` auto-records a `provenance` block
+  (library version, device, dtype, timestamp, and the realized scale / `Sigma`) into
+  the metadata.
+
 ## [0.4.0] - 2026-06-22
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.4.0
+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.0 → 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,25 +76,10 @@ 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
+fastlsq/benchmark.py
 fastlsq/block.py
 fastlsq/device.py
 fastlsq/diagnostics.py
@@ -125,21 +99,12 @@ 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
 tests/test_derivatives.py
 tests/test_device.py
+tests/test_diagnostics_timing.py
 tests/test_grad_shafranov.py
 tests/test_grid_swing.py
 tests/test_integral.py

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.4.0
+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.0 → 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.0 → fastlsq-0.4.2}/fastlsq/__init__.py

@@ -53,8 +53,9 @@ from fastlsq.export import (
     load_checkpoint,
 )
 from fastlsq import viz
+from fastlsq import benchmark
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 __all__ = [
     # Device selection (CPU / CUDA / Apple-MPS, dtype-aware)
     "resolve_device",

{fastlsq-0.4.0 → fastlsq-0.4.2}/fastlsq/api.py

@@ -105,16 +105,20 @@ def solve_linear(
     if n_bc is None:
         n_bc = max(800, n_pde // 5)
 
-    # Auto-select scale if needed
+    # Auto-select scale if needed (timed as its own phase: it is a search that can
+    # be amortised / skipped at deployment, so it must not inflate the solve time).
+    scale_search_s = 0.0
     if scale is None and auto_scale:
         if verbose:
             print("Auto-selecting optimal scale...")
+        t_phase = time.perf_counter()
         scale = auto_select_scale(
             problem, solver_class=FastLSQSolver,
             n_blocks=n_blocks, hidden_size=hidden_size,
             n_pde=n_pde, n_bc=n_bc, n_trials=auto_scale_trials,
             verbose=verbose,
         )
+        scale_search_s = time.perf_counter() - t_phase
         if verbose:
             print(f"Selected scale: {scale:.3f}")
 
@@ -137,10 +141,25 @@ def solve_linear(
         x_pde, bcs = data
         build_args = (bcs,)
 
-    # Assemble and solve
+    # Assemble (timed phase)
+    t_phase = time.perf_counter()
     A, b = problem.build(solver, x_pde, *build_args)
-    beta_raw = solve_lstsq(A, b, mu=mu, method=method)
+    assemble_s = time.perf_counter() - t_phase
+
+    # Solve (timed phase).  With metrics on, ``solve_lstsq`` hands back the
+    # device-synced solve time plus rank/residual/cond diagnostics directly; with
+    # metrics off, keep the plain fast solve and just time it externally.
     n_outputs = getattr(problem, "n_outputs", 1)
+    if return_metrics:
+        beta_raw, solve_info = solve_lstsq(
+            A, b, mu=mu, method=method, return_info=True
+        )
+        solve_s = solve_info["t_solve"]
+    else:
+        t_phase = time.perf_counter()
+        beta_raw = solve_lstsq(A, b, mu=mu, method=method)
+        solve_s = time.perf_counter() - t_phase
+        solve_info = None
     solver.beta = unpack_beta(beta_raw, solver.n_features, n_outputs)
 
     runtime = time.time() - t0
@@ -169,6 +188,15 @@ def solve_linear(
             "val_err": val_err,
             "grad_err": grad_err,
             "runtime": runtime,
+            # Phased breakdown: the conflated ``runtime`` split into its parts so
+            # the headline solve time is no longer dominated by the scale search.
+            "scale_search_s": scale_search_s,
+            "assemble_s": assemble_s,
+            "solve_s": solve_s,
+            # Rank-revealing solve diagnostics (the paper's central mechanism).
+            "rank_used": solve_info["rank_used"],
+            "residual": solve_info["residual"],
+            "cond_estimate": solve_info["cond_estimate"],
         }
         if verbose:
             print(f"Value error: {val_err:.2e}, Gradient error: {grad_err:.2e}")

{fastlsq-0.4.0 → 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,
@@ -197,6 +213,43 @@ class SinusoidalBasis:
         b = torch.rand(1, n_features, device=get_device()) * 2 * np.pi
         return cls(W, b, normalize=normalize, dc_eps=dc_eps)
 
+    @classmethod
+    def random_covariance(
+        cls,
+        input_dim: int,
+        n_features: int,
+        Sigma: Optional[Union[list, np.ndarray, torch.Tensor]] = None,
+        L: Optional[Union[list, np.ndarray, torch.Tensor]] = None,
+        normalize: bool = True,
+        dc_eps: float = 1e-8,
+    ) -> SinusoidalBasis:
+        """Create a basis with full-covariance Gaussian frequencies.
+
+        Frequencies are drawn ``W[:, j] ~ N(0, Sigma)`` via ``W = L @ W_hat`` with
+        ``W_hat ~ N(0, I_d)`` and ``Sigma = L L^T``.  Provide **exactly one** of
+        ``Sigma`` (the ``d x d`` covariance) or its lower-triangular Cholesky factor
+        ``L``.  This is the fixed full-``Sigma`` analogue of :meth:`random`
+        (isotropic) and :meth:`random_anisotropic` (axis-aligned), and uses the same
+        ``W = L @ W_hat`` reparameterisation as
+        :class:`~fastlsq.learnable.LearnableFastLSQ` -- so a swept covariance no
+        longer needs a hand-rolled ``chol(Sigma) @ randn``.
+        """
+        if (Sigma is None) == (L is None):
+            raise ValueError(
+                "random_covariance: provide exactly one of Sigma or L."
+            )
+        dev = get_device()
+        dt = torch.get_default_dtype()
+        if L is None:
+            Sigma_t = torch.as_tensor(Sigma, device=dev, dtype=dt)
+            L_t = torch.linalg.cholesky(Sigma_t)
+        else:
+            L_t = torch.as_tensor(L, device=dev, dtype=dt)
+        W_hat = torch.randn(input_dim, n_features, device=dev, dtype=L_t.dtype)
+        W = L_t @ W_hat
+        b = torch.rand(1, n_features, device=dev, dtype=L_t.dtype) * 2 * np.pi
+        return cls(W, b, normalize=normalize, dc_eps=dc_eps)
+
     # ------------------------------------------------------------------
     # Caching
     # ------------------------------------------------------------------
@@ -321,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)
     # ------------------------------------------------------------------
@@ -837,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:
 
@@ -894,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.2/fastlsq/benchmark.py

@@ -0,0 +1,100 @@
+# Copyright (c) 2026 Antonin Sulc
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""Device-correct timing primitives for FastLSQ.
+
+Naively wall-clock-timing a CUDA solve is wrong: kernels are launched
+asynchronously, so ``t1 - t0`` measures launch overhead, not compute.  Without a
+``synchronize`` bracket every GPU number is meaningless (and irreproducible).
+:func:`time_solve` adds the missing primitive -- ``synchronize`` bracketing plus
+warm-up and a min-of-reps reduction -- so the reported solve time is the
+reproducible compute *floor* on any device (CPU / CUDA / Apple-MPS).
+
+    import fastlsq as fl
+    t = fl.benchmark.time_solve(lambda: fl.solve_lstsq(A, b))   # seconds, floor
+"""
+
+import time
+
+import torch
+
+from fastlsq.device import get_device
+
+
+def synchronize(device=None):
+    """Block until all queued work on ``device`` has finished.
+
+    No-op on CPU; calls ``torch.cuda.synchronize`` on CUDA and
+    ``torch.mps.synchronize`` on Apple-MPS (when available).  ``device=None``
+    uses the active FastLSQ device.
+    """
+    device = get_device() if device is None else torch.device(device)
+    if device.type == "cuda":
+        torch.cuda.synchronize(device)
+    elif device.type == "mps":
+        sync = getattr(getattr(torch, "mps", None), "synchronize", None)
+        if sync is not None:
+            sync()
+
+
+def time_solve(fn, reps=10, warmup=2, device=None, return_all=False):
+    """Device-correct timing floor for a callable.
+
+    Runs ``warmup`` unmeasured calls (allocator / autotune warm-up), then ``reps``
+    measured calls, each bracketed by :func:`synchronize` so CUDA/MPS asynchronous
+    execution is fully accounted for.  Returns the **minimum** elapsed time in
+    seconds -- the reproducible solve-time floor -- which is the right summary for
+    a deterministic op whose variance is pure system noise.
+
+    Parameters
+    ----------
+    fn : callable
+        Zero-argument callable performing the work to time, e.g.
+        ``lambda: solve_lstsq(A, b)``.
+    reps : int
+        Number of measured repetitions (>= 1).
+    warmup : int
+        Number of unmeasured warm-up repetitions.
+    device : str | torch.device | None
+        Device to synchronize around each call.  ``None`` uses the active FastLSQ
+        device.
+    return_all : bool
+        If True, return a stats dict
+        ``{"min", "median", "mean", "std", "times", "reps", "warmup", "device"}``
+        instead of the bare floor.
+
+    Returns
+    -------
+    float
+        The minimum solve time in seconds (``return_all=False``).
+    dict
+        Full timing statistics (``return_all=True``).
+    """
+    device = get_device() if device is None else torch.device(device)
+
+    for _ in range(max(0, warmup)):
+        fn()
+    synchronize(device)
+
+    times = []
+    for _ in range(max(1, reps)):
+        synchronize(device)
+        t0 = time.perf_counter()
+        fn()
+        synchronize(device)
+        times.append(time.perf_counter() - t0)
+
+    t = torch.tensor(times, dtype=torch.float64)
+    floor = float(t.min())
+    if not return_all:
+        return floor
+    return {
+        "min": floor,
+        "median": float(t.median()),
+        "mean": float(t.mean()),
+        "std": float(t.std(unbiased=False)),
+        "times": times,
+        "reps": len(times),
+        "warmup": max(0, warmup),
+        "device": str(device),
+    }

{fastlsq-0.4.0 → fastlsq-0.4.2}/fastlsq/export.py

@@ -3,6 +3,8 @@
 
 """Export utilities for FastLSQ solutions (NumPy, VTK, etc.)."""
 
+import time
+
 import torch
 import numpy as np
 from typing import Optional, Union, Dict, Any
@@ -10,6 +12,32 @@ from typing import Optional, Union, Dict, Any
 from fastlsq.solvers import FastLSQSolver
 
 
+def _provenance(solver: FastLSQSolver) -> Dict[str, Any]:
+    """Auto-recorded provenance for a saved model: library version, device, dtype,
+    and the realized frequency bandwidth (scale / Sigma) the model actually uses."""
+    import fastlsq  # lazy: avoids a circular import at module load
+
+    prov: Dict[str, Any] = {
+        "fastlsq_version": getattr(fastlsq, "__version__", None),
+        "created": time.time(),
+        "input_dim": solver.input_dim,
+        "n_features": solver.n_features,
+    }
+    W = torch.cat(solver.W_list, dim=1) if solver.W_list else None
+    ref = W if W is not None else solver.beta
+    if ref is not None:
+        prov["device"] = str(ref.device)
+        prov["dtype"] = str(ref.dtype).replace("torch.", "")
+    if W is not None:
+        # Realized frequency second moment Sigma = (W Wᵀ)/N and per-axis scale.
+        freq_cov = (W @ W.transpose(-2, -1)) / W.shape[1]
+        prov["freq_cov"] = freq_cov.cpu().numpy()
+        prov["freq_std"] = torch.sqrt(
+            torch.diagonal(freq_cov).clamp_min(0.0)
+        ).cpu().numpy()
+    return prov
+
+
 def to_numpy(
     solver: FastLSQSolver,
     x: Union[torch.Tensor, np.ndarray],
@@ -138,11 +166,14 @@ def save_checkpoint(
     path : str
         File path (.pt or .pth extension recommended).
     metadata : dict, optional
-        Additional metadata to save.
+        Additional metadata to save.  A ``provenance`` block (library version,
+        device, dtype, timestamp, and realized scale / Sigma) is auto-recorded
+        unless the caller supplies its own ``provenance`` key.
     """
     state = to_dict(solver, include_weights=True, include_metadata=True)
-    if metadata:
-        state["metadata"] = metadata
+    meta = dict(metadata) if metadata else {}
+    meta.setdefault("provenance", _provenance(solver))
+    state["metadata"] = meta
     torch.save(state, path)
 
 

{fastlsq-0.4.0 → fastlsq-0.4.2}/fastlsq/learnable.py

@@ -153,6 +153,20 @@ class LearnableFastLSQ(nn.Module):
         """
         return SinusoidalBasis(self._W(), self.b, normalize=self._normalize)
 
+    def freeze(self) -> SinusoidalBasis:
+        """Freeze the learned bandwidth into a plain, detached ``SinusoidalBasis``.
+
+        Unlike the :attr:`basis` property -- which reconstructs *with grad* on every
+        access -- this returns a fixed basis built from the current
+        ``W = L @ W_hat`` with the weights detached and cloned.  Run the (untimed)
+        bandwidth search, then ``freeze()`` the learned ``Sigma`` into this plain
+        basis for one clean, timed one-shot solve: the deployment artifact.
+        """
+        with torch.no_grad():
+            W = self._W().detach().clone()
+            b = self.b.detach().clone()
+        return SinusoidalBasis(W, b, normalize=self._normalize)
+
     # ------------------------------------------------------------------
     # Prediction
     # ------------------------------------------------------------------