aurasync-engine 0.4.1__tar.gz

aurasync_engine-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sahil Kundu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aurasync_engine-0.4.1/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: aurasync-engine
+Version: 0.4.1
+Summary: Event-camera state estimator and controller for a cart-pole (simulation prototype)
+Author: Sahil Kundu
+License-Expression: MIT
+Project-URL: Repository, https://github.com/sahil03kundu-code/AuraSync-Engine
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: torch
+Requires-Dist: matplotlib
+Dynamic: license-file
+
+# AuraSync-Engine V4 — Detect → Correct → Recover (simulation prototype)
+
+An event-camera state estimator and controller for an inverted pendulum (cart-pole) that
+is hit by sudden impulses. V4 adds a way to **detect** when the learned observer is
+confidently wrong, **correct** it from independent event geometry, and **recover** with
+an uncertainty-aware safety supervisor.
+
+**Everything here runs in simulation on a 2-core CPU.** No hardware result is claimed.
+The V3 README is in `docs/V3_README.md`.
+
+## V4.1 update: geometry-first, evidence-aware, selective neural assistance
+
+**Result (held-out seeds 4000+, 272 paired stress trials):**
+- **Adding the network did not help.** V4.1 against the same pipeline without the network
+  (D-ev): survival −1.8 points [−7, +3], safe recovery −0.4 [−6, +5].
+- **The evidence fix is the real gain.** D-ev against Baseline D: survival
+  **+7.7 [+2, +13]**, safe recovery **+9.2 [+4, +14]**, and occlusion survival 45% → **84%**.
+- **Recommended default:** D-ev, which needs no network and 0.73 cores (V4: 1.83).
+
+Details: [`docs/V41_REPORT.md`](docs/V41_REPORT.md) · audit: [`docs/V41_AUDIT.md`](docs/V41_AUDIT.md) ·
+code: `aurasync/v41/pipeline.py`, `benchmark_v41.py`, `analyze_v41.py`, `v41/` · tests: `tests/test_v41.py`.
+
+![v41](results/v41/v41_results.png)
+
+## The idea in one analogy
+The V3 neural observer is a ship's navigator who dead-reckons. After a big wave he is
+sure of his position, and wrong. In V3, that was the cause of every fall.
+
+V4 adds three things:
+- **a lookout** who takes direct bearings on the mast: a RANSAC line fit on events less
+  than 3 ms old;
+- **a rule for when to believe him:** a CUSUM consistency detector plus a gated Kalman
+  update, with re-initialisation only after several consistent bearings;
+- **a way to warn the captain** (the supervisor) when nobody is sure.
+
+## Headline results (test seeds, never used for any choice)
+
+![nominal](results/v4/v4_nominal.png)
+
+| Nominal, 112 trials/seed | Survival [95% CI] | Safe (≤ 12°) | Tilt error |
+|---|---|---|---|
+| **V4 proposed** (3 seeds) | **96.4 [93, 99]** | **62.5** | 1.22° |
+| C: V3 + uncertainty + shield (3 seeds) | 54.8 [47, 62] | 32.1 | 6.38° |
+| B: V3 triggered (3 seeds) | 73.8 [68, 79] | 16.7 | 4.96° |
+| E: learned frame camera 120 fps (3 seeds) | 84.5 [79, 90] | 45.8 | 1.41° |
+| **D: event geometry + supervisor, no network** | **99.1 [97, 100]** | **69.6** | 1.59° |
+| F: IMU + encoder | 100 | 57.1 | 0.06° |
+
+**What holds up:**
+- **V4 vs V3 + shield:** survival +41.7 points [+34, +49], safe recovery +30.4
+  [+23, +37].
+- **Faults V3 cannot survive:** V4 survives the injected sign flip and the confident
+  15° error on 16/16 trials (V3 + shield: 44% and 38%). Its alarm fires a median 4 ms
+  after the fault.
+- **HDR:** 100% survival, where V3 and the frame camera get 0%.
+
+**What does not:**
+- **Baseline D**, the same detect-and-correct idea without the neural network, is level
+  with or better than V4 in 14 of 15 non-nominal conditions. In nominal conditions its
+  safe recovery is 7.1 points higher [2, 13], at a sixth of the compute.
+- **Occlusion** is the only condition where V4 is clearly ahead (69% vs 44% survival).
+- **Correction is essential.** Detection plus uncertainty inflation without it is worse
+  than V3: 8% nominal survival.
+- **Uncertainty inflation** showed no benefit.
+- **The first V4 design** (the network overwrites the state) had the lowest error and
+  27% survival.
+- **Compute:** default V4 needs about 1.5 CPU cores of compute per second of control.
+
+Full report with CIs, ablations, failure analyses and limitations:
+**[`docs/V4_REPORT.md`](docs/V4_REPORT.md)**.
+
+![envelope](results/v4/v4_envelope.png)
+
+## Repository map
+
+| Path | What it is |
+|---|---|
+| `aurasync/v4/geometry.py` | Module A: EventGeometry, the RANSAC pole-line measurement |
+| `aurasync/v4/pipeline.py` | Modules A–C, E: `ConsistencyDetector`, `V4Pipeline` (gated fusion, confirmed re-init, inflation, position-only neural fusion, compute budget) |
+| `aurasync/v4/geo_pipeline.py` | Baseline D: physics + gated geometry, no network |
+| `aurasync/safety.py` | Module D: CBF supervisor, delay compensation, stale fallback (from V3) |
+| `benchmark_v4.py` | Test benchmark: baselines A–F, V4, ablations, 9 stress conditions, 6 new fault scenarios |
+| `analyze_v4.py` | Statistics (paired bootstrap CIs, Cohen's h) and figures → `results/v4/v4_report.json` |
+| `v4/repro_v3.py` | Step 2: bit-exact V3 reproduction |
+| `v4/collect_dev.py`, `v4/eval_dev.py` | Steps 3–5: validation failure catalogue and open-loop detector/correction evaluation |
+| `v4/select_v4.py`, `v4/tune_v4.py` | Step 6: design selection and supervisor tuning (validation seeds 300–315 only) |
+| `v4/latency_v4.py` | Module E: per-stage timings |
+| `v4/plot_failures.py`, `v4/plot_test_cases.py` | Failure visualisations (validation and test) plus per-tick CSV logs |
+| `tests/test_v4.py` | Unit and integration tests |
+| `docs/` | V3 audit, V4 design, latency report, technical report, hardware-validation plan |
+
+## Reproduce
+```bash
+pip install torch numpy scipy matplotlib --break-system-packages
+python3 -m unittest discover -s tests -v       # 12 tests; 4 need the V3 checkpoints + dev set
+python3 v4/repro_v3.py                         # V3 reproduction check
+python3 v4/collect_dev.py && python3 v4/eval_dev.py     # validation set (about 3.4 GB in data/)
+python3 v4/select_v4.py && python3 v4/tune_v4.py        # selection and tuning (validation only)
+WHICH=all python3 benchmark_v4.py              # test benchmark, resumable (about 2 h on 2 cores)
+python3 analyze_v4.py                          # tables, CIs, figures
+python3 v4/latency_v4.py                       # timings (run on an idle CPU)
+```
+Runs are deterministic (fixed seeds, 1 thread per worker), and the V3 checkpoints in
+`checkpoints/v3/` are reused unchanged. Rules that hold throughout:
+- **Ground truth:** estimators never read it. Replay tests pass `s_true=None`.
+- **Configuration:** stored in `results/v4/tuning_v4.json` (supervisor),
+  `checkpoints/v3/calibration.json` and `results/v3/tuning.json` (inherited).
+
+## Integrity notes
+- **Simulation only.** No real event sensor, actuator or timing hardware.
+- **Latency.** The 1 kHz control loop is not a demonstrated 1 ms sensor-to-actuator
+  latency. See `docs/V4_LATENCY.md`.
+- **No priority claims.** No prior-art search was done, and nothing here is claimed as
+  first of its kind, formally safe or patentable.
+- **Sample size.** Stress and scenario cells use 16 trials and mostly one seed, so
+  differences below about 20 points there are not established.

aurasync_engine-0.4.1/README.md

@@ -0,0 +1,116 @@
+# AuraSync-Engine V4 — Detect → Correct → Recover (simulation prototype)
+
+An event-camera state estimator and controller for an inverted pendulum (cart-pole) that
+is hit by sudden impulses. V4 adds a way to **detect** when the learned observer is
+confidently wrong, **correct** it from independent event geometry, and **recover** with
+an uncertainty-aware safety supervisor.
+
+**Everything here runs in simulation on a 2-core CPU.** No hardware result is claimed.
+The V3 README is in `docs/V3_README.md`.
+
+## V4.1 update: geometry-first, evidence-aware, selective neural assistance
+
+**Result (held-out seeds 4000+, 272 paired stress trials):**
+- **Adding the network did not help.** V4.1 against the same pipeline without the network
+  (D-ev): survival −1.8 points [−7, +3], safe recovery −0.4 [−6, +5].
+- **The evidence fix is the real gain.** D-ev against Baseline D: survival
+  **+7.7 [+2, +13]**, safe recovery **+9.2 [+4, +14]**, and occlusion survival 45% → **84%**.
+- **Recommended default:** D-ev, which needs no network and 0.73 cores (V4: 1.83).
+
+Details: [`docs/V41_REPORT.md`](docs/V41_REPORT.md) · audit: [`docs/V41_AUDIT.md`](docs/V41_AUDIT.md) ·
+code: `aurasync/v41/pipeline.py`, `benchmark_v41.py`, `analyze_v41.py`, `v41/` · tests: `tests/test_v41.py`.
+
+![v41](results/v41/v41_results.png)
+
+## The idea in one analogy
+The V3 neural observer is a ship's navigator who dead-reckons. After a big wave he is
+sure of his position, and wrong. In V3, that was the cause of every fall.
+
+V4 adds three things:
+- **a lookout** who takes direct bearings on the mast: a RANSAC line fit on events less
+  than 3 ms old;
+- **a rule for when to believe him:** a CUSUM consistency detector plus a gated Kalman
+  update, with re-initialisation only after several consistent bearings;
+- **a way to warn the captain** (the supervisor) when nobody is sure.
+
+## Headline results (test seeds, never used for any choice)
+
+![nominal](results/v4/v4_nominal.png)
+
+| Nominal, 112 trials/seed | Survival [95% CI] | Safe (≤ 12°) | Tilt error |
+|---|---|---|---|
+| **V4 proposed** (3 seeds) | **96.4 [93, 99]** | **62.5** | 1.22° |
+| C: V3 + uncertainty + shield (3 seeds) | 54.8 [47, 62] | 32.1 | 6.38° |
+| B: V3 triggered (3 seeds) | 73.8 [68, 79] | 16.7 | 4.96° |
+| E: learned frame camera 120 fps (3 seeds) | 84.5 [79, 90] | 45.8 | 1.41° |
+| **D: event geometry + supervisor, no network** | **99.1 [97, 100]** | **69.6** | 1.59° |
+| F: IMU + encoder | 100 | 57.1 | 0.06° |
+
+**What holds up:**
+- **V4 vs V3 + shield:** survival +41.7 points [+34, +49], safe recovery +30.4
+  [+23, +37].
+- **Faults V3 cannot survive:** V4 survives the injected sign flip and the confident
+  15° error on 16/16 trials (V3 + shield: 44% and 38%). Its alarm fires a median 4 ms
+  after the fault.
+- **HDR:** 100% survival, where V3 and the frame camera get 0%.
+
+**What does not:**
+- **Baseline D**, the same detect-and-correct idea without the neural network, is level
+  with or better than V4 in 14 of 15 non-nominal conditions. In nominal conditions its
+  safe recovery is 7.1 points higher [2, 13], at a sixth of the compute.
+- **Occlusion** is the only condition where V4 is clearly ahead (69% vs 44% survival).
+- **Correction is essential.** Detection plus uncertainty inflation without it is worse
+  than V3: 8% nominal survival.
+- **Uncertainty inflation** showed no benefit.
+- **The first V4 design** (the network overwrites the state) had the lowest error and
+  27% survival.
+- **Compute:** default V4 needs about 1.5 CPU cores of compute per second of control.
+
+Full report with CIs, ablations, failure analyses and limitations:
+**[`docs/V4_REPORT.md`](docs/V4_REPORT.md)**.
+
+![envelope](results/v4/v4_envelope.png)
+
+## Repository map
+
+| Path | What it is |
+|---|---|
+| `aurasync/v4/geometry.py` | Module A: EventGeometry, the RANSAC pole-line measurement |
+| `aurasync/v4/pipeline.py` | Modules A–C, E: `ConsistencyDetector`, `V4Pipeline` (gated fusion, confirmed re-init, inflation, position-only neural fusion, compute budget) |
+| `aurasync/v4/geo_pipeline.py` | Baseline D: physics + gated geometry, no network |
+| `aurasync/safety.py` | Module D: CBF supervisor, delay compensation, stale fallback (from V3) |
+| `benchmark_v4.py` | Test benchmark: baselines A–F, V4, ablations, 9 stress conditions, 6 new fault scenarios |
+| `analyze_v4.py` | Statistics (paired bootstrap CIs, Cohen's h) and figures → `results/v4/v4_report.json` |
+| `v4/repro_v3.py` | Step 2: bit-exact V3 reproduction |
+| `v4/collect_dev.py`, `v4/eval_dev.py` | Steps 3–5: validation failure catalogue and open-loop detector/correction evaluation |
+| `v4/select_v4.py`, `v4/tune_v4.py` | Step 6: design selection and supervisor tuning (validation seeds 300–315 only) |
+| `v4/latency_v4.py` | Module E: per-stage timings |
+| `v4/plot_failures.py`, `v4/plot_test_cases.py` | Failure visualisations (validation and test) plus per-tick CSV logs |
+| `tests/test_v4.py` | Unit and integration tests |
+| `docs/` | V3 audit, V4 design, latency report, technical report, hardware-validation plan |
+
+## Reproduce
+```bash
+pip install torch numpy scipy matplotlib --break-system-packages
+python3 -m unittest discover -s tests -v       # 12 tests; 4 need the V3 checkpoints + dev set
+python3 v4/repro_v3.py                         # V3 reproduction check
+python3 v4/collect_dev.py && python3 v4/eval_dev.py     # validation set (about 3.4 GB in data/)
+python3 v4/select_v4.py && python3 v4/tune_v4.py        # selection and tuning (validation only)
+WHICH=all python3 benchmark_v4.py              # test benchmark, resumable (about 2 h on 2 cores)
+python3 analyze_v4.py                          # tables, CIs, figures
+python3 v4/latency_v4.py                       # timings (run on an idle CPU)
+```
+Runs are deterministic (fixed seeds, 1 thread per worker), and the V3 checkpoints in
+`checkpoints/v3/` are reused unchanged. Rules that hold throughout:
+- **Ground truth:** estimators never read it. Replay tests pass `s_true=None`.
+- **Configuration:** stored in `results/v4/tuning_v4.json` (supervisor),
+  `checkpoints/v3/calibration.json` and `results/v3/tuning.json` (inherited).
+
+## Integrity notes
+- **Simulation only.** No real event sensor, actuator or timing hardware.
+- **Latency.** The 1 kHz control loop is not a demonstrated 1 ms sensor-to-actuator
+  latency. See `docs/V4_LATENCY.md`.
+- **No priority claims.** No prior-art search was done, and nothing here is claimed as
+  first of its kind, formally safe or patentable.
+- **Sample size.** Stress and scenario cells use 16 trials and mostly one seed, so
+  differences below about 20 points there are not established.

aurasync_engine-0.4.1/aurasync/conditions.py

@@ -0,0 +1,84 @@
+"""Operating conditions for the stress benchmark (Upgrade D).
+
+One SensorConditions object describes the scene and both sensors, so the event
+camera and the frame camera always see the same world. NOMINAL reproduces the
+v2 simulation exactly.
+
+Physical models (deliberately simple, documented so a reviewer can argue with them):
+  brightness     scene illumination scale. Event pixels compute log(I + dark
+                 current), so dim scenes compress contrast and fire fewer
+                 events; background noise rises ~1/sqrt(b) and the photoreceptor
+                 slows (time constant 50 us / b). Frame cameras auto-expose up to
+                 8 ms (inside the estimator's training range), then add gain,
+                 so read noise grows ~sqrt(4 ms / (b * exposure)).
+  hdr_gain       a bright window behind the top of the pole (y > 0.30 m) is
+                 hdr_gain times brighter than the room. Frame pixels exposed for
+                 the room saturate there (clip at 1.0); event pixels are
+                 logarithmic and keep the contrast.
+  ev_noise_mult  multiplies event background activity (0.3 Hz/pixel nominal)
+  thresh_sigma   per-pixel contrast-threshold mismatch (0.03 nominal)
+  drop_prob      fraction of events lost in readout (bus saturation)
+  occlusion      (t0, t1) or a tuple of such windows: a grey panel covers the upper pole
+  x_offset_m, scale  camera miscalibration: the sensor images world x * scale + offset at the
+                 pixel the estimators believe shows world x (V4 'miscalib' scenario)
+"""
+from dataclasses import dataclass, replace
+import numpy as np
+
+READ_NOISE = 0.02
+BASE_EXPOSURE = 0.004
+MAX_EXPOSURE = 0.008
+
+
+@dataclass(frozen=True)
+class SensorConditions:
+    name: str = "nominal"
+    brightness: float = 1.0
+    hdr_gain: float = 1.0
+    hdr_y: float = 0.30
+    ev_noise_mult: float = 1.0
+    thresh_sigma: float = 0.03
+    drop_prob: float = 0.0
+    occlusion: tuple = None
+    occ_box: tuple = (-0.30, 0.30, 0.30, 0.62)   # world x0, x1, y0, y1 [m]
+    occ_value: float = 0.5
+    x_offset_m: float = 0.0       # camera mounted off-centre (estimators assume the nominal calibration)
+    scale: float = 1.0            # focal-length / pixel-scale error
+
+    @property
+    def is_nominal(self):
+        return self == NOMINAL
+
+    # ---- event sensor ---------------------------------------------------------
+    @property
+    def ev_noise_rate(self):
+        return 0.3 * self.ev_noise_mult / np.sqrt(self.brightness)
+
+    @property
+    def photoreceptor_tau(self):
+        return 50e-6 / self.brightness
+
+    # ---- frame sensor (also used for the event sensor's APS channel) ----------
+    def frame_exposure(self, base=BASE_EXPOSURE):
+        return float(min(base / self.brightness, max(base, MAX_EXPOSURE)))
+
+    def frame_noise(self, exposure):
+        return float(READ_NOISE * np.sqrt(BASE_EXPOSURE / (self.brightness * exposure)))
+
+    def frame_sensor(self, radiance_avg):
+        """Time-averaged scene radiance (already x brightness) -> normalised pixel values.
+        Exposure + gain map a room-lit scene back to the nominal range; anything
+        brighter than full scale saturates. Noise is added by the caller."""
+        return np.clip(radiance_avg / self.brightness, 0.0, 1.0)
+
+
+NOMINAL = SensorConditions()
+PRESETS = {
+    "nominal": NOMINAL,
+    "low_light": SensorConditions("low_light", brightness=0.05),
+    "hdr": SensorConditions("hdr", hdr_gain=40.0),
+    "event_noise": SensorConditions("event_noise", ev_noise_mult=10.0),
+    "thresh_mismatch": SensorConditions("thresh_mismatch", thresh_sigma=0.09),
+    "dropped_events": SensorConditions("dropped_events", drop_prob=0.5),
+    "occlusion": SensorConditions("occlusion", occlusion=(0.21, 0.31)),
+}

aurasync_engine-0.4.1/aurasync/controller.py

@@ -0,0 +1,36 @@
+"""1 kHz state-feedback controller.
+
+An infinite-horizon LQR is the unconstrained limit of linear MPC: it minimises
+the same quadratic cost over an unbounded horizon and collapses to a single
+gain matrix, so it costs a 4-element dot product per tick and runs comfortably
+at 1 kHz even in Python. Actuator limits are enforced by saturation.
+A constrained MPC can be dropped in through the same `act(state)` interface.
+"""
+import numpy as np
+from .physics import PlantParams, linearise
+
+
+def dlqr(A, B, Q, R, iters=20000, tol=1e-10):
+    P = Q.copy()
+    for _ in range(iters):
+        BtP = B.T @ P
+        K = np.linalg.solve(R + BtP @ B, BtP @ A)
+        P_new = Q + A.T @ P @ (A - B @ K)
+        if np.max(np.abs(P_new - P)) < tol:
+            P = P_new
+            break
+        P = P_new
+    K = np.linalg.solve(R + B.T @ P @ B, B.T @ P @ A)
+    return K
+
+
+class LQRController:
+    def __init__(self, p: PlantParams, dt=1e-3,
+                 Q=(30.0, 2.0, 200.0, 5.0), R=0.02):
+        A, B = linearise(p, dt)
+        self.K = dlqr(A, B, np.diag(Q), np.array([[R]]))
+        self.u_max = p.u_max
+
+    def act(self, s):
+        u = -float((self.K @ np.asarray(s))[0])
+        return float(np.clip(u, -self.u_max, self.u_max))

aurasync_engine-0.4.1/aurasync/estimator.py

@@ -0,0 +1,251 @@
+"""Physics-informed event observer (PINN + selective state-space model).
+
+Analogy: a blindfolded juggler who knows physics. Between glimpses, the juggler
+predicts where the ball is from Newton's laws (the physics prior). Every event
+spike is a tiny glimpse; the network only learns how much to *correct* the
+physical prediction. When the scene is still and no events arrive, the
+estimate simply keeps following the physics instead of going blind.
+
+    s_{k+1} = RK4(s_k, u_k)                      # differentiable physics
+            + G * MLP([z_{k+1}, h_{k+1}, s_k])   # learned event correction
+    z_k     = CNN(time_surface_k)                # event features
+    h_{k+1} = a(z) * h_k + (1 - a(z)) * B z      # selective SSM memory
+    a(z)    = exp(-softplus(W_d z) * lambda)     # input-dependent step (Mamba-style)
+
+Training loss = state error + physics residuals (kinematic consistency and a
+penalty on unexplained corrections) - i.e. the network is told that the
+physics is mostly right and must justify any deviation with evidence.
+"""
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+SCALE = torch.tensor([0.3, 1.0, 0.2, 2.0])  # typical magnitude of x, xd, th, thd
+
+
+class TorchCartPole(nn.Module):
+    def __init__(self, M=1.0, m=0.1, l=0.25, g=9.81, b_cart=0.1, b_pole=0.002):
+        super().__init__()
+        self.M, self.m, self.l, self.g = M, m, l, g
+        self.b_cart, self.b_pole = b_cart, b_pole
+
+    def deriv(self, s, u):
+        x, xd, th, thd = s.unbind(-1)
+        sin, cos = torch.sin(th), torch.cos(th)
+        total = self.M + self.m
+        temp = (u + self.m * self.l * thd ** 2 * sin - self.b_cart * xd) / total
+        thdd = (self.g * sin - cos * temp - self.b_pole * thd / (self.m * self.l)) / (
+            self.l * (4.0 / 3.0 - self.m * cos ** 2 / total))
+        xdd = temp - self.m * self.l * thdd * cos / total
+        return torch.stack([xd, xdd, thd, thdd], -1)
+
+    def step(self, s, u, dt):
+        k1 = self.deriv(s, u)
+        k2 = self.deriv(s + 0.5 * dt * k1, u)
+        k3 = self.deriv(s + 0.5 * dt * k2, u)
+        k4 = self.deriv(s + dt * k3, u)
+        return s + dt / 6.0 * (k1 + 2 * k2 + 2 * k3 + k4)
+
+
+class SpatialSoftmaxKeypoints(nn.Module):
+    """Full-resolution keypoint layer (sub-pixel precise).
+
+    Each of K learned heatmaps is turned into a probability map; its mean gives
+    a sub-pixel (x, y) location and its covariance gives the orientation and
+    spread of the blob - e.g. the angle of the pole. This preserves the fine
+    geometry that strided pooling throws away (1 px at the pole tip ~ 3 deg).
+    """
+
+    def __init__(self, cin, H, W, K=12):
+        super().__init__()
+        self.c1 = nn.Conv2d(cin, 16, 3, 1, 1)
+        self.c2 = nn.Conv2d(16, K, 3, 1, 1)
+        self.log_temp = nn.Parameter(torch.zeros(K))
+        yy, xx = torch.meshgrid(torch.linspace(-1, 1, H), torch.linspace(-1, 1, W) * (W / H), indexing="ij")
+        self.register_buffer("gx", xx.flatten())
+        self.register_buffer("gy", yy.flatten())
+        self.out_dim = 5 * K
+
+    def forward(self, x):
+        logits = self.c2(F.gelu(self.c1(x))).flatten(2) * torch.exp(self.log_temp)[None, :, None]
+        p = torch.softmax(logits, -1)
+        mx, my = (p * self.gx).sum(-1), (p * self.gy).sum(-1)
+        vxx = (p * self.gx ** 2).sum(-1) - mx ** 2
+        vyy = (p * self.gy ** 2).sum(-1) - my ** 2
+        vxy = (p * self.gx * self.gy).sum(-1) - mx * my
+        return torch.cat([mx, my, 10 * vxx, 10 * vyy, 10 * vxy], -1)
+
+
+class EventEncoder(nn.Module):
+    def __init__(self, H=32, W=96, d=128, cin=4):
+        super().__init__()
+        yy, xx = torch.meshgrid(torch.linspace(-1, 1, H), torch.linspace(-1, 1, W), indexing="ij")
+        self.register_buffer("coords", torch.stack([xx, yy])[None])
+        self.c1 = nn.Conv2d(cin + 2, 16, 5, 2, 2)
+        self.c2 = nn.Conv2d(16, 32, 3, 2, 1)
+        self.c3 = nn.Conv2d(32, 32, 3, 2, 1)
+        self.kp = SpatialSoftmaxKeypoints(cin, H, W)
+        self.fc = nn.Linear(32 * (H // 8) * (W // 8) + self.kp.out_dim, d)
+
+    def forward(self, ts):  # ts: (N, 4, H, W): ON, OFF, slow-any, APS frame
+        x = torch.cat([ts, self.coords.expand(ts.shape[0], -1, -1, -1)], 1)
+        x = F.gelu(self.c1(x)); x = F.gelu(self.c2(x)); x = F.gelu(self.c3(x))
+        return F.gelu(self.fc(torch.cat([x.flatten(1), self.kp(ts)], 1)))
+
+
+class EventObserver(nn.Module):
+    def __init__(self, dt=1e-3, d=128, n_state=64):
+        super().__init__()
+        self.dt = dt
+        self.physics = TorchCartPole()
+        self.enc = EventEncoder(d=d)
+        self.B = nn.Linear(d, n_state)
+        self.W_delta = nn.Linear(d, n_state)
+        self.log_lambda = nn.Parameter(torch.zeros(n_state))
+        self.head = nn.Sequential(nn.Linear(d + n_state + 4, 128), nn.GELU(),
+                                  nn.Linear(128, 64), nn.GELU(), nn.Linear(64, 4))
+        nn.init.zeros_(self.head[-1].weight); nn.init.zeros_(self.head[-1].bias)
+        self.register_buffer("scale", SCALE.clone())
+        self.n_state = n_state
+
+    def init_hidden(self, batch):
+        return torch.zeros(batch, self.n_state)
+
+    def cell(self, z, h, s, u):
+        """One 1 ms observer tick. z: event features at t_{k+1}; s, u at t_k."""
+        a = torch.exp(-F.softplus(self.W_delta(z)) * torch.exp(self.log_lambda))
+        h = a * h + (1 - a) * self.B(z)
+        s_pred = self.physics.step(s, u, self.dt)
+        corr = self.head(torch.cat([z, h, s / self.scale], -1))
+        # correction expressed in units of "typical magnitude per 50 ms"
+        s_new = s_pred + corr * self.scale * (self.dt / 0.05)
+        return s_new, h, corr
+
+    def forward(self, ts_seq, u_seq, s0):
+        """ts_seq: (B, T, 4, H, W) surfaces at t_1..t_T; u_seq: (B, T); s0: (B, 4)."""
+        Bsz, T = ts_seq.shape[:2]
+        z_all = self.enc(ts_seq.flatten(0, 1)).view(Bsz, T, -1)
+        h = self.init_hidden(Bsz)
+        s = s0
+        out, corrs = [], []
+        for k in range(T):
+            s, h, c = self.cell(z_all[:, k], h, s, u_seq[:, k])
+            out.append(s); corrs.append(c)
+        return torch.stack(out, 1), torch.stack(corrs, 1)
+
+
+def physics_informed_loss(s_hat, s_true, corr, s0, dt, w_kin=0.05, w_corr=1e-3):
+    scale = SCALE.to(s_hat)
+    # tilt and tilt-rate errors matter most to the controller: weight them up
+    w = torch.tensor([1.0, 1.0, 4.0, 2.0]).to(s_hat)
+    data = ((((s_hat - s_true) / scale) ** 2) * w).mean() / w.mean()
+    # kinematic residual: position change must match estimated velocity
+    s_prev = torch.cat([s0[:, None], s_hat[:, :-1]], 1)
+    dpos = (s_hat[..., [0, 2]] - s_prev[..., [0, 2]]) / dt
+    vel = 0.5 * (s_hat[..., [1, 3]] + s_prev[..., [1, 3]])
+    kin = (((dpos - vel) / scale[[1, 3]]) ** 2).mean()
+    # parsimony: corrections must be justified by evidence
+    reg = (corr ** 2).mean()
+    return data + w_kin * kin + w_corr * reg, dict(data=data.item(), kin=kin.item(), reg=reg.item())
+
+
+# =============================================================================
+# v3: confidence-aware, gap-aware observer (Upgrades A + C)
+# =============================================================================
+class ProbEventObserver(EventObserver):
+    """Event observer that also says how much to trust itself.
+
+    Analogy: a navigator who, besides plotting the ship's position, keeps an
+    'error circle' around it. In fog (event silence) or a storm (event burst,
+    occlusion) the circle grows; after a clear fix it shrinks. The controller
+    and safety shield read the circle, not just the dot.
+
+    Changes vs EventObserver:
+      * variance head  - predicts log-variance of the state error after each
+                         correction (heteroscedastic Gaussian, trained by NLL on
+                         detached residuals so the mean is trained exactly as before)
+      * activity input - mean ON / OFF / slow time-surface activity, so the model
+                         can tell silence and bursts apart explicitly
+      * gap-aware      - a correction can be applied after `gap` ticks of
+                         physics-only prediction (event-triggered scheduling);
+                         trained with random tick skipping
+      * use_aps flag   - event-only ablation zeroes the APS frame channel
+    """
+
+    def __init__(self, dt=1e-3, d=128, n_state=64, use_aps=True):
+        super().__init__(dt, d, n_state)
+        self.head = nn.Sequential(nn.Linear(d + n_state + 4 + 1, 128), nn.GELU(),
+                                  nn.Linear(128, 64), nn.GELU(), nn.Linear(64, 4))
+        nn.init.zeros_(self.head[-1].weight); nn.init.zeros_(self.head[-1].bias)
+        self.var_head = nn.Sequential(nn.Linear(d + n_state + 4 + 1 + 3, 64), nn.GELU(),
+                                      nn.Linear(64, 4))
+        nn.init.zeros_(self.var_head[-1].weight)
+        nn.init.constant_(self.var_head[-1].bias, -3.0)
+        self.register_buffer("use_aps", torch.tensor(bool(use_aps)))
+
+    def encode(self, ts):
+        """ts (N, 4, H, W) -> (features z, activity a)."""
+        if not bool(self.use_aps):
+            ts = torch.cat([ts[:, :3], torch.zeros_like(ts[:, 3:])], 1)
+        return self.enc(ts), ts[:, :3].mean((2, 3)) * 10.0
+
+    def physics_step(self, s, u):
+        return self.physics.step(s, u, self.dt)
+
+    def correct(self, z, act, h, s_pred, gap):
+        """Apply one neural correction to the physics-predicted state s_pred.
+        gap: (N,) ticks since the previous correction (1 = dense operation)."""
+        a = torch.exp(-F.softplus(self.W_delta(z)) * torch.exp(self.log_lambda))
+        h = a * h + (1 - a) * self.B(z)
+        g = torch.log1p(gap.float())[:, None]
+        feat = torch.cat([z, h, s_pred / self.scale, g], -1)
+        corr = self.head(feat)
+        s_new = s_pred + corr * self.scale * (self.dt * gap.float()[:, None] / 0.05)
+        logvar = self.var_head(torch.cat([feat, act], -1)).clamp(-12, 4)
+        return s_new, h, corr, logvar
+
+    def forward(self, ts_seq, u_seq, s0, skip_p=None, gen=None):
+        """Training/eval rollout. skip_p: (B,) probability of skipping the neural
+        correction at a tick (physics-only). Returns states, corrections,
+        log-variances and the correction mask."""
+        Bsz, T = ts_seq.shape[:2]
+        if skip_p is None:
+            mask = torch.ones(Bsz, T, dtype=torch.bool)
+        else:
+            mask = torch.rand(Bsz, T, generator=gen) >= skip_p[:, None]
+            mask[:, -1] = True
+        # encode only the ticks that receive a correction (identical result, less compute)
+        flat = mask.flatten()
+        sel = ts_seq.flatten(0, 1)[flat]
+        if torch.is_grad_enabled() and sel.shape[0] > 256:
+            # gradient checkpointing in chunks: activations are recomputed in the backward
+            # pass instead of stored (same maths; keeps long windows inside 8 GB RAM)
+            from torch.utils.checkpoint import checkpoint
+            parts = [checkpoint(self.encode, c, use_reentrant=False) for c in sel.split(256)]
+            z_sel = torch.cat([p[0] for p in parts]); act_sel = torch.cat([p[1] for p in parts])
+        else:
+            z_sel, act_sel = self.encode(sel)
+        z_all = z_sel.new_zeros(Bsz * T, z_sel.shape[-1]).index_put((flat.nonzero()[:, 0],), z_sel)
+        act_all = act_sel.new_zeros(Bsz * T, act_sel.shape[-1]).index_put((flat.nonzero()[:, 0],), act_sel)
+        z_all = z_all.view(Bsz, T, -1); act_all = act_all.view(Bsz, T, -1)
+        h = self.init_hidden(Bsz)
+        s = s0
+        gap = torch.zeros(Bsz)
+        out, corrs, lvs = [], [], []
+        for k in range(T):
+            s = self.physics_step(s, u_seq[:, k])
+            gap = gap + 1
+            s_c, h_c, c, lv = self.correct(z_all[:, k], act_all[:, k], h, s, gap)
+            m = mask[:, k][:, None]
+            s = torch.where(m, s_c, s)
+            h = torch.where(m, h_c, h)
+            gap = torch.where(mask[:, k], torch.zeros_like(gap), gap)
+            out.append(s); corrs.append(c * m); lvs.append(lv)
+        return torch.stack(out, 1), torch.stack(corrs, 1), torch.stack(lvs, 1), mask
+
+
+def gaussian_nll(s_hat, s_true, logvar, mask):
+    """Heteroscedastic Gaussian NLL in SCALE units on detached residuals (mean untouched)."""
+    e = ((s_hat.detach() - s_true) / SCALE.to(s_hat)) ** 2
+    nll = 0.5 * (e * torch.exp(-logvar) + logvar)
+    return (nll * mask[..., None]).sum() / (mask.sum() * 4).clamp(min=1)