FastLSQ 0.6.1__tar.gz → 0.6.2__tar.gz

{fastlsq-0.6.1 → fastlsq-0.6.2}/CHANGELOG.md

@@ -25,6 +25,23 @@ Three tags are **approximate**, and their tag messages say so:
 All three were released from a working tree holding source that was never committed.
 For those versions the sdist on PyPI is the record, not the tag.
 
+### Zenodo archives
+
+Every tag is archived on Zenodo under concept DOI
+[10.5281/zenodo.22830737](https://doi.org/10.5281/zenodo.22830737).
+
+Two things about that archive are worth knowing, because neither is obvious:
+
+- **Zenodo reads `.zenodo.json` from the tagged commit's tree, not from `main`.**
+  No tag before 0.6.2 contained the file, so every archived version up to and
+  including 0.6.1 carries GitHub's auto-generated metadata -- the title
+  `sulcantonin/FastLSQ: FastLSQ <version>`, no ORCID, no affiliation, no keywords
+  and no link to the preprint.
+- **Zenodo's "latest version" is the one published last, not the highest version
+  number.** The twenty releases were archived in parallel and finished out of
+  order, so the concept DOI resolved to 0.2.6 for a while. Cutting a new release is
+  what corrects it.
+
 ### Versions documented here that were never released
 
 - **0.2.0** (dated 2026-03-01 below) was never on PyPI and `pyproject.toml` never
@@ -43,6 +60,65 @@ this file jumps 0.1.0 → 0.2.0 → 0.1.5 and does not describe them. Reconstruc
 changelog entries a year after the fact would be invention rather than record, so the
 gap is documented here instead of filled in.
 
+## [0.6.2] - 2026-09-18
+
+Packaging, citation and repository metadata. **No change to `fastlsq/`** -- the
+importable library is byte-identical to 0.6.1, and the wheel is unchanged. The
+sdist gains one example and its test.
+
+### Added
+
+- **`examples/stealth_navigation.py`** -- a FastLSQ world model refit inside a
+  control loop. A drone crosses a radar interference field sensing only a
+  five-point cross at its own position; every three steps it refits a surrogate
+  over everything sensed so far (one Tikhonov least-squares solve, 6.1 ms median)
+  and steers on that surrogate's *analytic* gradient. The ablation is the
+  argument: with the gradient term off, driving straight at the goal trips the
+  detector at step 133 of an otherwise 275-step crossing.
+
+  `tests/test_stealth_navigation.py` checks the analytic gradient against finite
+  differences and asserts the ablation in both directions.
+
+  The project website quoted figures for this demo, but no script in the
+  repository produced them. Now the numbers are output rather than assertion.
+
+- **Citation and archive metadata.** `CITATION.cff` drives GitHub's *Cite this
+  repository* widget, with `preferred-citation` pointing at the paper.
+  `.zenodo.json` describes the Zenodo deposit -- title, abstract, ORCID,
+  affiliation, keywords, and related identifiers for the preprint, the repository
+  and PyPI.
+
+  Zenodo reads `.zenodo.json` from the **tagged commit's tree**, and no earlier tag
+  contained it, so every archived version up to 0.6.1 carries GitHub's
+  auto-generated metadata instead. This is the first tag that fixes that.
+
+- **`scripts/add_zenodo_doi.py`** writes a Zenodo concept DOI into `README.md`,
+  `CITATION.cff` and `.zenodo.json` consistently; idempotent, with a `--check` mode.
+- **`scripts/sync_release_notes.py`** flattens Markdown tables in GitHub Release
+  bodies. Zenodo turns a release body into the archived record's description and
+  its converter does not understand tables, so a table arrives as one unreadable
+  run of pipes -- the first thing anyone following the DOI sees. `CHANGELOG.md`
+  keeps its tables, which GitHub renders correctly.
+- **`docs/RELEASING.md`** -- the release procedure, the Zenodo behaviour worth
+  knowing in advance, and when JOSS actually requires a DOI (at acceptance, not at
+  submission).
+
+### Changed
+
+- The Zenodo concept DOI [10.5281/zenodo.22830737](https://doi.org/10.5281/zenodo.22830737)
+  is recorded in the README badge and citation section, and in `CITATION.cff`.
+- `pyproject.toml` `Homepage` is now <https://fastlsq.com>; `Repository` still
+  points at GitHub, so PyPI shows both. The 0.6.1 upload predated this and shows
+  the repository as its homepage.
+- The 0.6.0 feature table's third column is headed "Benefit".
+
+### Removed
+
+- **The website.** `site/` and its GitHub Pages workflow are gone: this repository
+  is the Python package, and the site is maintained separately at
+  <https://fastlsq.com>. The old copy remains recoverable from history
+  (`git checkout 8392f6e -- site/`).
+
 ## [0.6.1] - 2026-09-18
 
 A correctness and packaging pass. No published number changes, and no API is
@@ -159,7 +235,7 @@ Fredholm equations, with the integral-equation problems promoted into the same
 
 ### New features
 
-| Feature | API | What it buys |
+| Feature | API | Benefit |
 |---|---|---|
 | Multi-axis integrals | `MultiIntegralOperator`, `SinusoidalBasis.multi_integral` | Integrate over any subset of axes at once, each independently definite or Volterra — area/volume functionals and mixed "definite in space, running in time" memory terms that a single-axis operator cannot express |
 | Separable (degenerate) kernels | `SeparableKernelOperator` | `K(x,y) = Σ g_m(x) h_m(y)` assembles as a rank-`R` product `G @ C`; the inner products `C` are computed once, independent of the collocation points |

fastlsq-0.6.2/CITATION.cff

@@ -0,0 +1,53 @@
+cff-version: 1.2.0
+title: "FastLSQ: One-shot PDE solving via Fourier features with exact analytical derivatives"
+message: >-
+  If you use this software, please cite the paper below. If you need to cite a
+  specific archived version of the code, use the Zenodo DOI for that version.
+type: software
+authors:
+  - family-names: Sulc
+    given-names: Antonin
+    orcid: "https://orcid.org/0000-0001-7767-778X"
+    affiliation: "Lawrence Berkeley National Laboratory, Berkeley, CA, United States"
+repository-code: "https://github.com/sulcantonin/FastLSQ"
+url: "https://fastlsq.com"
+repository-artifact: "https://pypi.org/project/FastLSQ/"
+abstract: >-
+  FastLSQ solves linear partial differential, integral and integro-differential
+  equations in a single least-squares call, by expanding the unknown in a basis of
+  random Fourier features whose derivatives and integrals are available in closed
+  form. Because every feature is a plane wave, a linear operator maps the basis to
+  another explicit matrix: no mesh, no automatic differentiation, no iterative
+  training. The closed-form derivatives make the fitted field a differentiable
+  surrogate whose operator factors once, so inverse problems and control loops can
+  afford thousands of forward solves.
+keywords:
+  - partial differential equations
+  - integral equations
+  - inverse problems
+  - Fourier features
+  - least squares
+  - closed-form derivatives
+  - differentiable surrogate
+  - scientific machine learning
+  - PyTorch
+license: MIT
+version: 0.6.2
+date-released: "2026-09-18"
+
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.22830737
+    description: Concept DOI — resolves to the latest archived version
+
+preferred-citation:
+  type: article
+  title: "FastLSQ: Solving PDEs in One Shot via Fourier Features with Exact Analytical Derivatives"
+  authors:
+    - family-names: Sulc
+      given-names: Antonin
+      orcid: "https://orcid.org/0000-0001-7767-778X"
+  year: 2026
+  doi: "10.48550/arXiv.2602.10541"
+  url: "https://arxiv.org/abs/2602.10541"
+  journal: "arXiv preprint arXiv:2602.10541"

{fastlsq-0.6.1 → fastlsq-0.6.2}/FastLSQ.egg-info/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.6.1
+Version: 0.6.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
-Project-URL: Homepage, https://github.com/sulcantonin/FastLSQ
+Project-URL: Homepage, https://fastlsq.com
 Project-URL: Repository, https://github.com/sulcantonin/FastLSQ
 Project-URL: Paper, https://arxiv.org/abs/2602.10541
 Project-URL: Bug Tracker, https://github.com/sulcantonin/FastLSQ/issues
@@ -47,6 +47,8 @@ Dynamic: license-file
 [![Python](https://img.shields.io/pypi/pyversions/FastLSQ.svg)](https://pypi.org/project/FastLSQ/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![arXiv](https://img.shields.io/badge/arXiv-2602.10541-b31b1b.svg)](https://arxiv.org/abs/2602.10541)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22830737.svg)](https://doi.org/10.5281/zenodo.22830737)
+[![site](https://img.shields.io/badge/site-fastlsq.com-1f3df5.svg)](https://fastlsq.com)
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/sulcantonin/FastLSQ/main/misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="400"/>
@@ -559,7 +561,7 @@ message.  See the *Release tags* note at the top of `CHANGELOG.md`.
 
 ## Paper
 
-The preprint is on [arXiv](https://arxiv.org/abs/2602.10541).  A software paper for the
+The project site, with interactive demos, is at [fastlsq.com](https://fastlsq.com). The preprint is on [arXiv](https://arxiv.org/abs/2602.10541).  A software paper for the
 [Journal of Open Source Software](https://joss.theoj.org/) is drafted in
 [`paper.md`](paper.md).
 
@@ -583,6 +585,8 @@ If you use FastLSQ in your research, please cite:
 }
 ```
 
+To cite a specific archived version of the code rather than the paper, use the Zenodo concept DOI [10.5281/zenodo.22830737](https://doi.org/10.5281/zenodo.22830737), which always resolves to the most recent release.
+
 ## License
 
 This project is licensed under the MIT License -- see [LICENSE](LICENSE) for details.

{fastlsq-0.6.1 → fastlsq-0.6.2}/FastLSQ.egg-info/SOURCES.txt

@@ -1,4 +1,5 @@
 CHANGELOG.md
+CITATION.cff
 LICENSE
 MANIFEST.in
 README.md
@@ -34,6 +35,7 @@ examples/run_all_extensions.py
 examples/run_linear.py
 examples/run_nonlinear.py
 examples/sdf_domains.py
+examples/stealth_navigation.py
 examples/tutorial_basic.py
 examples/tutorial_nonlinear.py
 examples/vector_basis_stream_vorticity.py
@@ -123,5 +125,6 @@ tests/test_multi_integral.py
 tests/test_orbit_hill.py
 tests/test_problems_integral.py
 tests/test_projection.py
+tests/test_stealth_navigation.py
 tests/test_symbol.py
 tests/test_vector_basis.py

{fastlsq-0.6.1 → fastlsq-0.6.2}/MANIFEST.in

@@ -1,6 +1,7 @@
 include LICENSE
 include README.md
 include CHANGELOG.md
+include CITATION.cff
 include requirements.txt
 include fastlsq/py.typed
 recursive-include examples *.py

{fastlsq-0.6.1 → fastlsq-0.6.2}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.6.1
+Version: 0.6.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
-Project-URL: Homepage, https://github.com/sulcantonin/FastLSQ
+Project-URL: Homepage, https://fastlsq.com
 Project-URL: Repository, https://github.com/sulcantonin/FastLSQ
 Project-URL: Paper, https://arxiv.org/abs/2602.10541
 Project-URL: Bug Tracker, https://github.com/sulcantonin/FastLSQ/issues
@@ -47,6 +47,8 @@ Dynamic: license-file
 [![Python](https://img.shields.io/pypi/pyversions/FastLSQ.svg)](https://pypi.org/project/FastLSQ/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![arXiv](https://img.shields.io/badge/arXiv-2602.10541-b31b1b.svg)](https://arxiv.org/abs/2602.10541)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22830737.svg)](https://doi.org/10.5281/zenodo.22830737)
+[![site](https://img.shields.io/badge/site-fastlsq.com-1f3df5.svg)](https://fastlsq.com)
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/sulcantonin/FastLSQ/main/misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="400"/>
@@ -559,7 +561,7 @@ message.  See the *Release tags* note at the top of `CHANGELOG.md`.
 
 ## Paper
 
-The preprint is on [arXiv](https://arxiv.org/abs/2602.10541).  A software paper for the
+The project site, with interactive demos, is at [fastlsq.com](https://fastlsq.com). The preprint is on [arXiv](https://arxiv.org/abs/2602.10541).  A software paper for the
 [Journal of Open Source Software](https://joss.theoj.org/) is drafted in
 [`paper.md`](paper.md).
 
@@ -583,6 +585,8 @@ If you use FastLSQ in your research, please cite:
 }
 ```
 
+To cite a specific archived version of the code rather than the paper, use the Zenodo concept DOI [10.5281/zenodo.22830737](https://doi.org/10.5281/zenodo.22830737), which always resolves to the most recent release.
+
 ## License
 
 This project is licensed under the MIT License -- see [LICENSE](LICENSE) for details.

{fastlsq-0.6.1 → fastlsq-0.6.2}/README.md

@@ -5,6 +5,8 @@
 [![Python](https://img.shields.io/pypi/pyversions/FastLSQ.svg)](https://pypi.org/project/FastLSQ/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![arXiv](https://img.shields.io/badge/arXiv-2602.10541-b31b1b.svg)](https://arxiv.org/abs/2602.10541)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22830737.svg)](https://doi.org/10.5281/zenodo.22830737)
+[![site](https://img.shields.io/badge/site-fastlsq.com-1f3df5.svg)](https://fastlsq.com)
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/sulcantonin/FastLSQ/main/misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="400"/>
@@ -517,7 +519,7 @@ message.  See the *Release tags* note at the top of `CHANGELOG.md`.
 
 ## Paper
 
-The preprint is on [arXiv](https://arxiv.org/abs/2602.10541).  A software paper for the
+The project site, with interactive demos, is at [fastlsq.com](https://fastlsq.com). The preprint is on [arXiv](https://arxiv.org/abs/2602.10541).  A software paper for the
 [Journal of Open Source Software](https://joss.theoj.org/) is drafted in
 [`paper.md`](paper.md).
 
@@ -541,6 +543,8 @@ If you use FastLSQ in your research, please cite:
 }
 ```
 
+To cite a specific archived version of the code rather than the paper, use the Zenodo concept DOI [10.5281/zenodo.22830737](https://doi.org/10.5281/zenodo.22830737), which always resolves to the most recent release.
+
 ## License
 
 This project is licensed under the MIT License -- see [LICENSE](LICENSE) for details.

fastlsq-0.6.2/examples/stealth_navigation.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python
+# Copyright (c) 2026 Antonin Sulc
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""
+Stealth navigation: a FastLSQ world model refit inside a control loop.
+
+A drone crosses a radar interference field corner to corner.  It must reach the
+goal without the intensity it senses ever tripping a detector, and it has no map
+-- only a small cross of field samples around its current position, streaming in
+as it moves.
+
+    radar field      u(x, y) = sum_k sin(kappa r_k) / (r_k + eps)
+    detector         trips when  u^2 > TAU
+    sensing          5-point cross at the drone's position, every step
+    world model      beta = (H^T H + mu I)^-1 H^T u   refit every REFIT_EVERY steps
+    control          descend  w_goal * ||x - goal||^2 + w_stealth * u_hat(x)^2
+                     using the surrogate's ANALYTIC gradient
+
+The point of the demo is the third and fourth lines.  The surrogate is a
+`SinusoidalBasis`, so once beta is fit, grad u_hat is a closed-form expression --
+no finite differences, no autodiff graph, no re-solve.  Refitting is a single
+Tikhonov least-squares solve over the samples gathered so far, cheap enough to
+run hundreds of times per episode.
+
+The world model is trustworthy only where the drone has actually sensed, which is
+why the controller weights the stealth term by a confidence that decays with
+distance to the nearest sample.
+
+Run:
+    python examples/stealth_navigation.py
+    python examples/stealth_navigation.py --plot      # writes a PNG
+"""
+
+import argparse
+import os
+import sys
+import time
+
+import numpy as np
+import torch
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from fastlsq.basis import SinusoidalBasis  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+SEED = 0
+
+# Radar field
+N_EMITTERS = 5
+KAPPA = 34.0               # wavenumber -- sets the fringe spacing
+EPS = 0.06                 # softening, keeps the field finite at an emitter
+# Detector threshold on u^2.  Calibrated against the field: u^2 reaches 236 over
+# the domain and the straight start->goal line peaks at 79, so a threshold of 60
+# means the direct route WOULD be detected and the drone has to find a corridor.
+TAU = 60.0
+
+# Surrogate
+N_FEAT = 1000
+SIGMAS = (6.0, 14.0)       # two bandwidth blocks, N_FEAT split evenly
+MU_REG = 1e-6              # Tikhonov ridge
+REFIT_EVERY = 3
+
+# Sensing
+CROSS_H = 0.018            # arm length of the 5-point sensing cross
+
+# Control
+START = np.array([0.06, 0.06])
+GOAL = np.array([0.94, 0.94])
+STEP = 0.0045              # metres per step (domain is the unit square)
+MAX_STEPS = 1200
+GOAL_TOL = 0.03
+W_GOAL = 1.0
+W_STEALTH = 0.85
+CONF_LEN = 0.10            # confidence decay length for the surrogate
+
+
+# ---------------------------------------------------------------------------
+# Ground-truth radar field (the drone never sees this, only point samples)
+# ---------------------------------------------------------------------------
+def make_emitters(rng):
+    """Emitters placed away from the start/goal diagonal, so the corridor is
+    genuinely non-trivial but a stealthy path exists."""
+    return np.array([
+        [0.50, 0.18],
+        [0.22, 0.58],
+        [0.78, 0.44],
+        [0.55, 0.82],
+        [0.88, 0.14],
+    ])[:N_EMITTERS]
+
+
+def radar_field(xy, emitters):
+    """u(x, y) = sum_k sin(kappa r_k) / (r_k + eps).  xy is (M, 2)."""
+    xy = np.atleast_2d(xy)
+    d = xy[:, None, :] - emitters[None, :, :]        # (M, K, 2)
+    r = np.linalg.norm(d, axis=2)                    # (M, K)
+    return np.sum(np.sin(KAPPA * r) / (r + EPS), axis=1)
+
+
+# ---------------------------------------------------------------------------
+# FastLSQ surrogate
+# ---------------------------------------------------------------------------
+def build_basis(seed=SEED):
+    torch.manual_seed(seed)
+    per = N_FEAT // len(SIGMAS)
+    Ws, bs = [], []
+    for sigma in SIGMAS:
+        blk = SinusoidalBasis.random(2, per, sigma=sigma)
+        Ws.append(blk.W)
+        bs.append(blk.b)
+    return SinusoidalBasis(torch.cat(Ws, dim=1), torch.cat(bs, dim=1), normalize=True)
+
+
+class WorldModel:
+    """Tikhonov least-squares surrogate of the radar field, with analytic grad."""
+
+    def __init__(self, basis):
+        self.basis = basis
+        self.beta = None
+        self.n_refits = 0
+        self.refit_times = []
+
+    def refit(self, X, y):
+        """One regularised least-squares solve over every sample seen so far."""
+        t0 = time.perf_counter()
+        Xt = torch.tensor(X, dtype=torch.float64)
+        H = self.basis.evaluate(Xt).cpu().numpy().astype(np.float64)   # (M, N)
+        n = H.shape[1]
+        # normal equations with a ridge: the system is small in N and this is the
+        # cheapest stable route when M can be < N early in the episode
+        A = H.T @ H + MU_REG * np.eye(n)
+        self.beta = np.linalg.solve(A, H.T @ y)
+        self.refit_times.append((time.perf_counter() - t0) * 1e3)
+        self.n_refits += 1
+
+    def predict(self, xy):
+        Xt = torch.tensor(np.atleast_2d(xy), dtype=torch.float64)
+        H = self.basis.evaluate(Xt).cpu().numpy().astype(np.float64)
+        return H @ self.beta
+
+    def gradient(self, xy):
+        """Closed-form gradient of the surrogate -- the whole point of the demo."""
+        Xt = torch.tensor(np.atleast_2d(xy), dtype=torch.float64)
+        G = self.basis.gradient(Xt).cpu().numpy().astype(np.float64)   # (M, 2, N)
+        return G @ self.beta                                           # (M, 2)
+
+
+# ---------------------------------------------------------------------------
+# Episode
+# ---------------------------------------------------------------------------
+def sense_cross(pos, emitters):
+    """The drone's only observation: a 5-point cross around its position."""
+    offs = np.array([[0.0, 0.0], [CROSS_H, 0.0], [-CROSS_H, 0.0],
+                     [0.0, CROSS_H], [0.0, -CROSS_H]])
+    pts = np.clip(pos[None, :] + offs, 0.0, 1.0)
+    return pts, radar_field(pts, emitters)
+
+
+def run_episode(verbose=True, w_stealth=W_STEALTH):
+    rng = np.random.default_rng(SEED)
+    emitters = make_emitters(rng)
+    basis = build_basis()
+    wm = WorldModel(basis)
+
+    pos = START.copy()
+    X_buf, y_buf = [], []
+    path = [pos.copy()]
+    sensed_u2 = []
+    detected = False
+
+    for step in range(MAX_STEPS):
+        pts, vals = sense_cross(pos, emitters)
+        X_buf.append(pts)
+        y_buf.append(vals)
+
+        u_here = float(vals[0])
+        sensed_u2.append(u_here ** 2)
+        if u_here ** 2 > TAU:
+            detected = True
+            if verbose:
+                print(f"  DETECTED at step {step}: u^2 = {u_here**2:.2f} > {TAU}")
+            break
+
+        if step % REFIT_EVERY == 0:
+            wm.refit(np.vstack(X_buf), np.concatenate(y_buf))
+
+        to_goal = GOAL - pos
+        dist = np.linalg.norm(to_goal)
+        if dist < GOAL_TOL:
+            break
+
+        dir_goal = to_goal / (dist + 1e-12)
+
+        # Stealth term from the surrogate's analytic gradient: descend u_hat^2.
+        # Both terms are unit vectors so neither can swamp the other -- an
+        # unnormalised grad(u^2) reaches |2 u grad u| ~ 1e3 here and would pin the
+        # drone in the first null it finds.  The stealth direction is weighted by
+        # how close the *predicted* intensity is to the detector threshold, and by
+        # how much we trust the model at this point.
+        if wm.beta is not None and w_stealth > 0.0:
+            u_hat = float(wm.predict(pos)[0])
+            g_hat = wm.gradient(pos)[0]
+            grad_u2 = 2.0 * u_hat * g_hat
+            gn = np.linalg.norm(grad_u2)
+            if gn > 1e-9:
+                dir_stealth = -grad_u2 / gn
+                # trust the model only near where we have actually sensed
+                Xa = np.vstack(X_buf)
+                near = np.min(np.linalg.norm(Xa - pos[None, :], axis=1))
+                conf = float(np.exp(-(near / CONF_LEN) ** 2))
+                danger = min(1.0, (u_hat ** 2) / TAU)
+                stealth = w_stealth * conf * danger * dir_stealth
+            else:
+                stealth = np.zeros(2)
+        else:
+            stealth = np.zeros(2)
+
+        drive = W_GOAL * dir_goal + stealth
+        nrm = np.linalg.norm(drive)
+        drive = dir_goal if nrm < 1e-9 else drive / nrm
+
+        pos = np.clip(pos + STEP * drive, 0.0, 1.0)
+        path.append(pos.copy())
+
+    path = np.array(path)
+    reached = np.linalg.norm(path[-1] - GOAL) < GOAL_TOL
+    return dict(
+        path=path, emitters=emitters, world_model=wm, detected=detected,
+        reached=reached, steps=len(path) - 1, peak_u2=max(sensed_u2),
+        n_samples=len(X_buf) * 5,
+    )
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--plot", action="store_true", help="write a PNG of the episode")
+    args = ap.parse_args()
+
+    print("Stealth navigation -- FastLSQ world model refit in the loop")
+    print(f"  radar: {N_EMITTERS} emitters, kappa={KAPPA}, detector trips at u^2 > {TAU}")
+    print(f"  surrogate: N={N_FEAT} features, sigma={SIGMAS}, refit every {REFIT_EVERY} steps\n")
+
+    t0 = time.perf_counter()
+    r = run_episode()
+    wall = time.perf_counter() - t0
+
+    # Ablation: identical episode with the stealth term switched off.  This is
+    # what the drone does if it ignores the surrogate's gradient and just drives
+    # at the goal -- the control that shows the world model is doing the work.
+    base = run_episode(verbose=False, w_stealth=0.0)
+
+    wm = r["world_model"]
+    rt = np.array(wm.refit_times)
+    outcome = ("goal - undetected" if r["reached"] and not r["detected"]
+               else "DETECTED" if r["detected"] else "did not reach goal")
+
+    print("  Episode summary")
+    print(f"    outcome           {outcome}")
+    print(f"    steps             {r['steps']}")
+    print(f"    refits            {wm.n_refits}")
+    print(f"    refit cost        {np.median(rt):.1f} ms median  "
+          f"({rt.min():.1f}-{rt.max():.1f} ms)")
+    print(f"    samples gathered  {r['n_samples']}")
+    print(f"    peak sensed u^2   {r['peak_u2']:.2f}  (detector at {TAU})")
+    print(f"    wall clock        {wall:.1f} s")
+
+    b_out = ("goal - undetected" if base["reached"] and not base["detected"]
+             else "DETECTED" if base["detected"] else "did not reach goal")
+    print("\n  Ablation -- same episode, stealth term off (drive straight at goal)")
+    print(f"    outcome           {b_out}")
+    print(f"    steps             {base['steps']}")
+    print(f"    peak sensed u^2   {base['peak_u2']:.2f}  (detector at {TAU})")
+    if base["detected"]:
+        # The baseline stopped because it was detected, not because it arrived,
+        # so its step count is where it died -- not a path length to compare.
+        print(f"\n  Driving straight at the goal trips the detector at step "
+              f"{base['steps']} of a {r['steps']}-step crossing.")
+        print(f"  Steering on the surrogate's analytic gradient completes the "
+              f"crossing with peak exposure {r['peak_u2']:.1f}, "
+              f"{100.0 * (1 - r['peak_u2'] / TAU):.0f}% under the threshold.")
+    else:
+        print(f"\n  Gradient steering cut peak exposure "
+              f"{base['peak_u2'] / r['peak_u2']:.2f}x for "
+              f"{100.0 * (r['steps'] / base['steps'] - 1.0):+.0f}% path length.")
+
+    if args.plot:
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+
+        gx, gy = np.meshgrid(np.linspace(0, 1, 300), np.linspace(0, 1, 300))
+        grid = np.column_stack([gx.ravel(), gy.ravel()])
+        U = radar_field(grid, r["emitters"]).reshape(gx.shape)
+
+        # The surrogate is only meaningful where the drone actually sensed, so
+        # fade it out with distance to the path rather than showing extrapolation
+        # as if it were prediction.
+        from scipy.spatial import cKDTree
+        tree = cKDTree(r["path"])
+        dist_to_path, _ = tree.query(grid)
+        conf = np.exp(-(dist_to_path.reshape(gx.shape) / CONF_LEN) ** 2)
+
+        fig, ax = plt.subplots(1, 2, figsize=(11, 5.2))
+        panels = [(U, "true radar field", None),
+                  (wm.predict(grid).reshape(gx.shape),
+                   "FastLSQ world model (faded where unsensed)", conf)]
+        for a, (field, title, alpha) in zip(ax, panels):
+            im = a.imshow(field, extent=(0, 1, 0, 1), origin="lower",
+                          cmap="magma", vmin=U.min(), vmax=U.max(),
+                          alpha=None if alpha is None else np.clip(alpha, 0.06, 1.0))
+            a.plot(r["path"][:, 0], r["path"][:, 1], "-", color="#8ff", lw=1.8)
+            a.plot(*START, "o", color="w", ms=6)
+            a.plot(*GOAL, "*", color="#8f8", ms=14)
+            a.plot(r["emitters"][:, 0], r["emitters"][:, 1], "x", color="w", ms=7)
+            a.set_title(title, fontsize=10)
+            a.set_xticks([]); a.set_yticks([])
+            fig.colorbar(im, ax=a, fraction=0.046)
+        fig.suptitle(f"{r['steps']} steps - {outcome} - "
+                     f"{wm.n_refits} refits at {np.median(rt):.1f} ms", fontsize=11)
+        fig.tight_layout()
+        out = os.path.join(os.path.dirname(__file__), "..", "misc",
+                           "stealth_navigation.png")
+        fig.savefig(out, dpi=140)
+        print(f"\n  Saved figure -> {os.path.normpath(out)}")
+
+
+if __name__ == "__main__":
+    main()

{fastlsq-0.6.1 → fastlsq-0.6.2}/fastlsq/__init__.py

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

{fastlsq-0.6.1 → fastlsq-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "FastLSQ"
-version = "0.6.1"
+version = "0.6.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"
@@ -58,7 +58,7 @@ lightning = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/sulcantonin/FastLSQ"
+Homepage = "https://fastlsq.com"
 Repository = "https://github.com/sulcantonin/FastLSQ"
 Paper = "https://arxiv.org/abs/2602.10541"
 "Bug Tracker" = "https://github.com/sulcantonin/FastLSQ/issues"

fastlsq-0.6.2/tests/test_stealth_navigation.py

@@ -0,0 +1,51 @@
+# Copyright (c) 2026 Antonin Sulc
+# Licensed under the MIT License.
+
+"""Smoke tests for the stealth-navigation world-model demo."""
+
+import os
+import sys
+
+import numpy as np
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "examples"))
+
+import stealth_navigation as sn  # noqa: E402
+
+
+def test_radar_field_shape_and_finiteness():
+    em = sn.make_emitters(np.random.default_rng(0))
+    pts = np.random.default_rng(1).random((64, 2))
+    u = sn.radar_field(pts, em)
+    assert u.shape == (64,)
+    assert np.isfinite(u).all()
+
+
+def test_surrogate_gradient_matches_finite_differences():
+    """The selling point: grad of the surrogate is closed-form and correct."""
+    basis = sn.build_basis()
+    wm = sn.WorldModel(basis)
+    rng = np.random.default_rng(0)
+    X = rng.random((400, 2))
+    y = sn.radar_field(X, sn.make_emitters(rng))
+    wm.refit(X, y)
+
+    p = np.array([[0.5, 0.5]])
+    g = wm.gradient(p)[0]
+    h = 1e-6
+    fd = np.array([
+        (wm.predict(p + np.array([[h, 0.0]]))[0] - wm.predict(p - np.array([[h, 0.0]]))[0]) / (2 * h),
+        (wm.predict(p + np.array([[0.0, h]]))[0] - wm.predict(p - np.array([[0.0, h]]))[0]) / (2 * h),
+    ])
+    assert np.allclose(g, fd, rtol=1e-4, atol=1e-4), f"analytic {g} vs fd {fd}"
+
+
+@pytest.mark.parametrize("w_stealth,should_be_detected", [(0.0, True), (sn.W_STEALTH, False)])
+def test_gradient_steering_avoids_the_detector(w_stealth, should_be_detected):
+    """Driving straight trips the detector; steering on the analytic gradient does not."""
+    r = sn.run_episode(verbose=False, w_stealth=w_stealth)
+    assert r["detected"] is should_be_detected
+    if not should_be_detected:
+        assert r["reached"], "stealth run should still reach the goal"
+        assert r["peak_u2"] < sn.TAU