physverify 0.1.0__tar.gz → 0.3.0__tar.gz

{physverify-0.1.0/src/physverify.egg-info → physverify-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: physverify
-Version: 0.1.0
+Version: 0.3.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
@@ -39,7 +39,7 @@ Dynamic: license-file
 
 **A tool that checks whether a physics simulation is solving the right equations correctly, not just running without errors.**
 
-Status: early version (0.1.0). Nobody besides the author has used it yet, so feedback is very welcome.
+Status: early version (0.3.0). It has been tried on 68 public physics repositories (see below), but nobody besides the author has used it yet, so feedback is very welcome.
 
 ## The problem it addresses
 
@@ -51,9 +51,10 @@ physverify uses a few standard ideas from numerical analysis:
 
 1. **Make up an answer, then check the code finds it.** Pick a smooth function, work out what extra push (a "source term") would make it an exact solution, give that push to your code, and see if your code reproduces the function. This is called the *Method of Manufactured Solutions*.
 2. **Check the error shrinks at the right speed.** If your method is supposed to be 4th order, halving the time step should make the error about 16 times smaller. If it only gets 2 times smaller, something is wrong, even if the error looked small.
-3. **Check conserved quantities.** Energy, mass or momentum should stay constant (or drift in a predictable way).
+3. **Check conserved quantities and budgets.** Energy, mass or momentum should stay constant (or drift in a predictable way), and heat added through a wall or a source should match what went in, exactly, on every grid.
 4. **Check known special cases.** For example, a projectile with no air resistance has a range you can write down by hand.
 5. **Exact "patch" tests.** Some solutions should be reproduced to computer precision. This catches small bugs that the other checks let through.
+6. **Algebraic checks on the method itself.** For a Runge-Kutta method, whether the coefficients really have the order they claim can be settled exactly, with no test problem (the "order conditions").
 
 Each check reports **PASS**, **FAIL**, **EXACT** or **INCONCLUSIVE**.
 
@@ -67,10 +68,23 @@ To test it, 37 bugs were added one at a time to five small solvers (projectile,
 - **0 false alarms** on the bug-free versions.
 - The 2 missed bugs are explained in the [technical details](https://github.com/rcgiri-physics/physverify/blob/main/docs/technical.md).
 
-For the Monte Carlo checks, all 20 seeded bugs were caught with no false alarms.
+For the Monte Carlo checks, all 21 seeded bugs were caught with no false alarms.
 
 The bugs and the checks were written by the same person, so these numbers show the tool works as designed. They are not a promise about bugs in other people's code.
 
+## Trying it on other people's code
+
+To see what it does on code it was not written for, public Python physics repositories from GitHub were run in a locked-down container (October 2026): no network, the repository read-only, nothing from it run on the author's computer. 40 were drawn at random from topic searches (batches 1 to 4); another 60 were the newest small repositories whose README says the work is complete (batch 5), and 20 more were picked because they are quick to test (batch 6); batches 5 and 6 are not random.
+
+- **68 of the 120 could be tested.** Most of the others were not numerical solvers (neural networks, apps and games, analysis tools, finance), one needed a recent NVIDIA GPU, and a few need more set-up.
+- **16 confirmed bugs in 12 of the 68.** For example: a measured energy that counts the magnetic-field term twice; backward time-stepping that is only first-order accurate; Runge-Kutta coefficient tables labelled with a higher order than they have; a spectral derivative that crashes for an odd number of grid points; boundary values applied after the linear solve instead of inside it; an insulated wall that leaks heat; a grid spacing off by one interval; a Kepler solver that fails for negative angles.
+- **The rest had no confirmed bug.** Most passed every check that applied, often to 1e-13 or better.
+- **Our own adapters were wrong about 28 times** before checking (a wrong constant, too-coarse steps, a wrong sign convention, and so on). Every FAIL was checked by hand before being called a bug, and these mistakes are recorded, not hidden.
+
+These counts describe the repositories that were drawn; they are not a bug rate for physics code in general.
+
+Each lesson became a new check or a clearer message in physverify. The testing and write-ups were done with help from an AI assistant; every number comes from running the code. Authors are told about a finding before their project is named, so the repositories are listed by ID: [results/corpus/SUMMARY.md](https://github.com/rcgiri-physics/physverify/blob/main/results/corpus/SUMMARY.md).
+
 ## Try it
 
 You need Python 3.10 or newer.
@@ -108,6 +122,8 @@ pytest my_spec.py                              # each check becomes a pytest tes
 
 ## More
 
+- [results/corpus/SUMMARY.md](https://github.com/rcgiri-physics/physverify/blob/main/results/corpus/SUMMARY.md): the 120 public repositories, what was tested and what was found.
+- [sandbox/README.md](https://github.com/rcgiri-physics/physverify/blob/main/sandbox/README.md): the locked-down container used to run other people's code.
 - [results/own_work/SUMMARY.md](https://github.com/rcgiri-physics/physverify/blob/main/results/own_work/SUMMARY.md): results on four of the author's own public physics projects (two real bugs found and fixed).
 - [docs/technical.md](https://github.com/rcgiri-physics/physverify/blob/main/docs/technical.md): full details, benchmark tables, limits and related work.
 - [docs/patch.md](https://github.com/rcgiri-physics/physverify/blob/main/docs/patch.md): what the exact "patch" checks assume.

{physverify-0.1.0 → physverify-0.3.0}/README.md

@@ -2,7 +2,7 @@
 
 **A tool that checks whether a physics simulation is solving the right equations correctly, not just running without errors.**
 
-Status: early version (0.1.0). Nobody besides the author has used it yet, so feedback is very welcome.
+Status: early version (0.3.0). It has been tried on 68 public physics repositories (see below), but nobody besides the author has used it yet, so feedback is very welcome.
 
 ## The problem it addresses
 
@@ -14,9 +14,10 @@ physverify uses a few standard ideas from numerical analysis:
 
 1. **Make up an answer, then check the code finds it.** Pick a smooth function, work out what extra push (a "source term") would make it an exact solution, give that push to your code, and see if your code reproduces the function. This is called the *Method of Manufactured Solutions*.
 2. **Check the error shrinks at the right speed.** If your method is supposed to be 4th order, halving the time step should make the error about 16 times smaller. If it only gets 2 times smaller, something is wrong, even if the error looked small.
-3. **Check conserved quantities.** Energy, mass or momentum should stay constant (or drift in a predictable way).
+3. **Check conserved quantities and budgets.** Energy, mass or momentum should stay constant (or drift in a predictable way), and heat added through a wall or a source should match what went in, exactly, on every grid.
 4. **Check known special cases.** For example, a projectile with no air resistance has a range you can write down by hand.
 5. **Exact "patch" tests.** Some solutions should be reproduced to computer precision. This catches small bugs that the other checks let through.
+6. **Algebraic checks on the method itself.** For a Runge-Kutta method, whether the coefficients really have the order they claim can be settled exactly, with no test problem (the "order conditions").
 
 Each check reports **PASS**, **FAIL**, **EXACT** or **INCONCLUSIVE**.
 
@@ -30,10 +31,23 @@ To test it, 37 bugs were added one at a time to five small solvers (projectile,
 - **0 false alarms** on the bug-free versions.
 - The 2 missed bugs are explained in the [technical details](https://github.com/rcgiri-physics/physverify/blob/main/docs/technical.md).
 
-For the Monte Carlo checks, all 20 seeded bugs were caught with no false alarms.
+For the Monte Carlo checks, all 21 seeded bugs were caught with no false alarms.
 
 The bugs and the checks were written by the same person, so these numbers show the tool works as designed. They are not a promise about bugs in other people's code.
 
+## Trying it on other people's code
+
+To see what it does on code it was not written for, public Python physics repositories from GitHub were run in a locked-down container (October 2026): no network, the repository read-only, nothing from it run on the author's computer. 40 were drawn at random from topic searches (batches 1 to 4); another 60 were the newest small repositories whose README says the work is complete (batch 5), and 20 more were picked because they are quick to test (batch 6); batches 5 and 6 are not random.
+
+- **68 of the 120 could be tested.** Most of the others were not numerical solvers (neural networks, apps and games, analysis tools, finance), one needed a recent NVIDIA GPU, and a few need more set-up.
+- **16 confirmed bugs in 12 of the 68.** For example: a measured energy that counts the magnetic-field term twice; backward time-stepping that is only first-order accurate; Runge-Kutta coefficient tables labelled with a higher order than they have; a spectral derivative that crashes for an odd number of grid points; boundary values applied after the linear solve instead of inside it; an insulated wall that leaks heat; a grid spacing off by one interval; a Kepler solver that fails for negative angles.
+- **The rest had no confirmed bug.** Most passed every check that applied, often to 1e-13 or better.
+- **Our own adapters were wrong about 28 times** before checking (a wrong constant, too-coarse steps, a wrong sign convention, and so on). Every FAIL was checked by hand before being called a bug, and these mistakes are recorded, not hidden.
+
+These counts describe the repositories that were drawn; they are not a bug rate for physics code in general.
+
+Each lesson became a new check or a clearer message in physverify. The testing and write-ups were done with help from an AI assistant; every number comes from running the code. Authors are told about a finding before their project is named, so the repositories are listed by ID: [results/corpus/SUMMARY.md](https://github.com/rcgiri-physics/physverify/blob/main/results/corpus/SUMMARY.md).
+
 ## Try it
 
 You need Python 3.10 or newer.
@@ -71,6 +85,8 @@ pytest my_spec.py                              # each check becomes a pytest tes
 
 ## More
 
+- [results/corpus/SUMMARY.md](https://github.com/rcgiri-physics/physverify/blob/main/results/corpus/SUMMARY.md): the 120 public repositories, what was tested and what was found.
+- [sandbox/README.md](https://github.com/rcgiri-physics/physverify/blob/main/sandbox/README.md): the locked-down container used to run other people's code.
 - [results/own_work/SUMMARY.md](https://github.com/rcgiri-physics/physverify/blob/main/results/own_work/SUMMARY.md): results on four of the author's own public physics projects (two real bugs found and fixed).
 - [docs/technical.md](https://github.com/rcgiri-physics/physverify/blob/main/docs/technical.md): full details, benchmark tables, limits and related work.
 - [docs/patch.md](https://github.com/rcgiri-physics/physverify/blob/main/docs/patch.md): what the exact "patch" checks assume.

{physverify-0.1.0 → physverify-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "physverify"
-version = "0.1.0"
+version = "0.3.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.1.0 → physverify-0.3.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.1.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "Check",

physverify-0.3.0/src/physverify/butcher.py

@@ -0,0 +1,111 @@
+"""Order of a Runge-Kutta method from its Butcher table, by the order conditions.
+
+A Runge-Kutta method (A, b, c) has order p exactly when b . Phi(t) = 1 / gamma(t) for every rooted
+tree t with at most p vertices (Butcher). This is algebra on the coefficients: it needs no test
+problem, cannot be fooled by a lucky cancellation or a superconvergent test equation, and works the
+same for explicit and implicit methods.
+
+Lessons from testing other people's code: one package's `order` labels were wrong for 3 of its
+tables (one claimed 4 where the table satisfies only the order-3 conditions), and another's embedded
+weights for Tsitouras 5(4) did not even sum to 1. Order studies on test equations found both, but
+were slower to adjudicate than this check.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+
+from .checks import FAIL, PASS, Result
+
+
+@lru_cache(maxsize=None)
+def trees(order: int) -> tuple:
+    """All rooted trees with `order` vertices, each a sorted tuple of child subtrees."""
+    if order == 1:
+        return ((),)
+    out = set()
+
+    def forests(n, max_child):
+        # multisets of trees with n vertices in total, children in non-increasing canonical order
+        if n == 0:
+            yield ()
+            return
+        for k in range(n, 0, -1):
+            for t in trees(k):
+                if max_child is not None and (k, t) > max_child:
+                    continue
+                for rest in forests(n - k, (k, t)):
+                    yield ((k, t),) + rest
+
+    for forest in forests(order - 1, None):
+        out.add(tuple(sorted((t for _, t in forest), key=repr)))
+    return tuple(sorted(out, key=repr))
+
+
+def _size(t) -> int:
+    return 1 + sum(_size(s) for s in t)
+
+
+def _gamma(t) -> int:
+    g = _size(t)
+    for s in t:
+        g *= _gamma(s)
+    return g
+
+
+def _phi(t, A, e):
+    v = e.copy()
+    for s in t:
+        v = v * (A @ _phi(s, A, e))
+    return v
+
+
+def order_residuals(A, b, max_order: int = 6) -> dict:
+    """{order: largest |b . Phi(t) - 1/gamma(t)| over the trees of that order}."""
+    A = np.asarray(A, dtype=float)
+    b = np.asarray(b, dtype=float)
+    e = np.ones(len(b))
+    return {p: max(abs(float(b @ _phi(t, A, e)) - 1.0 / _gamma(t)) for t in trees(p)) for p in range(1, max_order + 1)}
+
+
+def tableau_order(A, b, *, max_order: int = 6, tol: float = 1e-8) -> int:
+    """Highest p <= max_order such that every condition up to order p holds within tol."""
+    p = 0
+    for q, r in order_residuals(A, b, max_order).items():
+        if r > tol:
+            break
+        p = q
+    return p
+
+
+def check_tableau(A, b, c=None, *, claimed: int, label: str = "", tol: float = 1e-8, max_order: int | None = None) -> Result:
+    """PASS when the table has at least the claimed order; FAIL when it has less.
+
+    The default tolerance 1e-8 accepts coefficients typed with 9 or 10 digits (a real package had
+    residuals of 2e-10 for that reason), while a missing order shows residuals of 1e-4 or more.
+    The message gives the residuals, so a table whose conditions hold only to about 1e-10 is visible, and a claim that is lower than the true
+    order is noted rather than failed. If `c` is given, the row sums of A are compared with it.
+    """
+    top = max_order or claimed + 1
+    res = order_residuals(A, b, top)
+    p = tableau_order(A, b, max_order=top, tol=tol)
+    shown = ", ".join(f"{q}: {r:.1e}" for q, r in res.items())
+    prefix = f"{label}: " if label else ""
+    notes = []
+    if c is not None:
+        rs = float(np.max(np.abs(np.asarray(A, float).sum(axis=1) - np.asarray(c, float))))
+        if rs > tol:
+            notes.append(f"row sums of A differ from c by {rs:.1e}")
+    worst_kept = max((r for q, r in res.items() if q <= max(p, 1)), default=0.0)
+    if p >= 1 and worst_kept > 1e-13:
+        notes.append(f"conditions hold only to {worst_kept:.0e} (coefficients with limited digits?)")
+    tail = ("; " + "; ".join(notes)) if notes else ""
+    if p < claimed:
+        return Result(FAIL, f"{prefix}claims order {claimed} but satisfies the order conditions only up to {p} "
+                            f"(largest residual per order: {shown}){tail}")
+    if p > claimed:
+        return Result(PASS, f"{prefix}claims order {claimed}; the conditions hold up to at least {p}, so the claim is "
+                            f"conservative ({shown}){tail}")
+    return Result(PASS, f"{prefix}order {claimed} confirmed by the order conditions ({shown}){tail}")

physverify-0.3.0/src/physverify/constants.py

@@ -0,0 +1,121 @@
+"""Find numeric literals in source code that are close to, but not equal to, a physical constant.
+
+Lessons from testing other people's code: a gravitational constant in au^3 / (Msun yr^2) of
+39.4769 (Gaussian, 365.25-day year) next to an orbital speed of 2 pi (which assumes 4 pi^2 = 39.4784),
+g = 9 in a projectile game, pi typed as 3.14. None of these is necessarily a bug, but each is worth
+one look, and an adapter's reference must use the code's value, not the textbook one.
+
+`scan(path)` returns notes, never failures: the code may be right to round.
+Several CODATA editions are accepted. When writing a reference, use the edition the code says it uses:
+one adapter failed at 1.35e-9 by taking the 2022 proton mass where the code stated 2018.
+"""
+
+from __future__ import annotations
+
+import ast
+import math
+from dataclasses import dataclass
+from pathlib import Path
+
+# name: (accepted values, unit, comment)
+KNOWN = {
+    "pi": ((math.pi,), "", "use math.pi or numpy.pi"),
+    "e (Euler)": ((math.e,), "", "use math.e or numpy.e"),
+    "g": ((9.80665, 9.81, 9.8), "m/s^2", "standard gravity 9.80665"),
+    "G (SI)": ((6.67430e-11, 6.674e-11, 6.67e-11), "m^3 kg^-1 s^-2", "CODATA 2018: 6.67430e-11"),
+    "G M_sun / 4 pi^2 (au, yr)": ((4 * math.pi**2,), "au^3 Msun^-1 yr^-2",
+                                  "4 pi^2 is exact for a 1 au, 1 yr circular orbit; 39.4769 is the Gaussian value for a 365.25-day year"),
+    "c": ((299792458.0, 3e8, 2.998e8), "m/s", "exact: 299792458"),
+    "h (Planck)": ((6.62607015e-34,), "J s", "exact: 6.62607015e-34"),
+    "hbar": ((1.054571817e-34,), "J s", "1.054571817e-34"),
+    "k_B": ((1.380649e-23,), "J/K", "exact: 1.380649e-23"),
+    "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"),
+    "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"),
+}
+
+
+@dataclass
+class Note:
+    line: int
+    literal: str
+    constant: str
+    nearest: float
+    relative: float
+    comment: str
+
+    def __str__(self):
+        return (f"line {self.line}: {self.literal} is {self.relative:+.2g} relative to {self.constant} "
+                f"({self.nearest:.10g}); {self.comment}")
+
+
+def _digits(x: float) -> int:
+    """Significant digits of a literal as written (3.14 -> 3)."""
+    s = repr(x).lower().split("e")[0].replace("-", "").replace(".", "").lstrip("0")
+    return max(len(s.rstrip("0")), 1)
+
+
+def check_value(value: float, *, max_rel: float = 0.1):
+    """(constant, nearest accepted value, relative difference) for a near miss, else None.
+
+    A value equal to an accepted value, or equal to it to the precision written with
+    at least 4 digits, is not a near miss: 3.1416 for pi and 9.81 for g are fine;
+    3.14 and 9 are noted.
+    """
+    if value == 0 or not math.isfinite(value):
+        return None
+    best = None
+    for name, (accepted, _unit, comment) in KNOWN.items():
+        for ref in accepted:
+            rel = value / ref - 1
+            if abs(rel) > max_rel:
+                continue
+            if value == ref:
+                return None
+            written = 0.5 * 10 ** (1 - _digits(value))  # half a unit in the last written digit, relative
+            if _digits(value) >= 4 and abs(rel) <= written * 1.0000001:
+                return None  # matches to the precision written, with at least 4 digits
+            if best is None or abs(rel) < abs(best[2]):
+                best = (name, ref, rel, comment)
+    return best
+
+
+# names under which a short literal (an integer, or fewer than 3 digits) is still taken to mean the constant
+NAMES = {"g": {"g", "grav", "gravity", "g_acc", "gacc"}, "G (SI)": {"G"}, "pi": {"pi", "PI"}, "c": {"c"}}
+
+
+def _assigned_names(tree):
+    """id(value node) -> names it is assigned to, for simple `name = literal` statements."""
+    out = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Assign):
+            out[id(node.value)] = {t.id for t in node.targets if isinstance(t, ast.Name)}
+        elif isinstance(node, ast.AnnAssign) and node.value is not None and isinstance(node.target, ast.Name):
+            out[id(node.value)] = {node.target.id}
+    return out
+
+
+def scan(path, *, max_rel: float = 0.1) -> list[Note]:
+    """Near-miss constants among the numeric literals of a Python file.
+
+    Literals with 3 or more significant digits are compared with every constant.
+    Integers and shorter literals (9, 3.1, 10) are so common that they are noted
+    only when assigned to a name that suggests the constant (g = 9).
+    """
+    path = Path(path)
+    tree = ast.parse(path.read_text(encoding="utf-8"), str(path))
+    names = _assigned_names(tree)
+    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)
+            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()):
+                    hit = None
+            if hit:
+                name, ref, rel, comment = hit
+                notes.append(Note(node.lineno, ast.unparse(node), name, ref, rel, comment))
+    return sorted(notes, key=lambda n: n.line)

physverify-0.3.0/src/physverify/loaders.py

@@ -0,0 +1,178 @@
+"""Import a module from a path without touching its folder.
+
+Used by the adapters that test other people's code. Nothing is written next to
+the module (no __pycache__), and optional plotting imports can be stubbed so a
+simulation file can be imported on a machine without matplotlib.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib
+import importlib.util
+import sys
+import types
+from pathlib import Path
+
+
+class Placeholder:
+    """Stand-in for a name from a module that is not installed.
+
+    Calling it returns another placeholder, except that calling it with a single
+    function returns that function, so stubbed decorators (``@app.route(...)``,
+    ``@jit``) leave the decorated code usable. Attribute access also returns a
+    placeholder. A tested code path that really uses the stub gets a placeholder
+    back instead of a result, which the checks then report.
+    """
+
+    def __init__(self, name: str = "stub"):
+        self._name = name
+
+    def __call__(self, *args, **kwargs):
+        if len(args) == 1 and not kwargs and callable(args[0]) and not isinstance(args[0], Placeholder):
+            return args[0]
+        return Placeholder(f"{self._name}()")
+
+    def __getattr__(self, attr):
+        if attr.startswith("__"):
+            raise AttributeError(attr)
+        return Placeholder(f"{self._name}.{attr}")
+
+    def __repr__(self):
+        return f"<stub {self._name}>"
+
+
+def _stub_module(name: str, attrs=()) -> types.ModuleType:
+    mod = types.ModuleType(name)
+    mod.__dict__["__stub__"] = True
+    for a in attrs:
+        setattr(mod, a, Placeholder(f"{name}.{a}"))
+    return mod
+
+
+def stub_modules(spec, *, force: bool = False) -> list[str]:
+    """Install stub modules for imports a tested code path does not use.
+
+    `spec` is an iterable of module names, or a mapping from a module name to the
+    names it must provide (``{"sklearn.metrics": ["accuracy_score"]}``), so that
+    ``from sklearn.metrics import accuracy_score`` succeeds. Parent packages are
+    created as needed. A module that imports for real is left alone unless
+    `force` is true. Returns the names installed.
+    """
+    items = spec.items() if hasattr(spec, "items") else ((s, ()) for s in spec)
+    installed = []
+    for name, attrs in items:
+        if not force:
+            try:
+                importlib.import_module(name)
+                continue
+            except ImportError:
+                pass
+        parts = name.split(".")
+        for i in range(1, len(parts)):
+            parent = ".".join(parts[:i])
+            if parent not in sys.modules:
+                sys.modules[parent] = _stub_module(parent)
+                installed.append(parent)
+        sys.modules[name] = _stub_module(name, attrs)
+        installed.append(name)
+        parent, _, child = name.rpartition(".")
+        if parent:
+            setattr(sys.modules[parent], child, sys.modules[name])
+    return installed
+
+
+def run_script(path, *, argv=(), stubs=None) -> tuple[dict, str]:
+    """Run a whole script as __main__ and return (its globals, what it printed).
+
+    For scripts whose results are only module-level variables (coursework,
+    notebooks exported to .py, demos). Matplotlib is switched to a non-interactive
+    backend and plt.show() does nothing, so the run never waits for a window.
+    """
+    import contextlib
+    import io
+    import runpy
+
+    if stubs:
+        stub_modules(stubs)
+    try:
+        import matplotlib
+
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+
+        plt.show = lambda *a, **k: None
+    except ImportError:
+        pass
+    old_argv = sys.argv
+    sys.argv = [str(path), *argv]
+    out = io.StringIO()
+    try:
+        with contextlib.redirect_stdout(out):
+            globs = runpy.run_path(str(path), run_name="__main__")
+    finally:
+        sys.argv = old_argv
+    return globs, out.getvalue()
+
+
+def load_module_from_path(name: str, path, stubs=()):
+    path = Path(path)
+    if not path.is_file():
+        raise FileNotFoundError(path)
+
+    added = stub_modules(stubs)
+
+    old_flag = sys.dont_write_bytecode
+    sys.dont_write_bytecode = True
+    try:
+        spec = importlib.util.spec_from_file_location(name, path)
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[name] = module
+        try:
+            spec.loader.exec_module(module)
+        except BaseException:
+            sys.modules.pop(name, None)  # do not leave a half-initialised module behind
+            raise
+    finally:
+        sys.dont_write_bytecode = old_flag
+        for stub in added:
+            sys.modules.pop(stub, None)
+    return module
+
+
+def load_definitions_from_path(name: str, path, *, keep=(), inner=(), namespace=None, stubs=()):
+    """Load only the definitions of a script whose top level runs a simulation.
+
+    Many research scripts parse argv, open a window or run a long simulation at
+    import. This executes only the top-level imports, functions and classes, and
+    the top-level assignments to the names in `keep` (constants the functions
+    use). `inner` names functions defined inside other functions (for example
+    marimo or Jupyter-exported cells); they are lifted to module level, and
+    their imports must then come from `namespace`.
+
+    Nothing else in the file runs, so a function that relies on a global set by
+    the skipped code fails with NameError; set it on the returned module.
+
+    `stubs` names modules (or maps module names to the names they must provide, see
+    `stub_modules`) to replace with stubs when they are not installed
+    (pygame, IPython, orbax, ...), for imports the tested functions do not use.
+    """
+    path = Path(path)
+    tree = ast.parse(path.read_text(encoding="utf-8"), str(path))
+    body = []
+    for node in tree.body:
+        if isinstance(node, (ast.Import, ast.ImportFrom, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            body.append(node)
+        elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+            if any(isinstance(t, ast.Name) and t.id in keep for t in targets):
+                body.append(node)
+    if inner:
+        wanted = set(inner)
+        body += [n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef) and n.name in wanted and n not in tree.body]
+    stub_modules(stubs)
+    module = types.ModuleType(name)
+    module.__file__ = str(path)
+    module.__dict__.update(namespace or {})
+    exec(compile(ast.Module(body=body, type_ignores=[]), str(path), "exec"), module.__dict__)
+    return module