aurasync-engine 0.4.1__py3-none-any.whl

aurasync/scheduler.py

@@ -0,0 +1,191 @@
+"""Event-triggered neural correction with a deadline guarantee (Upgrade C).
+
+Analogy: an air-traffic controller who dead-reckons every plane each second
+(cheap) and only asks for a radar sweep (expensive) when something happens: a
+burst of activity, growing doubt, a plane near another one, or simply because it
+has been too long. The radar takes time, so the controller never waits for it.
+
+Per 1 ms control tick (never waits on the network):
+  1. physics prediction s <- RK4(s, u); covariance  Sigma <- A Sigma A^T + Q
+  2. if a correction result has arrived: roll the corrected state at its capture
+     time forward through the controls applied since (replay), take its covariance
+  3. if the worker is idle and a trigger fires, capture the current time surface
+     and start a correction job; it completes after a compute latency sampled
+     from the latency measured on this CPU
+Triggers (mode 'triggered'):
+  burst      >= burst_thr pixels fired an event in the last tick
+  doubt      propagated sigma_theta > sigma_trig
+  margin     |psi| = |theta + 0.1 theta_dot| > margin_trig (close to the safety envelope)
+  max gap    >= max_gap ticks since the last correction (quiet scenes still get checked)
+Deadline: a job not finished within `deadline` ticks is abandoned (deadline
+miss, logged). Fallback is deterministic: keep the physics prediction and let
+the covariance grow, which tightens the safety shield and can trip its stale mode.
+Other modes, for comparison at matched compute:
+  dense      a correction every tick, synchronous, 1 tick delay (the v2 behaviour;
+             infeasible in real time on this CPU, kept as reference)
+  greedy     async; start a new job whenever the worker is free
+  periodic   async; start a job every `period` ticks
+"""
+from collections import deque
+import numpy as np
+import torch
+
+from .physics import PlantParams, rk4_step, linearise
+from .estimator import SCALE
+
+DT = 1e-3
+SCALE_NP = SCALE.numpy().astype(np.float64)
+FRESH = float(np.exp(-1e-3 / 0.008))     # fast time-surface value of an event < 1 ms old
+
+
+class TriggeredEventPipeline:
+    def __init__(self, models, mode="triggered", latency_samples=(0.0018,), deadline=6,
+                 period=5, max_gap=20, burst_thr=12, sigma_trig_deg=1.5, margin_trig_deg=7.0,
+                 temp=None, Q=None, seed=0, name=None, plant=None):
+        self.models = [m.eval() for m in (models if isinstance(models, (list, tuple)) else [models])]
+        self.mode, self.deadline, self.period, self.max_gap = mode, deadline, period, max_gap
+        self.burst_thr = burst_thr
+        self.sigma_trig, self.margin_trig = np.radians(sigma_trig_deg), np.radians(margin_trig_deg)
+        self.lat = np.asarray(latency_samples, float) * len(self.models)   # members run sequentially
+        self.temp = np.ones(4) if temp is None else np.asarray(temp, float)
+        self.p = plant or PlantParams()
+        self.A, _ = linearise(self.p, DT)
+        self.Q = np.diag([1e-9, 1e-5, 1e-8, 1e-4]) if Q is None else Q
+        self.seed = seed
+        tag = "" if len(self.models) == 1 else f"-ens{len(self.models)}"
+        self.name = name or f"event-{mode}{tag}"
+        self.delay_ticks = 1 if mode == "dense" else 0
+
+    # ---- interface used by run_episode / ShieldedController ---------------------
+    def reset(self, s0):
+        self.rng = np.random.default_rng(self.seed)
+        self.s = np.asarray(s0, float).copy()
+        self.Sigma = np.diag((0.05 * SCALE_NP) ** 2)
+        self.h = [m.init_hidden(1) for m in self.models]
+        self.u_hist = deque(maxlen=256)
+        self.k = -1
+        self.last_capture = 0
+        self.job = None                        # (capture_k, done_k, s_corr, Sigma_corr, new_h)
+        self.out = deque([(self.s.copy(), self.Sigma.copy())] * 2, maxlen=2)
+        self.log = dict(calls=0, misses=0, triggers=dict(burst=0, doubt=0, margin=0, gap=0, idle=0, periodic=0),
+                        busy_ticks=0, sigma_th=[], corrected=[])
+
+    def estimate(self):
+        return self.out[0][0] if self.mode == "dense" else self.out[-1][0]
+
+    def covariance(self):
+        return self.out[0][1] if self.mode == "dense" else self.out[-1][1]
+
+    def age_ticks(self):
+        return self.delay_ticks
+
+    # ---- internals ----------------------------------------------------------------
+    @torch.inference_mode()
+    def _correct(self, surface, s_pred, gap):
+        ts = torch.from_numpy(np.ascontiguousarray(surface, dtype=np.float32))[None]
+        sp = torch.tensor(s_pred, dtype=torch.float32)[None]
+        g = torch.tensor([float(gap)])
+        outs, vars_, hs = [], [], []
+        for m, h in zip(self.models, self.h):
+            z, act = m.encode(ts)
+            s_new, h_new, _, lv = m.correct(z, act, h, sp, g)
+            outs.append(s_new[0].double().numpy()); hs.append(h_new)
+            vars_.append((np.exp(lv[0].double().numpy()) * SCALE_NP ** 2) * self.temp ** 2)
+        outs = np.stack(outs)
+        mean = outs.mean(0)
+        var = np.mean(vars_, 0) + (outs.var(0) if len(outs) > 1 else 0.0)   # aleatoric + epistemic
+        return mean, np.diag(var), hs
+
+    def _propagate(self, s, Sigma, u):
+        return rk4_step(s, u, DT, self.p), self.A @ Sigma @ self.A.T + self.Q
+
+    def _trigger(self, surface):
+        if self.mode == "greedy":
+            return "idle"
+        gap = self.k - self.last_capture
+        if self.mode == "periodic":
+            return "periodic" if gap >= self.period else None
+        if gap >= self.max_gap:
+            return "gap"
+        if (surface[0] >= FRESH).sum() + (surface[1] >= FRESH).sum() >= self.burst_thr:
+            return "burst"
+        if np.sqrt(self.Sigma[2, 2]) > self.sigma_trig:
+            return "doubt"
+        if abs(self.s[2] + 0.1 * self.s[3]) > self.margin_trig:
+            return "margin"
+        return None
+
+    def update(self, k, t, s_true, surface, u):
+        self.k = k
+        self.u_hist.append(u)
+        if self.mode == "dense":
+            s_pred, _ = self._propagate(self.s, self.Sigma, u)
+            self.s, self.Sigma, self.h = self._correct(surface, s_pred, 1)
+            self.log["calls"] += 1
+            self.out.append((self.s.copy(), self.Sigma.copy()))
+            self.log["sigma_th"].append(np.sqrt(self.Sigma[2, 2])); self.log["corrected"].append(True)
+            return
+        # 1. cheap physics prediction, every tick
+        self.s, self.Sigma = self._propagate(self.s, self.Sigma, u)
+        corrected = False
+        # 2. collect a finished job (or abandon one past its deadline)
+        if self.job is not None:
+            cap_k, done_k, s_c, S_c, h_new = self.job
+            if done_k - cap_k > self.deadline and k >= cap_k + self.deadline:
+                self.log["misses"] += 1                          # deadline miss -> discard
+                self.job = None
+            elif k >= done_k:
+                for uu in list(self.u_hist)[-(k - cap_k):] if k > cap_k else []:
+                    s_c, S_c = self._propagate(s_c, S_c, uu)    # replay controls since capture
+                self.s, self.Sigma, self.h = s_c, S_c, h_new
+                self.job = None
+                corrected = True
+            else:
+                self.log["busy_ticks"] += 1
+        # 3. start a new job if idle and triggered
+        if self.job is None:
+            why = self._trigger(surface)
+            if why is not None:
+                gap = max(1, k - self.last_capture)
+                s_c, S_c, h_new = self._correct(surface, self.s, gap)
+                lat_ticks = int(np.ceil(self.rng.choice(self.lat) / DT))
+                self.job = (k, k + lat_ticks, s_c, S_c, h_new)
+                self.last_capture = k
+                self.log["calls"] += 1
+                self.log["triggers"][why] += 1
+        self.out.append((self.s.copy(), self.Sigma.copy()))
+        self.log["sigma_th"].append(np.sqrt(self.Sigma[2, 2])); self.log["corrected"].append(corrected)
+
+
+@torch.inference_mode()
+def measure_correction_latency(model, n=3000, warm=200):
+    """Wall-clock cost of one neural correction (encode + correct) on one CPU thread."""
+    import time
+    torch.set_num_threads(1)
+    ts = torch.rand(1, 4, 32, 96); h = model.init_hidden(1); s = torch.zeros(1, 4); g = torch.ones(1)
+    out = []
+    for i in range(n + warm):
+        a = time.perf_counter()
+        z, act = model.encode(ts)
+        model.correct(z, act, h, s, g)
+        b = time.perf_counter()
+        if i >= warm:
+            out.append(b - a)
+    return np.array(out)
+
+
+def physics_tick_cost(n=5000):
+    """Cost of the always-on part of the control tick: prediction + covariance + LQR + shield."""
+    import time
+    from .controller import LQRController
+    from .safety import SafetyShield
+    p = PlantParams(); A, _ = linearise(p, DT); Q = np.diag([1e-9, 1e-5, 1e-8, 1e-4])
+    lqr = LQRController(p); sh = SafetyShield(p)
+    s = np.array([0.01, 0.0, 0.02, 0.1]); S = np.eye(4) * 1e-4
+    out = []
+    for i in range(n):
+        a = time.perf_counter()
+        s2 = rk4_step(s, 0.5, DT, p); S2 = A @ S @ A.T + Q
+        sh.filter(s2, S2, lqr.act(s2))
+        out.append(time.perf_counter() - a)
+    return np.array(out)

