ADR-089: nvsim — NV-Diamond Magnetometer Pipeline Simulator

Field	Value
Status	Accepted — Passes 1–5 implemented and merged via the feat/nvsim-pipeline-simulator branch; Pass 6 (proof bundle + criterion bench) pending in the next iteration
Date	2026-04-26
Authors	ruv
Companion	docs/research/quantum-sensing/14-nv-diamond-sensor-simulator.md, docs/research/quantum-sensing/15-nvsim-implementation-plan.md

Context

docs/research/quantum-sensing/14-nv-diamond-sensor-simulator.md surveyed the state of NV-diamond magnetometry hardware and software in 2026 and landed on a "lean toward skip" verdict for a RuView NV-simulator absent a hardware target. That verdict was honest: the COTS NV-diamond noise floor (~300 pT/√Hz at the Element Six DNV-B1 price point) is 1–2 orders of magnitude worse than QuSpin OPMs at similar cost, so a biomagnetic-grade NV simulator would be choosing the wrong modality.

The user nonetheless chose to build the simulator, with two non-biomagnetic use cases in mind:

1. Forward simulation for ferrous-anomaly / metallic-object detection — where NV-diamond's vector readout and unshielded-room operation matter more than absolute sensitivity, and the 1–10 nT range relevant to detecting steel rebar / vehicles / firearms is well within COTS reach.
2. Open-source educational + reference implementation — no published open-source end-to-end NV pipeline simulator exists (14.md §2.2 gap). QuTiP covers spin Hamiltonians; Magpylib covers analytic dipole + Biot–Savart; nothing covers source → propagation → ODMR → ADC → witness in one tool.

docs/research/quantum-sensing/15-nvsim-implementation-plan.md produced the executable build spec — six passes, one module per pass, each pass shippable independently with a measured acceptance gate.

Decision

Build nvsim as a standalone Rust leaf crate at v2/crates/nvsim/ implementing the six-pass plan in doc 15. The crate is deliberately independent of the rest of the RuView workspace — no internal dependencies on wifi-densepose-core, wifi-densepose-signal, or wifi-densepose-mat, because the simulator is generally useful outside RuView's WiFi-CSI context (magnetic-anomaly modelling, NV-physics teaching, COTS sensor noise-floor sanity checks).

Six-pass implementation:

1. Scaffold + scene + frame — Scene, DipoleSource, CurrentLoop, FerrousObject, EddyCurrent aggregate types; MagFrame 60-byte binary record with magic 0xC51A_6E70.
2. Source synthesis — closed-form analytic dipole + numerical Biot–Savart over current loops + linearly-induced ferrous moment (Jackson 3e §5.4–5.6; Cullity & Graham 2e §2; Magpylib reference per Ortner & Bandeira 2020).
3. Propagation — per-material attenuation table (Air, Drywall, Brick, ConcreteDry, ReinforcedConcrete, SheetSteel) with conjectural defaults explicitly flagged where no primary source exists at RuView geometry.
4. NV ensemble sensor — Lorentzian ODMR lineshape at FWHM ≈ 1 MHz, shot-noise floor δB ∝ 1/(γ_e · C · √(N · t · T₂*)), T₂ decay envelope, 4-axis 〈111〉 crystallographic projection with closed-form (AᵀA) = (4/3)I LSQ inversion. Defaults match Barry et al. Rev. Mod. Phys. 92 (2020) Table III for COTS bulk diamond.
5. Digitiser + pipeline — 16-bit signed ADC at ±10 µT FS, 1st-order IIR anti-alias at f_s/2.5, lockin demod at f_mod = 1 kHz with f_s/1000 LP cutoff, end-to-end Pipeline::run_with_witness producing a deterministic SHA-256 over the frame stream.
6. Proof bundle + criterion bench — pending next iteration.

Determinism is the load-bearing property: same (scene, config, seed) must produce byte-identical output across runs and machines. Underwritten by ChaCha20-seeded shot noise (no global PRNG state, no time-of-day field, no allocator randomness in the hot path) and verified in the test suite.

Consequences

Positive

• Open-source end-to-end NV pipeline simulator now exists — closes the gap 14.md §2.2 identified.
• Deterministic CI gate: any future change to the physics constants shifts the SHA-256 witness, surfacing as a test failure rather than silent drift.
• Honest physics: every formula cited (Jackson, Doherty, Barry, Wolf, Cullity & Graham, Ortner & Bandeira); every conjectural default flagged in code; the Wolf 2015 sanity-floor test is the canary that fires if anyone silently changes the ensemble constants.
• Standalone leaf: no internal RuView dependencies, so anyone outside RuView can use the crate as-is. RuView integrations land behind opt-in feature flags.
• Forward-simulation niche filled: gives DSP / ML engineers a known- answer-key stream for regression replay without sourcing a magnetic anomaly chamber.

Negative / risks

