physverify 0.6.0__tar.gz → 0.7.0__tar.gz

{physverify-0.6.0/src/physverify.egg-info → physverify-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: physverify
-Version: 0.6.0
+Version: 0.7.0
 Summary: Verification checks for physics simulation code: manufactured solutions, order-of-accuracy studies and a seeded-bug benchmark.
 Author: Ram Chandra Giri
 License-Expression: MIT
@@ -46,7 +46,7 @@ Dynamic: license-file
 
 **Checks that a simulation solves the equations it claims, at the order of accuracy it claims, not just that it runs.**
 
-physverify is actively evolving (v0.6.0), welcoming contributions and test cases from the computational physics community. Scope: numerical solutions of ODEs and PDEs (time integration, convergence, conservation), plus a few Monte Carlo checks. It needs only NumPy.
+physverify is actively evolving (v0.7.0), welcoming contributions and test cases from the computational physics community. Status: under active development and maintenance, tested on a growing corpus of public physics codes; releases come at milestones. Scope: numerical solutions of ODEs and PDEs (time integration, convergence, conservation), plus a few Monte Carlo checks. It needs only NumPy.
 
 ![The check loop: your solver and an independent description of the physics go in; physverify runs the solver at several resolutions, measures the error and reports a verdict with a reason](https://raw.githubusercontent.com/rcgiri-physics/physverify/main/docs/images/check-loop.svg)
 
@@ -73,7 +73,7 @@ New to this? [Start here](https://rcgiri-physics.github.io/physverify/start-here
 A failed check fails the job, like a broken unit test ([CI guide](https://rcgiri-physics.github.io/physverify/ci/): options, pre-commit, pytest):
 
 ```yaml
-      - uses: rcgiri-physics/physverify@v0.6.0
+      - uses: rcgiri-physics/physverify@v0.7.0
         with:
           specs: tests/verify_*.py
 ```

{physverify-0.6.0 → physverify-0.7.0}/README.md

@@ -4,7 +4,7 @@
 
 **Checks that a simulation solves the equations it claims, at the order of accuracy it claims, not just that it runs.**
 
-physverify is actively evolving (v0.6.0), welcoming contributions and test cases from the computational physics community. Scope: numerical solutions of ODEs and PDEs (time integration, convergence, conservation), plus a few Monte Carlo checks. It needs only NumPy.
+physverify is actively evolving (v0.7.0), welcoming contributions and test cases from the computational physics community. Status: under active development and maintenance, tested on a growing corpus of public physics codes; releases come at milestones. Scope: numerical solutions of ODEs and PDEs (time integration, convergence, conservation), plus a few Monte Carlo checks. It needs only NumPy.
 
 ![The check loop: your solver and an independent description of the physics go in; physverify runs the solver at several resolutions, measures the error and reports a verdict with a reason](https://raw.githubusercontent.com/rcgiri-physics/physverify/main/docs/images/check-loop.svg)
 
@@ -31,7 +31,7 @@ New to this? [Start here](https://rcgiri-physics.github.io/physverify/start-here
 A failed check fails the job, like a broken unit test ([CI guide](https://rcgiri-physics.github.io/physverify/ci/): options, pre-commit, pytest):
 
 ```yaml
-      - uses: rcgiri-physics/physverify@v0.6.0
+      - uses: rcgiri-physics/physverify@v0.7.0
         with:
           specs: tests/verify_*.py
 ```

{physverify-0.6.0 → physverify-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "physverify"
-version = "0.6.0"
+version = "0.7.0"
 description = "Verification checks for physics simulation code: manufactured solutions, order-of-accuracy studies and a seeded-bug benchmark."
 readme = "README.md"
 requires-python = ">=3.10"

{physverify-0.6.0 → physverify-0.7.0}/src/physverify/__init__.py

@@ -6,7 +6,7 @@ from .order import check_order, fit_order, pairwise_orders
 from .order import check_exact
 from .studies import invariant_study, ode_checks, patch_study, reference_study
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "Check",

{physverify-0.6.0 → physverify-0.7.0}/src/physverify/agent.py

@@ -112,14 +112,18 @@ def hook_main(stdin=None, stderr=None) -> int:
         event = json.load(stdin)
     except (json.JSONDecodeError, ValueError):
         return 0  # not a hook event; never block the assistant on our own input problem
-    tool_input = event.get("tool_input") or {}
+    if not isinstance(event, dict):
+        return 0
+    tool_input = event.get("tool_input")
+    tool_input = tool_input if isinstance(tool_input, dict) else {}
     edited = tool_input.get("file_path") or tool_input.get("notebook_path") or ""
-    if edited and not edited.endswith(".py"):
+    if not isinstance(edited, str) or (edited and not edited.endswith(".py")):
         return 0
     cwd = Path(event.get("cwd") or ".").resolve()
-    if edited and not Path(edited).resolve().is_relative_to(cwd):
+    edited_path = (cwd / edited).resolve() if edited else None  # a relative path is relative to the session folder
+    if edited_path is not None and not edited_path.is_relative_to(cwd):
         return 0  # an edit outside the session folder must not run that folder's code (GCVE-110-VULN-PYPI-2026-000391)
-    root = find_project_root(Path(edited).parent if edited else cwd)
+    root = find_project_root(edited_path.parent if edited_path is not None else cwd)
     if not root.is_relative_to(cwd):
         root = cwd  # never climb above the session folder
     specs = find_specs(root)
@@ -141,8 +145,11 @@ META_VERSION = "io.modelcontextprotocol/protocolVersion"
 META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities"
 META_SERVER_INFO = "io.modelcontextprotocol/serverInfo"
 
-INVALID_PARAMS = -32602
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
 METHOD_NOT_FOUND = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
 UNSUPPORTED_PROTOCOL_VERSION = -32022
 
 CACHE_HINTS = {"ttlMs": 300_000, "cacheScope": "public"}  # the tool list does not change while the server runs
@@ -252,6 +259,16 @@ def handle(message: dict):
     return _error(msg_id, METHOD_NOT_FOUND, f"method not found: {method}")
 
 
+def _respond(message):
+    """handle(), but a message that is not an object, or an exception, becomes an error response; the server keeps running."""
+    if not isinstance(message, dict):  # a batch, a number, a string: not a request this server answers
+        return _error(None, INVALID_REQUEST, "invalid request: expected a JSON object")
+    try:
+        return handle(message)
+    except Exception as exc:  # report the failure to the client
+        return _error(message.get("id"), INTERNAL_ERROR, f"{type(exc).__name__}: {exc}")
+
+
 def mcp_main(stdin=None, stdout=None) -> int:
     stdin = stdin or sys.stdin
     stdout = stdout or sys.stdout
@@ -262,12 +279,9 @@ def mcp_main(stdin=None, stdout=None) -> int:
         try:
             message = json.loads(line)
         except json.JSONDecodeError:
-            response = {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "parse error"}}
+            response = _error(None, PARSE_ERROR, "parse error")
         else:
-            try:
-                response = handle(message)
-            except Exception as exc:  # keep the server alive; report the failure to the client
-                response = {"jsonrpc": "2.0", "id": message.get("id"), "error": {"code": -32603, "message": f"{type(exc).__name__}: {exc}"}}
+            response = _respond(message)
         if response is not None:
             stdout.write(json.dumps(response) + "\n")
             stdout.flush()

{physverify-0.6.0 → physverify-0.7.0}/src/physverify/butcher.py

@@ -186,6 +186,7 @@ def a_stability_margin(A, b) -> float:
     iy = np.polynomial.Polynomial([0, 1j])
     Pi = np.polynomial.Polynomial(P.astype(complex))(iy)
     Qi = np.polynomial.Polynomial(Q.astype(complex))(iy)
+
     def sq(p):  # |p(iy)|^2 for real y, as a polynomial in y
         return p * np.polynomial.Polynomial(np.conj(p.coef))
 
@@ -205,9 +206,39 @@ def is_stiffly_accurate(A, b, *, tol: float = 1e-12) -> bool:
     return bool(np.max(np.abs(np.asarray(A, float)[-1] - np.asarray(b, float))) <= tol)
 
 
+def square_tableau(A, b, c=None):
+    """(A, b, c) with A made square: a table stored as s x (s - 1) (the last column of an explicit table is
+    zero and is often left out) or with an extra FSAL stage that has weight 0 in b is padded with zeros.
+    Explicit FSAL tables (Dormand-Prince, Bogacki-Shampine) then check like any other."""
+    A = np.atleast_2d(np.asarray(A, dtype=float))
+    b = np.asarray(b, dtype=float)
+    n = max(A.shape[0], A.shape[1], b.size)
+    full = np.zeros((n, n))
+    full[:A.shape[0], :A.shape[1]] = A
+    bb = np.zeros(n)
+    bb[:b.size] = b
+    if c is not None:
+        cc = np.zeros(n)
+        cc[:np.size(c)] = np.asarray(c, dtype=float)
+        if np.size(c) < n:
+            cc[np.size(c):] = full[np.size(c):].sum(axis=1)
+        c = cc
+    return full, bb, c
+
+
+def symplectic_residual(A, b) -> float:
+    """max |b_i a_ij + b_j a_ji - b_i b_j|: zero exactly for a symplectic Runge-Kutta method (Sanz-Serna 1988;
+    Hairer, Lubich and Wanner, Geometric Numerical Integration, Thm. VI.4.3). Gauss methods are symplectic;
+    no explicit Runge-Kutta method is."""
+    A, b, _ = square_tableau(A, b)
+    M = b[:, None] * A + (b[:, None] * A).T - np.outer(b, b)
+    return float(np.max(np.abs(M)))
+
+
 def check_tableau(A, b, c=None, *, claimed: int, label: str = "", tol: float = 1e-8, max_order: int | None = None,
                   claimed_linear: int | None = None, claimed_stage: int | None = None, a_stable: bool | None = None,
-                  l_stable: bool | None = None, stiffly_accurate: bool | None = None) -> Result:
+                  l_stable: bool | None = None, stiffly_accurate: bool | None = None, embedded=None,
+                  claimed_embedded: int | None = None, symplectic: bool | None = None) -> Result:
     """PASS when the table has at least the claimed order and every other stated property; FAIL otherwise.
 
     The default tolerance 1e-8 accepts coefficients typed with 9 or 10 digits (a real package had
@@ -222,8 +253,13 @@ def check_tableau(A, b, c=None, *, claimed: int, label: str = "", tol: float = 1
     a_stable        |R(z)| <= 1 on Re z <= 0; see `a_stability_margin`
     l_stable        A-stable and R(inf) = 0
     stiffly_accurate  b equals the last row of A
+    symplectic      b_i a_ij + b_j a_ji = b_i b_j; see `symplectic_residual`
     True means "the method has it" and False means "the method does not"; a mismatch either way fails.
+    embedded        the weights of the embedded (error-estimate) method; with `claimed_embedded`, its order
+                    is checked too, and the error weights b - embedded must sum to 0.
+    A table stored as s x (s - 1), or with an FSAL stage of weight 0, is padded first (`square_tableau`).
     """
+    A, b, c = square_tableau(A, b, c)
     top = max_order or claimed + 1
     res = order_residuals(A, b, top)
     p = tableau_order(A, b, max_order=top, tol=tol)
@@ -258,8 +294,8 @@ def check_tableau(A, b, c=None, *, claimed: int, label: str = "", tol: float = 1
             notes.append(f"linear order is at least {pl} (claimed {claimed_linear})")
         else:
             notes.append(f"linear order {pl} confirmed")
-    elif linear_order(A, b, max_order=max(p, claimed) + 2, tol=tol) > p:
-        notes.append(f"linear order {linear_order(A, b, max_order=max(p, claimed) + 2, tol=tol)} is higher than the order {p}:"
+    elif (pl := linear_order(A, b, max_order=max(p, claimed) + 2, tol=tol)) > p:
+        notes.append(f"linear order {pl} is higher than the order {p}:"
                      " a convergence test on y' = lambda*y alone would overstate the order")
     if claimed_stage is not None:
         q = stage_order(A, c, b, max_order=claimed_stage + 1, tol=tol)
@@ -291,6 +327,78 @@ def check_tableau(A, b, c=None, *, claimed: int, label: str = "", tol: float = 1
         else:
             notes.append(f"{'' if has else 'not '}stiffly accurate as stated")
 
+    if embedded is not None:
+        Ae = A
+        if np.size(embedded) > A.shape[0]:
+            # error weights over one more stage (SciPy's E): the FSAL stage, evaluated at y_{n+1}, has row b
+            Ae = np.vstack([np.hstack([A, np.zeros((A.shape[0], 1))]), np.append(b, 0.0)])
+        Ae, be, _ = square_tableau(Ae, embedded)
+        if abs(be.sum() - 1) > tol:
+            fails.append(f"embedded weights sum to {be.sum():.10g}, not 1 (so b - embedded does not sum to 0)")
+        if claimed_embedded is not None:
+            pe = tableau_order(Ae, be, max_order=claimed_embedded + 1, tol=tol)
+            if pe < claimed_embedded:
+                fails.append(f"claims embedded order {claimed_embedded} but the embedded weights satisfy the order"
+                             f" conditions only up to {pe}")
+            else:
+                notes.append(f"embedded order {pe}" + (f" (claimed {claimed_embedded})" if pe > claimed_embedded else " confirmed"))
+    if symplectic is not None:
+        r = symplectic_residual(A, b)
+        has = r <= tol
+        if has != symplectic:
+            fails.append(f"stated {'' if symplectic else 'not '}symplectic, but max |b_i a_ij + b_j a_ji - b_i b_j| = {r:.1e}")
+        else:
+            notes.append(f"{'' if has else 'not '}symplectic as stated")
+
     if fails:
         return Result(FAIL, prefix + "; ".join(fails + notes))
     return Result(PASS, prefix + "; ".join(notes))
+
+
+# Published tables, for comparing a code's copy against them (exact rationals as floats).
+_S3 = np.sqrt(3.0)
+TABLES = {
+    "rk4": dict(A=[[0, 0, 0, 0], [0.5, 0, 0, 0], [0, 0.5, 0, 0], [0, 0, 1, 0]], b=[1 / 6, 1 / 3, 1 / 3, 1 / 6],
+                c=[0, 0.5, 0.5, 1], order=4),
+    # Bogacki and Shampine 1989; SciPy's RK23 (embedded order 2, FSAL)
+    "bogacki_shampine_3_2": dict(A=[[0, 0, 0, 0], [1 / 2, 0, 0, 0], [0, 3 / 4, 0, 0], [2 / 9, 1 / 3, 4 / 9, 0]],
+                                 b=[2 / 9, 1 / 3, 4 / 9, 0], c=[0, 1 / 2, 3 / 4, 1], order=3,
+                                 embedded=[7 / 24, 1 / 4, 1 / 3, 1 / 8], embedded_order=2),
+    # Dormand and Prince 1980; SciPy's RK45 and MATLAB's ode45 (embedded order 4, FSAL)
+    "dormand_prince_5_4": dict(
+        A=[[0, 0, 0, 0, 0, 0, 0],
+           [1 / 5, 0, 0, 0, 0, 0, 0],
+           [3 / 40, 9 / 40, 0, 0, 0, 0, 0],
+           [44 / 45, -56 / 15, 32 / 9, 0, 0, 0, 0],
+           [19372 / 6561, -25360 / 2187, 64448 / 6561, -212 / 729, 0, 0, 0],
+           [9017 / 3168, -355 / 33, 46732 / 5247, 49 / 176, -5103 / 18656, 0, 0],
+           [35 / 384, 0, 500 / 1113, 125 / 192, -2187 / 6784, 11 / 84, 0]],
+        b=[35 / 384, 0, 500 / 1113, 125 / 192, -2187 / 6784, 11 / 84, 0], c=[0, 1 / 5, 3 / 10, 4 / 5, 8 / 9, 1, 1],
+        order=5, embedded=[5179 / 57600, 0, 7571 / 16695, 393 / 640, -92097 / 339200, 187 / 2100, 1 / 40],
+        embedded_order=4),
+    "implicit_midpoint": dict(A=[[0.5]], b=[1.0], c=[0.5], order=2),
+    "gauss_legendre_4": dict(A=[[1 / 4, 1 / 4 - _S3 / 6], [1 / 4 + _S3 / 6, 1 / 4]], b=[0.5, 0.5],
+                             c=[0.5 - _S3 / 6, 0.5 + _S3 / 6], order=4),
+}
+
+
+def _drop_fsal(A, b, tol: float = 1e-14):
+    """Without a last FSAL stage (row equal to b, weight 0 in b): codes store such tables with or without it."""
+    if A.shape[0] > 1 and abs(b[-1]) <= tol and np.allclose(A[-1, :-1], b[:-1], atol=tol, rtol=0):
+        return A[:-1, :-1], b[:-1]
+    return A, b
+
+
+def compare_tableau(A, b, name: str, *, tol: float = 1e-10) -> Result:
+    """A code's copy of a published table (one of `TABLES`) has the published coefficients."""
+    ref = TABLES[name]
+    A1, b1 = _drop_fsal(*square_tableau(A, b)[:2])
+    A2, b2 = _drop_fsal(*square_tableau(ref["A"], ref["b"])[:2])
+    if A1.shape != A2.shape:
+        return Result(FAIL, f"{name}: {A1.shape[0]} stages, the published table has {A2.shape[0]}")
+    dA, db = np.abs(A1 - A2), np.abs(b1 - b2)
+    if max(dA.max(), db.max()) <= tol:
+        return Result(PASS, f"{name}: coefficients match the published table to {tol:g}")
+    i, j = np.unravel_index(int(np.argmax(dA)), dA.shape)
+    where = f"A[{i}][{j}] off by {dA[i, j]:.3g}" if dA.max() >= db.max() else f"b[{int(np.argmax(db))}] off by {db.max():.3g}"
+    return Result(FAIL, f"{name}: coefficients differ from the published table, largest at {where}")

{physverify-0.6.0 → physverify-0.7.0}/src/physverify/cli.py

@@ -61,6 +61,9 @@ def _cmd_run(args) -> int:
             print(f"physverify: {spec}: checks() returned no checks, so nothing was tested", file=sys.stderr)
             return 2
         outcomes += run_checks(checks, args.budget)
+        from .specscan import reference_notes
+        for note in reference_notes(spec):
+            print(f"physverify: note: {note}", file=sys.stderr)
     source = ", ".join(str(Path(s)) for s in args.specs)
     if args.json == "-":
         print(to_json(outcomes, source))

{physverify-0.6.0 → physverify-0.7.0}/src/physverify/constants.py

@@ -129,7 +129,10 @@ def scan(path, *, max_rel: float = 0.1) -> list[Note]:
     notes = []
     for node in ast.walk(tree):
         if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool):
-            v = float(node.value)
+            try:
+                v = float(node.value)
+            except OverflowError:  # an integer literal too large for a float is no physical constant
+                continue
             hit = check_value(abs(v), max_rel=max_rel)
             if hit and (isinstance(node.value, int) or _digits(v) < 3):
                 if not names.get(id(node), set()) & NAMES.get(hit[0], set()):

physverify-0.7.0/src/physverify/fluxes.py

@@ -0,0 +1,58 @@
+"""Exactness properties every numerical flux of a conservation law must have (Toro, Riemann Solvers and
+Numerical Methods for Fluid Dynamics, 3rd ed., ch. 10-11; LeVeque, Finite Volume Methods, sec. 12.1):
+
+- consistency  F(W, W) = f(W), the physical flux, for any state W
+- upwinding    when every wave speed is positive on both sides, F(WL, WR) = f(WL) (all negative: f(WR));
+               Roe, HLL, HLLC and Rusanov fluxes with exact wave-speed bounds satisfy it
+- mirror       reflecting the normal velocity and swapping the sides gives F(R WR, R WL) = -R F(WL, WR),
+               with R the reflection acting on the flux components
+
+Each needs only the flux function and the physical flux written from the equations, not a solver run.
+In the 2026-10 corpus sessions these checks found both bugs in one Euler solver: a Roe flux that broke
+upwinding when density and tangential velocity both jumped, and an HLLE flux built for the wrong fluid.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Iterable
+
+import numpy as np
+
+from .checks import FAIL, PASS, Result
+from .identities import _verdict
+
+
+def check_flux(flux: Callable, physical: Callable, states: Iterable, *, upwind_pairs: Iterable = (),
+               downwind_pairs: Iterable = (), mirror: tuple | None = None, rtol: float = 1e-10,
+               atol: float = 1e-12) -> Result:
+    """Consistency, upwinding and (optionally) mirror symmetry of a numerical flux `flux(WL, WR)`.
+
+    `physical(W)` is the exact flux written from the equations; `states` are the states W for the
+    consistency check. `upwind_pairs` are (WL, WR) with all wave speeds positive on both sides (F must equal
+    f(WL)) and `downwind_pairs` all negative (F must equal f(WR)); the caller builds them from the sound
+    speed. `mirror = (reflect, signs)`: `reflect(W)` flips the normal velocity of a state and `signs` holds
+    +1 or -1 per flux component (for the 1D Euler equations (-1, +1, -1): mass and energy fluxes change sign,
+    the momentum flux does not); the check is F(reflect(WR), reflect(WL)) = signs * F(WL, WR), over all pairs.
+    """
+    states = list(states)
+    if not states:
+        raise ValueError("no states given")
+    up, down = list(upwind_pairs), list(downwind_pairs)
+    results = [("consistency F(W, W) = f(W)",
+                _verdict("consistency", [(f"state {i}", flux(w, w), physical(w)) for i, w in enumerate(states)], rtol, atol))]
+    if up:
+        results.append(("upwinding F = f(WL) for flow to the right",
+                        _verdict("upwinding", [(f"pair {i}", flux(a, b), physical(a)) for i, (a, b) in enumerate(up)], rtol, atol)))
+    if down:
+        results.append(("upwinding F = f(WR) for flow to the left",
+                        _verdict("upwinding", [(f"pair {i}", flux(a, b), physical(b)) for i, (a, b) in enumerate(down)], rtol, atol)))
+    if mirror is not None:
+        reflect, signs = mirror
+        signs = np.asarray(signs, dtype=float)
+        pairs = up + down + list(zip(states, states[1:]))
+        cases = [(f"pair {i}", flux(reflect(b), reflect(a)), signs * np.asarray(flux(a, b))) for i, (a, b) in enumerate(pairs)]
+        results.append(("mirror symmetry", _verdict("mirror symmetry", cases, rtol, atol)))
+    failed = [f"{name}: {r.message}" for name, r in results if not r.ok]
+    if failed:
+        return Result(FAIL, "; ".join(failed))
+    return Result(PASS, "the numerical flux passes " + ", ".join(name for name, _r in results))

{physverify-0.6.0 → physverify-0.7.0}/src/physverify/identities.py

@@ -22,7 +22,11 @@ from .checks import FAIL, PASS, Result
 
 
 def _worst(got, ref, rtol: float, atol: float):
-    """Largest violation of |got - ref| <= atol + rtol |ref|, as (excess, abs error, where)."""
+    """Largest violation of |got - ref| <= atol + rtol |ref|, as (excess, abs error, where, got there, ref there).
+
+    `where` indexes the broadcast shape, so the values there are returned too: indexing the original
+    `got` with it fails when a scalar was compared with an array.
+    """
     g = np.asarray(got)
     r = np.asarray(ref)
     if g.shape != r.shape:
@@ -34,12 +38,12 @@ def _worst(got, ref, rtol: float, atol: float):
     tol = atol + rtol * np.abs(r)
     excess = err - tol
     if excess.size == 0:
-        return -np.inf, 0.0, ()
+        return -np.inf, 0.0, (), got, ref
     if not np.all(np.isfinite(err)):
         i = np.unravel_index(int(np.argmax(~np.isfinite(err))), err.shape)
-        return np.inf, np.inf, i
+        return np.inf, np.inf, i, (g[i] if i else got), (r[i] if i else ref)
     i = np.unravel_index(int(np.argmax(excess)), excess.shape)
-    return float(excess[i]), float(err[i]), i
+    return float(excess[i]), float(err[i]), i, (g[i] if i else got), (r[i] if i else ref)
 
 
 def _verdict(what: str, cases, rtol: float, atol: float) -> Result:
@@ -48,18 +52,16 @@ def _verdict(what: str, cases, rtol: float, atol: float) -> Result:
     n = 0
     for label, got, ref in cases:
         n += 1
-        excess, err, where = _worst(got, ref, rtol, atol)
+        excess, err, where, g, r = _worst(got, ref, rtol, atol)
         if worst is None or excess > worst[0]:
-            worst = (excess, err, label, where, got, ref)
+            worst = (excess, err, label, where, g, r)
     if worst is None:
         raise ValueError(f"{what}: no inputs given")
-    excess, err, label, where, got, ref = worst
+    excess, err, label, where, g, r = worst
     at = f" at index {tuple(int(k) for k in where)}" if where else ""
     detail = f"worst case {label}{at}: |difference| = {err:.3g} (rtol {rtol:g}, atol {atol:g})"
     if excess <= 0:
         return Result(PASS, f"{what}: {n} case{'s' if n != 1 else ''} within tolerance; {detail}")
-    g = np.asarray(got)[where] if where else got
-    r = np.asarray(ref)[where] if where else ref
     return Result(FAIL, f"{what}: {detail}; got {g!r}, expected {r!r}")
 
 
@@ -155,3 +157,103 @@ def check_unitary(matrix, *, atol: float = 1e-10) -> Result:
     eye = np.eye(m.shape[-1])
     prod = np.einsum("...ji,...jk->...ik", m.conj(), m)
     return _verdict("unitarity M^H M = I", [("matrix", prod, np.broadcast_to(eye, prod.shape))], 0.0, atol)
+
+
+def _passes(outcome, rtol: float, atol: float) -> tuple[bool, str]:
+    """A test outcome as (passed, detail): a Result, a bool, or a (got, ref) pair compared within tolerance."""
+    if isinstance(outcome, Result):
+        return outcome.ok, outcome.message
+    if isinstance(outcome, tuple) and len(outcome) == 2:
+        excess, err, _where, _g, _r = _worst(outcome[0], outcome[1], rtol, atol)
+        return excess <= 0, f"|difference| = {err:.3g}"
+    return bool(outcome), ""
+
+
+def vary_one(test: Callable, defaults: dict, changes: dict, *, rtol: float = 1e-9, atol: float = 0.0) -> Result:
+    """Re-run a test that passes at the default parameters with one parameter changed at a time.
+
+    `test(**params)` returns a Result, a bool, or a (got, ref) pair with the reference from the physics.
+    `defaults` are the usual values (often symmetric ones: Lx = Ly, nx = ny, zero boundary data, s polarisation,
+    vacuum); `changes` maps a parameter to a value, or a list of values, to try instead while the others keep
+    their defaults. FAIL names each change that breaks the test.
+
+    In the 2026-10 corpus sessions 7 of the confirmed bugs passed every check at the example values and
+    appeared only when one parameter left them: a y-derivative scaled with Lx (only when Lx != Ly), a
+    Neumann row that dropped the boundary value (only when g != 0), the p-polarisation path of a grating
+    solver, an inertia formula right for rectangles only, a factor that cancels for low-loss media.
+    """
+    ok, detail = _passes(test(**defaults), rtol, atol)
+    if not ok:
+        return Result(FAIL, f"fails already at the defaults {defaults}" + (f": {detail}" if detail else ""))
+    broken, tried = [], 0
+    for name, values in changes.items():
+        if name not in defaults:
+            raise ValueError(f"{name} is not one of the default parameters")
+        for v in values if isinstance(values, (list, tuple)) else [values]:
+            tried += 1
+            try:
+                ok, detail = _passes(test(**{**defaults, name: v}), rtol, atol)
+            except Exception as exc:  # noqa: BLE001 - an exception fails that change, not the helper
+                ok, detail = False, f"{type(exc).__name__}: {exc}"
+            if not ok:
+                broken.append(f"{name} = {v!r}" + (f" ({detail})" if detail else ""))
+    if broken:
+        return Result(FAIL, f"passes at the defaults but fails when one parameter changes: {'; '.join(broken)}")
+    return Result(PASS, f"passes at the defaults and with each of {tried} one-parameter changes ({', '.join(changes)})")
+
+
+_FACTORS = {"2": 2.0, "1/2": 0.5, "pi": np.pi, "1/pi": 1 / np.pi, "2 pi": 2 * np.pi, "1/(2 pi)": 1 / (2 * np.pi),
+            "sqrt(2)": np.sqrt(2), "1/sqrt(2)": 1 / np.sqrt(2), "4 pi": 4 * np.pi, "1/(4 pi)": 1 / (4 * np.pi),
+            "-1": -1.0, "4": 4.0, "1/4": 0.25, "3": 3.0, "1/3": 1 / 3}
+
+
+def check_scale(got, ref, *, rtol: float = 1e-6, min_correlation: float = 0.999) -> Result:
+    """The output has the right size, not only the right shape: got = k * ref with k = 1.
+
+    Fits the single factor k (least squares) and the correlation of got with ref. A correlation near 1
+    with k != 1 is a scale or units error (a missing 1/(2 dx), a missing time step, a factor 1/2); the
+    message names a nearby simple factor (2, pi, sqrt 2, ...) or gives k to match against a grid spacing
+    or a sampling rate. In the 2026-10 corpus sessions the ratio alone pointed to the bug in four
+    repositories. A low correlation means the shape itself is wrong, and a plain comparison says more.
+    """
+    g = np.ravel(np.asarray(got, dtype=complex))
+    r = np.ravel(np.asarray(ref, dtype=complex))
+    if g.shape != r.shape:
+        raise ValueError(f"shapes differ: got {np.shape(got)}, reference {np.shape(ref)}")
+    rr = np.vdot(r, r).real
+    if rr == 0:
+        raise ValueError("the reference is zero everywhere, so no scale can be fitted")
+    k = np.vdot(r, g) / rr
+    gg = np.vdot(g, g).real
+    corr = abs(np.vdot(r, g)) / np.sqrt(rr * gg) if gg > 0 else 0.0
+    kshow = f"{k.real:.6g}" if abs(k.imag) <= 1e-12 * abs(k) else f"{k:.6g}"
+    if corr < min_correlation:
+        return Result(FAIL, f"output and reference differ in shape, not only in scale (correlation {corr:.4f},"
+                            f" best factor {kshow}); compare them directly")
+    if abs(k - 1) <= rtol:
+        return Result(PASS, f"output = {kshow} x reference (correlation {corr:.6f})")
+    near = [n for n, v in _FACTORS.items() if abs(k - v) <= 1e-3 * abs(v)]
+    hint = f", which is {near[0]}" if near else ""
+    return Result(FAIL, f"output = {kshow} x reference{hint} (correlation {corr:.6f}): the shape is right but the scale"
+                        " is not; look for a missing factor (grid spacing, time step, sampling rate, 2, pi) or a units slip")
+
+
+def check_vec_convention(superop, f: Callable, x, *, expected: str | None = None, atol: float = 1e-10) -> Result:
+    """Which vectorisation a superoperator follows: superop @ vec(X) == vec(f(X)), with vec in C (row-major)
+    or F (column-major) order.
+
+    Kronecker constructions of Liouvillians and other superoperators depend on the convention
+    (vec(A X B) = (B^T kron A) vec(X) holds for column stacking); code that builds S for one and reshapes
+    with the other gives a wrong but well-formed answer (corpus repo L204). With `expected` ('C' or 'F'),
+    FAIL unless S follows it; without, PASS when S follows either, and say which.
+    """
+    S = np.asarray(superop)
+    X = np.asarray(x)
+    want = np.asarray(f(X))
+    match = [o for o in ("C", "F") if np.allclose(S @ X.ravel(order=o), want.ravel(order=o), atol=atol, rtol=0)]
+    if not match:
+        return Result(FAIL, "the superoperator matches f(X) in neither C (row-major) nor F (column-major) vectorisation")
+    which = " and ".join(match)
+    if expected is not None and expected.upper() not in match:
+        return Result(FAIL, f"the superoperator follows {which}-order vectorisation, not the expected {expected.upper()}")
+    return Result(PASS, f"the superoperator follows {which}-order vectorisation (row-major is C, column-major is F)")