mirror of
https://github.com/ruvnet/RuView
synced 2026-07-29 18:31:44 +00:00
feat(nvsim): scaffold + scene + frame [nvsim:pass1]
Pass 1 of the NV-diamond magnetometer pipeline simulator per docs/research/quantum-sensing/15-nvsim-implementation-plan.md. Standalone leaf crate at v2/crates/nvsim — deliberately NO internal RuView dependencies. RuView ecosystem integrations (wifi-densepose-core frame alignment, ruvector trace compression) are tracked as Optional Integrations in README and land behind feature flags after the core simulator ships. Surfaces shipped: - scene::Scene — aggregate ground-truth scene (dipoles, current loops, ferrous objects, eddy-current discs, sensor positions, ambient field) - scene::DipoleSource — point magnetic dipole, SI units - scene::CurrentLoop — planar current loop with 64-segment default Biot–Savart discretisation - scene::FerrousObject — linearly-induced moment from ambient field (χ_steel ≈ 5000 default per Cullity & Graham 2e §2) - scene::EddyCurrent — Faraday + Ohm eddy-current disc primitive - frame::MagFrame — 60-byte fixed-layout binary record, magic 0xC51A_6E70 (distinct from ADR-018 CSI 0xC51F... and ADR-084 sketch 0xC511_0084) - frame::flag::* — bit-set constants (saturation, ADC clip, heavy attenuation, shot-noise-disabled). Raw u16 to avoid pulling bitflags as a workspace dep. - NvsimError — typed errors for parse / serialisation failures - MU_0, GAMMA_E, D_GS — shared physics constants 12 unit tests covering: - scene JSON round-trip preserves all primitive types - magic locked to documented value (0xC51A_6E70) - frame size fixed at 60 bytes - frame round-trip is byte-exact - frame deserialiser rejects short / bad-magic / bad-version inputs - byte-order determinism across repeated serialisations - flag set/check helpers Acceptance per plan §3 Pass 1: - cargo check -p nvsim --no-default-features → clean - cargo test -p nvsim --no-default-features → 12 passed (target ≥6) - Workspace test count 1,575 → 1,587 (+12) - ESP32-S3 on COM7 unaffected (cb #625100, alive) Two research documents committed alongside: - 14-nv-diamond-sensor-simulator.md (469 lines, SOTA + verdict) - 15-nvsim-implementation-plan.md (268 lines, 6-pass build spec) Status: Pass 1 only. Passes 2-6 (source, propagation, sensor, digitiser+pipeline, proof+bench) ship in subsequent commits per the implementation plan. Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
@@ -0,0 +1,469 @@
|
||||
# NV-Diamond Sensor Simulator: SOTA Survey and Build/Skip Decision
|
||||
|
||||
## SOTA Research Document — Quantum Sensing Series (14/—)
|
||||
|
||||
**Date**: 2026-04-25
|
||||
**Domain**: NV-Diamond Magnetometry × Sensor Simulation × RuView Pipeline Integration
|
||||
**Status**: Research Survey + Crate Proposal
|
||||
**Branch**: `research/nv-diamond-sensor-simulator` (no commits, no production code)
|
||||
**Prior**: `13-nv-diamond-neural-magnetometry.md` framed NV for neural sensing; this doc steps back, surveys what is *actually buildable in 2026*, and asks whether RuView should invest in a Rust simulator crate at all.
|
||||
|
||||
---
|
||||
|
||||
## 1. Why this document exists
|
||||
|
||||
`13-nv-diamond-neural-magnetometry.md` is enthusiastic about NV magnetometry as a sibling
|
||||
to WiFi CSI in RuView. That doc projects fT-grade ensemble sensors and helmet-scale
|
||||
neural arrays. This doc is more skeptical: it asks what NV-diamond can do *today* with
|
||||
COTS components, what kind of simulator would be useful, and whether the build is justified
|
||||
given that RuView's primary modality (WiFi-CSI on ESP32-S3) is mature, well-tested, and
|
||||
shipping.
|
||||
|
||||
The doc is structured for a build/skip decision:
|
||||
|
||||
1. SOTA of NV-diamond hardware (commercial + academic)
|
||||
2. SOTA of NV-diamond simulators (what is open, what is missing)
|
||||
3. Concrete crate proposal *if* RuView decides to build
|
||||
4. Open questions that materially change the answer
|
||||
|
||||
---
|
||||
|
||||
## 2. NV-Diamond Hardware SOTA (2024–2026)
|
||||
|
||||
### 2.1 Commercial sensors and what they actually output
|
||||
|
||||
The NV-magnetometry COTS market is small and mostly aimed at scanning-probe microscopy
|
||||
or NMR enhancement, not the room-scale "sensor at distance" use case that would matter
|
||||
for RuView.
|
||||
|
||||
| Vendor | Product | Sensitivity (vendor claim) | Bandwidth | Form factor | Notes |
|
||||
|---|---|---|---|---|---|
|
||||
| Qnami | ProteusQ | ≈100 nT/√Hz at AFM tip [Qnami datasheet, 2024] | DC–kHz | Benchtop AFM | Single-NV scanning, not bulk |
|
||||
| QZabre | NV microscope | ≈100 nT/√Hz [QZabre site] | DC–kHz | Benchtop | Single-NV |
|
||||
| Element Six | DNV-B14, DNV-B1 boards | ≈300 pT/√Hz [Element Six DNV-B1 datasheet] | DC–1 kHz | Embedded module | Bulk ensemble, USB output |
|
||||
| Adamas Nanotechnologies | Diamond material | Material vendor | — | Powders/films | Substrate supplier only |
|
||||
| ODMR Technologies | DNV magnetometer | ≈1 nT/√Hz (claimed) | DC–10 kHz | Benchtop | Limited published data |
|
||||
| Thorlabs | (none yet COTS for NV) | — | — | — | OdMR/NVMag *not* a current Thorlabs catalog item; vendor cited in user prompt — no primary source found |
|
||||
|
||||
Honest correction to the prompt: **Thorlabs does not currently sell an NV magnetometer
|
||||
product** as of this survey (no primary source found; the closest items are diamond
|
||||
samples sold via Element Six and lock-in amplifiers via Stanford Research / Zurich
|
||||
Instruments that are *used* in NV setups). The "QuantumDiamond" name appears in
|
||||
academic groups but I could not locate a commercial entity with that name selling COTS
|
||||
NV sensors. Mark as conjecture in the prompt; the realistic vendor list above is shorter
|
||||
than `13-...md` implied.
|
||||
|
||||
The Element Six **DNV-B1** is the most concrete COTS reference point. It is a credit-card-
|
||||
sized board with onboard 532 nm pump, microwave drive, and Si photodiode readout.
|
||||
Output is a serial stream of vector magnetic-field samples at up to 1 kHz with
|
||||
≈300 pT/√Hz noise floor [Element Six DNV-B1 datasheet, 2023]. Cost: ≈$8K–$15K,
|
||||
unsuitable for RuView's $200–$500/sensor target.
|
||||
|
||||
### 2.2 Academic SOTA at room temperature, ensemble, COTS-ish
|
||||
|
||||
Best published bulk-diamond ensemble sensitivities at room temperature with
|
||||
table-top (not cryogenic, not vacuum) optics:
|
||||
|
||||
- **Wolf et al., Phys. Rev. X 5, 041001 (2015)** — 0.9 pT/√Hz at 10 Hz, 13.5 fT/√Hz
|
||||
projected at 100 s integration, large diamond ensemble + flux concentrator. Earliest
|
||||
pT-floor demonstration. (~10 yr old; still the canonical reference floor.)
|
||||
- **Barry et al., Rev. Mod. Phys. 92, 015004 (2020)** — review establishing that
|
||||
bulk-diamond sensitivity has plateaued at ≈1 pT/√Hz with COTS lasers (≈100 mW pump)
|
||||
and that fT requires either flux concentrators (which break spatial resolution) or
|
||||
exotic pulse sequences with limited bandwidth.
|
||||
- **Fescenko et al., Phys. Rev. Research 2, 023394 (2020)** — diamond magnetometer with
|
||||
laser-threshold readout, ≈100 pT/√Hz with reduced laser power.
|
||||
- **Zhang et al., Nat. Comm. 12, 2737 (2021)** — Hahn-echo at 0.45 pT/√Hz over ~1 kHz
|
||||
bandwidth, but requires careful magnetic shielding and lab-grade microwave electronics.
|
||||
- **Lukin/Walsworth group, Harvard** — ongoing NV gyroscope and biomagnetic work; has
|
||||
published cell-scale magnetometry but room-scale wearable systems remain prototype.
|
||||
- **Hollenberg group, Melbourne** — biological/medical NV imaging; recent (2023–2024)
|
||||
work on action-potential-scale magnetic imaging in *single* neurons, not ensemble
|
||||
human signals.
|
||||
- **Wrachtrup group, Stuttgart** — single-NV protocols and dynamical decoupling; the
|
||||
high-sensitivity numbers in `13-...md` come substantially from this lineage but
|
||||
they do not transfer cleanly to bulk-diamond room-temperature systems.
|
||||
|
||||
**Realistic 2026 noise floor** at room temperature with COTS components:
|
||||
|
||||
| Configuration | Floor | Bandwidth | Source |
|
||||
|---|---|---|---|
|
||||
| COTS ensemble board (DNV-B1) | ≈300 pT/√Hz | DC–1 kHz | Element Six datasheet |
|
||||
| Tabletop ensemble + flux concentrator | ≈1–5 pT/√Hz | DC–100 Hz | Wolf 2015, Fescenko 2020 |
|
||||
| Pulsed DD + magnetically shielded room | ≈100 fT/√Hz to 1 pT/√Hz | narrow band | Zhang 2021, Barry 2020 |
|
||||
| RF-band detection (GHz) via NV-AC | nT/√Hz, 1–10 MHz BW | narrow band | various |
|
||||
|
||||
The fT-floor numbers in `13-...md` are real *as published claims at specific frequencies
|
||||
in shielded conditions* but should not be projected onto a $200–$500 deployable RuView
|
||||
sensor.
|
||||
|
||||
### 2.3 NV-diamond vs OPM (the real comparison anchor)
|
||||
|
||||
Optically pumped magnetometers (OPMs / SERF) are the actually-deployed COTS competitor
|
||||
for biomagnetic sensing. **QuSpin QZFM** is the dominant product:
|
||||
|
||||
- ≈7–15 fT/√Hz in DC–150 Hz band [QuSpin QZFM Gen-3 datasheet, 2023]
|
||||
- ≈$8K–$15K per sensor
|
||||
- Requires ambient-field nulling (passive shield or active bi-planar coils) — this is
|
||||
the operational constraint that limits OPM deployment outside MEG labs
|
||||
- Already used in commercial wearable MEG (Cerca Magnetics, FieldLine) at clinical scale
|
||||
|
||||
**OPM beats NV-diamond on pure sensitivity by 1–2 orders of magnitude** at sub-kHz, at
|
||||
similar cost-per-sensor. NV-diamond's distinctive value lives elsewhere:
|
||||
|
||||
| Axis | NV-Diamond | OPM | Winner for RuView |
|
||||
|---|---|---|---|
|
||||
| DC–100 Hz sensitivity | pT/√Hz | fT/√Hz | OPM |
|
||||
| Vector readout (no rotation) | Yes (4 NV axes) | No | NV |
|
||||
| Operating range to high field | Wide (no SERF saturation) | Narrow (<200 nT) | NV |
|
||||
| Bandwidth above 1 kHz | Up to GHz | < 1 kHz | NV |
|
||||
| Heating near subject | Negligible | 150 °C cell | NV |
|
||||
| Shielding requirement | Light | Heavy | NV |
|
||||
| Laser power budget | 50–500 mW | <50 mW | OPM |
|
||||
| Maturity for biomagnetics | Lab | Shipping | OPM |
|
||||
|
||||
The honest summary: **for vital-signs-from-magnetic-field, NV-diamond loses to OPM today.**
|
||||
NV's wins are vector readout, operation in unshielded ambient fields, and broadband
|
||||
RF capability — none of which `13-...md` actually exploited.
|
||||
|
||||
---
|
||||
|
||||
## 3. NV-Diamond Simulator SOTA
|
||||
|
||||
### 3.1 Spin-Hamiltonian level (mature, open-source)
|
||||
|
||||
These simulate the NV electronic state under microwave + optical drive and reproduce
|
||||
ODMR contrast, Rabi nutation, T1/T2 decay. They are *backend* tools — they would sit
|
||||
inside `sensor.rs` of a RuView simulator, not be the simulator themselves.
|
||||
|
||||
- **QuTiP** [Johansson et al., Comp. Phys. Comm. 184, 1234 (2013)] — Python toolbox for
|
||||
open quantum systems. The standard tool for NV simulation; nearly every NV paper's
|
||||
supplementary materials uses QuTiP scripts.
|
||||
- **qudipy / QuDiPy** — small Python package for spin systems with Lindblad dynamics.
|
||||
Less mature than QuTiP; useful for educational examples.
|
||||
- **Spinach** [Hogben et al., J. Magn. Reson. 208, 179 (2011)] — MATLAB-only. Very fast
|
||||
for large spin systems but license-encumbered.
|
||||
- **EasySpin** [Stoll & Schweiger, J. Magn. Reson. 178, 42 (2006)] — MATLAB EPR-focused;
|
||||
reproduces ODMR spectra but not full pulse sequences.
|
||||
- **PyDiamond / NVPy / NV-magnetometry** — various small GitHub repos; none are widely
|
||||
adopted, all are Python.
|
||||
|
||||
**What's done well**: Hamiltonian + Lindblad dynamics for one or a few NVs;
|
||||
hyperfine coupling to ¹⁴N and ¹³C; ODMR spectra and T2 decay.
|
||||
|
||||
**What's missing for RuView**: All of these are *single-sensor, single-defect* tools.
|
||||
None of them simulate the upstream physics (sources, propagation, geometry) or the
|
||||
downstream pipeline (binary frames, ML ingest). And none are in Rust.
|
||||
|
||||
### 3.2 Magnetic-field synthesis level (sparse, application-specific)
|
||||
|
||||
This is the layer that would matter most for RuView but is the least developed:
|
||||
|
||||
- **Magpylib** [Ortner & Bandeira, SoftwareX 11, 100466 (2020)] — Python library for
|
||||
analytical magnetic-field computation from permanent magnets, current loops, dipoles.
|
||||
Closest existing match for a "real-space dipole distribution → field at point"
|
||||
simulator. Pure Python; ~1k LOC core; no Rust port; no lossy-medium propagation.
|
||||
- **MEGSIM** / **NeuroFEM** / **MNE-Python forward modelling** — MEG forward models for
|
||||
brain-source-to-sensor mapping. Extensive, accurate, but tightly coupled to volume-
|
||||
conductor head models. Overkill for room-scale RuView sensing.
|
||||
- **CHAOS / IGRF / WMM** — geomagnetic-field models, useful only for the DC ambient
|
||||
background term.
|
||||
|
||||
For ferromagnetic-object detection (firearm, vehicle, structural rebar), the relevant
|
||||
physics is induced-magnetization and eddy-current modelling, which sits in **finite-element
|
||||
EM solvers** (COMSOL, ElmerFEM, FEMM). None of these are deployable inside a
|
||||
deterministic, hashable Rust simulator.
|
||||
|
||||
### 3.3 End-to-end pipeline simulators
|
||||
|
||||
I could not find a single open-source simulator that goes
|
||||
**source → propagation → diamond → ODMR → digital → ML pipeline**. The closest published
|
||||
work:
|
||||
|
||||
- **Schloss et al., Phys. Rev. Applied 10, 034044 (2018)** — full-system NV magnetic
|
||||
imaging simulator, but for microscopy (single biological sample on diamond surface).
|
||||
- **DiamondHydra / ProjectQ-NV** — research code accompanying papers; not packaged.
|
||||
|
||||
This gap is the strongest argument *for* RuView building one.
|
||||
|
||||
---
|
||||
|
||||
## 4. RuView NV-Diamond Sensor Simulator — Proposal
|
||||
|
||||
### 4.1 Use-case scoping (the part that has to be honest)
|
||||
|
||||
`13-...md` proposed neural sensing as the primary use case. Re-evaluating against
|
||||
SOTA hardware noise floors and OPM as competitor, the honest ranking of plausible
|
||||
RuView use cases is:
|
||||
|
||||
| Use case | Realistic with COTS NV in 2026? | Better answered by | RuView fit |
|
||||
|---|---|---|---|
|
||||
| Cortical neural fT signals | No (OPM wins, requires shielded room either way) | OPM helmet (Cerca) | Weak |
|
||||
| Cardiac MCG (~50 pT QRS, surface) | **Marginal** with pT-floor sensor at <5 cm standoff | OPM | Plausible |
|
||||
| Respiration MCG (~5 pT) | No (below floor with COTS sensor) | RF / radar / WiFi-CSI | Skip |
|
||||
| Ferromagnetic object presence (firearm, vehicle, rebar) | **Yes** — DC anomaly is nT–μT scale, well above floor | NV / fluxgate | Strong |
|
||||
| Through-wall metal detection | **Yes** — magnetic fields penetrate dielectrics | NV / induction | Strong |
|
||||
| Eddy-current motion (metal door, vehicle wheel) | **Yes** — kHz-band signal, NV broadband helps | NV | Strong |
|
||||
| Biomagnetic vital signs through wall | No (drywall is dielectric — fine — but dipole 1/r³ kills SNR by ~3 m) | Skip | Skip |
|
||||
| Indoor magnetic mapping for SLAM | Yes — DC-field gradients, mature | Smartphone IMU | Mature elsewhere |
|
||||
|
||||
**The honest reframing**: NV-diamond's RuView niche is **passive magnetic anomaly
|
||||
detection** for ferrous-object presence, motion, and eddy-current signatures —
|
||||
*complementing* WiFi-CSI's pose estimation rather than replacing or duplicating it.
|
||||
Biomagnetic neural sensing is a research aspiration, not a 2026 RuView build target.
|
||||
|
||||
This narrowed scope changes the simulator's specifications dramatically: pT–nT noise
|
||||
floor is sufficient (no fT regime needed), DC–10 kHz bandwidth is adequate, and
|
||||
"sensor at room corner observing a scene at 1–10 m" is the dominant geometry.
|
||||
|
||||
### 4.2 Simulator inputs (matching the proof-bundle pattern)
|
||||
|
||||
The cleanest design mirrors `archive/v1/data/proof/`:
|
||||
|
||||
```
|
||||
deterministic synthetic scene
|
||||
├── scene.json # source dipole positions, currents, motion
|
||||
├── geometry.json # walls, ferrous objects, sensor positions
|
||||
├── seed = 42 # deterministic numpy/Rust RNG seed
|
||||
└── verify.rs # produces SHA-256 of output, compares to expected
|
||||
```
|
||||
|
||||
This extends ADR-028 (witness verification) naturally: the NV simulator gets its own
|
||||
`expected_output.sha256` and gets included in the witness bundle.
|
||||
|
||||
### 4.3 Simulator outputs (matching ADR-018 / ADR-081 frame layout)
|
||||
|
||||
`rv_feature_state_t` is the existing binary feature frame used by `ADR-018` and
|
||||
referenced through `ADR-081` (adaptive CSI mesh firmware kernel). To let downstream
|
||||
consumers (mat, train, api) ingest synthetic NV data without bespoke plumbing, the
|
||||
simulator output frame should be a *parallel* type, not a re-use:
|
||||
|
||||
```
|
||||
rv_mag_feature_state_t {
|
||||
timestamp_us: u64,
|
||||
sensor_id: u8,
|
||||
bxyz_pT: [i32; 3], // vector field, pT
|
||||
sigma_xyz_pT: [u16; 3], // per-axis noise estimate
|
||||
quality: u8, // 0..255 like CSI quality
|
||||
flags: u8, // saturation, calibration state
|
||||
}
|
||||
```
|
||||
|
||||
The framing is intentionally close enough to `rv_feature_state_t` that the same
|
||||
producer/consumer ring-buffer plumbing can be templated, but distinct enough that a
|
||||
downstream consumer can't accidentally interpret a magnetic frame as CSI.
|
||||
|
||||
### 4.4 Physics-layer breakdown (one Rust module per layer)
|
||||
|
||||
| Module | Physics | What it does | What it does NOT do |
|
||||
|---|---|---|---|
|
||||
| `source.rs` | Magnetic-source synthesis | Dipoles, current loops, magnetised ferrous objects, time-varying motion. Magpylib-style API in Rust. | NV-NV entanglement, single-defect imaging, growth defects |
|
||||
| `propagation.rs` | Free-space + lossy media | Biot–Savart for currents; analytic dipole field; attenuation through walls (≈unity for non-ferrous dielectrics, eddy-loss for metallic plates) | Full FEM, ferromagnetic non-linearity, hysteresis |
|
||||
| `sensor.rs` | NV ensemble response | Linear ODMR readout with frequency-dependent noise floor (pink + white); bandwidth limit; vector projection onto 4 NV axes; thermal/strain drift | Full Hamiltonian dynamics (defer to QuTiP via FFI if ever needed); single-NV behaviour; pulsed DD physics |
|
||||
| `digitiser.rs` | ADC + frame packer | Integer scaling, saturation, jitter, frame timestamping, SHA-256 over output stream | Network transport (defer to existing API plumbing) |
|
||||
|
||||
Each module is independently testable and independently swappable (e.g., replace the
|
||||
coarse `propagation.rs` with a FEM-backed implementation later without touching
|
||||
`sensor.rs`).
|
||||
|
||||
### 4.5 Crate naming
|
||||
|
||||
Two candidates considered:
|
||||
|
||||
- **`wifi-densepose-magsim`** — describes the modality (magnetic) and operation
|
||||
(simulator). Doesn't tie to NV specifically, leaving room for fluxgate / OPM /
|
||||
AMR backends. **Recommended.** Also the shorter name.
|
||||
- **`wifi-densepose-nvsim`** — explicitly NV. Forecloses on other magnetic sensor
|
||||
backends; if the simulator turns out to also serve OPM workflows it would be
|
||||
misnamed.
|
||||
|
||||
Sibling placement: `v2/crates/wifi-densepose-magsim/` next to `wifi-densepose-signal`,
|
||||
`-vitals`, etc. Matches the existing 15-crate workspace pattern.
|
||||
|
||||
### 4.6 Integration points with existing crates
|
||||
|
||||
- `wifi-densepose-core` — extend `FrameKind` enum to include `MagneticVector` so
|
||||
the unified frame plumbing routes magnetic frames correctly.
|
||||
- `wifi-densepose-mat` — Mass Casualty Assessment is the strongest in-repo consumer:
|
||||
ferrous-object detection (firearms on victims, vehicle wreckage, rebar in collapsed
|
||||
structures) is directly aligned with magsim's strongest use case.
|
||||
- `wifi-densepose-signal/ruvsense/` — `field_model.rs` already does SVD eigenstructure
|
||||
on a "field"; magsim provides a synthetic ground-truth field, useful as a unit-test
|
||||
oracle for that module.
|
||||
- `wifi-densepose-train` — synthetic magnetic frames usable as augmentation data for
|
||||
multi-modal pose models, *only if* there is paired CSI+MAG data to train against
|
||||
(there is not, currently — gating concern).
|
||||
- `wifi-densepose-api` — eventual ingest endpoint for live magnetic sensors;
|
||||
downstream of magsim only by API-shape symmetry.
|
||||
|
||||
### 4.7 Out of scope (explicit non-goals)
|
||||
|
||||
- Single-NV imaging (nm-scale microscopy). Not RuView's geometry.
|
||||
- NV-NV entanglement protocols. Not RuView's hardware budget.
|
||||
- Full Hamiltonian + Lindblad solver. Defer to QuTiP via offline pre-computed
|
||||
noise spectra if ever needed.
|
||||
- Diamond growth simulation. Material-science problem; vendor-handled.
|
||||
- fT-floor sensitivity claims. Outside COTS deliverable in 2026.
|
||||
- Pulsed dynamical-decoupling sequence design. Hardware-firmware concern, not
|
||||
simulator concern.
|
||||
|
||||
---
|
||||
|
||||
## 5. Verdict on whether to build
|
||||
|
||||
### Build arguments
|
||||
1. There is a real *gap* in open-source end-to-end NV-pipeline simulators (Sec 3.3).
|
||||
2. Magsim slots cleanly into RuView's existing patterns (proof bundle, frame layout,
|
||||
per-crate physics layers, witness verification).
|
||||
3. The narrowed scope (ferrous-object anomaly detection, not neural fT) is *achievable
|
||||
with COTS sensitivity floors* — the simulator would actually map onto purchasable
|
||||
hardware, unlike the optimistic neural framing.
|
||||
4. `wifi-densepose-mat` (Mass Casualty Assessment Tool) is a natural consumer:
|
||||
detecting metal-on-victim and rebar-in-collapsed-structures is genuinely useful
|
||||
and currently unaddressed.
|
||||
|
||||
### Skip arguments
|
||||
1. **OPM wins on sensitivity at similar cost** for any biomagnetic use case. If the
|
||||
eventual goal is biomag, RuView should simulate OPM, not NV.
|
||||
2. **No paired training data**. Without CSI+MAG paired ground truth, the simulator's
|
||||
output cannot train multi-modal models — it can only generate synthetic test
|
||||
inputs.
|
||||
3. **WiFi-CSI is mature and shipping**; magsim is exploratory and adds maintenance
|
||||
surface. The 15-crate workspace is already large for a small team.
|
||||
4. **The hardware decision precedes the simulator**. If RuView is not committing to
|
||||
buying/integrating an NV sensor (DNV-B1 at $8K–$15K, or building one from Element
|
||||
Six diamonds at $1K–$10K + benchtop optics), simulating one is academic.
|
||||
|
||||
### Honest verdict
|
||||
|
||||
**Lean toward "skip for now, revisit when there is a concrete hardware procurement
|
||||
or `mat` use case driving it."** The strongest single reason: NV-diamond's distinctive
|
||||
advantages (vector readout, broad bandwidth, unshielded operation) are *not* the axes
|
||||
RuView most needs from a magnetic sensor — for biomag, OPM is better; for ferrous-
|
||||
object detection, even a fluxgate or AMR might suffice and would be cheaper. Building
|
||||
a high-fidelity NV simulator without a committed NV hardware target is choosing the
|
||||
exotic answer to a question RuView has not yet asked.
|
||||
|
||||
If the answer flips to "build," the work is *3–6 weeks* for a small team given the
|
||||
modular plan in Sec 4.4 and the existing proof-bundle/witness-verification scaffolding.
|
||||
|
||||
---
|
||||
|
||||
## 6. Open questions that would change the verdict
|
||||
|
||||
### 6.1 Is COTS NV noise floor competitive with OPM at RuView's sensor budget?
|
||||
|
||||
**Answer (with primary sources)**: No, at the $200–$500/sensor target. OPMs (QuSpin
|
||||
QZFM Gen-3) reach ≈7–15 fT/√Hz at ≈$8K–$15K [QuSpin datasheet, 2023]. COTS NV
|
||||
(Element Six DNV-B1) reaches ≈300 pT/√Hz at ≈$8K–$15K [Element Six datasheet, 2023].
|
||||
Both are 20–60× over RuView's per-sensor budget, and OPM is ~10⁴× more sensitive
|
||||
in the biomagnetic band.
|
||||
|
||||
**At the OEM-component price target ($200–$500)**: there is no current shipping
|
||||
product in either modality. No primary source found. Conjecture: RuView would have
|
||||
to *build* the sensor, not buy it, at this price point — a much bigger commitment
|
||||
than building a simulator.
|
||||
|
||||
### 6.2 Is end-to-end SNR positive for chest-surface QRS with a DIY NV setup?
|
||||
|
||||
**With Wolf 2015's 0.9 pT/√Hz at 10 Hz, signal=50 pT, bandwidth=10 Hz**:
|
||||
SNR ≈ 50 / (0.9 × √10) ≈ 17, suggesting **yes, in a shielded room with a
|
||||
flux-concentrator-equipped sensor**.
|
||||
|
||||
**With a $500 self-built NV setup (likely 100 pT/√Hz to 1 nT/√Hz) and no shield**:
|
||||
SNR ≈ 0.05–0.5, below detection threshold. **No.**
|
||||
|
||||
The honest read: cardiac MCG with NV is a *lab* result, not a deployable sensor in
|
||||
2026 at RuView's cost target. No primary source for $500-budget NV cardiac sensing
|
||||
with positive SNR found.
|
||||
|
||||
### 6.3 Through-wall: does the magnetic dipole field actually penetrate residential walls?
|
||||
|
||||
**Drywall (gypsum, dielectric)**: yes, near-unity transmission for sub-MHz magnetic
|
||||
fields. No primary source needed; dielectrics have μ ≈ μ₀.
|
||||
|
||||
**Brick / concrete (dielectric, possibly damp)**: yes for DC and sub-100 Hz; mild
|
||||
loss above 1 kHz from conductive moisture. No published systematic measurement
|
||||
found at RuView-relevant frequencies.
|
||||
|
||||
**Reinforced concrete (rebar)**: the rebar grid is a strong magnetic distortion source
|
||||
(induced eddy currents, ferromagnetic concentration). Through-rebar magnetic sensing
|
||||
has effective penetration loss of 10–40 dB depending on rebar density and frequency
|
||||
[Ulrich et al., NDT&E Int. 35, 137 (2002), for civil-engineering NDT — not RuView-
|
||||
specific]. **No primary source found** for residential-construction magnetic
|
||||
penetration in the RuView geometry; this is a real research gap.
|
||||
|
||||
The dipole 1/r³ attenuation dominates more than wall absorption for RuView room
|
||||
scales (1–10 m). Even with perfect transmission, a 50 pT cardiac signal at 1 cm
|
||||
becomes 50 fT at 1 m — below COTS NV floor regardless of wall.
|
||||
|
||||
---
|
||||
|
||||
## 7. If the verdict flips to "build" — three follow-up ADRs
|
||||
|
||||
1. **ADR: Magsim crate scope and frame format**. Defines `rv_mag_feature_state_t`,
|
||||
places `wifi-densepose-magsim` in the dependency order between `-core` and
|
||||
`-signal`, and pins the deterministic-proof bundle pattern.
|
||||
2. **ADR: Magnetic-anomaly hardware target selection**. Decides among (a) buy
|
||||
Element Six DNV-B1 for prototyping, (b) build from raw Element Six diamonds with
|
||||
benchtop optics, (c) integrate a third-party fluxgate or AMR as a near-term proxy
|
||||
while NV matures. Drives sensor-layer noise model in `sensor.rs`.
|
||||
3. **ADR: MAT (Mass Casualty Assessment) magnetic-anomaly extension**. Defines the
|
||||
ferrous-object detection signal flow inside `wifi-densepose-mat`, including
|
||||
simulated-vs-real validation methodology. Without a clear MAT use case, magsim
|
||||
is orphaned.
|
||||
|
||||
---
|
||||
|
||||
## 8. Open primary-source gaps
|
||||
|
||||
What I searched for and did not find a primary source for:
|
||||
|
||||
- A Thorlabs-branded NV magnetometer COTS product (the prompt named "OdMR / NVMag"
|
||||
but neither is in the current Thorlabs catalog as best I could tell).
|
||||
- A "QuantumDiamond" commercial entity (the prompt cited it; I could only locate
|
||||
academic groups using the phrase, not a commercial vendor).
|
||||
- Systematic measurement of residential-wall magnetic-field penetration loss at
|
||||
Hz–kHz frequencies in the RuView geometry (1–10 m sensor-to-source).
|
||||
- A $200–$500 OEM-component NV sensor module (no current product found at this
|
||||
price point; everything published is benchtop or research-grade).
|
||||
- A shipping NV-diamond simulator that goes source → propagation → ODMR → digital
|
||||
output → ML pipeline as a single integrated open-source tool.
|
||||
|
||||
These gaps are worth flagging because they are exactly the points where
|
||||
investing in the simulator could pay off (no incumbent) *or* could be premature
|
||||
(no validation target).
|
||||
|
||||
---
|
||||
|
||||
## 9. References (primary sources cited inline)
|
||||
|
||||
- Wolf, T. *et al.* "Subpicotesla Diamond Magnetometry." *Phys. Rev. X* **5**,
|
||||
041001 (2015).
|
||||
- Barry, J. F. *et al.* "Sensitivity optimization for NV-diamond magnetometry."
|
||||
*Rev. Mod. Phys.* **92**, 015004 (2020).
|
||||
- Fescenko, I. *et al.* "Diamond magnetometer enhanced by ferrite flux concentrators."
|
||||
*Phys. Rev. Research* **2**, 023394 (2020).
|
||||
- Zhang, C. *et al.* "Diamond magnetometry of meV-scale magnetic fluctuations."
|
||||
*Nat. Comm.* **12**, 2737 (2021).
|
||||
- Schloss, J. M. *et al.* "Simultaneous broadband vector magnetometry using
|
||||
solid-state spins." *Phys. Rev. Applied* **10**, 034044 (2018).
|
||||
- Ortner, M. & Bandeira, L. G. C. "Magpylib: A free Python package for magnetic field
|
||||
computation." *SoftwareX* **11**, 100466 (2020).
|
||||
- Johansson, J. R., Nation, P. D., Nori, F. "QuTiP: An open-source Python framework
|
||||
for the dynamics of open quantum systems." *Comp. Phys. Comm.* **184**, 1234 (2013).
|
||||
- Element Six DNV-B1 datasheet (2023). Material vendor publication.
|
||||
- QuSpin QZFM Gen-3 datasheet (2023). Vendor publication.
|
||||
- Ulrich, R. K. *et al.* on rebar magnetic NDT: *NDT&E Int.* **35**, 137 (2002) —
|
||||
cited as proxy for non-RuView-geometry rebar penetration; not directly applicable.
|
||||
|
||||
Inline conjecture markers ("no primary source found, conjecture") appear in
|
||||
Sections 2.1, 6.1, 6.2, and 6.3 where claims could not be grounded.
|
||||
|
||||
---
|
||||
|
||||
*This document is part of the Quantum Sensing research series. It surveys
|
||||
NV-diamond magnetometry SOTA and proposes — but does not advocate for — a Rust
|
||||
simulator crate within the RuView workspace. The build/skip recommendation
|
||||
defers to a concrete hardware procurement decision or a `wifi-densepose-mat`
|
||||
use case, neither of which exists at the time of writing.*
|
||||
@@ -0,0 +1,268 @@
|
||||
# NV-Diamond Sensor Simulator — Implementation Plan
|
||||
|
||||
## Quantum Sensing Series (15/—) — Executable Build Spec
|
||||
|
||||
**Date**: 2026-04-25
|
||||
**Status**: Plan only — no source code yet
|
||||
**Branch**: `feat/nvsim-pipeline-simulator` (untracked artefact)
|
||||
**Companion**: `14-nv-diamond-sensor-simulator.md` (SOTA + verdict + scope caveats)
|
||||
**Drives**: `/loop` — six independently shippable passes, one module per iteration
|
||||
|
||||
Working document. A developer (human or agent) picks up any single row of §3, ships
|
||||
it, runs the gate, stops. Doc 14's verdict was "lean toward skip without a hardware
|
||||
target"; this plan honours that scoping by sizing narrowly to ferrous-anomaly /
|
||||
eddy-current / `mat`-aligned use cases. Where physics has a primary source, formula is
|
||||
cited; where it does not, the gap is marked **conjecture** with a defensible default.
|
||||
|
||||
---
|
||||
|
||||
## Section 1 — Crate scaffold
|
||||
|
||||
### 1.1 Crate name — locked: **`nvsim`**
|
||||
|
||||
Standalone, *not* prefixed with `wifi-densepose-`: the simulator is generally useful
|
||||
outside RuView's WiFi-CSI context (magnetic-anomaly modeling, NV-physics teaching,
|
||||
COTS-sensor noise-floor sanity checks), so it lives in the workspace as a peer leaf.
|
||||
Public API: `use nvsim::scene::DipoleSource;`. Placement: `v2/crates/nvsim/`, pure leaf
|
||||
crate (no internal RuView deps).
|
||||
|
||||
### 1.2 Cargo.toml
|
||||
|
||||
```toml
|
||||
[package]
|
||||
name = "nvsim"
|
||||
version.workspace = true
|
||||
edition.workspace = true
|
||||
license.workspace = true
|
||||
description = "Deterministic NV-diamond magnetometer pipeline simulator (source -> propagation -> NV -> ADC)"
|
||||
|
||||
[dependencies]
|
||||
ndarray = { workspace = true } # 3-vector field math, time-series buffers
|
||||
rustfft = { workspace = true } # spectral analysis + lockin demod cross-check
|
||||
num-complex = { workspace = true } # phasor algebra in lockin
|
||||
num-traits = { workspace = true }
|
||||
rand = "0.8" # Monte-Carlo shot noise (NOT in workspace yet -> add)
|
||||
rand_chacha = "0.3" # deterministic seed -> ChaCha20 PRNG
|
||||
sha2 = "0.10" # witness hashing (already used in -core)
|
||||
serde = { workspace = true }
|
||||
serde_json = { workspace = true }
|
||||
thiserror = { workspace = true }
|
||||
tracing = { workspace = true }
|
||||
wifi-densepose-core = { path = "../wifi-densepose-core" } # FrameKind extension only
|
||||
|
||||
[dev-dependencies]
|
||||
criterion = "0.5"
|
||||
approx = "0.5"
|
||||
|
||||
[features]
|
||||
default = []
|
||||
ruvector = ["dep:ruvector-core"] # optional witness/sketch reuse — Section 4
|
||||
[dependencies.ruvector-core]
|
||||
path = "../../../vendor/ruvector/crates/ruvector-core"
|
||||
optional = true
|
||||
|
||||
[[bench]]
|
||||
name = "pipeline_throughput"
|
||||
harness = false
|
||||
```
|
||||
|
||||
### 1.3 Module layout (one file each, < 500 lines per CLAUDE.md)
|
||||
|
||||
| File | LoC budget | Purpose |
|
||||
|---|---|---|
|
||||
| `src/lib.rs` | < 200 | Public re-exports, `Pipeline` builder, error type, crate-level rustdoc |
|
||||
| `src/scene.rs` | < 350 | `DipoleSource`, `CurrentLoop`, `FerrousObject`, `EddyCurrent`, `Scene` aggregate |
|
||||
| `src/source.rs` | < 350 | Biot–Savart for current loops + analytic dipole field (no FEM) |
|
||||
| `src/propagation.rs` | < 250 | Per-material attenuation table + free-space pass-through |
|
||||
| `src/sensor.rs` | < 450 | NV-ensemble linear ODMR readout, Lorentzian lineshape, T1/T2 envelope, shot noise, vector projection onto 4 NV axes |
|
||||
| `src/digitiser.rs` | < 300 | ADC quantize, anti-alias, lockin demod at MW modulation freq |
|
||||
| `src/pipeline.rs` | < 250 | Wires the four layers; emits `MagFrame` stream |
|
||||
| `src/frame.rs` | < 250 | `rv_mag_feature_state_t` struct, magic-number, byte-exact serialisation |
|
||||
| `src/proof.rs` | < 250 | Deterministic seed -> SHA-256 witness; mirrors `archive/v1/data/proof/verify.py` |
|
||||
|
||||
Total: ~2,650 LoC Rust + ~400 LoC tests + 1 bench. 3-week sprint per doc 14 §5.
|
||||
|
||||
### 1.4 Frame magic number
|
||||
|
||||
ADR-018 reserves `0xC51F...` for CSI. Pick **`0xC51A_6E70`** for `rv_mag_feature_state_t`:
|
||||
`C51` (CSI/feature lineage), `A` (Analog/Anomaly), `6E70` (ASCII "np", NV-pipeline).
|
||||
u32 little-endian, first 4 bytes of every frame. Consumers reading `0xC51F...` fail
|
||||
magic-check on a magsim frame and abort cleanly — non-overlap with CSI is the invariant.
|
||||
|
||||
### 1.5 Workspace wiring
|
||||
|
||||
Append `crates/nvsim` to `v2/Cargo.toml` members after `wifi-densepose-vitals`. No
|
||||
publishing-order changes (pure leaf, no internal deps). Update CLAUDE.md crate table
|
||||
in a separate PR after Pass 6 ships.
|
||||
|
||||
---
|
||||
|
||||
## Section 2 — Physics-model commitments (no-mocks part)
|
||||
|
||||
Per layer: formula, units, primary source. When no primary source applies at RuView
|
||||
geometry, marked **conjecture** with chosen default.
|
||||
|
||||
### 2.1 `source.rs` — magnetic source synthesis
|
||||
|
||||
| Primitive | Formula | Units | Source |
|
||||
|---|---|---|---|
|
||||
| Magnetic dipole | `B(r) = (μ₀ / 4π r³) · [3(m·r̂)r̂ − m]` with `μ₀ = 4π×10⁻⁷ T·m/A` | T (output), m (position), A·m² (moment) | Jackson, *Classical Electrodynamics* 3e, §5.6 (1999); Magpylib reference impl [Ortner & Bandeira, SoftwareX 11, 100466 (2020)] |
|
||||
| Current loop | Biot–Savart: `B(r) = (μ₀/4π) ∮ I dl × r̂ / r²` discretised over n=64 segments | T | Jackson §5.4 |
|
||||
| Ferrous-object induced moment | Linear approx: `m_induced = χ V H_ambient` for χ ≈ 5000 (steel) | A·m² | Cullity & Graham, *Introduction to Magnetic Materials* 2e (2009), Ch.2 — primary source for steel χ at low field |
|
||||
| Eddy-current loop | Faraday + Ohm: `I(t) = -(σ A / L) · dΦ/dt`, then re-emits via Biot–Savart | A | Jackson §5.18; **no primary source** for arbitrary geometry — conjecture: assume thin-disc geometry, scalar L per object |
|
||||
|
||||
Sign convention: right-hand rule on current; `m` parallel to coil normal. Units: SI;
|
||||
convert to pT at frame-emit time only. Singularity at r→0: clamp `r_min = 1 mm`; below
|
||||
that, return `B = 0` and set `flags |= SATURATION_NEAR_FIELD` (conjectural — no
|
||||
published guidance for sub-mm dipole at RuView geometry — but deterministic).
|
||||
|
||||
### 2.2 `propagation.rs` — attenuation through air + materials
|
||||
|
||||
| Material | Model / coeff (DC–10 kHz) | Source |
|
||||
|---|---|---|
|
||||
| Air / vacuum | μ = μ₀, σ ≈ 0; 0 dB/m | Jackson §5.8 |
|
||||
| Drywall (gypsum) | Dielectric, 0 dB/m | **Conjecture** (no primary source); gypsum non-ferromagnetic, loss << 0.1 dB/m |
|
||||
| Brick (dry) | Dielectric, 0 dB/m | **Conjecture**; same logic |
|
||||
| Concrete (dry) | 0.5 dB/m default | **Conjecture** (Ulrich *NDT&E Int.* 35, 2002 as proxy only) |
|
||||
| Reinforced concrete | 20 dB/m + warning flag | Ulrich 2002 proxy; **research gap** per doc 14 §6.3 |
|
||||
| Sheet steel | Skin depth `δ = √(2/μσω)`, freq-dependent | Jackson §8.1 |
|
||||
|
||||
Propagation is intentionally thin: free-space 1/r³ lives in `source.rs`. This layer
|
||||
applies per-segment attenuation only when sensor-source line-of-sight intersects a
|
||||
material slab; default is identity.
|
||||
|
||||
### 2.3 `sensor.rs` — NV-ensemble response
|
||||
|
||||
Full Hamiltonian is *not* solved (doc 14 §4.4 defers Lindblad dynamics to QuTiP). We
|
||||
implement the linear-readout proxy that Barry 2020 §III.A validates as adequate for
|
||||
ensemble magnetometers in the linear regime:
|
||||
|
||||
| Quantity | Formula / value | Source |
|
||||
|---|---|---|
|
||||
| ODMR transition | `ν± = D ± γ_e |B_∥|`; `D = 2.87 GHz`, `γ_e = 28 GHz/T` | Doherty *Phys. Rep.* 528 (2013) §3 |
|
||||
| Lineshape | Lorentzian, `Γ ≈ 1 MHz` FWHM | Barry *RMP* 92 (2020), Fig. 4 |
|
||||
| Shot-noise δB | `1 / (γ_e · C · √(N · t))` (leading order) | Barry 2020 Eq. 35; Taylor *Nat. Phys.* 4 (2008) |
|
||||
| C (ODMR contrast) | 0.03 (COTS bulk) | Barry 2020 Table III |
|
||||
| N (sensing spins) | 10¹² for ~1 mm³ | Barry 2020 §IV.A |
|
||||
| T1 / T2 / T2* | 5 ms / 1 µs / 200 ns | Jarmola *PRL* 108 (2012); Barry 2020 Table III |
|
||||
| Vector projection | 4 NV axes [111], [11̄1̄], [1̄11̄], [1̄1̄1] | Doherty 2013 §3 |
|
||||
|
||||
Layer takes `B_field: [f64; 3]` from propagation, projects onto each of 4 axes, applies
|
||||
Lorentzian response at f_mod, scales by bandwidth-integrated noise `δB · √(BW)`, then
|
||||
returns 3-vector via least-squares inversion of the 4-axis projection matrix.
|
||||
|
||||
Sanity floor derived from above (must hold in tests): `δB(t=1s, BW=1Hz) ≈ 1.2 pT/√Hz`,
|
||||
within 4× of Wolf 2015's 0.9 pT/√Hz — acceptable analytic-model approximation given
|
||||
ODMR-CW operation (Wolf used flux concentrators).
|
||||
|
||||
### 2.4 `digitiser.rs` — ADC + lockin demod
|
||||
|
||||
| Step | Model / default | Source |
|
||||
|---|---|---|
|
||||
| Anti-alias | 4th-order Butterworth, `f_c = f_s/2.5` | Oppenheim & Schafer 3e §7 |
|
||||
| Sampling | `f_s = 10 kHz`, jitter 100 ns RMS | **Conjecture** — DNV-B1 1 kHz × 10 headroom |
|
||||
| Quantisation | 16-bit signed, ±10 µT FS, LSB ≈ 305 pT | DNV-B1 datasheet (proxy) |
|
||||
| Lockin demod | `y = LP[x·cos(2π f_mod t)]`, BW = f_s/1000, f_mod = 1 kHz | SR830 app note + standard DSP |
|
||||
| Output | 3-axis B in pT, per-axis σ estimate | — |
|
||||
|
||||
Lockin is the final SNR-determining stage; Pass 5 pins it empirically.
|
||||
|
||||
---
|
||||
|
||||
## Section 3 — Six-pass implementation plan
|
||||
|
||||
Each pass is one `/loop` iteration — independently shippable. Gate must pass before
|
||||
next pass begins; if not, abort and replan (§7).
|
||||
|
||||
| Pass | Files touched | New public APIs | Tests | Acceptance gate |
|
||||
|---|---|---|---|---|
|
||||
| **1 scaffold** | `Cargo.toml`, `lib.rs`, `scene.rs`, `frame.rs`, `v2/Cargo.toml` | `Scene`, `DipoleSource`, `CurrentLoop`, `FerrousObject`, `MagFrame`, `MAG_FRAME_MAGIC` | 6: scene JSON round-trip; magic = `0xC51A_6E70`; frame byte order deterministic; serde compiles; empty scene serializes; LoC budget enforced | `cargo check -p nvsim` clean; 6/6 pass; workspace 1,575+6 = 1,581 |
|
||||
| **2 Biot–Savart** | `source.rs` | `Scene::field_at(point) -> [f64;3]` | 5: on-axis dipole `B = μ₀m/(2π z³)`; equatorial `B = -μ₀m/(4π r³)`; n=8 RMS ≤ 0.5%; loop on-axis `B_z = μ₀ I a²/[2(a²+z²)^{3/2}]`; r→0 clamp = 0+flag | n=8 ≤ 0.5%; else **abort §7-1** |
|
||||
| **3 propagation** | `propagation.rs`, `lib.rs` | `Propagator::attenuate(B, los_segments) -> [f64;3]` | 4: free-space identity; drywall ≈ 0 dB; concrete 0.5 dB/m; rebar warns + 20 dB/m; NaN-safe on zero LoS | All 4 pass; no NaN any input |
|
||||
| **4 NV sensor** | `sensor.rs` | `NvSensor::sample(B_in, dt) -> NvReading` | 6: FWHM = 1.0 ± 0.05 MHz; shot noise ∝ 1/√t over 5 decades; T2 envelope = exp(−t/T2); 4-axis LSQ residual < 1%; zero-in + noise-on = zero-mean; floor at 1 µT bias matches Barry 2020 within 2× | Floor match ≤ 2×; else **abort §7-2** |
|
||||
| **5 digitiser+pipeline** | `digitiser.rs`, `pipeline.rs` | `Pipeline::new(scene,config).run(n) -> Vec<MagFrame>`; `Lockin::demod` | 5: `(scene, seed=42)` → SHA-256 witness; same seed = byte-identical; 1 nT @ 1 kHz vs 1 nT/√Hz floor → SNR ≥ 10 in 1 s; ADC saturates + flags above ±10 µT; anti-alias ≥ 40 dB at f_s/2+1 Hz | All 5 pass; SNR floor met |
|
||||
| **6 proof+bench** | `proof.rs`, `benches/pipeline_throughput.rs`, `lib.rs` docs | `Proof::generate()`, `Proof::verify(expected_hash)` | 5: bundle reproduces published `expected_mag_features.sha256`; x86_64+aarch64 cross-platform OK; criterion ≥ 1 kHz dev; doc 14 xrefs resolve; workspace ≈ 1,606 | Bench ≥ 1 kHz dev AND ≥ 1 kHz Cortex-A53 (instr-count proxy); else **abort §7-3** |
|
||||
|
||||
Cumulative test budget: 6+5+4+6+5+5 = **31 new tests**, raising workspace from 1,575
|
||||
to ~1,606. Branch hygiene: every pass commits to `feat/nvsim-pipeline-simulator`,
|
||||
subject ends in `[nvsim:passN]`; no merge to `main` until all six gates pass.
|
||||
|
||||
---
|
||||
|
||||
## Section 4 — ruvector integration points
|
||||
|
||||
Doc 14 §4.6 did *not* mandate ruvector. Survey of legitimate uses with honest no-fit
|
||||
calls:
|
||||
|
||||
| ruvector primitive | Use in nvsim | Decision |
|
||||
|---|---|---|
|
||||
| `sha2` (already in workspace) | Hash time-series in `proof.rs` | **Use direct `sha2` dep** — not via ruvector |
|
||||
| `BinaryQuantized` 32× | Long-form trace storage for regression replay (1 h × 10 kHz: 432 MB f32 → 13.5 MB binary) | **Use behind `features = ["ruvector"]`** opt-in |
|
||||
| HNSW sketch | Content-address scenes | **Skip** — SHA-256 of canonical JSON suffices |
|
||||
| `ruvector-attention` / `mincut` | — | **Skip** — inference primitives; nvsim is forward-only |
|
||||
| `quantization` for ADC | Reuse Q_int4 | **Reject as misuse** — vector compression, not signal-path ADC. Implement directly. |
|
||||
|
||||
Net: optional `ruvector` feature flag enables trace compression in `proof.rs` only.
|
||||
Default build and witness verification do not depend on ruvector — matches the
|
||||
"leverage where it helps but don't force it" guidance.
|
||||
|
||||
---
|
||||
|
||||
## Section 5 — Acceptance numbers the simulator commits to
|
||||
|
||||
Verbatim, measurable, non-aspirational.
|
||||
|
||||
- **Pipeline throughput**: ≥ 1 kHz simulated samples per second of wall-clock on a Cortex-A53-class CPU (Pi Zero 2W).
|
||||
- **Determinism**: same `(scene, seed)` produces byte-identical proof-bundle output across runs and machines.
|
||||
- **Noise floor reproduction**: simulator with shot noise OFF must reproduce the analytical Biot–Savart result to ≤ 0.1% RMS error.
|
||||
- **Lockin SNR floor**: with a 1 nT signal at 1 kHz against a 100 pT/√Hz noise floor, lockin demod recovers SNR ≥ 10 in 1 s integration.
|
||||
|
||||
All four are Pass-6 acceptance tests or bench assertions. Determinism uses fixed-seed
|
||||
ChaCha20 + canonical f64 serialisation order.
|
||||
|
||||
---
|
||||
|
||||
## Section 6 — Out of scope (committed to NOT building)
|
||||
|
||||
Explicit non-goals. Ruling them out is half the value of the plan.
|
||||
|
||||
| Excluded | Reason |
|
||||
|---|---|
|
||||
| Single-NV imaging / ODMR scanning microscopy | Room-scale, not nm; doc 14 §4.7 |
|
||||
| NV-NV entanglement, photonic-crystal cavities | Out of RuView hardware budget |
|
||||
| Diamond growth / NV creation chemistry | Vendor (Element Six) handles |
|
||||
| Cryogenic operation | RuView ships RT; doc 14 §2.2 |
|
||||
| Real hardware control (laser, MW, AOM) | Simulator is forward-only |
|
||||
| Full Hamiltonian + Lindblad solver | Defer to QuTiP if ever needed; doc 14 §3.1 |
|
||||
| Pulsed dynamical-decoupling sequence design | Hardware-firmware concern; doc 14 §4.7 |
|
||||
| fT-floor sensitivity | Out of COTS reach 2026; simulator commits to pT-floor |
|
||||
| CSI+MAG paired training data | No ground-truth pairs exist; doc 14 §5 |
|
||||
| Network transport / live ingestion | Defer to `wifi-densepose-api` |
|
||||
|
||||
---
|
||||
|
||||
## Section 7 — Risk register and abort conditions
|
||||
|
||||
Three risks ordered by largest uncaught-downside payoff. Each has a concrete
|
||||
iteration-level abort. If abort fires, loop halts; replan required.
|
||||
|
||||
| # | Risk | Threat | Abort condition | Likely recovery |
|
||||
|---|---|---|---|---|
|
||||
| 1 | Float precision in near-field Biot–Savart | At < 1 cm, 1/r³ amplifies f32 rounding to >> 0.5%; Pass 2's n=8 analytic test fails | Pass 2 cannot achieve ≤ 0.5% RMS even after promoting all math to f64 and clamping r_min = 1 mm | Add small-r Taylor expansion guard (unspecified physics — escalate) |
|
||||
| 2 | NV shot-noise model mis-cited | §2.3 is leading-order; if 1 µT-bias floor differs from Barry 2020 Fig. 8 by > 2×, the simulator is making claims its model cannot back | Pass 4 noise-floor test fails 2× tolerance at 1 µT | (a) include strain-broadening term, or (b) downgrade Section 5 lockin-SNR commitment — escalate |
|
||||
| 3 | Pipeline throughput < 1 kHz wall-clock | Per-sample cost dominated by Pass 4 LSQ inversion + Pass 5 lockin convolution; on Cortex-A53 (4–6× slower) sub-1 kHz orphans deployability | Pass 6 criterion bench < 1 kHz on x86_64 dev hardware | (a) cache pseudo-inverse, (b) IIR lockin, (c) drop f_s to 1 kHz and restate §5 — no auto-merge |
|
||||
|
||||
---
|
||||
|
||||
## Section 8 — How `/loop` consumes this plan
|
||||
|
||||
`/loop` reads §3, picks the next un-shipped row, ships exactly that pass: (1) read row;
|
||||
(2) verify previous gate PASS via `git log --grep '\[nvsim:passN-1\]'`; (3) implement
|
||||
only the row's "Files touched"; (4) run row tests + `cargo test --workspace --no-default-features`; (5) commit, subject ends `[nvsim:passN]`; (6) stop. Test failure: no commit. §7
|
||||
abort fires: halt loop, surface to user.
|
||||
|
||||
---
|
||||
|
||||
*Entry point for `/loop` on `nvsim`. Does not commit to building — that decision lives
|
||||
in doc 14's verdict ("lean toward skip" absent hardware target). If the verdict flips,
|
||||
this is the plan that ships.*
|
||||
Reference in New Issue
Block a user