aurasync/simulate.py

@@ -0,0 +1,168 @@
+"""Closed-loop hardware-in-the-loop style simulation.
+
+Plant physics runs at 5 kHz (200 us substeps); the event camera samples every
+substep; the controller ticks at 1 kHz. Perception pipelines plug in through a
+small interface so event-based and frame-based stacks are compared on the
+exact same plant, disturbances and controller.
+"""
+from collections import deque
+import numpy as np
+import torch
+
+from .physics import rk4_step, failed
+from .event_camera import SceneRenderer, EventCamera, TimeSurfaceEncoder
+from .conditions import NOMINAL
+
+DT = 1e-3
+SUB = 5
+
+
+class OraclePipeline:
+    """Perfect, instantaneous state (upper bound - not physically achievable)."""
+    name = "oracle"
+
+    def reset(self, s0): self.s = s0.copy()
+
+    def update(self, k, t, s_true, surface, u): self.s = s_true.copy()
+
+    def estimate(self): return self.s
+
+
+class FramePipeline:
+    """Conventional frame camera + vision model.
+
+    A frame is captured every 1/fps seconds; its result is available `latency`
+    seconds later (readout + inference). Deliberately generous: the frame model
+    is given the TRUE pose and velocity at capture time (no estimation error,
+    no motion blur). Only the timing is realistic.
+    """
+
+    def __init__(self, fps, latency):
+        self.fps, self.latency = fps, latency
+        self.name = f"frame-{fps}fps"
+
+    def reset(self, s0):
+        self.pending = deque()
+        self.s = s0.copy()
+        self.next_capture = 0.0
+
+    def update(self, k, t, s_true, surface, u):
+        if t + 1e-9 >= self.next_capture:
+            self.pending.append((t + self.latency, s_true.copy()))
+            self.next_capture += 1.0 / self.fps
+        while self.pending and self.pending[0][0] <= t + 1e-9:
+            self.s = self.pending.popleft()[1]
+
+    def estimate(self): return self.s
+
+
+class EventPipeline:
+    """AuraSync: event time-surface -> physics-informed observer, 1 tick latency."""
+    name = "aurasync-event"
+
+    def __init__(self, model, delay_ticks=1):
+        self.model = model.eval()
+        self.delay_ticks = delay_ticks
+
+    def reset(self, s0):
+        self.s_hat = torch.tensor(s0, dtype=torch.float32)[None]
+        self.h = self.model.init_hidden(1)
+        self.buf = deque([s0.copy()] * (self.delay_ticks + 1), maxlen=self.delay_ticks + 1)
+
+    @torch.inference_mode()
+    def update(self, k, t, s_true, surface, u):
+        z = self.model.enc(torch.from_numpy(surface)[None])
+        self.s_hat, self.h, _ = self.model.cell(z, self.h, self.s_hat,
+                                                torch.tensor([u], dtype=torch.float32))
+        self.buf.append(self.s_hat[0].numpy().astype(np.float64))
+
+    def estimate(self): return self.buf[0]
+
+
+def run_episode(p, controller, pipeline, n_ticks, s0, kicks=(), snap=None,
+                exploration=None, rng=None, record=False, cam_seed=0,
+                stop_on_fail=True, renderer=None, aps_fps=30, aps_latency=0.005, cond=NOMINAL,
+                aps_seed=None):
+    """kicks: list of (tick, delta_theta_dot). snap: (tick, new_params) mid-episode
+    plant change (e.g. mass shift from a mechanical failure).
+
+    The sensor is modelled as a hybrid DAVIS-style pixel array: asynchronous
+    events PLUS a slow absolute intensity (APS) frame at `aps_fps`, delivered
+    `aps_latency` after capture. Events give speed; the slow frame anchors
+    drift when the scene is still and no events are produced.
+
+    cond: SensorConditions shared by the scene, the event camera, its APS frame
+    and any frame-camera pipeline (NOMINAL reproduces v2 exactly)."""
+    nominal = cond.is_nominal
+    renderer = renderer or SceneRenderer(cond=cond)
+    if nominal:
+        cam = EventCamera(renderer.H, renderer.W, seed=cam_seed)
+    else:
+        cam = EventCamera(renderer.H, renderer.W, seed=cam_seed, C_sigma=cond.thresh_sigma,
+                          noise_rate_hz=cond.ev_noise_rate, drop_prob=cond.drop_prob,
+                          tau=cond.photoreceptor_tau)
+        aps_rng = np.random.default_rng(10_000 + (cam_seed if aps_seed is None else aps_seed))
+        aps_exp = cond.frame_exposure()
+        aps_hist = deque(maxlen=max(1, int(round(aps_exp / (DT / SUB)))))
+    enc = TimeSurfaceEncoder(renderer.H, renderer.W)
+    s = np.array(s0, dtype=np.float64)
+    cam.reset(renderer.render(s, p.l, 0.0))
+    kicks = dict(kicks)
+    if hasattr(pipeline, "set_conditions"):
+        pipeline.set_conditions(cond)
+    if getattr(pipeline, "needs_true_plant", False):       # sensor simulation needs the real plant from tick 0
+        pipeline.p_true = p
+    pipeline.reset(s)
+    log = dict(s=[], s_hat=[], u=[], surf=[], events=[], fail_tick=None)
+    aps = renderer.render(s, p.l, 0.0).astype(np.float32)
+    if not nominal:
+        aps = cond.frame_sensor(aps).astype(np.float32)
+    aps_pending, next_aps = deque(), 0.0
+    t = 0.0
+    u = 0.0
+    for k in range(n_ticks):
+        if snap is not None and k == snap[0]:
+            p = snap[1]
+        if k in kicks:
+            s[3] += kicks[k]
+        est = pipeline.estimate()
+        u = controller.act(est)
+        if exploration is not None:
+            u = float(np.clip(u + exploration(), -p.u_max, p.u_max))
+        n_ev = 0
+        for j in range(SUB):
+            s = rk4_step(s, u, DT / SUB, p)
+            img = renderer.render(s, p.l, t + (j + 1) * DT / SUB)
+            lp, ln, c = cam.step(img, t + j * DT / SUB, DT / SUB)
+            enc.update(lp, ln)
+            n_ev += c
+            if not nominal:
+                aps_hist.append(img)
+            if aps_fps and t + j * DT / SUB >= next_aps - 1e-9:
+                if nominal:
+                    frame = img.astype(np.float32)
+                else:   # same sensor model as the frame camera: exposure blur, saturation, noise
+                    frame = cond.frame_sensor(np.mean(aps_hist, 0))
+                    frame = (frame + aps_rng.normal(0, cond.frame_noise(aps_exp), frame.shape)).astype(np.float32)
+                aps_pending.append((next_aps + aps_latency, frame))
+                next_aps += 1.0 / aps_fps
+        t += DT
+        while aps_pending and aps_pending[0][0] <= t + 1e-9:
+            aps = aps_pending.popleft()[1]
+        surface = np.concatenate([enc.tensor(t), aps[None]])
+        if getattr(pipeline, "needs_true_plant", False):   # proprioceptive sensors feel the real plant
+            pipeline.p_true = p
+        pipeline.update(k, t, s, surface, u)
+        log["s"].append(s.copy()); log["u"].append(u); log["events"].append(n_ev)
+        log["s_hat"].append(np.array(pipeline.estimate()))
+        if record:
+            log["surf"].append(surface.astype(np.float16))
+        if failed(s, p):
+            log["fail_tick"] = k
+            if stop_on_fail:
+                break
+    for key in ("s", "s_hat", "u", "events"):
+        log[key] = np.array(log[key])
+    if record:
+        log["surf"] = np.stack(log["surf"])
+    return log

