physverify 0.4.2__tar.gz → 0.5.1__tar.gz

{physverify-0.4.2/src/physverify.egg-info → physverify-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: physverify
-Version: 0.4.2
+Version: 0.5.1
 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
@@ -45,7 +45,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.4.2), 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.5.1), 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.
 
 ![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)
 
@@ -58,8 +58,11 @@ The demo checks a correct solver (all checks pass), then the same solver with th
 
 ![Error against step size: the correct solver follows the slope-2 line, the broken one levels off](https://raw.githubusercontent.com/rcgiri-physics/physverify/main/docs/images/convergence.svg)
 
+New to this? [Start here](https://rcgiri-physics.github.io/physverify/start-here/) walks through installation and a first check in about ten minutes, with a prompt to paste if you use an AI coding assistant.
+
 ## Use it on your own code
 
+- **Any project, no set-up:** `physverify scan PATH` reads the code (it runs nothing) and flags Runge-Kutta methods that do not have their stated order (written as tables, as class attributes or as stages in code), grid spacings that do not match their grid, near-miss physical constants, and inverse function pairs worth a round-trip test.
 - **An ODE solver:** `physverify init verify_solver.py --solver mysolver --order 4` writes a spec; fill in the equations (from the physics, not from your code) and run `physverify run verify_solver.py`.
 - **A Runge-Kutta table:** `check_tableau(A, b, c, claimed=3)` from `physverify.butcher` checks its order, stage order and stability from the coefficients alone.
 - **Errors you already have:** `check_order(hs, errors, expected=2)` gives PASS, FAIL or INCONCLUSIVE with a reason.
@@ -69,7 +72,7 @@ The demo checks a correct solver (all checks pass), then the same solver with th
 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.4.2
+      - uses: rcgiri-physics/physverify@v0.5.1
         with:
           specs: tests/verify_*.py
 ```
@@ -78,7 +81,7 @@ A failed check fails the job, like a broken unit test ([CI guide](https://rcgiri
 
 ## Does it catch bugs?
 
-Of 37 bugs seeded into five small solvers, it flagged 35 (plain "compare with one answer" tests: 27), with no false alarms. The bugs and checks were written by the same person, so this shows the tool works as designed, not how it does on other people's code. On public physics repositories it found real bugs, for example Runge-Kutta tables with a wrong order label; the counts are not a bug rate. Details: [results](https://rcgiri-physics.github.io/physverify/results/), and [results/README.md](https://github.com/rcgiri-physics/physverify/blob/main/results/README.md) to regenerate every table.
+Of 37 bugs seeded into five small solvers, it flagged 35 (plain "compare with one answer" tests: 27), with no false alarms. The bugs and checks were written by the same person, so this shows the tool works as designed, not how it does on other people's code. On public physics repositories, 74 defects were reported to authors; 14 of them were found by a physverify check as such, 11 by simply running the code, and the rest by the per-repository test scripts or by reading the code. `physverify scan` alone, with no script, now finds 18 of the 74, up from 2 in its first version, and found 7 new defects in the same repositories ([which found what](https://github.com/rcgiri-physics/physverify/blob/main/results/corpus/FINDINGS_BY_METHOD.md)). The counts describe that sample only and are not a bug rate. Details: [results](https://rcgiri-physics.github.io/physverify/results/), and [results/README.md](https://github.com/rcgiri-physics/physverify/blob/main/results/README.md) to regenerate every table.
 
 ## Limits
 
@@ -86,4 +89,6 @@ Works best for ODEs; PDEs only in 1D so far. Your code needs a way to add a sour
 
 ## Contributing, citing, licence
 
-Help is welcome: a trial report on your own solver, seeded bugs written by someone other than the author, adapters, documentation. See [CONTRIBUTING.md](https://github.com/rcgiri-physics/physverify/blob/main/CONTRIBUTING.md). To cite, use [doi:10.5281/zenodo.23534512](https://doi.org/10.5281/zenodo.23534512) or [CITATION.cff](https://github.com/rcgiri-physics/physverify/blob/main/CITATION.cff). Changes: [CHANGELOG.md](https://github.com/rcgiri-physics/physverify/blob/main/CHANGELOG.md); plans: [ROADMAP.md](https://github.com/rcgiri-physics/physverify/blob/main/ROADMAP.md). MIT licence, copyright (c) 2026 Ram Chandra Giri.
+Help is welcome: a trial report on your own solver, seeded bugs written by someone other than the author, adapters, documentation. See [CONTRIBUTING.md](https://github.com/rcgiri-physics/physverify/blob/main/CONTRIBUTING.md), the [code of conduct](https://github.com/rcgiri-physics/physverify/blob/main/CODE_OF_CONDUCT.md), [SUPPORT.md](https://github.com/rcgiri-physics/physverify/blob/main/SUPPORT.md) for help, [SECURITY.md](https://github.com/rcgiri-physics/physverify/blob/main/SECURITY.md) on running untrusted code, and [AGENTS.md](https://github.com/rcgiri-physics/physverify/blob/main/AGENTS.md) for AI assistants. To cite, use [doi:10.5281/zenodo.23534512](https://doi.org/10.5281/zenodo.23534512) or [CITATION.cff](https://github.com/rcgiri-physics/physverify/blob/main/CITATION.cff). Changes: [CHANGELOG.md](https://github.com/rcgiri-physics/physverify/blob/main/CHANGELOG.md); plans: [ROADMAP.md](https://github.com/rcgiri-physics/physverify/blob/main/ROADMAP.md). MIT licence, copyright (c) 2026 Ram Chandra Giri.
+
+<!-- mcp-name: io.github.rcgiri-physics/physverify -->

{physverify-0.4.2 → physverify-0.5.1}/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.4.2), 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.5.1), 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.
 
 ![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)
 
@@ -17,8 +17,11 @@ The demo checks a correct solver (all checks pass), then the same solver with th
 
 ![Error against step size: the correct solver follows the slope-2 line, the broken one levels off](https://raw.githubusercontent.com/rcgiri-physics/physverify/main/docs/images/convergence.svg)
 
+New to this? [Start here](https://rcgiri-physics.github.io/physverify/start-here/) walks through installation and a first check in about ten minutes, with a prompt to paste if you use an AI coding assistant.
+
 ## Use it on your own code
 
+- **Any project, no set-up:** `physverify scan PATH` reads the code (it runs nothing) and flags Runge-Kutta methods that do not have their stated order (written as tables, as class attributes or as stages in code), grid spacings that do not match their grid, near-miss physical constants, and inverse function pairs worth a round-trip test.
 - **An ODE solver:** `physverify init verify_solver.py --solver mysolver --order 4` writes a spec; fill in the equations (from the physics, not from your code) and run `physverify run verify_solver.py`.
 - **A Runge-Kutta table:** `check_tableau(A, b, c, claimed=3)` from `physverify.butcher` checks its order, stage order and stability from the coefficients alone.
 - **Errors you already have:** `check_order(hs, errors, expected=2)` gives PASS, FAIL or INCONCLUSIVE with a reason.
@@ -28,7 +31,7 @@ The demo checks a correct solver (all checks pass), then the same solver with th
 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.4.2
+      - uses: rcgiri-physics/physverify@v0.5.1
         with:
           specs: tests/verify_*.py
 ```
@@ -37,7 +40,7 @@ A failed check fails the job, like a broken unit test ([CI guide](https://rcgiri
 
 ## Does it catch bugs?
 
-Of 37 bugs seeded into five small solvers, it flagged 35 (plain "compare with one answer" tests: 27), with no false alarms. The bugs and checks were written by the same person, so this shows the tool works as designed, not how it does on other people's code. On public physics repositories it found real bugs, for example Runge-Kutta tables with a wrong order label; the counts are not a bug rate. Details: [results](https://rcgiri-physics.github.io/physverify/results/), and [results/README.md](https://github.com/rcgiri-physics/physverify/blob/main/results/README.md) to regenerate every table.
+Of 37 bugs seeded into five small solvers, it flagged 35 (plain "compare with one answer" tests: 27), with no false alarms. The bugs and checks were written by the same person, so this shows the tool works as designed, not how it does on other people's code. On public physics repositories, 74 defects were reported to authors; 14 of them were found by a physverify check as such, 11 by simply running the code, and the rest by the per-repository test scripts or by reading the code. `physverify scan` alone, with no script, now finds 18 of the 74, up from 2 in its first version, and found 7 new defects in the same repositories ([which found what](https://github.com/rcgiri-physics/physverify/blob/main/results/corpus/FINDINGS_BY_METHOD.md)). The counts describe that sample only and are not a bug rate. Details: [results](https://rcgiri-physics.github.io/physverify/results/), and [results/README.md](https://github.com/rcgiri-physics/physverify/blob/main/results/README.md) to regenerate every table.
 
 ## Limits
 
@@ -45,4 +48,6 @@ Works best for ODEs; PDEs only in 1D so far. Your code needs a way to add a sour
 
 ## Contributing, citing, licence
 
-Help is welcome: a trial report on your own solver, seeded bugs written by someone other than the author, adapters, documentation. See [CONTRIBUTING.md](https://github.com/rcgiri-physics/physverify/blob/main/CONTRIBUTING.md). To cite, use [doi:10.5281/zenodo.23534512](https://doi.org/10.5281/zenodo.23534512) or [CITATION.cff](https://github.com/rcgiri-physics/physverify/blob/main/CITATION.cff). Changes: [CHANGELOG.md](https://github.com/rcgiri-physics/physverify/blob/main/CHANGELOG.md); plans: [ROADMAP.md](https://github.com/rcgiri-physics/physverify/blob/main/ROADMAP.md). MIT licence, copyright (c) 2026 Ram Chandra Giri.
+Help is welcome: a trial report on your own solver, seeded bugs written by someone other than the author, adapters, documentation. See [CONTRIBUTING.md](https://github.com/rcgiri-physics/physverify/blob/main/CONTRIBUTING.md), the [code of conduct](https://github.com/rcgiri-physics/physverify/blob/main/CODE_OF_CONDUCT.md), [SUPPORT.md](https://github.com/rcgiri-physics/physverify/blob/main/SUPPORT.md) for help, [SECURITY.md](https://github.com/rcgiri-physics/physverify/blob/main/SECURITY.md) on running untrusted code, and [AGENTS.md](https://github.com/rcgiri-physics/physverify/blob/main/AGENTS.md) for AI assistants. To cite, use [doi:10.5281/zenodo.23534512](https://doi.org/10.5281/zenodo.23534512) or [CITATION.cff](https://github.com/rcgiri-physics/physverify/blob/main/CITATION.cff). Changes: [CHANGELOG.md](https://github.com/rcgiri-physics/physverify/blob/main/CHANGELOG.md); plans: [ROADMAP.md](https://github.com/rcgiri-physics/physverify/blob/main/ROADMAP.md). MIT licence, copyright (c) 2026 Ram Chandra Giri.
+
+<!-- mcp-name: io.github.rcgiri-physics/physverify -->

{physverify-0.4.2 → physverify-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "physverify"
-version = "0.4.2"
+version = "0.5.1"
 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"
@@ -52,4 +52,4 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-pythonpath = ["src"]
+pythonpath = ["src", "benchmark"]

{physverify-0.4.2 → physverify-0.5.1}/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.4.2"
+__version__ = "0.5.1"
 
 __all__ = [
     "Check",

{physverify-0.4.2 → physverify-0.5.1}/src/physverify/agent.py

@@ -55,7 +55,9 @@ def find_specs(root: Path) -> list[Path]:
         except Exception:
             config = {}
         if config.get("specs"):
-            return [(root / s).resolve() for s in config["specs"]]
+            # Entries that leave the root are dropped (GCVE-110-VULN-PYPI-2026-000391).
+            inside = root.resolve()
+            return [p for p in ((root / s).resolve() for s in config["specs"]) if p.is_relative_to(inside)]
     specs = []
     for path in sorted(root.rglob("verify_*.py")):
         parts = path.relative_to(root).parts[:-1]
@@ -111,8 +113,12 @@ def hook_main(stdin=None, stderr=None) -> int:
     edited = tool_input.get("file_path") or tool_input.get("notebook_path") or ""
     if edited and not edited.endswith(".py"):
         return 0
-    cwd = Path(event.get("cwd") or ".")
+    cwd = Path(event.get("cwd") or ".").resolve()
+    if edited and not Path(edited).resolve().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)
+    if not root.is_relative_to(cwd):
+        root = cwd  # never climb above the session folder
     specs = find_specs(root)
     if not specs:
         return 0

{physverify-0.4.2 → physverify-0.5.1}/src/physverify/cli.py

@@ -3,8 +3,8 @@
     physverify run SPEC.py [SPEC.py ...] [--json FILE|-] [--html FILE] [--markdown FILE] [--quiet]
     physverify demo        (a correct and a broken solver, no files needed)
     physverify init [SPEC.py] [--solver MODULE] [--function NAME] [--dim N] [--order P]
-    physverify matrix [OUT.md]
-    physverify compare [OUT.md]
+    physverify scan PATH   (reads the source, runs nothing: constants, RK tables, grid spacing, inverse pairs,
+                           undefined names, removed APIs, typo-like literals, unit tables)
     physverify hook        (Claude Code PostToolUse hook; see docs/agent.md)
     physverify mcp         (MCP server on stdio; see docs/agent.md)
 
@@ -98,18 +98,6 @@ def _cmd_demo(args) -> int:
     return demo_main()
 
 
-def _cmd_matrix(args) -> int:
-    from . import matrix
-
-    return matrix.main([args.out] if args.out else [])
-
-
-def _cmd_compare(args) -> int:
-    from . import compare
-
-    return compare.main([args.out] if args.out else [])
-
-
 def _cmd_hook(args) -> int:
     from .agent import hook_main
 
@@ -134,6 +122,37 @@ def _cmd_smoke(args) -> int:
     return 1 if bad else 0
 
 
+def _cmd_scan(args) -> int:
+    import json
+
+    from .scan import STAGES, WARN, scan, to_dict
+
+    stages = args.only.split(",") if args.only else STAGES
+    unknown = set(stages) - set(STAGES)
+    if unknown:
+        print(f"physverify: unknown stage {', '.join(sorted(unknown))}; choose from {', '.join(STAGES)}", file=sys.stderr)
+        return 2
+    if not Path(args.path).exists():
+        print(f"physverify: {args.path} does not exist", file=sys.stderr)
+        return 2
+    findings, unparsed = scan(args.path, stages=stages)
+    if args.json:
+        text = json.dumps(to_dict(findings, unparsed), indent=1)
+        if args.json == "-":
+            print(text)
+        else:
+            Path(args.json).write_text(text, encoding="utf-8")
+    if args.json != "-":
+        for f in findings:
+            print(f)
+        for u in unparsed:
+            print(f"NOTE parse     {u}")
+        warn = sum(f.level == WARN for f in findings)
+        print(f"{warn} warnings, {len(findings) - warn} notes, {len(unparsed)} files not parsed"
+              " (the scan reads the code and runs nothing; a clean scan means only that these patterns were not found)")
+    return 1 if any(f.level == WARN for f in findings) else 0
+
+
 def _cmd_references(args) -> int:
     from . import references
 
@@ -173,14 +192,6 @@ def build_parser() -> argparse.ArgumentParser:
     i.add_argument("--force", action="store_true", help="overwrite an existing file")
     i.set_defaults(func=_cmd_init)
 
-    m = sub.add_parser("matrix", help="run the seeded-bug benchmark")
-    m.add_argument("out", nargs="?", help="also write the tables next to this Markdown file")
-    m.set_defaults(func=_cmd_matrix)
-
-    c = sub.add_parser("compare", help="compare the families with plain tests on the seeded bugs")
-    c.add_argument("out", nargs="?", help="also write the table to this Markdown file")
-    c.set_defaults(func=_cmd_compare)
-
     h = sub.add_parser("hook", help="Claude Code PostToolUse hook: reads the event on stdin, exits 2 on a failed check")
     h.set_defaults(func=_cmd_hook)
 
@@ -189,6 +200,12 @@ def build_parser() -> argparse.ArgumentParser:
     sm.add_argument("--timeout", type=float, default=60.0, help="seconds per script (default 60)")
     sm.set_defaults(func=_cmd_smoke)
 
+    sc = sub.add_parser("scan", help="look for common defects without a spec file; reads the code and runs nothing")
+    sc.add_argument("path", help="a Python file or a folder")
+    sc.add_argument("--only", metavar="STAGES", help="comma-separated stages: constants,tables,grid,pairs,names,api,literals,units (default all)")
+    sc.add_argument("--json", metavar="FILE", help="write findings as JSON to FILE, or to stdout with -")
+    sc.set_defaults(func=_cmd_scan)
+
     r = sub.add_parser("references", help="list the exact reference solutions in physverify.references")
     r.set_defaults(func=_cmd_references)
 

{physverify-0.4.2 → physverify-0.5.1}/src/physverify/constants.py

@@ -32,8 +32,27 @@ KNOWN = {
     "e (charge)": ((1.602176634e-19,), "C", "exact: 1.602176634e-19"),
     "m_e": ((9.1093837015e-31, 9.1093837139e-31), "kg", "CODATA 2018: 9.1093837015e-31, 2022: 9.1093837139e-31"),
     "m_p": ((1.67262192369e-27, 1.67262192595e-27), "kg", "CODATA 2018: 1.67262192369e-27, 2022: 1.67262192595e-27"),
+    "m_n": ((1.67492749804e-27, 1.67492750056e-27), "kg", "CODATA 2018: 1.67492749804e-27, 2022: 1.67492750056e-27"),
+    "atomic mass unit": ((1.66053906660e-27, 1.66053906892e-27), "kg", "CODATA 2018: 1.66053906660e-27, 2022: 1.66053906892e-27"),
     "epsilon_0": ((8.8541878128e-12,), "F/m", "8.8541878128e-12"),
     "T_c (2D Ising)": ((2 / math.log(1 + math.sqrt(2)),), "J/k_B", "2 / ln(1 + sqrt 2) = 2.269185314"),
+    # exact by definition (SI 2019, IAU 2012, international units)
+    "N_A": ((6.02214076e23,), "1/mol", "exact: 6.02214076e23"),
+    "R (gas constant)": ((8.31446261815324,), "J/(mol K)", "exact: N_A k_B = 8.31446261815324"),
+    "sigma (Stefan-Boltzmann)": ((5.670374419e-8,), "W m^-2 K^-4", "5.670374419e-8"),
+    "astronomical unit": ((149597870700.0, 149597870.7, 1.495978707e13), "m, km or cm", "exact: 149597870700 m (IAU 2012)"),
+    "light year": ((9460730472580800.0,), "m", "exact: 9460730472580800 m (Julian year)"),
+    "parsec": ((3.0856775814913673e16,), "m", "648000/pi au = 3.0856775814913673e16 m"),
+    "standard atmosphere": ((101325.0,), "Pa", "exact: 101325 Pa"),
+    "torr": ((101325 / 760,), "Pa", "exact: 101325/760 = 133.32236842 Pa (mmHg is 133.322387415 Pa)"),
+    "nautical mile": ((1852.0,), "m", "exact: 1852 m"),
+    # the same constants in CGS, so a CGS block can be compared with an SI one
+    "h (CGS)": ((6.62607015e-27,), "erg s", "exact: 6.62607015e-27"),
+    "k_B (CGS)": ((1.380649e-16,), "erg/K", "exact: 1.380649e-16"),
+    "c (CGS)": ((2.99792458e10,), "cm/s", "exact: 2.99792458e10"),
+    "e (esu)": ((4.803204712570263e-10,), "statC", "4.803204712570263e-10"),
+    "m_e (g)": ((9.1093837015e-28, 9.1093837139e-28), "g", "CODATA 2018: 9.1093837015e-28, 2022: 9.1093837139e-28"),
+    "G (CGS)": ((6.67430e-8, 6.674e-8), "cm^3 g^-1 s^-2", "CODATA 2018: 6.67430e-8"),
 }
 
 

physverify-0.5.1/src/physverify/identities.py

@@ -0,0 +1,157 @@
+"""Checks that need no exact solution: round trips, derivatives, sibling agreement and identities.
+
+These are the checks that found most of the bugs in the batch-8 corpus study (popular libraries):
+two functions that should agree but do not (an air-absorption term with the opposite sign in one
+of two reverberation formulas), an operation that should be undone by its inverse but is not
+(a zero-time rotation that shifts an image by half a pixel), an analytic derivative compared with
+finite differences, and textbook identities (Poisson's equation, unitarity, conservation).
+
+Each function returns a `Result` (PASS or FAIL with the worst case in the message); wrap it in a
+`Check("limit", label, lambda: ...)` to run it with the others. Values may be real or complex scalars
+or arrays. The reference side must come from the physics, not from the code under test: a round trip
+or a sibling comparison can pass when both sides share the same mistake.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Iterable
+
+import numpy as np
+
+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)."""
+    g = np.asarray(got)
+    r = np.asarray(ref)
+    if g.shape != r.shape:
+        try:
+            g, r = np.broadcast_arrays(g, r)
+        except ValueError:
+            raise ValueError(f"shapes differ: got {np.shape(got)}, reference {np.shape(ref)}") from None
+    err = np.abs(g - r)
+    tol = atol + rtol * np.abs(r)
+    excess = err - tol
+    if excess.size == 0:
+        return -np.inf, 0.0, ()
+    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
+    i = np.unravel_index(int(np.argmax(excess)), excess.shape)
+    return float(excess[i]), float(err[i]), i
+
+
+def _verdict(what: str, cases, rtol: float, atol: float) -> Result:
+    """cases: iterable of (label, got, ref). PASS when every case is within tolerance."""
+    worst = None
+    n = 0
+    for label, got, ref in cases:
+        n += 1
+        excess, err, where = _worst(got, ref, rtol, atol)
+        if worst is None or excess > worst[0]:
+            worst = (excess, err, label, where, got, ref)
+    if worst is None:
+        raise ValueError(f"{what}: no inputs given")
+    excess, err, label, where, got, ref = 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}")
+
+
+def check_roundtrip(forward: Callable, inverse: Callable, inputs: Iterable, *, rtol: float = 1e-9, atol: float = 0.0) -> Result:
+    """inverse(forward(x)) == x for every x in `inputs`.
+
+    Catches conversions that disagree with their own inverse: a reference pixel off by half a pixel,
+    a dewpoint formula that does not invert the saturation formula, a unit conversion with the wrong
+    constant on one side. Both functions come from the code under test, so a PASS says only that
+    they are consistent, not that either is right.
+    """
+    cases = []
+    for x in inputs:
+        cases.append((repr(x) if np.ndim(x) == 0 else f"input of shape {np.shape(x)}", inverse(forward(x)), x))
+    return _verdict("round trip inverse(forward(x)) = x", cases, rtol, atol)
+
+
+def check_agree(a: Callable, b: Callable, inputs: Iterable, *, rtol: float = 1e-9, atol: float = 0.0,
+                names: tuple[str, str] = ("a", "b")) -> Result:
+    """Two implementations that must give the same answer do: a(*x) == b(*x) for each x in `inputs`.
+
+    Use it for sibling code paths (a 2D and a 3D version, a fast path and a slow path, the `min` and
+    `max` variants, two formulas that coincide in a limit). Each element of `inputs` is a tuple of
+    arguments, or a single argument.
+    """
+    cases = []
+    for x in inputs:
+        args = x if isinstance(x, tuple) else (x,)
+        cases.append((repr(x), a(*args), b(*args)))
+    return _verdict(f"{names[0]} agrees with {names[1]}", cases, rtol, atol)
+
+
+def fd_derivative(f: Callable, x, *, h: float | None = None, order: int = 1):
+    """Central finite-difference derivative of f at x (scalar x), with one Richardson step.
+
+    `order` is 1 or 2 (first or second derivative). The default step is cbrt(machine epsilon) times
+    max(1, |x|) for the first derivative and its square root for the second; the Richardson step
+    combines h and h/2 to cancel the leading error term.
+    """
+    x = float(x)
+    if order == 1:
+        h = h or np.cbrt(np.finfo(float).eps) * max(1.0, abs(x))
+        d = lambda s: (np.asarray(f(x + s)) - np.asarray(f(x - s))) / (2 * s)  # noqa: E731
+    elif order == 2:
+        h = h or np.finfo(float).eps ** 0.25 * max(1.0, abs(x))
+        d = lambda s: (np.asarray(f(x + s)) - 2 * np.asarray(f(x)) + np.asarray(f(x - s))) / (s * s)  # noqa: E731
+    else:
+        raise ValueError("order must be 1 or 2")
+    return (4 * d(h / 2) - d(h)) / 3
+
+
+def check_derivative(f: Callable, df: Callable, points: Iterable, *, order: int = 1, h: float | None = None,
+                     rtol: float = 1e-6, atol: float = 1e-10) -> Result:
+    """An analytic derivative `df` agrees with a finite-difference derivative of `f` at each point.
+
+    This is how a thermodynamic-consistency claim is settled cheaply: a reader's derivation said an
+    activity-coefficient derivative dropped a term, and comparing it with finite differences of the
+    activity coefficients themselves showed agreement to 1e-10, so the claim was wrong. The default
+    tolerance allows for the finite-difference error; tighten it only with a well-scaled `h`.
+    """
+    cases = [(f"x = {p!r}", df(p), fd_derivative(f, p, h=h, order=order)) for p in points]
+    return _verdict(f"{'first' if order == 1 else 'second'} derivative agrees with finite differences", cases, rtol, atol)
+
+
+def check_identity(cases: Iterable, *, rtol: float = 1e-9, atol: float = 0.0, what: str = "identity") -> Result:
+    """Each (label, lhs, rhs) in `cases` satisfies lhs == rhs.
+
+    For identities written from the physics: Poisson's equation (Laplacian of the potential equals
+    4 pi G rho), unitarity of a lossless scattering matrix (S^H S = I), E^2 = p^2 + m^2, a limit that
+    must reproduce a simpler formula. Compute the right-hand side yourself, not with the code under test.
+    """
+    return _verdict(what, list(cases), rtol, atol)
+
+
+def laplacian_fd(f: Callable, point, *, h: float = 1e-3):
+    """Cartesian Laplacian of a scalar field f(x) (x a 1D array) by second-order central differences."""
+    x = np.asarray(point, dtype=float)
+    f0 = f(x)
+    total = 0.0
+    for k in range(x.size):
+        e = np.zeros_like(x)
+        e[k] = h
+        total = total + (f(x + e) - 2 * f0 + f(x - e)) / (h * h)
+    return total
+
+
+def check_unitary(matrix, *, atol: float = 1e-10) -> Result:
+    """A matrix (or a stack of matrices, last two axes) is unitary: M^H M = I.
+
+    A lossless network's scattering matrix, a time-evolution operator, a rotation.
+    """
+    m = np.asarray(matrix)
+    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)