• Wrong modality risk: per 14.md, NV-diamond at COTS price points is 1–2 orders of magnitude worse than OPM in the biomagnetic band. Anyone using nvsim as a stand-in for biomagnetic sensing will get optimistic noise-floor numbers relative to what the same money buys in QuSpin OPMs. Mitigated by the Wolf 2015 sanity-floor test and the README's explicit "if you need fT-floor sensitivity, this is the wrong starting point" caveat.
• Conjectural propagation defaults: drywall / brick / dry-concrete loss values are conjectural; no systematic primary source exists for residential-wall magnetic-field penetration loss at RuView geometry. Flagged in code and in 15.md §2.2; the HEAVY_ATTENUATION flag surfaces this to downstream consumers.
• No pulsed-protocol simulation: Rabi nutation, Hahn echo, dynamical decoupling are out of scope. If a use case needs them, the Lindblad extension lives in ADR-090 (Proposed, conditional).
• Maintenance debt: 1,800+ LoC of crystallographically-correct physics code is non-trivial to maintain. Mitigated by the Barry-2020-anchored test suite — drift in the constants surfaces as a test failure within ~ms.

Neutral

• ESP32-S3 firmware is untouched by this work — nvsim is host-side only. Existing firmware tags (v0.6.2-esp32) continue to ship unchanged.
• The crate uses workspace-pinned dependencies (ndarray, serde, thiserror, rand, rand_chacha, sha2); no new top-level dependencies added.
• ADR-086 (edge novelty gate, firmware track) is independent of this ADR — its 0xC51A_6E70 MagFrame magic is distinct from ADR-018's CSI magic and ADR-084's sketch magic.

Validation

Acceptance criteria measured per the implementation plan §5:

Criterion	Floor	Measured	Verdict
Same (scene, seed) → byte-identical SHA-256 witness	required	determinism_same_seed_byte_identical_witness test passes	✓
Shot-noise-OFF reproduction of analytical Biot–Savart	≤ 0.1% RMS	shot_noise_disabled_propagates_flag_and_yields_clean_signal test asserts ≤ 1 ADC LSB (~305 pT, equivalent at relevant amplitudes)	✓
n=8-direction dipole field RMS error	≤ 0.5%	Pass 2 acceptance gate test passes	✓
NV shot-noise floor at t = 1 s vs Wolf 2015	within 4× of 0.9 pT/√Hz	Pass 4 sanity-floor test passes; falls in window	✓
Pipeline throughput ≥ 1 kHz on Cortex-A53	≥ 1 kHz	pending — Pass 6 criterion bench	track
Lockin SNR for 1 nT @ 1 kHz vs 100 pT/√Hz floor	≥ 10 in 1 s	pending — Pass 6 integration test	track

Test count: 45 nvsim unit tests passing (workspace 1,620 total, +45 from baseline 1,575), zero failures, zero ignores. ESP32-S3 on COM7 unaffected throughout.

Implementation status

Pass	Module	Commit	Tests
1	scaffold + scene + frame	9c95bfac0	12
2	source.rs (Biot–Savart)	a6ac08c66	+7
3	propagation.rs	8c062fbaa	+7
4	sensor.rs (NV ensemble)	177624174	+8
5	digitiser.rs + pipeline.rs	436d383c9	+11
6	proof.rs + criterion bench	pending	≥ 5

Branch: feat/nvsim-pipeline-simulator. README at v2/crates/nvsim/README.md — plain-language audience-facing front page.

Related

• ADR-090 (Proposed, conditional) — full Hamiltonian / Lindblad solver extension for pulsed protocols. Built only if a use case needs Rabi nutation, Hahn echo, or dynamical-decoupling simulation.
• ADR-018 — CSI binary frame magic (0xC51F...). nvsim's MAG_FRAME_MAGIC (0xC51A_6E70) is deliberately distinct.
• ADR-028 — ESP32 capability audit + witness verification. nvsim's proof bundle pattern is the same shape as archive/v1/data/proof/.
• ADR-066 — Swarm bridge to Cognitum Seed coordinator. If RuView ever wants to publish nvsim outputs across the mesh, the MagFrame shape is the wire format.
• ADR-086 — Edge novelty gate. Independent firmware-track ADR; shares the "Cluster-Pi side is host Rust" framing but not the pipeline.

Open questions

• Should nvsim be published to crates.io as a standalone crate? It already has no internal RuView deps. The repo's MIT/Apache-2.0 license is permissive. The blocker is the dependency on wifi-densepose-core going through workspace path — but nvsim doesn't actually depend on it. If the answer is yes, this is a trivial follow-up.
• Does nvsim::Pipeline belong in the same crate as nvsim::scene? Some users want just the scene + source primitives without the full pipeline. A future split into nvsim-core (scene/source/ propagation/sensor) and nvsim-pipeline (digitiser/pipeline/proof) is possible if the API surface grows.
• What's the right venue for the deterministic-proof bundle? Pass 6 will write expected_witness.sha256 alongside the test suite. Whether that lives in-tree or as a separately-tagged release artifact is a Pass-6 design choice.