aurasync-engine 0.4.1__py3-none-any.whl

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/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/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)

aurasync/event_camera.py

@@ -0,0 +1,196 @@
+"""Event-camera simulator (ESIM-style) and the scene renderer.
+
+A real event camera pixel does not take pictures. Each pixel watches its own
+log-brightness and fires an event (x, y, t, polarity) every time that value has
+moved by a contrast threshold C since the pixel's last event. Static scenes
+produce almost nothing; moving edges produce microsecond-timestamped spikes.
+
+We reproduce that from a finely-sampled rendered scene:
+  * per-pixel log-intensity reference, per-pixel threshold mismatch
+  * multiple crossings per step, with linearly interpolated timestamps
+  * background-activity noise events
+"""
+import numpy as np
+
+
+PIVOT_REF = 0.04   # scale errors are taken about the pivot height
+
+
+class SceneRenderer:
+    """Renders the cart-pole as a grayscale image (antialiased, H x W)."""
+
+    def __init__(self, H=32, W=96, px_per_m=40.0, y_min=-0.12, bg=0.15, fg=0.9, cond=None):
+        self.H, self.W, self.S = H, W, px_per_m
+        jj, ii = np.meshgrid(np.arange(W), np.arange(H))
+        self.wx = (jj + 0.5 - W / 2) / px_per_m
+        self.wy = y_min + (H - ii - 0.5) / px_per_m
+        self.bg, self.fg = bg, fg
+        self.cond = None if (cond is None or cond.is_nominal) else cond
+        if self.cond is not None:
+            c = self.cond
+            if c.x_offset_m or c.scale != 1.0:          # miscalibrated camera: pixel -> world mapping is off
+                self.wx = self.wx * c.scale + c.x_offset_m
+                self.wy = PIVOT_REF + (self.wy - PIVOT_REF) * c.scale
+            self.bgmap = np.where(self.wy > c.hdr_y, bg * c.hdr_gain, bg)
+            x0, x1, y0, y1 = c.occ_box
+            d = np.maximum(np.maximum(x0 - self.wx, self.wx - x1), np.maximum(y0 - self.wy, self.wy - y1))
+            self.occ_cov = np.clip(0.5 - d * px_per_m, 0, 1)
+
+    def render(self, s, l, t=None):
+        """Scene radiance. With conditions: HDR window, occluder (needs t), illumination scale."""
+        if self.cond is None:
+            return self._render_nominal(s, l)
+        c = self.cond
+        cov = self._coverage(s, l)
+        img = self.bgmap * (1 - cov) + self.fg * cov
+        if c.occlusion is not None and t is not None:
+            wins = c.occlusion if isinstance(c.occlusion[0], (tuple, list)) else (c.occlusion,)
+            if any(a <= t < b for a, b in wins):
+                img = img * (1 - self.occ_cov) + c.occ_value * self.occ_cov
+        return img * c.brightness
+
+    def _render_nominal(self, s, l):
+        return self.bg + (self.fg - self.bg) * self._coverage(s, l)
+
+    def _coverage(self, s, l):
+        x, th = s[0], s[2]
+        S, wx, wy = self.S, self.wx, self.wy
+        # cart: 0.2 m x 0.08 m box (signed-distance antialiasing)
+        dx = np.abs(wx - x) - 0.10
+        dy = np.abs(wy - 0.0) - 0.04
+        d_box = np.maximum(dx, dy)
+        cov_cart = np.clip(0.5 - d_box * S, 0, 1)
+        # pole: segment from pivot to tip, ~1 px thick
+        px, py = x, 0.04
+        tx, ty = x + 2 * l * np.sin(th), py + 2 * l * np.cos(th)
+        vx, vy = tx - px, ty - py
+        t = np.clip(((wx - px) * vx + (wy - py) * vy) / (vx * vx + vy * vy), 0, 1)
+        d_seg = np.hypot(wx - (px + t * vx), wy - (py + t * vy))
+        cov_pole = np.clip(0.5 - (d_seg - 0.013) * S, 0, 1)
+        return np.maximum(cov_cart, cov_pole)
+
+
+class EventCamera:
+    """Converts a stream of rendered frames into asynchronous events.
+
+    Rather than materialising every event object (memory-hungry at MHz rates)
+    the simulator reports, per pixel and polarity, the timestamp of the latest
+    crossing plus counts. `record=True` additionally keeps a raw (x, y, t, p)
+    list for visualisation.
+    """
+
+    def __init__(self, H, W, C=0.18, C_sigma=0.03, noise_rate_hz=0.3, eps=0.02,
+                 seed=0, record=False, drop_prob=0.0, tau=0.0):
+        rng = np.random.default_rng(seed)
+        self.rng = rng
+        self.Cp = np.clip(rng.normal(C, C_sigma, (H, W)), 0.05, None)
+        self.Cn = np.clip(rng.normal(C, C_sigma, (H, W)), 0.05, None)
+        self.noise_rate = noise_rate_hz
+        self.eps = eps
+        self.drop_prob = drop_prob    # events lost in readout
+        self.tau = tau                # photoreceptor time constant (0 = instantaneous)
+        self.H, self.W = H, W
+        self.L_ref = None
+        self.L_prev = None
+        self.record = record
+        self.events = []
+        self.n_events = 0
+
+    def reset(self, img):
+        self.L_ref = np.log(img + self.eps)
+        self.L_prev = self.L_ref.copy()
+        self.L_filt = self.L_ref.copy()
+
+    def step(self, img, t0, dt):
+        """Process scene change between t0 and t0+dt.
+
+        Returns (last_t_pos, last_t_neg) arrays with the crossing timestamps in
+        this interval (NaN where the pixel was silent) and the event count.
+        """
+        L = np.log(img + self.eps)
+        if self.tau > dt:   # slow photoreceptor (dim light): first-order low-pass on log intensity
+            self.L_filt = self.L_filt + (L - self.L_filt) * (dt / self.tau)
+            L = self.L_filt
+        dL = L - self.L_prev
+        diff = L - self.L_ref
+        out_p = np.full((self.H, self.W), np.nan)
+        out_n = np.full((self.H, self.W), np.nan)
+        count = 0
+        safe = np.where(np.abs(dL) > 1e-9, dL, 1e-9)
+
+        n_pos = np.floor(np.maximum(diff, 0) / self.Cp)
+        mp = n_pos >= 1
+        if mp.any():
+            level = self.L_ref[mp] + n_pos[mp] * self.Cp[mp]
+            frac = np.clip((level - self.L_prev[mp]) / safe[mp], 0, 1)
+            out_p[mp] = t0 + frac * dt
+            self.L_ref[mp] = level
+            count += int(n_pos[mp].sum())
+        n_neg = np.floor(np.maximum(-diff, 0) / self.Cn)
+        mn = n_neg >= 1
+        if mn.any():
+            level = self.L_ref[mn] - n_neg[mn] * self.Cn[mn]
+            frac = np.clip((level - self.L_prev[mn]) / safe[mn], 0, 1)
+            out_n[mn] = t0 + frac * dt
+            self.L_ref[mn] = level
+            count += int(n_neg[mn].sum())
+
+        if self.drop_prob > 0:   # readout losses: the pixel resets but the event never arrives
+            for arr in (out_p, out_n):
+                fired = ~np.isnan(arr)
+                lost = fired & (self.rng.random(arr.shape) < self.drop_prob)
+                count -= int(lost.sum()); arr[lost] = np.nan
+
+        # background-activity noise (leak / shot noise)
+        p_noise = self.noise_rate * dt
+        noise = self.rng.random((self.H, self.W)) < p_noise
+        if noise.any():
+            pol = self.rng.random(noise.sum()) < 0.5
+            ts = t0 + self.rng.random(noise.sum()) * dt
+            tgt_p = out_p[noise]; tgt_n = out_n[noise]
+            tgt_p[pol] = np.fmax(tgt_p[pol], ts[pol])
+            tgt_n[~pol] = np.fmax(tgt_n[~pol], ts[~pol])
+            out_p[noise] = tgt_p; out_n[noise] = tgt_n
+            count += int(noise.sum())
+
+        if self.record:
+            for pol, arr in ((1, out_p), (-1, out_n)):
+                ys, xs = np.nonzero(~np.isnan(arr))
+                for y, x in zip(ys, xs):
+                    self.events.append((x, y, arr[y, x], pol))
+        self.L_prev = L
+        self.n_events += count
+        return out_p, out_n, count
+
+
+class TimeSurfaceEncoder:
+    """Event-to-tensor compression: fixed-size, exponentially-decaying time surface.
+
+    Every pixel/polarity keeps only the timestamp of its latest event. When the
+    controller asks for a state at time t, the surface is
+        T[c, y, x] = exp(-(t - t_last[c, y, x]) / tau_c)
+    Memory is constant (H x W x channels) no matter how many events arrive, so
+    there is no buffer bloat and no dropped events at high event rates; the
+    newest events dominate and old ones fade continuously.
+
+    Channels: [pos fast, neg fast, any slow]
+    """
+
+    def __init__(self, H, W, tau_fast=0.008, tau_slow=0.040):
+        self.tau_fast, self.tau_slow = tau_fast, tau_slow
+        self.t_pos = np.full((H, W), -1e9)
+        self.t_neg = np.full((H, W), -1e9)
+
+    def update(self, last_p, last_n):
+        self.t_pos = np.fmax(self.t_pos, last_p)
+        self.t_neg = np.fmax(self.t_neg, last_n)
+
+    def tensor(self, t):
+        tp = np.exp(-(t - self.t_pos) / self.tau_fast)
+        tn = np.exp(-(t - self.t_neg) / self.tau_fast)
+        ta = np.exp(-(t - np.maximum(self.t_pos, self.t_neg)) / self.tau_slow)
+        return np.stack([tp, tn, ta]).astype(np.float32)
+
+    @property
+    def nbytes(self):
+        return self.t_pos.nbytes + self.t_neg.nbytes