physverify 0.1.0__py3-none-any.whl

physverify/__init__.py

@@ -0,0 +1,26 @@
+"""physverify: verification checks for physics simulation code."""
+
+from .checks import Check, OrderResult, Result
+from .mms import ManufacturedODE, mms_order_study, zero_source
+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"
+
+__all__ = [
+    "Check",
+    "ManufacturedODE",
+    "OrderResult",
+    "Result",
+    "check_exact",
+    "check_order",
+    "fit_order",
+    "invariant_study",
+    "mms_order_study",
+    "ode_checks",
+    "pairwise_orders",
+    "patch_study",
+    "reference_study",
+    "zero_source",
+]

physverify/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

physverify/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""Adapters that connect physverify to existing simulation code (read-only)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def sibling_project(env_var: str, folder: str) -> Path:
+    """Folder of another project: $env_var if set, else a sibling of this repository."""
+    if os.environ.get(env_var):
+        return Path(os.environ[env_var])
+    repo_root = Path(__file__).resolve().parents[3]
+    return repo_root.parent / folder

physverify/adapters/double_pendulum.py

@@ -0,0 +1,55 @@
+"""Adapter for double-pendulum-simulation/src/mechanics.py.
+
+Only the right-hand side (get_derivatives) and the energy (calculate_energy)
+are tested. They are stepped with physverify's own RK4, because the project's
+solvers.py needs SciPy. So these checks say nothing about solvers.py.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..checks import Check
+from ..loaders import load_module_from_path
+from ..problems import pendulum as P
+from ..problems._common import make_integrate
+from ..studies import ode_checks
+from . import sibling_project
+
+ENV_VAR = "PHYSVERIFY_PENDULUM_DIR"
+FOLDER = "double-pendulum-simulation"
+
+
+def source_path():
+    return sibling_project(ENV_VAR, FOLDER) / "src" / "mechanics.py"
+
+
+def load():
+    return load_module_from_path("double_pendulum_mechanics_under_test", source_path())
+
+
+def checks(module=None) -> list[Check]:
+    module = module or load()
+    params = dict(P.PARAMS)
+
+    def rhs(t, y):
+        return np.asarray(module.get_derivatives(t, y, params), dtype=float)
+
+    def energy(y):
+        return module.calculate_energy(y, **params)
+
+    out = ode_checks(
+        "mechanics.py RHS + physverify RK4",
+        make_integrate(rhs, frozenset(), "rk4"),
+        rhs_ref=P.rhs_reference(params),
+        mms=P.manufactured(),
+        y0_free=P.Y0_FREE,
+        t_end=P.MMS_T_END,
+        ns=P.NS_RK4,
+        order=4.0,
+        quantity=energy,
+        patch=P.PATCH,
+        integrate_trajectory=make_integrate(rhs, frozenset(), "rk4", trajectory=True),
+    )
+    out.append(P.frequency_check(rhs, label="mechanics.py small-oscillation frequencies"))
+    return out

physverify/adapters/lorenz.py

@@ -0,0 +1,152 @@
+"""Adapter for lorenz-attractor-simulation/src/mechanics.py (lorenz_derivatives).
+
+The project integrates with SciPy's solve_ivp, so only the right-hand side is
+under test here; it is stepped with physverify's own RK4. The flow is chaotic
+(largest Lyapunov exponent about 0.906), so trajectories are compared only up
+to t = 1, well inside one Lyapunov time's worth of growth (exp(0.9) < 3).
+Beyond that the project is checked through exact properties of the flow:
+fixed points, the constant divergence -(sigma + 1 + beta), and the Jacobian
+that scripts/calculate_lyapunov.py writes by hand.
+"""
+
+from __future__ import annotations
+
+import ast
+import math
+from pathlib import Path
+
+import numpy as np
+
+from ..checks import EXACT, FAIL, PASS, Check, Result
+from ..loaders import load_module_from_path
+from ..mms import ManufacturedODE
+from ..problems._common import make_integrate
+from ..studies import ode_checks
+from . import sibling_project
+
+ENV_VAR = "PHYSVERIFY_LORENZ_DIR"
+FOLDER = "lorenz-attractor-simulation"
+PARAMS = {"sigma": 10.0, "rho": 28.0, "beta": 8.0 / 3.0}
+Y0_FREE = np.array([1.0, 1.0, 1.0])
+T_END = 1.0
+NS_RK4 = (100, 200, 400, 800)
+
+
+def source_path():
+    return sibling_project(ENV_VAR, FOLDER) / "src" / "mechanics.py"
+
+
+def lyapunov_path():
+    return sibling_project(ENV_VAR, FOLDER) / "scripts" / "calculate_lyapunov.py"
+
+
+def load():
+    return load_module_from_path("lorenz_mechanics_under_test", source_path())
+
+
+def rhs_reference(p=PARAMS):
+    """From docs/theory.md, written in matrix-free form independently of the code."""
+    s, r, b = p["sigma"], p["rho"], p["beta"]
+
+    def f(t, u):
+        x, y, z = u
+        return np.array([s * y - s * x, r * x - x * z - y, x * y - b * z])
+
+    return f
+
+
+def manufactured() -> ManufacturedODE:
+    def u(t):
+        return np.array([2.0 * np.sin(t), 1.0 + np.cos(1.7 * t), 20.0 + 3.0 * np.sin(0.6 * t)])
+
+    return ManufacturedODE(u, rhs_reference())
+
+
+def fixed_points(p=PARAMS):
+    c = math.sqrt(p["beta"] * (p["rho"] - 1.0))
+    return [np.zeros(3), np.array([c, c, p["rho"] - 1.0]), np.array([-c, -c, p["rho"] - 1.0])]
+
+
+def central_jacobian(f, u, h=1e-3):
+    """Centred differences are exact (to round-off) for a quadratic field like Lorenz."""
+    jac = np.zeros((3, 3))
+    for j in range(3):
+        e = np.zeros(3)
+        e[j] = h
+        jac[:, j] = (np.asarray(f(0.0, u + e)) - np.asarray(f(0.0, u - e))) / (2 * h)
+    return jac
+
+
+SAMPLE_POINTS = [np.array(v) for v in ([1.0, 1.0, 1.0], [-8.3, 4.1, 27.0], [12.0, -3.0, 5.5], [0.0, 0.0, 0.0])]
+
+
+def fixed_point_check(rhs) -> Check:
+    def run():
+        worst = max(float(np.max(np.abs(rhs(0.0, p)))) for p in fixed_points())
+        if worst <= 1e-12 * 30:
+            return Result(EXACT, f"all three fixed points are zeros of the field (largest |f| = {worst:.1e})")
+        return Result(FAIL, f"field is {worst:.3g} at a fixed point")
+
+    return Check("limit", "fixed points 0 and (+-sqrt(beta(rho-1)), ., rho-1)", run)
+
+
+def divergence_check(rhs) -> Check:
+    expected = -(PARAMS["sigma"] + 1.0 + PARAMS["beta"])
+
+    def run():
+        divs = [float(np.trace(central_jacobian(rhs, p))) for p in SAMPLE_POINTS]
+        worst = max(abs(d - expected) for d in divs)
+        if worst <= 1e-9:
+            return Result(EXACT, f"divergence {divs[0]:.12f} = -(sigma+1+beta) at {len(divs)} points")
+        return Result(FAIL, f"divergence differs from {expected:.6f} by {worst:.3g}")
+
+    return Check("invariant", "flow divergence is constant -(sigma+1+beta)", run)
+
+
+def jacobian_check(rhs, jacobian) -> Check:
+    def run():
+        worst = max(
+            float(np.max(np.abs(np.asarray(jacobian(p, PARAMS)) - central_jacobian(rhs, p)))) for p in SAMPLE_POINTS
+        )
+        if worst <= 1e-9:
+            return Result(EXACT, f"hand-written Jacobian matches the field's derivative (max diff {worst:.1e})")
+        return Result(FAIL, f"hand-written Jacobian differs from the field's derivative by {worst:.3g}")
+
+    return Check("limit", "calculate_lyapunov.py Jacobian vs derivative of the field", run)
+
+
+def load_function(path, name):
+    """One top-level function from a script, without running the script's imports.
+
+    The script appends to sys.path and imports SciPy at module level; only the
+    function's own source is executed here, with numpy as np in scope.
+    """
+    tree = ast.parse(Path(path).read_text(encoding="utf-8"))
+    node = next(n for n in tree.body if isinstance(n, ast.FunctionDef) and n.name == name)
+    namespace = {"np": np}
+    exec(compile(ast.Module([node], []), str(path), "exec"), namespace)
+    return namespace[name]
+
+
+def checks(module=None) -> list[Check]:
+    module = module or load()
+
+    def rhs(t, y):
+        return np.asarray(module.lorenz_derivatives(t, y, PARAMS), dtype=float)
+
+    out = ode_checks(
+        "mechanics.py RHS + physverify RK4",
+        make_integrate(rhs, frozenset(), "rk4"),
+        rhs_ref=rhs_reference(),
+        mms=manufactured(),
+        y0_free=Y0_FREE,
+        t_end=T_END,
+        ns=NS_RK4,
+        order=4.0,
+        patch=(np.array([1.0, -2.0, 15.0]), np.array([0.5, 1.5, -2.0])),
+        integrate_trajectory=make_integrate(rhs, frozenset(), "rk4", trajectory=True),
+    )
+    out += [fixed_point_check(rhs), divergence_check(rhs)]
+    if lyapunov_path().is_file():
+        out.append(jacobian_check(rhs, load_function(lyapunov_path(), "lorenz_jacobian")))
+    return out

physverify/adapters/projectile_v1.py

@@ -0,0 +1,92 @@
+"""Adapter for projectile-simulation/src/projectile_sim_v1.py (class Projectile, forward Euler).
+
+simulate() returns only positions and runs until landing, with no source hook,
+so there is no MMS or patch check (row 25 of the audit plan). Positions at a
+fixed time are compared with the closed-form vacuum and linear-drag solutions
+from the README and with an RK4 reference for quadratic drag; the landing range
+is compared with the vacuum formula v0^2 sin(2 angle) / g. Forward Euler is
+first order by design, so order 1 is the pass mark.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from ..checks import Check
+from ..loaders import load_module_from_path
+from ..order import check_order
+from ..steppers import integrate_fixed, rk4
+from . import sibling_project
+
+ENV_VAR = "PHYSVERIFY_PROJECTILE_DIR"
+FOLDER = "projectile-simulation"
+MASS, RADIUS, V0, ANGLE = 0.145, 0.037, 30.0, 45.0
+T_END = 2.0
+NS = (200, 400, 800, 1600)
+
+
+def source_path():
+    return sibling_project(ENV_VAR, FOLDER) / "src" / "projectile_sim_v1.py"
+
+
+def load():
+    return load_module_from_path("projectile_sim_v1_under_test", source_path(), stubs=("matplotlib", "matplotlib.pyplot"))
+
+
+def exact_position(mode, t, k, g=9.81):
+    vx0 = V0 * math.cos(math.radians(ANGLE))
+    vy0 = V0 * math.sin(math.radians(ANGLE))
+    if mode == "vacuum":
+        return np.array([vx0 * t, vy0 * t - 0.5 * g * t * t])
+    if mode == "linear":
+        decay = 1.0 - math.exp(-k * t)
+        return np.array([vx0 / k * decay, (vy0 + g / k) / k * decay - g * t / k])
+    # quadratic: no closed form; RK4 on the README's equations with a fine step
+    def f(_t, z):
+        speed = math.hypot(z[2], z[3])
+        return np.array([z[2], z[3], -k * speed * z[2], -g - k * speed * z[3]])
+
+    return integrate_fixed(f, [0.0, 0.0, vx0, vy0], 0.0, t, 20000, rk4)[:2]
+
+
+def drag_constant(mode, viscosity=1.81e-5, cd=0.47, rho=1.225):
+    if mode == "linear":
+        return 6.0 * math.pi * viscosity * RADIUS / MASS
+    if mode == "quadratic":
+        return 0.5 * rho * math.pi * RADIUS**2 * cd / MASS
+    return 0.0
+
+
+def position_check(module, mode) -> Check:
+    def run():
+        ball = module.Projectile(mass=MASS, radius=RADIUS)
+        expected = exact_position(mode, T_END, drag_constant(mode))
+        hs, errs = [], []
+        for n in NS:
+            _, xs, ys = ball.simulate(V0, ANGLE, mode=mode, dt=T_END / n)
+            hs.append(T_END / n)
+            errs.append(float(np.max(np.abs(np.array([xs[n], ys[n]]) - expected))))
+        return check_order(hs, errs, 1.0, scale=float(np.max(np.abs(expected))))
+
+    return Check("reference", f"v1 {mode}/euler position at t = {T_END:g}", run)
+
+
+def range_check(module) -> Check:
+    def run():
+        ball = module.Projectile(mass=MASS, radius=RADIUS)
+        exact = V0 * V0 * math.sin(math.radians(2 * ANGLE)) / 9.81
+        hs, errs = [], []
+        for dt in (0.02, 0.01, 0.005, 0.0025):
+            _, xs, _ = ball.simulate(V0, ANGLE, mode="vacuum", dt=dt)
+            hs.append(dt)
+            errs.append(abs(xs[-1] - exact))
+        return check_order(hs, errs, 1.0, scale=exact)
+
+    return Check("limit", "v1 vacuum/euler range", run)
+
+
+def checks(module=None) -> list[Check]:
+    module = module or load()
+    return [position_check(module, m) for m in ("vacuum", "linear", "quadratic")] + [range_check(module)]