aurasync/v4/geo_pipeline.py

@@ -0,0 +1,61 @@
+"""Baseline D: independent event-geometry estimator (no neural network).
+
+Physics prediction every tick (same nominal RK4 model and process noise as the
+V3 filter) + gated Kalman fusion of the event-geometry measurement (theta and
+pivot x). Velocities are inferred by the filter through the dynamics. When no
+valid measurement exists (quiet scene) it coasts on physics with growing
+covariance. Same pipeline interface as every other estimator.
+"""
+import numpy as np
+
+from ..physics import PlantParams, rk4_step, linearise
+from ..estimator import SCALE
+from .geometry import EventGeometry
+
+DT = 1e-3
+SCALE_NP = SCALE.numpy().astype(np.float64)
+
+
+class GeoPipeline:
+    def __init__(self, Q=None, gate=9.0, sigma_x_floor=0.004, plant=None, seed=0, name="event-geometry"):
+        self.p = plant or PlantParams()
+        self.A, _ = linearise(self.p, DT)
+        self.Q = np.diag([1e-9, 1e-5, 1e-8, 1e-4]) * 1e4 if Q is None else Q
+        self.gate, self.sx = gate, sigma_x_floor
+        self.geo = EventGeometry(seed=seed + 1)
+        self.seed, self.name = seed, name
+        self.delay_ticks = 0
+
+    def reset(self, s0):
+        self.geo.rng = np.random.default_rng(self.seed + 1)
+        self.s = np.asarray(s0, float).copy()
+        self.Sigma = np.diag((0.05 * SCALE_NP) ** 2)
+        self.n_fused = 0
+
+    def update(self, k, t, s_true, surface, u):
+        self.s = rk4_step(self.s, u, DT, self.p)
+        self.Sigma = self.A @ self.Sigma @ self.A.T + self.Q
+        m = self.geo.measure(surface, self.s[0])
+        if m is None or not m["valid"]:
+            return
+        H = np.array([[0, 0, 1.0, 0], [1.0, 0, 0, 0]])
+        z = np.array([m["theta"], m["x_pivot"]])
+        R = np.diag([m["sigma_theta"] ** 2, max(self.sx, 0.5 / self.geo.S / np.sqrt(m["n_inliers"])) ** 2])
+        S = H @ self.Sigma @ H.T + R
+        nu = z - H @ self.s
+        if nu[0] ** 2 / S[0, 0] > self.gate and self.n_fused > 50:        # outlier rejection once tracking
+            return
+        K = np.linalg.solve(S, H @ self.Sigma).T
+        self.s = self.s + K @ nu
+        I_KH = np.eye(4) - K @ H
+        self.Sigma = I_KH @ self.Sigma @ I_KH.T + K @ R @ K.T
+        self.n_fused += 1
+
+    def estimate(self):
+        return self.s
+
+    def covariance(self):
+        return self.Sigma
+
+    def age_ticks(self):
+        return 0

