spatial-computing 0.5.0__py3-none-any.whl

spatial/runtime/microvm.py

@@ -0,0 +1,125 @@
+"""Linux micro-VM runner (QEMU). Boots a kernel + generated initramfs containing a static
+Linux ELF, runs it, captures its output from the serial console, powers off.
+
+accel="hvf" : hardware virtualization (same ISA as host)  -> near-native CPU speed
+accel="tcg" : full software emulation                      -> the cost of cross-ISA execution
+
+No network device, no disk, no host folder is attached to the guest: it only sees the
+files packed in its initramfs. Guest RAM is a hard cap (-m).
+"""
+from __future__ import annotations
+
+import gzip
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+VENDOR = Path(__file__).resolve().parents[2] / "vendor"
+KERNEL = VENDOR / "vmlinuz-virt"
+BUSYBOX = VENDOR / "busybox-x86_64"
+
+
+def _cpio_entry(name: str, mode: int, data: bytes = b"", rdev: tuple[int, int] = (0, 0), ino: int = 0) -> bytes:
+    n = name.encode() + b"\0"
+    hdr = "070701" + "".join(f"{v:08X}" for v in (
+        ino, mode, 0, 0, 1, 0, len(data), 0, 0, rdev[0], rdev[1], len(n), 0))
+    out = hdr.encode() + n
+    out += b"\0" * (-len(out) % 4)
+    out += data + b"\0" * (-len(data) % 4)
+    return out
+
+
+def build_initramfs(app: bytes, args: list[str], out_path: str, files: dict | None = None,
+                    app_name: str = "app") -> int:
+    """newc cpio archive written directly (no root needed for the device node)."""
+    init = "\n".join([
+        "#!/bin/sh",
+        "/bin/busybox mount -t devtmpfs dev /dev 2>/dev/null",
+        "/bin/busybox mount -t proc proc /proc 2>/dev/null",
+        "echo SPATIAL_BEGIN",
+        f"/{app_name} " + " ".join(args),
+        "echo SPATIAL_EXIT $?",
+        "/bin/busybox poweroff -f",
+        ""]).encode()
+    S_DIR, S_REG, S_CHR, S_LNK = 0o040755, 0o100755, 0o020600, 0o120777
+    parts = [
+        _cpio_entry("bin", S_DIR, ino=1), _cpio_entry("dev", S_DIR, ino=2), _cpio_entry("proc", S_DIR, ino=3),
+        _cpio_entry("dev/console", S_CHR, rdev=(5, 1), ino=4),
+        _cpio_entry("bin/busybox", S_REG, BUSYBOX.read_bytes(), ino=5),
+        _cpio_entry("bin/sh", S_LNK, b"busybox", ino=6),
+        _cpio_entry("init", S_REG, init, ino=7),
+        _cpio_entry(app_name, S_REG, app, ino=8),
+        _cpio_entry("data", S_DIR, ino=9),
+    ]
+    for i, (fname, content) in enumerate((files or {}).items()):
+        if "/" in fname or fname in ("", ".", ".."):
+            raise ValueError(f"input file name must be a plain name, got {fname!r}")
+        parts.append(_cpio_entry(f"data/{fname}", 0o100444, content, ino=10 + i))
+    parts.append(_cpio_entry("TRAILER!!!", 0))
+    blob = gzip.compress(b"".join(parts), compresslevel=1)
+    Path(out_path).write_bytes(blob)
+    return len(blob)
+
+
+@dataclass
+class VmResult:
+    ok: bool
+    accel: str
+    stdout: str          # what the app printed
+    exit_code: int | None
+    total_wall_s: float  # QEMU start -> QEMU exit (boot + app + shutdown)
+    boot_s: float | None # QEMU start -> app start marker
+    raw_tail: str = ""
+
+
+def available() -> dict:
+    return {"qemu": shutil.which("qemu-system-x86_64"), "kernel": KERNEL.exists(), "busybox": BUSYBOX.exists()}
+
+
+def run_elf(elf_path: str, args: list[str] | None = None, accel: str = "hvf", mem_mb: int = 256,
+            cpus: int = 1, timeout_s: float = 180.0, files: dict | None = None,
+            app_name: str = "app") -> VmResult:
+    """`files` ({name: bytes}) are copied read-only into the guest under /data. They are the
+    only host data the guest can see; nothing is written back to the host."""
+    qemu = shutil.which("qemu-system-x86_64")
+    if not (qemu and KERNEL.exists() and BUSYBOX.exists()):
+        raise RuntimeError(f"micro-VM prerequisites missing: {available()}")
+    with tempfile.TemporaryDirectory(prefix="spatial-vm-") as td:
+        initrd = os.path.join(td, "initramfs.cpio.gz")
+        build_initramfs(Path(elf_path).read_bytes(), args or [], initrd, files, app_name)
+        cmd = [qemu, "-accel", accel, "-cpu", "host" if accel == "hvf" else "max",
+               "-m", str(mem_mb), "-smp", str(cpus), "-kernel", str(KERNEL), "-initrd", initrd,
+               "-append", "console=ttyS0 quiet panic=-1 rdinit=/init",
+               "-nodefaults", "-no-reboot", "-display", "none", "-serial", "stdio"]
+        t0 = time.perf_counter()
+        p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL, text=True,
+                             errors="replace")
+        lines, boot_s, code, capture, app_out = [], None, None, False, []
+        try:
+            for line in p.stdout:
+                line = line.rstrip("\r\n")
+                lines.append(line)
+                if line.strip() == "SPATIAL_BEGIN":
+                    boot_s = time.perf_counter() - t0
+                    capture = True
+                elif line.startswith("SPATIAL_EXIT"):
+                    code = int(line.split()[1])
+                    capture = False
+                elif capture:
+                    app_out.append(line)
+                if time.perf_counter() - t0 > timeout_s:
+                    break
+            p.wait(timeout=max(1.0, timeout_s - (time.perf_counter() - t0)))
+        except subprocess.TimeoutExpired:
+            pass
+        finally:
+            if p.poll() is None:
+                p.kill()
+                p.wait()
+        total = time.perf_counter() - t0
+    return VmResult(ok=code == 0, accel=accel, stdout="\n".join(app_out), exit_code=code,
+                    total_wall_s=total, boot_s=boot_s, raw_tail="\n".join(lines[-15:]))

