aurasync-engine 0.4.1__py3-none-any.whl

aurasync_engine-0.4.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,23 @@
+aurasync/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aurasync/conditions.py,sha256=gy0M6pzs8guXEt_XzGFl626mGx7sZlyyfNK-Ap_Mo70,3756
+aurasync/controller.py,sha256=k1Dx63vL04CzavCjFzI3BD6Qr-1iDIcMTUNscPvYTzY,1230
+aurasync/estimator.py,sha256=6IM5RmJKo9kB4MFFIFzpypHT5cLKA9n4UCsuJ5Drigo,12390
+aurasync/event_camera.py,sha256=NeEsZFRPlM0H8VhfgzK5AjPFD3JSxugTYwdI_K2YlwE,8415
+aurasync/frame_camera.py,sha256=lDNiNVH1CBe99DVVVbhe61oUtJ5uB_FikX2HY6w8jso,8254
+aurasync/imu.py,sha256=qSU8bI3N3AH1tkQAxTlnBNKNl0NcJuUAytMU5U8gP54,4322
+aurasync/monitor.py,sha256=33vVypk1CzMh2jpEJTbARtmR7x23Lm7mSrty52YcmTA,3844
+aurasync/physics.py,sha256=-W6_IJTwcWnDyC8jUVjpPGInlv67G18I2A79knin8Cs,2372
+aurasync/safety.py,sha256=ACOH2upJ4hF-lcI43_L8KkzEGzRvWtRMJkaafJNAL8M,9057
+aurasync/scheduler.py,sha256=c4nCm6d-j1NeCr0p2AXvAbzF83jJ3THZWnI9cusHa84,9146
+aurasync/simulate.py,sha256=e5mJgh0sSqiNs1PqBN9hMMrX0OSVbfWag0sFfLMg3-8,6893
+aurasync/v4/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aurasync/v4/geo_pipeline.py,sha256=NfpfBDIib0dAFrIe4nUZ6wLc9G9LdZw1Aq4vt_a8RAI,2325
+aurasync/v4/geometry.py,sha256=bae72m0c42koTHxhQZaflzIo9tgwF6L8E3K-fD_0wyA,5007
+aurasync/v4/pipeline.py,sha256=s94ezJMBDPtWmyjXJNFgS6oceeNPA7raCDG4kW3-fnU,14565
+aurasync/v41/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aurasync/v41/pipeline.py,sha256=FP287c6E2F7Rh3Jjz5HdJcVzaopizY4yjV6RLYU8e0g,13926
+aurasync_engine-0.4.1.dist-info/licenses/LICENSE,sha256=NdrPQ4QWLflSRb_CFdu8o6eN-AC6ufXnXI4lgYaye3k,1067
+aurasync_engine-0.4.1.dist-info/METADATA,sha256=17BokzAEQCOhvgN4d7RT1InCzVTLlaxSmMSw9cXd9mU,7260
+aurasync_engine-0.4.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+aurasync_engine-0.4.1.dist-info/top_level.txt,sha256=lsy2ckuU5PdfNw69mMtVlO3l2YfVNZ90D9riYy_4JO0,9
+aurasync_engine-0.4.1.dist-info/RECORD,,

aurasync_engine-0.4.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aurasync_engine-0.4.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+aurasync