FastLSQ 0.2.6__tar.gz → 0.3.0__tar.gz

{fastlsq-0.2.6 → fastlsq-0.3.0}/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to FastLSQ will be documented in this file.
 
+## [0.3.0] - 2026-06-21
+
+### Added
+
+- **Exact closed-form integral & integro-differential operators.** The cyclic
+  derivative identity `D^α sin(W·x+b) = (∏ W^{α_k}) Φ_{|α| mod 4}` runs *backwards* --
+  integration is differentiation of *negative* order, `∫ sin(wx+b) dx = −(1/w)cos(wx+b)`.
+  `SinusoidalBasis.derivative` now accepts **signed** multi-indices (negative entries =
+  indefinite integration), with a DC guard (`dc_eps`) that zeros features whose frequency
+  along an integrated axis is ~0 (their primitive is a ramp that leaves the sinusoidal
+  family). `DiffOperator.antiderivative(dim, order, d)` exposes this as a factory, so
+  `Op.partial(0,1,1) - k*Op.antiderivative(0,1,1)` composes integro-differential operators.
+- **`IntegralOperator`** -- definite and running (Volterra) integrals with limits,
+  via the new `SinusoidalBasis.definite_integral`. Evaluated with a numerically stable
+  `sinc` identity (no `1/w` division), so the running integral of a near-DC feature is
+  exact rather than singular. Factories `IntegralOperator.volterra(...)` /
+  `IntegralOperator.definite(...)`.
+- **`IntegroDifferentialOperator`** -- the common roof under which differential and
+  integral terms compose (`+`, `−`, scalar/`nn.Parameter` `*`) into one `(M, N)`
+  linear-least-squares design matrix; coefficients stay differentiable so learnable
+  integral-term coefficients train through the solve. All three exported from `fastlsq`.
+- **Examples** `examples/integro_differential_demo.py` (one-shot forward solve of
+  `u'(x) + ∫_0^x u ds = f`, rel-L2 ~3e-11) and
+  `examples/inverse/inverse_memory_kernel.py` (recover an unknown memory strength λ from
+  noisy data via AdamW through the differentiable solve). New `tests/test_integral.py`
+  asserts ∫-then-∂ round-trips to identity, Volterra/definite match quadrature, the DC
+  guard stays finite, and gradients flow to learnable coefficients.
+
+## [0.2.6] - 2026-06-09
+
+### Changed
+
+- **Faster `_auto_solve` fallback for ill-conditioned systems.** When the
+  Cholesky path fails on CPU with no ridge (`mu = 0`), `_auto_solve` now goes
+  straight to the rank-deficient-safe SVD solve (LAPACK `gelsd`) instead of
+  first attempting Householder QR with the blow-up guard -- on CPU `gelsd` is
+  faster than QR, so the detour only added a full extra factorization. The
+  QR-then-SVD path is unchanged for ridge solves and non-CPU devices.
+
 ## [0.2.5] - 2026-06-04
 
 ### Fixed

{fastlsq-0.2.6 → fastlsq-0.3.0}/FastLSQ.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.2.6
+Version: 0.3.0
 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

{fastlsq-0.2.6 → fastlsq-0.3.0}/FastLSQ.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ examples/grid_rl_control.py
 examples/grid_swing.py
 examples/gs_inverse.py
 examples/gs_rl_control.py
+examples/integro_differential_demo.py
 examples/inverse_heat_source.py
 examples/inverse_magnetostatics.py
 examples/inverse_source_position.py
@@ -88,6 +89,7 @@ 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_turbulence.py
 examples/inverse/shape_ns.py
 examples/inverse/subsurface_imaging.py
@@ -135,6 +137,7 @@ tests/test_derivatives.py
 tests/test_device.py
 tests/test_grad_shafranov.py
 tests/test_grid_swing.py
+tests/test_integral.py
 tests/test_learnable.py
 tests/test_orbit_hill.py
 tests/test_vector_basis.py