aurasync/v4/geometry.py

@@ -0,0 +1,97 @@
+"""Independent event-derived geometric measurement of the pole (V4, Modules A + B).
+
+Analogy: instead of asking the navigator where the ship is, look out of the window
+and line up the mast against the horizon. No memory, no learned model: just the
+geometry of where events are firing right now.
+
+The pole is a straight segment from the pivot (x_p, PIVOT_Y) at angle theta.
+A moving pole fires events along its edges, so the fresh events (younger than
+`window` seconds; their age is exactly recoverable from the time surface) lie
+near the line
+        x = x_p + (y - PIVOT_Y) * tan(theta)
+Fitting x as a function of y is well conditioned for the angles that matter
+(|theta| < 60 deg). The fit is robust (RANSAC + least-squares refinement on
+inliers) because background noise events are scattered uniformly.
+
+Output per call (or None when the evidence is insufficient):
+    theta, x_pivot      measured pole angle and pivot position
+    sigma_theta         measurement standard deviation (from inlier scatter,
+                        inlier count and vertical extent, floored)
+    n_inliers, span     support of the fit (span = fraction of pole length covered)
+    snr                 inlier density / background event density
+    quality in [0, 1]   combined reliability used for gating
+Uses nothing but the sensor surface and the nominal pole length (no ground truth).
+"""
+import numpy as np
+
+from ..event_camera import SceneRenderer
+
+PIVOT_Y = 0.04
+TAU_FAST = 0.008
+
+
+class EventGeometry:
+    def __init__(self, l=0.25, window=0.003, band_halfwidth=0.6, inlier_px=1.5, n_iter=60,
+                 min_inliers=8, min_span=0.35, min_snr=4.0, sigma_floor_deg=0.4, seed=0):
+        r = SceneRenderer()
+        self.S = r.S
+        self.wx, self.wy = r.wx, r.wy
+        self.l, self.band = l, band_halfwidth
+        self.fresh = float(np.exp(-window / TAU_FAST))
+        self.inl = inlier_px / r.S
+        self.n_iter, self.min_inliers, self.min_span, self.min_snr = n_iter, min_inliers, min_span, min_snr
+        self.sigma_floor = np.radians(sigma_floor_deg)
+        self.rng = np.random.default_rng(seed)
+        self.y_lo, self.y_hi = PIVOT_Y + 0.06, PIVOT_Y + 2 * l + 0.04     # above the cart, up to the tip
+
+    def events(self, surface):
+        ev = (surface[0] >= self.fresh) | (surface[1] >= self.fresh)
+        return ev
+
+    def measure(self, surface, x_hint):
+        """Fit the pole line to fresh events in a vertical band around x_hint (the current
+        pivot estimate; only used to choose where to look)."""
+        ev = self.events(surface)
+        roi = (self.wy >= self.y_lo) & (self.wy <= self.y_hi) & (np.abs(self.wx - x_hint) <= self.band)
+        sel = ev & roi
+        n = int(sel.sum())
+        if n < self.min_inliers:
+            return None
+        X, Y = self.wx[sel], self.wy[sel] - PIVOT_Y
+        # background density from fresh events outside the region (per pixel)
+        out = ev & ~roi & (self.wy > self.y_lo)
+        bg_density = out.sum() / max((~roi & (self.wy > self.y_lo)).sum(), 1)
+        # vectorised RANSAC: all hypotheses scored in one array operation
+        i = self.rng.integers(0, n, self.n_iter); j = self.rng.integers(0, n, self.n_iter)
+        dy = Y[i] - Y[j]
+        ok = np.abs(dy) >= 0.08
+        if not ok.any():
+            return None
+        i, j, dy = i[ok], j[ok], dy[ok]
+        slope = (X[i] - X[j]) / dy                                          # tan(theta) per hypothesis
+        keep = np.abs(slope) <= np.tan(np.radians(70))
+        if not keep.any():
+            return None
+        slope, x0 = slope[keep], (X[i] - slope * Y[i])[keep]
+        inl_all = np.abs(X[None, :] - (x0[:, None] + slope[:, None] * Y[None, :])) <= self.inl
+        b = int(inl_all.sum(1).argmax())
+        best_in = inl_all[b]
+        if best_in.sum() < self.min_inliers:
+            return None
+        Xi, Yi = X[best_in], Y[best_in]
+        A = np.stack([np.ones_like(Yi), Yi], 1)
+        (x0, slope), *_ = np.linalg.lstsq(A, Xi, rcond=None)                # refine on inliers
+        res = Xi - (x0 + slope * Yi)
+        theta = float(np.arctan(slope))
+        span = float((Yi.max() - Yi.min()) / (2 * self.l))
+        # inlier band area (pixels) for the noise comparison
+        band_px = 2 * self.inl * self.S * (Yi.max() - Yi.min()) * self.S + 1e-9
+        snr = float(best_in.sum() / max(bg_density * band_px, 0.5))
+        # angle uncertainty: horizontal scatter over the vertical lever arm (Gauss-Markov), floored
+        sx = max(float(res.std()), 0.5 / self.S)
+        sy = max(float(Yi.std()), 1e-3)
+        sigma = float(np.hypot(sx / (sy * np.sqrt(best_in.sum())), self.sigma_floor)) / np.cos(theta) ** 2
+        quality = float(np.clip(min(span / 0.8, snr / 10.0, best_in.sum() / 30.0), 0, 1))
+        valid = span >= self.min_span and snr >= self.min_snr
+        return dict(theta=theta, x_pivot=float(x0), sigma_theta=sigma, n_inliers=int(best_in.sum()),
+                    n_events=n, span=span, snr=snr, quality=quality, valid=bool(valid))