spatial/runtime/planner.py

@@ -0,0 +1,155 @@
+"""Spatial Runtime Engine planner + executor.
+
+plan(artifact, host): ordered list of execution routes, each marked feasible or not WITH the
+reason. execute(): runs the first feasible route and returns the app output and timings.
+No route is reported as feasible unless its prerequisites were detected on this host.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import microvm
+from .inspect import Artifact, inspect
+
+
+@dataclass
+class Route:
+    name: str
+    feasible: bool
+    reason: str
+    expected_overhead: str = ""
+    isolation: str = ""
+
+
+@dataclass
+class Execution:
+    route: str
+    ok: bool
+    stdout: str
+    wall_s: float
+    extra: dict = field(default_factory=dict)
+
+
+def find_wine() -> str | None:
+    """Wine on PATH, or a user-level unpacked build under ~/.local/share/spatial (no system install)."""
+    w = shutil.which("wine64") or shutil.which("wine")
+    if w:
+        return w
+    base = Path.home() / ".local" / "share" / "spatial"
+    for cand in sorted(base.glob("**/bin/wine")) if base.exists() else []:
+        if os.access(cand, os.X_OK):
+            return str(cand)
+    return None
+
+
+def host_caps(node=None) -> dict:
+    import platform
+    caps = {"os": {"Darwin": "macos", "Linux": "linux", "Windows": "windows"}.get(platform.system(), "?"),
+            "arch": {"AMD64": "x86_64", "arm64": "aarch64"}.get(platform.machine(), platform.machine()),
+            "node": shutil.which("node"), "wine": find_wine(),
+            "docker": shutil.which("docker") or shutil.which("podman"),
+            "qemu_x86": shutil.which("qemu-system-x86_64"),
+            "microvm": all(microvm.available().values())}
+    try:
+        caps["hvf"] = subprocess.run(["sysctl", "-n", "kern.hv_support"], capture_output=True,
+                                     text=True, timeout=5).stdout.strip() == "1"
+    except Exception:
+        caps["hvf"] = False
+    return caps
+
+
+def plan(art: Artifact, caps: dict | None = None) -> list[Route]:
+    caps = caps or host_caps()
+    R: list[Route] = []
+    same_arch = caps["arch"] in art.arch or ("arm64" in art.arch and caps["arch"] == "aarch64")
+    if art.format == "macho":
+        ok = caps["os"] == "macos" and same_arch
+        R.append(Route("native", ok, "same OS and CPU" if ok else f"host is {caps['os']}/{caps['arch']}, binary is macOS/{art.arch}",
+                       "none", "none (host process)"))
+    elif art.format == "elf":
+        if caps["os"] == "linux" and same_arch:
+            R.append(Route("native", True, "same OS and CPU", "none", "none"))
+        hv = caps["microvm"] and caps["hvf"] and "x86_64" in art.arch and caps["arch"] == "x86_64"
+        R.append(Route("microvm-hvf", hv,
+                       "Linux x86_64 guest under Hypervisor.framework" if hv else
+                       "needs QEMU + kernel + HVF and an x86_64 guest on an x86_64 host",
+                       "VM boot (~1-2 s) + near-native CPU", "hardware VM, no network, no host files"))
+        tcg = caps["microvm"] and "x86_64" in art.arch
+        R.append(Route("microvm-tcg", tcg,
+                       "software emulation (works without HVF or across CPU families)" if tcg else
+                       "no kernel/emulator available for this guest architecture",
+                       "5-30x slower CPU", "emulated VM"))
+        R.append(Route("container", bool(caps["docker"]) and same_arch,
+                       "OCI runtime found" if caps["docker"] else "no Docker/Podman installed",
+                       "Linux VM shared by containers on macOS", "namespace isolation inside a VM"))
+    elif art.format == "pe":
+        R.append(Route("native", caps["os"] == "windows" and same_arch,
+                       "same OS" if caps["os"] == "windows" else "host is not Windows", "none", "none"))
+        R.append(Route("wine", bool(caps["wine"]),
+                       "Wine found" if caps["wine"] else
+                       "Wine is not installed (not installed automatically: unsigned third-party build, needs user consent)",
+                       "API translation, no CPU emulation on x86_64", "host process (weak)"))
+        R.append(Route("windows-vm", False,
+                       "no Windows image/licence on this machine; would run under QEMU+HVF",
+                       "full guest OS (>=4 GB RAM, >=20 GB disk)", "hardware VM"))
+        R.append(Route("remote-windows", False, "no remote Windows host configured", "network latency", "remote machine"))
+    elif art.format == "wasm":
+        ok = bool(caps["node"])
+        R.append(Route("wasm-node-wasi", ok, "Node.js WASI runtime found" if ok else "no WASM runtime",
+                       "JIT, typically 1.1-2x native", "WASI sandbox (no files/network unless granted)"))
+    elif art.format == "script":
+        R.append(Route("native-interpreter", True, f"interpreter: {art.detail}", "none", "none"))
+    else:
+        R.append(Route("none", False, "unrecognised format"))
+    return R
+
+
+_WASI_JS = """
+const { WASI } = require('node:wasi'); const fs = require('node:fs');
+process.removeAllListeners('warning');
+const wasi = new WASI({ version: 'preview1', args: ['app', ...process.argv.slice(3)], env: {} });
+(async () => {
+  const m = await WebAssembly.compile(fs.readFileSync(process.argv[2]));
+  const i = await WebAssembly.instantiate(m, wasi.getImportObject());
+  wasi.start(i);
+})();
+"""
+
+
+def execute(path: str, args: list[str] | None = None, route: str | None = None, timeout_s: float = 300) -> Execution:
+    art = inspect(path)
+    routes = plan(art)
+    chosen = next((r for r in routes if r.feasible and (route is None or r.name == route)), None)
+    if chosen is None:
+        why = "; ".join(f"{r.name}: {r.reason}" for r in routes)
+        return Execution(route or "none", False, "", 0.0, {"not_runnable": why, "format": art.format})
+    args = args or []
+    t0 = time.perf_counter()
+    if chosen.name in ("native", "native-interpreter"):
+        r = subprocess.run([path, *args], capture_output=True, text=True, timeout=timeout_s)
+        return Execution(chosen.name, r.returncode == 0, r.stdout.strip(), time.perf_counter() - t0)
+    if chosen.name.startswith("microvm-"):
+        v = microvm.run_elf(path, args, accel=chosen.name.split("-")[1], timeout_s=timeout_s)
+        return Execution(chosen.name, v.ok, v.stdout.strip(), v.total_wall_s,
+                         {"boot_s": v.boot_s, "exit_code": v.exit_code, "tail": "" if v.ok else v.raw_tail})
+    if chosen.name == "wasm-node-wasi":
+        js = Path(os.environ.get("TMPDIR", "/tmp")) / f"spatial-wasi-{os.getpid()}.js"
+        js.write_text(_WASI_JS)
+        try:
+            r = subprocess.run(["node", "--no-warnings", str(js), path, *args], capture_output=True,
+                               text=True, timeout=timeout_s)
+        finally:
+            js.unlink(missing_ok=True)
+        return Execution(chosen.name, r.returncode == 0, r.stdout.strip(), time.perf_counter() - t0,
+                         {"stderr": r.stderr[-300:]})
+    if chosen.name == "wine":
+        env = {**os.environ, "WINEDEBUG": "-all", "WINEPREFIX": str(Path.home() / ".local/share/spatial/wineprefix")}
+        r = subprocess.run([find_wine(), path, *args], capture_output=True, text=True, timeout=timeout_s, env=env)
+        return Execution(chosen.name, r.returncode == 0, r.stdout.strip(), time.perf_counter() - t0,
+                         {"stderr": r.stderr[-300:]})
+    return Execution(chosen.name, False, "", 0.0, {"not_runnable": "route has no executor yet"})

spatial/runtime/runner.py

@@ -0,0 +1,108 @@
+"""Remote execution: a runner that accepts a Linux ELF over SWP/1 and runs it ONLY inside a
+micro-VM (no network, no disk, no host files, RAM capped). This is the one place where
+code crosses the wire, which is why the sandbox is not optional and cannot be disabled
+by the caller.
+
+Run:  spatial serve runtime --token-file <path>
+"""
+from __future__ import annotations
+
+import os
+import secrets
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from ..core.protocol import RpcClient, RpcServer
+from . import microvm
+from .inspect import inspect
+
+MAX_ELF = 64 * 1024 * 1024
+MAX_TIMEOUT = 300.0
+
+
+def _handler(h: dict, blob: bytes):
+    op = h.get("op")
+    if op == "ping":
+        return {"pong": True, "microvm": microvm.available()}, b""
+    if op != "run_elf":
+        raise ValueError(f"unknown op {op!r}")
+    if len(blob) > MAX_ELF:
+        raise ValueError("binary too large")
+    args = [str(a) for a in h.get("args", [])]
+    if any(c in a for a in args for c in "\n;&|`$<>"):
+        raise ValueError("argument contains shell metacharacters")
+    with tempfile.NamedTemporaryFile(prefix="spatial-remote-", suffix=".elf", delete=False) as f:
+        f.write(blob)
+        path = f.name
+    try:
+        art = inspect(path)
+        if art.format != "elf" or "x86_64" not in art.arch:
+            raise ValueError(f"runner only accepts Linux x86_64 ELF binaries, got {art.format}/{art.arch}")
+        accel = "hvf" if h.get("accel", "hvf") == "hvf" else "tcg"
+        r = microvm.run_elf(path, args, accel=accel, mem_mb=min(int(h.get("mem_mb", 256)), 1024),
+                            timeout_s=min(float(h.get("timeout_s", 120)), MAX_TIMEOUT))
+    finally:
+        os.unlink(path)
+    return {"run_ok": r.ok, "exit_code": r.exit_code, "stdout": r.stdout, "boot_s": r.boot_s,
+            "total_wall_s": r.total_wall_s, "accel": r.accel}, b""
+
+
+def serve(token: bytes, host: str = "127.0.0.1", port: int = 0, allow_remote: bool = False) -> RpcServer:
+    return RpcServer(_handler, token, host=host, port=port, allow_remote=allow_remote)
+
+
+def run_remote(client: RpcClient, elf_path: str, args: list[str] | None = None, **opts) -> dict:
+    rh, _ = client.call({"op": "run_elf", "args": args or [], **opts}, Path(elf_path).read_bytes())
+    return rh
+
+
+class LocalRunnerProcess:
+    """Runner in a separate OS process on loopback (stand-in for a remote host)."""
+
+    def __init__(self):
+        self.token = secrets.token_bytes(32)
+        self._tf = Path(os.environ.get("TMPDIR", "/tmp")) / f"spatial-rt-{os.getpid()}-{secrets.token_hex(4)}"
+        self._tf.write_bytes(self.token)
+        os.chmod(self._tf, 0o600)
+        self.proc = subprocess.Popen([sys.executable, "-m", "spatial.runtime.runner", "--token-file", str(self._tf)],
+                                     cwd=Path(__file__).resolve().parents[2], stdout=subprocess.PIPE, text=True)
+        line = self.proc.stdout.readline()
+        if not line.startswith("PORT "):
+            raise RuntimeError(f"runner failed to start: {line!r}")
+        self.port = int(line.split()[1])
+
+    def client(self) -> RpcClient:
+        return RpcClient("127.0.0.1", self.port, self.token, timeout=MAX_TIMEOUT + 30)
+
+    def stop(self):
+        self.proc.terminate()
+        try:
+            self.proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self.proc.kill()
+        self._tf.unlink(missing_ok=True)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        self.stop()
+
+
+def main():
+    import argparse
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--token-file", required=True)
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--port", type=int, default=0)
+    ap.add_argument("--allow-remote", action="store_true")
+    a = ap.parse_args()
+    srv = serve(Path(a.token_file).read_bytes(), a.host, a.port, a.allow_remote)
+    print(f"PORT {srv.port}", flush=True)
+    srv.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

spatial/runtime/toolchain.py

@@ -0,0 +1,35 @@
+"""Cross-compilation of one C source to several executable formats (zig cc from PyPI `ziglang`).
+Used to produce REAL foreign binaries for the runtime tests instead of mock files."""
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+TARGETS = {
+    "macos-x86_64": (None, "bench-macos"),                       # host clang
+    "linux-x86_64": ("x86_64-linux-musl", "bench-linux.elf"),
+    "windows-x86_64": ("x86_64-windows-gnu", "bench-windows.exe"),
+    "wasm32-wasi": ("wasm32-wasi", "bench.wasm"),
+}
+FLAGS = ["-O2", "-ffp-contract=off"]   # no FMA contraction: identical IEEE results everywhere
+
+
+def build(src: str, out_dir: str, target: str) -> Path:
+    triple, name = TARGETS[target]
+    out = Path(out_dir) / name
+    out.parent.mkdir(parents=True, exist_ok=True)
+    if triple is None:
+        cmd = ["clang", *FLAGS, src, "-o", str(out)]
+    else:
+        cmd = [sys.executable, "-m", "ziglang", "cc", "-target", triple, *FLAGS, src, "-o", str(out)]
+        if "linux" in triple:
+            cmd.insert(-2, "-static")
+    r = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+    if r.returncode != 0:
+        raise RuntimeError(f"build {target} failed: {r.stderr[-800:]}")
+    return out
+
+
+def build_all(src: str, out_dir: str) -> dict[str, Path]:
+    return {t: build(src, out_dir, t) for t in TARGETS}

spatial/scientific/__init__.py

@@ -0,0 +1,8 @@
+"""Spatial Scientific & Industrial Engine — FIRST COMPONENTS ONLY.
+
+A JobSpec describes a numerical job with a validation target; the engine runs it and
+checks the answer against an independent reference. One reference job is implemented
+(Monte Carlo option pricing vs Black-Scholes) plus an RK4 ODE job checked against its
+analytic solution. No industrial solver is claimed.
+"""
+from .jobs import JobSpec, run_job, european_call_mc, black_scholes_call, harmonic_rk4  # noqa: F401

spatial/scientific/jobs.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Callable
+
+import numpy as np
+
+from ..compute.monitor import Measure
+from ..core.model import Measurement
+
+
+def black_scholes_call(s0: float, k: float, r: float, sigma: float, t: float) -> float:
+    d1 = (math.log(s0 / k) + (r + sigma * sigma / 2) * t) / (sigma * math.sqrt(t))
+    d2 = d1 - sigma * math.sqrt(t)
+    cdf = lambda x: 0.5 * (1 + math.erf(x / math.sqrt(2)))
+    return s0 * cdf(d1) - k * math.exp(-r * t) * cdf(d2)
+
+
+def european_call_mc(s0: float, k: float, r: float, sigma: float, t: float, paths: int,
+                     seed: int = 0) -> tuple[float, float]:
+    """Returns (price, standard error). Antithetic variates."""
+    rng = np.random.default_rng(seed)
+    acc = acc2 = 0.0
+    n = 0
+    left = paths // 2
+    drift, vol = (r - sigma * sigma / 2) * t, sigma * math.sqrt(t)
+    disc = math.exp(-r * t)
+    while left > 0:
+        m = min(left, 1_000_000)
+        z = rng.standard_normal(m)
+        pay = 0.5 * disc * (np.maximum(s0 * np.exp(drift + vol * z) - k, 0)
+                            + np.maximum(s0 * np.exp(drift - vol * z) - k, 0))
+        acc += float(pay.sum())
+        acc2 += float((pay * pay).sum())
+        n += m
+        left -= m
+    mean = acc / n
+    return mean, math.sqrt(max(acc2 / n - mean * mean, 0) / n)
+
+
+def harmonic_rk4(omega: float, t_end: float, steps: int) -> tuple[float, float]:
+    """x'' = -omega^2 x, x(0)=1, v(0)=0, integrated with RK4. Returns (x(t_end), error bound).
+    The bound is the RK4 global error scale (omega*dt)^4 * omega*t_end, used as the tolerance."""
+    dt = t_end / steps
+    x, v = 1.0, 0.0
+    f = lambda x, v: (v, -omega * omega * x)
+    for _ in range(steps):
+        k1 = f(x, v)
+        k2 = f(x + dt / 2 * k1[0], v + dt / 2 * k1[1])
+        k3 = f(x + dt / 2 * k2[0], v + dt / 2 * k2[1])
+        k4 = f(x + dt * k3[0], v + dt * k3[1])
+        x += dt / 6 * (k1[0] + 2 * k2[0] + 2 * k3[0] + k4[0])
+        v += dt / 6 * (k1[1] + 2 * k2[1] + 2 * k3[1] + k4[1])
+    return x, (omega * dt) ** 4 * omega * t_end
+
+
+@dataclass
+class JobSpec:
+    name: str
+    sector: str
+    fn: Callable[[], tuple[float, float]]        # returns (value, standard error)
+    reference: float | None = None
+    tolerance_sigmas: float = 4.0
+    tags: list[str] = field(default_factory=list)
+
+
+def run_job(job: JobSpec) -> Measurement:
+    out = {}
+    with Measure("scientific", job.name, "local_numpy", power=False) as m:
+        out["v"], out["se"] = job.fn()
+    if m.ok:
+        m.metrics.update(value=out["v"], std_error=out["se"], reference=job.reference)
+        if job.reference is not None:
+            dev = abs(out["v"] - job.reference) / max(out["se"], 1e-300)
+            m.metrics["deviation_sigmas"] = dev
+            m.ok = dev <= job.tolerance_sigmas
+            if not m.ok:
+                m.notes = "validation against reference failed"
+    return m

spatial/simulation/__init__.py

@@ -0,0 +1,7 @@
+"""Spatial Simulation Engine — FIRST COMPONENTS ONLY.
+
+An explicit 2-D heat-diffusion solver (NumPy and Numba variants producing the same field)
+and a symplectic N-body integrator. No multiphysics, no digital twin.
+"""
+from .heat import step_numpy, step_numba, simulate, stable_dt  # noqa: F401
+from . import nbody  # noqa: F401

spatial/simulation/heat.py

@@ -0,0 +1,48 @@
+"""Explicit finite-difference heat equation u_t = alpha * laplacian(u), insulated borders."""
+from __future__ import annotations
+
+import numpy as np
+
+try:
+    from numba import njit
+    HAVE_NUMBA = True
+except Exception:  # pragma: no cover
+    HAVE_NUMBA = False
+
+
+def stable_dt(alpha: float, dx: float) -> float:
+    """Largest stable time step for the explicit scheme in 2-D (CFL): dx^2 / (4 alpha)."""
+    return dx * dx / (4 * alpha)
+
+
+def step_numpy(u: np.ndarray, c: float) -> np.ndarray:
+    """c = alpha*dt/dx^2 (must be <= 0.25). Neumann (zero-flux) boundaries via edge padding."""
+    p = np.pad(u, 1, mode="edge")
+    return u + c * (p[:-2, 1:-1] + p[2:, 1:-1] + p[1:-1, :-2] + p[1:-1, 2:] - 4 * u)
+
+
+if HAVE_NUMBA:
+    @njit(cache=True)
+    def step_numba(u, c):
+        n, m = u.shape
+        out = np.empty_like(u)
+        for i in range(n):
+            for j in range(m):
+                up = u[i - 1, j] if i > 0 else u[i, j]
+                dn = u[i + 1, j] if i < n - 1 else u[i, j]
+                lf = u[i, j - 1] if j > 0 else u[i, j]
+                rt = u[i, j + 1] if j < m - 1 else u[i, j]
+                out[i, j] = u[i, j] + c * (up + dn + lf + rt - 4 * u[i, j])
+        return out
+else:  # pragma: no cover
+    step_numba = step_numpy
+
+
+def simulate(u0: np.ndarray, c: float, steps: int, backend: str = "numpy") -> np.ndarray:
+    if c > 0.25:
+        raise ValueError("unstable: c = alpha*dt/dx^2 must be <= 0.25")
+    f = step_numba if backend == "numba" else step_numpy
+    u = u0.astype(np.float64)
+    for _ in range(steps):
+        u = f(u, c)
+    return u

spatial/simulation/nbody.py

@@ -0,0 +1,31 @@
+"""Gravitational N-body with a leapfrog (kick-drift-kick) integrator. Symplectic: total
+energy oscillates but does not drift, which the test checks."""
+from __future__ import annotations
+
+import numpy as np
+
+
+def accelerations(pos: np.ndarray, mass: np.ndarray, soft: float = 1e-3) -> np.ndarray:
+    d = pos[None, :, :] - pos[:, None, :]
+    r2 = (d ** 2).sum(-1) + soft ** 2
+    np.fill_diagonal(r2, np.inf)
+    return (d * (mass[None, :, None] / r2[..., None] ** 1.5)).sum(1)
+
+
+def energy(pos, vel, mass, soft: float = 1e-3) -> float:
+    kin = 0.5 * (mass * (vel ** 2).sum(-1)).sum()
+    d = pos[None] - pos[:, None]
+    r = np.sqrt((d ** 2).sum(-1) + soft ** 2)
+    iu = np.triu_indices(len(mass), 1)
+    return float(kin - (mass[iu[0]] * mass[iu[1]] / r[iu]).sum())
+
+
+def leapfrog(pos, vel, mass, dt: float, steps: int, soft: float = 1e-3):
+    pos, vel = pos.copy(), vel.copy()
+    a = accelerations(pos, mass, soft)
+    for _ in range(steps):
+        vel += 0.5 * dt * a
+        pos += dt * vel
+        a = accelerations(pos, mass, soft)
+        vel += 0.5 * dt * a
+    return pos, vel