From eb88035699f313a51e130fec36a7510f086657db Mon Sep 17 00:00:00 2001 From: rUv Date: Fri, 22 May 2026 07:54:19 -0400 Subject: [PATCH] docs(examples/research-sota): add main + 9 sub-folder READMEs (follow-up to #744) (#745) PR #744 moved the files into 9 thematic folders via git mv but missed the READMEs due to a working-directory issue with git add. This PR adds the actual READMEs: - examples/research-sota/README.md (main overview) - examples/research-sota/01-physics-floor/README.md - examples/research-sota/02-placement/README.md - examples/research-sota/03-spatial-intelligence/README.md - examples/research-sota/04-rssi/README.md - examples/research-sota/05-cross-room-reid/README.md - examples/research-sota/06-structure-detection/README.md - examples/research-sota/07-negative-results/README.md - examples/research-sota/08-verticals/README.md - examples/research-sota/09-quantum-fusion/README.md Each sub-README documents: - Scripts + headlines table - Why this folder bounds/composes with others - Sample output / honest scope - Cross-references to related loop notes + ADRs Main README covers: - Folder map with thread numbers - Cross-folder dependency graph - 8-entry headline findings table - Reading order for newcomers (4 scripts in suggested order) - Honest scope (synthetic-physics caveats) --- .../research-sota/01-physics-floor/README.md | 43 +++++++++ examples/research-sota/02-placement/README.md | 39 +++++++++ .../03-spatial-intelligence/README.md | 39 +++++++++ examples/research-sota/04-rssi/README.md | 35 ++++++++ .../05-cross-room-reid/README.md | 48 ++++++++++ .../06-structure-detection/README.md | 58 +++++++++++++ .../07-negative-results/README.md | 48 ++++++++++ examples/research-sota/08-verticals/README.md | 50 +++++++++++ .../research-sota/09-quantum-fusion/README.md | 62 +++++++++++++ examples/research-sota/README.md | 87 +++++++++++++++++++ 10 files changed, 509 insertions(+) create mode 100644 examples/research-sota/01-physics-floor/README.md create mode 100644 examples/research-sota/02-placement/README.md create mode 100644 examples/research-sota/03-spatial-intelligence/README.md create mode 100644 examples/research-sota/04-rssi/README.md create mode 100644 examples/research-sota/05-cross-room-reid/README.md create mode 100644 examples/research-sota/06-structure-detection/README.md create mode 100644 examples/research-sota/07-negative-results/README.md create mode 100644 examples/research-sota/08-verticals/README.md create mode 100644 examples/research-sota/09-quantum-fusion/README.md create mode 100644 examples/research-sota/README.md diff --git a/examples/research-sota/01-physics-floor/README.md b/examples/research-sota/01-physics-floor/README.md new file mode 100644 index 00000000..7f3e3fb0 --- /dev/null +++ b/examples/research-sota/01-physics-floor/README.md @@ -0,0 +1,43 @@ +# 01 — Physics-floor primitives + +Bedrock physics that bounds everything else in the loop. Three primitives: + +## Scripts + +| Script | Thread | Headline | +|---|---|---| +| `r1_toa_crlb.py` | R1 | 20 MHz HT20 @ 20 dB SNR ToA CRLB: 41 cm single-shot, 4 cm with 100× averaging. Phase vs ToA: 238× advantage with cycle-slip resolution. | +| `r6_fresnel_zone.py` | R6 | First-Fresnel envelope at 5 m link, 2.4 GHz: 40 cm wide ellipsoid at midpoint. Per-subcarrier phase predictions for 4 canonical scatterer scenarios. | +| `r6_1_multiscatterer.py` | R6.1 | 6-scatterer human body model. Multi-scatterer penalty: **+4.7 dB** worse than idealised single-scatterer (matches R13's 5-dB shortfall to 0.3 dB). | + +## Why this folder bounds the rest + +- **R1 CRLB** sets the temporal-resolution floor for any localisation feature. +- **R6 Fresnel** gives the spatial envelope of CSI sensitivity (~40 cm wide at 5 m link). +- **R6.1 multi-scatterer** extends R6 from point-scatterer to realistic distributed body; quantifies the gap between idealised and real physics. + +Together: physics floors that bound R6.2 family (placement), R12 family (structure detection), R14 (vitals), R20 (quantum integration). + +## Sample output + +``` +=== R6 first Fresnel radii (m) === + freq lambda link p=0.10 p=0.25 p=0.50 p=0.75 p=0.90 + 2.4 124.9mm 5.0m 0.237 0.342 0.395 0.342 0.237 + +=== R6.1 multi-scatterer penalty === + Single-scatterer ideal: +23.7 dB + Multi-scatterer (6 body parts): +19.0 dB + Penalty: +4.7 dB +``` + +## Honest scope + +- All numbers are best-case physics; real CSI has additional noise channels. +- Body model is 6 point-scatterers; real body is distributed continuous RCS. +- 2D (top-down) approximations; 3D extensions live in `02-placement/`. + +## See also + +- Loop research notes: `docs/research/sota-2026-05-22/R{1,6,6_1}-*.md` +- Used by: `02-placement/`, `03-spatial-intelligence/`, `06-structure-detection/`, `09-quantum-fusion/` diff --git a/examples/research-sota/02-placement/README.md b/examples/research-sota/02-placement/README.md new file mode 100644 index 00000000..479e329c --- /dev/null +++ b/examples/research-sota/02-placement/README.md @@ -0,0 +1,39 @@ +# 02 — Antenna placement (R6.2 family, 7 sub-ticks) + +The 9-tick R6.2 family productised R6's forward model into a working CLI-shaped placement search. Each script answers one axis of the placement question. + +## Scripts (in development order) + +| Script | Thread | Axis | Headline | +|---|---|---|---| +| `r6_2_antenna_placement.py` | R6.2 | 2D single-pair | Optimal placement is **93× better** than median random; corner-to-corner diagonal | +| `r6_2_1_3d_placement.py` | R6.2.1 | 3D single-pair | **Ceiling-only mounting fails (0% coverage)** — Fresnel envelope sits at ceiling, never reaches floor targets | +| `r6_2_2_multistatic_placement.py` | R6.2.2 | 2D N-anchor | Knee at **N=5** anchors for typical bedroom (96.8% body-zone coverage) | +| `r6_2_2_1_3d_multistatic.py` | R6.2.2.1 | 3D N-anchor | **2D knee disappears in 3D** — only 49% at N=5 with body zones | +| `r6_2_3_chest_centric.py` | R6.2.3 | 2D chest-centric | +27 pp coverage gain when targeting chest specifically (vital-signs cog) | +| `r6_2_4_3d_chest_multistatic.py` | R6.2.4 | 3D chest-centric | Recovers 3D shortfall — **77% at N=5, 82% at N=6 chest-centric** | +| `r6_2_5_multi_subject.py` | R6.2.5 | Multi-subject union | **100% coverage for 1-4 occupants at N=5** chest-centric | + +## Decision matrix (final ADR-113 output) + +| Cog category | Dimension | Zone mode | Occupants | N | Heights | Coverage | +|---|---|---|---:|---:|---|---:| +| Vital signs | 2D | chest | 1-4 | 5 | walls 0.8/1.5 m | **100%** | +| Vital signs | 3D | chest | 1-4 | 6 | walls 0.8/1.5 (NO ceiling) | 82% | +| Pose estimation | 2D | body | 1-2 | 5 | walls mixed | 97% | +| Pose estimation | 3D | body | 1-2 | 7-8 | mixed L/M/H | 65%+ | +| Person count | 2D | body | 1-4 | 4 | walls mixed | 86% | + +## Counter-intuitive findings + +1. **Longer links cover more space.** Fresnel envelope width = √(d·λ)/2 grows with d. +2. **Ceiling-only fails entirely** (R6.2.1) — both anchors at 2.5 m put envelope at ceiling height, target zones below are missed. +3. **2D N=5 knee doesn't hold in 3D** (R6.2.2.1) — 3D ellipsoids are thin slabs, not 2D rectangles. +4. **Anchor heights should match target zone heights** (R6.2.4) — chest-centric uses low+mid, NOT ceiling. +5. **Chest-centric beats body-centric for vital signs by +27 pp** (R6.2.3). + +## See also + +- Architectural decision: `docs/adr/ADR-113-multistatic-placement-strategy.md` +- Research notes: `docs/research/sota-2026-05-22/R6_2*.md` +- Composes with: `01-physics-floor/` (forward model), `06-structure-detection/` (PABS uses placement coverage) diff --git a/examples/research-sota/03-spatial-intelligence/README.md b/examples/research-sota/03-spatial-intelligence/README.md new file mode 100644 index 00000000..9473010e --- /dev/null +++ b/examples/research-sota/03-spatial-intelligence/README.md @@ -0,0 +1,39 @@ +# 03 — Spatial intelligence + +Subcarrier-selection and multi-link adversarial-defence primitives. + +## Scripts + +| Script | Thread | Headline | +|---|---|---| +| `r5_subcarrier_saliency.py` | R5 | Top-8 most-informative subcarriers for person-count classification. Band-spread (not band-clustered) — explained by R6 Fresnel forward model (zone-1 occupancy has flat per-subcarrier phase). Max/mean ratio 2.85×. | +| `r7_multilink_consistency.py` | R7 | Stoer-Wagner minimum cut detects **3/3 adversarial spoofs** across multi-link CSI graphs. Identifies which links were compromised; reports "physically impossible CSI" via topological consistency. | + +## Why these compose + +- **R5 saliency** tells us WHICH subcarriers carry the discriminative information for each cog. +- **R7 mincut** tells us WHEN we should trust the CSI at all (multi-link consistency check). + +Both feed into the production cogs (R8 RSSI counter uses R5's top-8 subcarriers; R12 PABS uses R7's per-link consistency check as an adversarial defence layer). + +## Sample output + +``` +=== R5 subcarrier saliency === +Top 8 most informative subcarriers (out of 56): + [41, 52, 30, 31, 10, 35, 2, 38] + Max/mean ratio: 2.85x (band-spread, not band-clustered) + +=== R7 mincut adversarial detection === +Scenario A (no adversary): detected as compromised: [] +Scenario B (link 0 spoofed): detected as compromised: [0] ✓ +Scenario C (link 2 spoofed): detected as compromised: [2] ✓ +Scenario D (multi compromised): detected as compromised: [1,3] ✓ +Detection rate: 3/3 +``` + +## See also + +- R5 explained by `01-physics-floor/r6_fresnel_zone.py` (band-spread = zone-1 occupancy signature) +- R7 used by `06-structure-detection/r12_pabs_implementation.py` and `09-quantum-fusion/` +- Research notes: `docs/research/sota-2026-05-22/R5-*.md`, `R7-*.md` diff --git a/examples/research-sota/04-rssi/README.md b/examples/research-sota/04-rssi/README.md new file mode 100644 index 00000000..70cddef4 --- /dev/null +++ b/examples/research-sota/04-rssi/README.md @@ -0,0 +1,35 @@ +# 04 — RSSI-only sensing + +RSSI is the simplest CSI summary (one number per packet). These scripts quantify what's recoverable from RSSI alone vs full CSI. + +## Scripts + +| Script | Thread | Headline | +|---|---|---| +| `r8_rssi_only_count.py` | R8 | RSSI-only person count: **59.1% accuracy = 94.82% of full-CSI v0.0.2** with a tiny 656-parameter MLP. RSSI keeps 95% of counting capacity. | +| `r9_rssi_fingerprint_knn.py` | R9 | Cosine-NN on RSSI fingerprints: **2.18× lift** over chance (MODERATE). Surfaces counting-vs-localization asymmetry: RSSI is great for count, weaker for per-location ID. | + +## The counting-vs-localization asymmetry + +R8 + R9 together demonstrate that RSSI: +- **Retains 95% of person-count capacity** (R8) +- **Retains only ~30% of localization capacity** (R9) + +This means RSSI-only deployments (the cheap path) are viable for **occupancy / count** but inadequate for **per-occupant features** (vitals, identity, pose). + +## When to use RSSI-only + +Per ADR-113 placement matrix, RSSI-only is appropriate for: +- `cog-presence` (binary occupancy) +- `cog-person-count` (occupant count) +- Very cost-sensitive deployments (chicken-scale R19 livestock, for instance) + +NOT appropriate for: +- `cog-vital-signs` (needs CSI per-subcarrier shape) +- `cog-pose-estimation` (needs CSI multistatic geometry) +- `cog-quantum-vitals` (ADR-114, needs CSI fusion with NV) + +## See also + +- Research notes: `docs/research/sota-2026-05-22/R8-*.md`, `R9-*.md` +- Composes with: `01-physics-floor/` (uses Fresnel forward model insight) diff --git a/examples/research-sota/05-cross-room-reid/README.md b/examples/research-sota/05-cross-room-reid/README.md new file mode 100644 index 00000000..3ce8a532 --- /dev/null +++ b/examples/research-sota/05-cross-room-reid/README.md @@ -0,0 +1,48 @@ +# 05 — Cross-room person re-identification (R3 arc, 3 ticks) + +Whether the same person can be identified across two different rooms with WiFi CSI. Three-tick arc: R3 baseline → R3.1 (architecture error negative) → R3.2 (corrected architecture, structurally validated). + +## Scripts (in arc order) + +| Script | Thread | Headline | State | +|---|---|---|---| +| `r3_crossroom_reid.py` | R3 | MERIDIAN env-centroid subtraction recovers cross-room re-ID to 100% (synthetic 128-dim embedding setup) | POSITIVE | +| `r3_1_physics_informed_env.py` | R3.1 | **Physics-informed env subtraction at raw-CSI level FAILS** (10% = chance). Even labelled MERIDIAN at raw CSI = 10%. Identifies architecture error: position-variance dominates at raw level. | **NEGATIVE (architecture-error)** | +| `r3_2_embedding_physics_env.py` | R3.2 | Embedding-level physics-informed env: **20% = matches labelled oracle with zero labels**. Architecture correct; per-subject signal weak in synthetic AETHER stand-in. | **STRUCTURALLY VALIDATED** | + +## The three-kind-of-negative pattern + +R3.1 was the loop's first **architecture-error negative**: + +| Kind | Example | Path forward | +|---|---|---| +| Missing-tool (revisitable) | R12 → R12 PABS | Tool arrives later; approach works | +| Physics-floor (permanent) | R13 contactless BP | Hard wall; no tool changes this | +| **Architecture-error (correctable)** | **R3.1 (here)** | **Wrong application level; corrected sketch explicit** | + +## Corrected architecture (R3.2) + +``` +raw CSI → AETHER embedding (position-invariant, ADR-024) + → physics-informed env subtraction (uses R6.1 forward operator) + → cosine K-NN against per-installation gallery +``` + +The physics-informed env prediction must operate at **embedding level**, not raw level. AETHER does position-invariance; predicted-env removes the remaining room-shift component. + +## Privacy constraints (R14 + R15 + ADR-106/107) + +Cross-room re-ID is a powerful biometric. The loop's privacy framework enforces: + +1. **No cross-installation linkage** — each install has its own embedding space +2. **Storage requires explicit opt-in** (biometric-class consent) +3. **Cryptographically verifiable forgetting** of raw primitives +4. **No re-ID across legal entities** (hard-walled) + +ADR-107 Layer 5 (per-installation embedding-space rotation key) enforces these technically. + +## See also + +- Research notes: `docs/research/sota-2026-05-22/R3-*.md`, `R3_1-*.md`, `R3_2-*.md` +- ADRs: ADR-024 (AETHER), ADR-027 (MERIDIAN), ADR-106 (DP+isolation), ADR-107 (cross-install) +- Composes with: `01-physics-floor/` (R6.1 forward operator) diff --git a/examples/research-sota/06-structure-detection/README.md b/examples/research-sota/06-structure-detection/README.md new file mode 100644 index 00000000..2ee9bea4 --- /dev/null +++ b/examples/research-sota/06-structure-detection/README.md @@ -0,0 +1,58 @@ +# 06 — Structure detection (R12 arc, 3 ticks) + +Detecting "something new in the room" — new furniture, intruder, fallen person. Three-tick arc: R12 NEGATIVE → R12 PABS POSITIVE → R12.1 closed loop. + +## Scripts (in arc order) + +| Script | Thread | Headline | State | +|---|---|---|---| +| `r12_rf_weather_eigenshift.py` | R12 | Naive SVD-spectrum cosine distance: **0.69× signal/drift = undetectable**. Fails because eigenshift is indistinguishable from natural drift. | **NEGATIVE (missing-tool)** | +| `r12_pabs_implementation.py` | R12 PABS | Physics-Anchored Background Subtraction: **1,161× signal/drift** for unexpected occupant. ~100× lift over R12 NEGATIVE. Achieved by composing R6.1 forward operator as the PABS basis. | **POSITIVE** | +| `r12_1_pose_pabs_loop.py` | R12.1 | Pose-aware closed loop: **9.36× intruder detection in dynamic scenes** (false-alarm problem from R12 PABS resolved). Pose updates suppress subject-motion contribution 20×. | **CLOSED LOOP** | + +## The arc summary + +R12 (tick 5) → R12 PABS (tick 19) → R12.1 (tick 29): failure → success with caveat → success without caveat. + +The arc validates the **research-loop pattern**: catalogue NEGATIVE results explicitly, then revisit them when better tools arrive. R6.1 multi-scatterer (tick 18) provided the tool that R12 was missing in tick 5. + +## How PABS works (R12 PABS implementation) + +``` +y_predicted = sum over voxels of A(voxel) × reflectivity(voxel) + where A is the R6.1 forward operator +PABS = ||y_observed − y_predicted||² / ||y_observed||² + +If PABS > threshold: + structural change detected (new scatterer in scene) +``` + +## How the closed loop works (R12.1) + +``` +At each frame: + pose_estimate = pose_tracker.estimate(csi_window) // ADR-079 / ADR-101 + expected_scene = body_model.from_pose(pose) + walls + y_predicted = R6.1.forward(expected_scene) + PABS = ||y_observed − y_predicted||² / ||y_observed||² + if PABS > threshold: + emit_structure_event() +``` + +Subject motion is **absorbed** into the prediction; only unexplained residuals trigger structure events. This is the V0 security feature in R14 + R16/R17/R18 verticals. + +## Composition with other folders + +- `01-physics-floor/r6_1_multiscatterer.py` provides the A(voxel) forward operator +- `03-spatial-intelligence/r7_multilink_consistency.py` provides per-link adversarial check +- `09-quantum-fusion/r20_1_quantum_classical_fusion.py` composes structure detection with NV-magnetometer fusion + +## Production status (per `PRODUCTION-ROADMAP.md`) + +- Tier 1.2: R12.1 pose-PABS in `vital_signs` cog (~80 LOC Rust) +- Tier 3.4: Standalone `cog-fall-detection` (~200 LOC) + +## See also + +- Research notes: `docs/research/sota-2026-05-22/R12-*.md`, `R12_1-*.md` +- ADRs: ADR-079 (pose tracker), ADR-101 (cog-pose-estimation), ADR-029 (multistatic) diff --git a/examples/research-sota/07-negative-results/README.md b/examples/research-sota/07-negative-results/README.md new file mode 100644 index 00000000..37b204a9 --- /dev/null +++ b/examples/research-sota/07-negative-results/README.md @@ -0,0 +1,48 @@ +# 07 — Negative results (R13 contactless BP) + +**Productive failure**: empirical / physics-based scrutiny of widely-claimed but un-validated CSI capabilities. + +## Scripts + +| Script | Thread | Verdict | +|---|---|---| +| `r13_bp_physics_floor.py` | R13 | **Don't ship contactless BP from CSI as a primary RuView feature.** Four physics floors make it provably worse than a $20 arm cuff. | + +## The four floors (R13) + +| Floor | Need | Have | Gap | +|---|---|---|---| +| PTT temporal resolution | 0.5 ms (for 1 mmHg) | 10 ms typical, 1 ms max ESP32 | typical ESP32 deployment cannot do <20 mmHg | +| Spatial separation of two body sites | 55 cm | 40 cm Fresnel envelope at 5 m | sites NOT resolvable by single link | +| Pulse-contour SNR | +25 dB | +20 dB after bandpass | **5 dB short** (matches R6.1's 4.7 dB penalty) | +| Vs $20 arm cuff baseline | ±2 mmHg | best published ±10 mmHg | **5× worse** + needs per-subject calibration | + +## Why R13 is sensor-bound, not physics-bound-period + +R20 (tick 37) + doc 17 + ADR-114 establish that **the 5 dB shortfall is the multi-scatterer penalty** (R6.1). It's sensor-bound: a different sensor (NV-diamond magnetometer at bedside) recovers what CSI cannot. + +| Sensor | Can detect HRV contour? | Can detect BP? | +|---|---:|---:| +| CSI alone (R13 NEGATIVE) | ❌ 5 dB short | ❌ same physics | +| **NV-diamond at 1 m bedside** (ADR-114) | ✅ SDNN 119 ms | ✅ via mm-PWV | +| Arm cuff (gold standard) | n/a | ✅ ±2 mmHg | + +## R13's value in the loop + +Categorising R13 as a **permanent physics-floor negative** initially saved engineering effort. Then R20 + doc 17 + ADR-114 recategorised it as **sensor-bound, recoverable**. This is the **research-loop pattern at its best**: explicit failure modes that survive scrutiny but get reclassified when new tools arrive. + +R20.1 (quantum-fusion demo) is the concrete demonstration that R13's recovery works. + +## Three niche scenarios where BP-from-CSI might close + +1. Single-subject **trend** monitoring (relative not absolute) +2. Bed-instrumented controlled-still subject (25+ dB SNR achievable) +3. Multistatic PWV with 6+ anchors + per-installation calibration + +The general "BP from a $9 ESP32 in the corner" claim does **not** close. + +## See also + +- Research notes: `docs/research/sota-2026-05-22/R13-contactless-bp-negative.md` +- Recovery path: `docs/research/sota-2026-05-22/R20-*.md`, doc 17, ADR-114 +- The other 2 negative result categories: R12 (missing-tool, revisitable) in `06-structure-detection/`, R3.1 (architecture-error) in `05-cross-room-reid/` diff --git a/examples/research-sota/08-verticals/README.md b/examples/research-sota/08-verticals/README.md new file mode 100644 index 00000000..d3030331 --- /dev/null +++ b/examples/research-sota/08-verticals/README.md @@ -0,0 +1,50 @@ +# 08 — Exotic vertical physics + +Concrete physics for two vertical applications: wildlife (through-foliage) and maritime (through-bulkhead). Other verticals (R14 empathic, R16 healthcare, R17 industrial, R18 disaster, R19 livestock, R20 quantum) are vision/spec only — only R10 and R11 have computable physics demos. + +## Scripts + +| Script | Thread | Vertical | Headline | +|---|---|---|---| +| `r10_foliage_attenuation.py` | R10 | Wildlife sensing through foliage | ITU-R P.833-9 attenuation. ESP32 sparse-foliage range: **~100 m at 2.4 GHz** (later corrected to ~70 m by R6's Fresnel-clearance consideration). Per-species gait taxonomy (8 species). | +| `r11_maritime_propagation.py` | R11 | Maritime / ship-cabin sensing | Steel skin depth 3.25 µm at 2.4 GHz → through-bulkhead impossible. But **slot diffraction works**: cabin door with 2 mm gasket gap = +31 dB SNR margin. **Through-seam, not through-bulkhead.** | + +## What R10 (wildlife) enables + +- Solar-powered ESP32 nodes at forest edges +- Through-foliage detection at ~70-100 m range +- Per-species gait classification: + +| Species | Stride frequency | +|---|---| +| Bear / sloth / wild boar | 0.5-1.5 Hz | +| Human walking | 1.2-2.5 Hz | +| Deer / fox | 1.8-4.5 Hz | +| Squirrel / mouse / songbird | 4.0-15.0 Hz | + +The gait taxonomy directly extends to R19 livestock (cattle 0.6-1.2 Hz, pig 1.0-2.0 Hz, etc.). + +## What R11 (maritime) enables + +- Man-overboard surface detection at ~200 m +- Through-seam crew vitals (lone-watch monitoring) +- Container tamper detection via 30 mm vent slots +- Hatch-seal integrity audit (predictive maintenance) + +**What R11 rules out**: +- Through-hull submarine sensing (steel impassable) +- Underwater sensing at WiFi bands (saltwater 853 dB/m) + +## Composition with privacy + federation chain + +Both R10 and R11 use: +- `cog-wildlife` or `cog-maritime-watch` packaging (ADR-100) +- Cross-installation federation (ADR-107 + ADR-108 PQC) +- Per-installation embedding spaces (R3 + R14 privacy framework) + +For wildlife the privacy framework is largely moot (animals don't consent); for maritime the crew-consent framework applies. + +## See also + +- Research notes: `docs/research/sota-2026-05-22/R10-*.md`, `R11-*.md`, plus R16-R20 verticals (vision-only) +- Composes with: `01-physics-floor/` (forward model), `06-structure-detection/` (PABS for predator-detection / container-tamper) diff --git a/examples/research-sota/09-quantum-fusion/README.md b/examples/research-sota/09-quantum-fusion/README.md new file mode 100644 index 00000000..6aed8b93 --- /dev/null +++ b/examples/research-sota/09-quantum-fusion/README.md @@ -0,0 +1,62 @@ +# 09 — Quantum-classical fusion (ADR-114 demo) + +Working numpy demo of the cog-quantum-vitals architecture: **classical CSI for multi-subject context, NV-diamond magnetometry for per-patient HRV contour fidelity**. + +## Scripts + +| Script | Thread | Headline | +|---|---|---| +| `r20_1_quantum_classical_fusion.py` | R20.1 | Bayesian fusion of CSI (R14 V1 breathing) + NV-diamond cardiac magnetometry. **Empirically confirms R13 NEGATIVE** (classical HR conf 38%, 105 BPM estimate vs 72 truth) AND **doc 16's cube-of-distance bound** (27× signal drop 1 m → 3 m). | + +## Five confirmations from the demo + +1. **Classical breathing rate is reliable** — 15.00 BPM correct (14 dB SNR) +2. **Classical HR is unreliable** — 105 BPM vs 72 truth, conf 38% (R13 NEGATIVE empirically confirmed) +3. **NV cardiac at 1 m works** — 72.00 BPM correct, SDNN 119 ms (R13 recovery validated) +4. **Cube-of-distance falloff is real** — 6.25 pT @ 1 m → 0.23 pT @ 3 m (27× drop, matches 1/r³) +5. **Fusion produces correct breathing + improved HR** at bedside + +## The arc that produced this demo + +| Tick | Output | Time | +|---|---|---| +| 37 | R20 — quantum-classical vision | 11:15 UTC | +| 38 | Doc 17 — quantum-classical bridge | 11:25 UTC | +| 39 | ADR-114 — shippable cog spec | 11:35 UTC | +| **40** | **R20.1 — working numpy demo** | **11:40 UTC** | + +**Vision → integration → spec → working code in 25 minutes.** + +## Production status + +ADR-114 specifies ~200 LOC Rust port; this 140 LOC numpy demo runs in <100 ms and validates the architecture. Engineering risk for `cog-quantum-vitals` (Tier 4.x in `PRODUCTION-ROADMAP.md`) is substantially lowered. + +## Bedside cost (per ADR-114) + +| Component | Cost | +|---|---| +| 4× ESP32-S3 | $60 | +| 1× NV-diamond (today / 2028) | $200-2,000 / ~$200 | +| Mount + calibration | $50 | +| **Total** | **$310-$2,110** | + +vs clinical continuous monitor: $3,000-$10,000. + +## Honest scope + +- Synthetic NV signals (`nvsim` is also a simulator) +- Cube-of-distance assumes clean dipole field +- HRV extraction = simple threshold (production needs Pan-Tompkins QRS) +- Naive Bayesian fusion (production needs threshold-based hand-off when NV confidence > 60%) + +## Composes with + +- `01-physics-floor/r6_1_multiscatterer.py` — provides the forward operator the fusion extends +- `06-structure-detection/r12_1_pose_pabs_loop.py` — pose-PABS hook in ADR-114 architecture +- `07-negative-results/r13_bp_physics_floor.py` — the negative result this demo recovers + +## See also + +- ADR-114: `docs/adr/ADR-114-cog-quantum-vitals.md` +- Quantum-sensing series: `docs/research/quantum-sensing/{11..17}-*.md` (especially doc 17 which bridges the loop with the existing series) +- Research notes: `docs/research/sota-2026-05-22/R20-*.md`, `R20_1-*.md` diff --git a/examples/research-sota/README.md b/examples/research-sota/README.md new file mode 100644 index 00000000..47a32746 --- /dev/null +++ b/examples/research-sota/README.md @@ -0,0 +1,87 @@ +# SOTA Research Loop — Examples Overview + +Pure-numpy reference implementations from the 2026-05-22 autonomous SOTA research loop. Every script is self-contained, prints headline numbers, and writes a machine-readable JSON result file alongside. + +## Folder map + +| Folder | Threads | What it covers | +|---|---|---| +| **[01-physics-floor/](01-physics-floor/)** | R1, R6, R6.1 | Bedrock physics — ToA CRLB, single-scatterer Fresnel, multi-scatterer forward model | +| **[02-placement/](02-placement/)** | R6.2 family (7 sub-ticks) | Antenna placement search — 2D / 3D / multi-anchor / chest-centric / multi-subject | +| **[03-spatial-intelligence/](03-spatial-intelligence/)** | R5, R7 | Subcarrier saliency + Stoer-Wagner mincut adversarial defence | +| **[04-rssi/](04-rssi/)** | R8, R9 | RSSI-only counting + RSSI fingerprint K-NN | +| **[05-cross-room-reid/](05-cross-room-reid/)** | R3 arc (3 ticks) | Cross-room person re-identification — naive, physics-informed, embedding-level | +| **[06-structure-detection/](06-structure-detection/)** | R12 arc (3 ticks) | RF-weather eigenshift → PABS → pose-PABS closed loop (NEGATIVE → POSITIVE) | +| **[07-negative-results/](07-negative-results/)** | R13 | Physics-floor scrutiny — why contactless BP from CSI doesn't work | +| **[08-verticals/](08-verticals/)** | R10, R11 | Exotic vertical physics — wildlife (foliage attenuation) and maritime (through-bulkhead) | +| **[09-quantum-fusion/](09-quantum-fusion/)** | R20.1 | Quantum-classical Bayesian fusion (ADR-114 cog-quantum-vitals demo) | + +## Running any example + +All scripts are pure NumPy. No external dependencies beyond `numpy` itself. + +```bash +python examples/research-sota/01-physics-floor/r6_fresnel_zone.py +python examples/research-sota/02-placement/r6_2_5_multi_subject.py +# etc. +``` + +Each script: +- Prints headline numbers to stdout +- Writes `_results.json` next to itself +- Runs in <2 minutes on a laptop (most run in <10 seconds) + +## Cross-folder dependency graph + +``` +01-physics-floor ──┐ + │ │ + ▼ │ +02-placement ◀────┤ + │ │ + ▼ │ +03-spatial-intel ◀──┤ + │ │ + ▼ │ +06-structure-detection ◀──┘ + │ + ▼ +09-quantum-fusion (composes 01+03+06) + +04-rssi (independent, uses 01 forward model) +05-cross-room-reid (uses 01+03) +07-negative-results (uses 01) +08-verticals (uses 01) +``` + +## Headline findings + +| Finding | Source | +|---|---| +| 93× sensing-coverage lift from physics-aware placement | 02-placement (R6.2) | +| 9.36× intruder-detection lift from pose-PABS closed loop | 06-structure-detection (R12.1) | +| 100% coverage of 1-4 occupant household at N=5 anchors | 02-placement (R6.2.5) | +| ~50% breathing-band SNR cost from realistic body multi-scatterer | 01-physics-floor (R6.1) | +| RSSI alone preserves 95% of full-CSI person count | 04-rssi (R8) | +| Stoer-Wagner mincut catches 3/3 adversarial spoofs | 03-spatial-intelligence (R7) | +| Contactless BP/HRV-contour: 5 dB short, physically blocked | 07-negative-results (R13) | +| NV-diamond cardiac magnetometry recovers R13 at bedside | 09-quantum-fusion (R20.1) | + +## Related loop output + +- **Research notes**: `docs/research/sota-2026-05-22/R{1..20}-*.md` +- **Per-tick summaries**: `docs/research/sota-2026-05-22/ticks/tick-{1..40}.md` +- **Production roadmap**: `docs/research/sota-2026-05-22/PRODUCTION-ROADMAP.md` +- **ADRs from the loop**: `docs/adr/ADR-{105..109,113,114}-*.md` +- **Quantum-sensing series**: `docs/research/quantum-sensing/{11..17}-*.md` + +## Honest scope + +All scripts are **synthetic-physics derivations**, not bench measurements. Real ESP32-S3 deployments may diverge from these numbers by 5-30% due to multipath, hardware tolerance, environmental drift. Bench validation is the critical next step for any production use; see `PRODUCTION-ROADMAP.md` Tier 2.3. + +## Reading order for newcomers + +1. Start with **01-physics-floor/R6** (Fresnel forward model) — bedrock for everything else +2. Then **02-placement/R6.2.5** (multi-subject) — practical placement recipe +3. Then **06-structure-detection/R12.1** (pose-PABS) — the security feature +4. Then **09-quantum-fusion/R20.1** (Bayesian fusion) — the future direction