{fastlsq-0.2.6 → fastlsq-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.2.6
+Version: 0.3.0
 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

fastlsq-0.3.0/examples/integro_differential_demo.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+# Copyright (c) 2026 Antonin Sulc
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""
+Integro-differential equation in one shot: exact closed-form *calculus* -> linear LSQ.
+
+FastLSQ solves PDEs by exploiting that every *derivative* of a sinusoidal feature is
+closed-form.  The same identity runs backwards -- integration is differentiation of
+negative order -- so *integral* terms are closed-form too.  Differential and integral
+terms then compose into a single linear-least-squares design matrix.
+
+Here we solve the Volterra integro-differential boundary-value problem
+
+        u'(x) + ∫_0^x u(s) ds = f(x),   u(0) = 0,   x in [0, L],
+
+whose exact solution is u*(x) = sin(w x), giving the (known) forcing
+
+        f(x) = w cos(w x) + (1 - cos(w x)) / w.
+
+The operator is assembled as one object,
+
+        L = Op.partial(0, 1, d=1) + IntegralOperator.volterra(dim=0, lower=0.0, d=1),
+
+stacked with the initial condition, and solved in a single ``solve_lstsq`` call -- no
+time stepping, no quadrature, no autodiff.  We then verify a global conservation
+identity ∫_0^L u with ``IntegralOperator.definite``.
+
+Usage:  python integro_differential_demo.py
+"""
+
+import numpy as np
+import torch
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+from fastlsq import SinusoidalBasis, Op, IntegralOperator, solve_lstsq
+from fastlsq.geometry import sample_box
+
+
+def main():
+    torch.set_default_dtype(torch.float64)
+    torch.manual_seed(0)
+
+    # ------------------------------------------------------------------
+    # Problem definition (analytic ground truth -> exact forcing)
+    # ------------------------------------------------------------------
+    w, L = 3.0, 1.0
+    u_star = lambda x: torch.sin(w * x)                                  # exact solution
+    f_rhs = lambda x: w * torch.cos(w * x) + (1.0 - torch.cos(w * x)) / w  # known forcing
+    u0 = 0.0                                                             # initial condition
+
+    # ------------------------------------------------------------------
+    # Basis + collocation
+    # ------------------------------------------------------------------
+    basis = SinusoidalBasis.random(input_dim=1, n_features=800, sigma=5.0, normalize=False)
+    x_col = sample_box(4000, 1) * L          # interior collocation points in [0, L]
+    x_ic = torch.zeros(1, 1)                  # x = 0 for the initial condition
+
+    # ------------------------------------------------------------------
+    # One unified integro-differential operator:  u'(x) + ∫_0^x u(s) ds
+    # ------------------------------------------------------------------
+    op = Op.partial(0, 1, d=1) + IntegralOperator.volterra(dim=0, lower=0.0, d=1)
+    print("Operator:", op)
+
+    # Assemble [PDE rows ; weighted IC row]  =  [f ; weighted u0]  and solve once.
+    W_IC = 100.0
+    A = torch.cat([op.apply(basis, x_col), W_IC * basis.evaluate(x_ic)])
+    b = torch.cat([f_rhs(x_col),           W_IC * torch.full((1, 1), u0)])
+    beta = solve_lstsq(A, b, mu=1e-10)
+
+    # ------------------------------------------------------------------
+    # Report accuracy on held-out points
+    # ------------------------------------------------------------------
+    x_test = sample_box(3000, 1) * L
+    u_pred = basis.evaluate(x_test) @ beta
+    u_true = u_star(x_test)
+    val_err = (torch.norm(u_pred - u_true) / (torch.norm(u_true) + 1e-15)).item()
+
+    # Global conservation identity:  ∫_0^L u  (closed form, single functional row)
+    int_num = float(IntegralOperator.definite(0, 0.0, L, d=1).apply(basis, x_test[:1]) @ beta)
+    int_exact = float((1.0 - np.cos(w * L)) / w)
+
+    print(f"  solution rel-L2 error      : {val_err:.2e}")
+    print(f"  ∫_0^L u  (closed form)     : {int_num:.6f}   exact {int_exact:.6f}")
+
+    # ------------------------------------------------------------------
+    # Plot:  solution vs exact, and pointwise residual
+    # ------------------------------------------------------------------
+    xs = torch.linspace(0, L, 400).reshape(-1, 1)
+    us = (basis.evaluate(xs) @ beta).squeeze().numpy()
+    ue = u_star(xs).squeeze().numpy()
+    xg = xs.squeeze().numpy()
+
+    fig, (ax0, ax1) = plt.subplots(1, 2, figsize=(11, 4))
+    ax0.plot(xg, ue, "k-", lw=2.5, label="exact  sin(w x)")
+    ax0.plot(xg, us, "C1--", lw=1.8, label="FastLSQ")
+    ax0.set_title("u'(x) + ∫₀ˣ u ds = f(x),  u(0)=0")
+    ax0.set_xlabel("x"); ax0.set_ylabel("u(x)"); ax0.legend()
+    ax1.semilogy(xg, np.abs(us - ue) + 1e-18, "C3-")
+    ax1.set_title(f"pointwise |error|   (rel-L2 = {val_err:.1e})")
+    ax1.set_xlabel("x"); ax1.set_ylabel("|u_pred - u*|")
+    plt.tight_layout()
+    out = "integro_differential_demo.pdf"
+    plt.savefig(out, dpi=150, bbox_inches="tight")
+    plt.close()
+    print(f"  -> Saved: {out}")
+
+
+if __name__ == "__main__":
+    main()

fastlsq-0.3.0/examples/inverse/inverse_memory_kernel.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+# Copyright (c) 2026 Antonin Sulc
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""
+Inverse problem: recover a memory-kernel strength from data through an INTEGRAL term.
+
+Many physical systems have *memory*: the rate of change depends not only on the present
+state but on its accumulated history.  A minimal model is the Volterra integro-differential
+equation
+
+        u'(x) + λ ∫_0^x u(s) ds = f(x),   u(0) = 0,
+
+where the scalar λ is the (unknown) memory / relaxation strength.  Given the known forcing
+f and noisy observations of u, we recover λ.
+
+This mirrors ``examples/learnable_helmholtz.py`` (learnable operator coefficient + AdamW),
+but the learnable coefficient now multiplies an ``IntegralOperator``: the operator is rebuilt
+each forward() as
+
+        L(λ) = Op.partial(0, 1, d=1) + λ · IntegralOperator.volterra(dim=0, lower=0.0, d=1),
+
+solved in one differentiable least-squares call, and gradients flow  loss -> u(λ) -> β ->
+lstsq -> A(λ) -> λ.  The inner solve uses Tikhonov regularisation + the SVD-based
+``gelsd`` driver (as in ``fastlsq/learnable.py``); a plain ``lstsq`` on the rank-deficient
+feature matrix yields an unreliable gradient.
+
+A closed-form / SINDy alternative (fit u, then linearly regress u' against [u, ∫u, ...] in one
+LSQ -- no optimiser) is shown in ``examples/inverse/denoising_parameter_estimation.py``.
+
+Usage:  python inverse_memory_kernel.py
+"""
+
+import numpy as np
+import torch
+import torch.nn as nn
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+from fastlsq import SinusoidalBasis, Op, IntegralOperator
+from fastlsq.geometry import sample_box
+
+
+class MemoryKernelInverse(nn.Module):
+    """Recover λ in  u'(x) + λ ∫_0^x u ds = f(x),  u(0)=0.
+
+    The operator is rebuilt each forward() so λ is always current.  The inner solve is
+    differentiable and rank-revealing (Tikhonov + gelsd), so AdamW can descend in λ.
+    """
+
+    def __init__(self, n_features: int = 600, sigma: float = 5.0, init_lam: float = 1.0,
+                 mu: float = 1e-8, rcond: float = 1e-12, w_ic: float = 100.0):
+        super().__init__()
+        self.basis = SinusoidalBasis.random(
+            input_dim=1, n_features=n_features, sigma=sigma, normalize=True
+        )
+        self.lam = nn.Parameter(torch.tensor(float(init_lam)))
+        self.mu, self.rcond, self.w_ic = mu, rcond, w_ic
+        self.beta: torch.Tensor | None = None
+
+    def solve(self, x_col, f_col, u0):
+        """Differentiable physics-constrained solve β(λ) for the current λ."""
+        op = Op.partial(0, 1, d=1) + self.lam * IntegralOperator.volterra(0, 0.0, d=1)
+        x_ic = torch.zeros(1, 1, dtype=x_col.dtype)
+        A = torch.cat([op.apply(self.basis, x_col), self.w_ic * self.basis.evaluate(x_ic)])
+        b = torch.cat([f_col, self.w_ic * torch.full((1, 1), float(u0))])
+        # Tikhonov-augmented, SVD-based solve -> stable gradient w.r.t. λ.
+        N = self.basis.n_features
+        A_aug = torch.cat([A, (self.mu ** 0.5) * torch.eye(N, dtype=A.dtype)])
+        b_aug = torch.cat([b, torch.zeros(N, 1, dtype=A.dtype)])
+        self.beta = torch.linalg.lstsq(A_aug, b_aug, rcond=self.rcond, driver="gelsd").solution
+        return self.beta
+
+    def predict(self, x):
+        return self.basis.evaluate(x) @ self.beta
+
+
+def main():
+    torch.set_default_dtype(torch.float64)
+    torch.manual_seed(0)
+
+    # ------------------------------------------------------------------
+    # Synthetic data: u* = sin(w x); forcing f encodes the TRUE memory λ*
+    # ------------------------------------------------------------------
+    w, L = 3.0, 1.0
+    lam_true = 5.0
+    u_star = lambda x: torch.sin(w * x)
+    f_rhs = lambda x: w * torch.cos(w * x) + lam_true * (1.0 - torch.cos(w * x)) / w
+    u0 = 0.0
+
+    x_col = sample_box(3000, 1) * L          # physics collocation points
+    f_col = f_rhs(x_col)                      # known forcing
+    x_obs = sample_box(300, 1) * L            # where u is observed
+    noise = 1e-3
+    u_obs = u_star(x_obs) + noise * torch.randn_like(x_obs)   # noisy observations
+
+    # ------------------------------------------------------------------
+    # Recover λ by gradient descent through the differentiable solve
+    # ------------------------------------------------------------------
+    model = MemoryKernelInverse(init_lam=1.0)
+    optimizer = torch.optim.AdamW(model.parameters(), lr=0.2)
+
+    print(f"Recovering memory strength λ  (true λ = {lam_true})")
+    print("-" * 52)
+    lam_hist, loss_hist = [], []
+    for step in range(150):
+        optimizer.zero_grad()
+        model.solve(x_col, f_col, u0)
+        loss = torch.mean((model.predict(x_obs) - u_obs) ** 2)
+        loss.backward()
+        torch.nn.utils.clip_grad_norm_(model.parameters(), 10.0)
+        optimizer.step()
+        lam_hist.append(model.lam.item()); loss_hist.append(loss.item())
+        if step % 25 == 0 or step == 149:
+            print(f"  step {step:3d}:  λ = {model.lam.item():.4f},  data-misfit = {loss.item():.2e}")
+
+    lam_hat = model.lam.item()
+    print("-" * 52)
+    print(f"  recovered λ = {lam_hat:.4f}   (true {lam_true},  |error| = {abs(lam_hat - lam_true):.2e})")
+    print(f"  noise floor ~ {noise:.0e};  recovery is within the noise level")
+
+    # ------------------------------------------------------------------
+    # Plots: λ convergence  &  fitted solution vs observations
+    # ------------------------------------------------------------------
+    with torch.no_grad():
+        xs = torch.linspace(0, L, 400).reshape(-1, 1)
+        us = model.predict(xs).squeeze().numpy()
+        ue = u_star(xs).squeeze().numpy()
+
+    fig, (ax0, ax1) = plt.subplots(1, 2, figsize=(11, 4))
+    ax0.axhline(lam_true, color="k", ls="--", lw=1.5, label=f"true λ = {lam_true}")
+    ax0.plot(lam_hist, "C0-", lw=1.8, label="AdamW iterate")
+    ax0.set_title("memory strength λ convergence")
+    ax0.set_xlabel("step"); ax0.set_ylabel("λ"); ax0.legend()
+
+    ax1.scatter(x_obs.squeeze().numpy(), u_obs.squeeze().numpy(), s=8, c="0.6",
+                label="noisy data", zorder=1)
+    ax1.plot(xs.squeeze().numpy(), ue, "k-", lw=2.2, label="true u*", zorder=2)
+    ax1.plot(xs.squeeze().numpy(), us, "C1--", lw=1.8, label="recovered u(λ̂)", zorder=3)
+    ax1.set_title(f"fit with recovered λ̂ = {lam_hat:.3f}")
+    ax1.set_xlabel("x"); ax1.set_ylabel("u(x)"); ax1.legend()
+    plt.tight_layout()
+    out = "inverse_memory_kernel.pdf"
+    plt.savefig(out, dpi=150, bbox_inches="tight")
+    plt.close()
+    print(f"  -> Saved: {out}")
+
+
+if __name__ == "__main__":
+    main()

{fastlsq-0.2.6 → fastlsq-0.3.0}/fastlsq/__init__.py

@@ -11,7 +11,15 @@ Reference:
 """
 
 from fastlsq.device import resolve_device, set_device, get_device, device_info
-from fastlsq.basis import SinusoidalBasis, BasisCache, DiffOperator, Op, FeatureBasis
+from fastlsq.basis import (
+    SinusoidalBasis,
+    BasisCache,
+    DiffOperator,
+    Op,
+    IntegralOperator,
+    IntegroDifferentialOperator,
+    FeatureBasis,
+)
 from fastlsq.solvers import FastLSQSolver, PIELMSolver
 from fastlsq.vector  import VectorBasis, VectorFastLSQSolver
 from fastlsq.linalg import solve_lstsq
@@ -44,7 +52,7 @@ from fastlsq.export import (
 )
 from fastlsq import viz
 
-__version__ = "0.2.5"
+__version__ = "0.3.0"
 __all__ = [
     # Device selection (CPU / CUDA / Apple-MPS, dtype-aware)
     "resolve_device",
@@ -56,6 +64,8 @@ __all__ = [
     "BasisCache",
     "DiffOperator",
     "Op",
+    "IntegralOperator",
+    "IntegroDifferentialOperator",
     "FeatureBasis",
     # Vector-valued basis  (0.1.5)
     "VectorBasis",