physverify/adapters/projectile_v2.py

@@ -0,0 +1,94 @@
+"""Adapter for projectile-simulation/src/projectile_sim_v2.py (class ProjectileV2).
+
+The class has no time argument and no source-term hook, so the manufactured
+forcing is injected by wrapping `_state_derivative` and reading time from x:
+the manufactured solution has x_m(t) = t. The wrapped problem is then the
+autonomous system  z' = f(z) + s(x), whose exact solution is the manufactured
+one. The code itself is not modified.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from ..checks import Check
+from ..loaders import load_module_from_path
+from ..mms import zero_source
+from ..problems import projectile as P
+from ..studies import ode_checks
+from . import sibling_project
+
+ENV_VAR = "PHYSVERIFY_PROJECTILE_DIR"
+FOLDER = "projectile-simulation"
+
+
+def source_path():
+    return sibling_project(ENV_VAR, FOLDER) / "src" / "projectile_sim_v2.py"
+
+
+def load():
+    return load_module_from_path("projectile_sim_v2_under_test", source_path(), stubs=("matplotlib", "matplotlib.pyplot"))
+
+
+def _new_sim(module):
+    p = P.PARAMS
+    return module.ProjectileV2(mass=p["m"], radius=p["r"], C_d=p["Cd"])
+
+
+def make_integrate(module, mode: str, method: str, trajectory: bool = False):
+    def integrate(source, y0, t_end, n):
+        if y0[0] != 0.0 or y0[1] != 0.0:
+            raise ValueError("ProjectileV2 always launches from the origin")
+        sim = _new_sim(module)
+        original = sim._state_derivative
+        # simulate() runs until landing; stop a run that never lands instead of hanging
+        budget = [8 * 10 * n]
+        # In a forced run x = t, and past the measurement time the state no longer matters, so a
+        # strong downward push ends the run (the linear patch solution would never land). Half a
+        # step of margin keeps it out of the last measured step. Free runs are left alone.
+        after = t_end + 0.5 * t_end / n if source is not zero_source else math.inf
+        land = np.array([0.0, 0.0, 0.0, -1000.0])
+
+        def wrapped(z, m):
+            budget[0] -= 1
+            if budget[0] < 0:
+                raise RuntimeError("simulation ran 10x past the measurement time without landing")
+            extra = land if z[0] > after else 0.0
+            return original(z, m) + source(z[0]) + extra
+
+        sim._state_derivative = wrapped
+        v0 = math.hypot(y0[2], y0[3])
+        angle = math.degrees(math.atan2(y0[3], y0[2]))
+        states = sim.simulate(v0, angle, mode=mode, dt=t_end / n, method=method)
+        return np.asarray(states[: n + 1]) if trajectory else states[n]
+
+    return integrate
+
+
+def checks(module=None) -> list[Check]:
+    module = module or load()
+    out: list[Check] = []
+    for mode in P.MODES:
+        for method, ns, order in (("rk4", P.NS_RK4, 4.0), ("euler", P.NS_EULER, 1.0)):
+            out += ode_checks(
+                f"{mode}/{method}",
+                make_integrate(module, mode, method),
+                rhs_ref=P.rhs_reference(mode),
+                mms=P.manufactured(mode),
+                y0_free=P.Y0_FREE,
+                t_end=P.MMS_T_END,
+                ns=ns,
+                order=order,
+                quantity=P.energy_vacuum if mode == "vacuum" else None,
+                patch=P.PATCH,
+                integrate_trajectory=make_integrate(module, mode, method, trajectory=True),
+            )
+
+    def range_fn(v0, angle, dt):
+        trajectory = _new_sim(module).simulate(v0, angle, mode="vacuum", dt=dt, method="rk4")
+        return trajectory[-1][0]
+
+    out.append(P.range_check(range_fn, label="ProjectileV2 vacuum/rk4 range"))
+    return out