docs(adr): ADR-089 (nvsim simulator, Accepted) + ADR-090 (Lindblad, Proposed)
ADR-089 — nvsim NV-Diamond Pipeline Simulator. Status: Accepted. Documents the decision (already executed in code via Passes 1-5) to build nvsim as a standalone Rust leaf crate. Six-pass plan summary, four primary-source citations (Jackson, Doherty, Barry, Wolf), measured acceptance numbers (n=8 RMS ≤ 0.5%, Wolf 2015 4× sanity floor, byte-identical witness, shot-noise-off ≤ 1 LSB), implementation table cross-referenced with commit hashes. Six open questions around crates.io publication, crate split, and proof-bundle venue. ADR-090 — nvsim Full Hamiltonian / Lindblad Solver Extension. Status: Proposed (conditional). Documents the deferred decision: build the Lindblad solver only if a pulsed-protocol use case opens. Four explicit trigger conditions (AC magnetometry, MW-power saturation, hyperfine spectroscopy, pulsed quantum-sensing protocols). Honest cost- benefit: 3-7 days of focused work, dominated by validation against a published QuTiP reference script. Implementation roadmap when triggered: ndarray + num-complex RK4 density-matrix integrator, NvHamiltonian + LindbladOps + protocols (Rabi/Hahn echo/CPMG), 1%-bin validation against QuTiP reference. Three open questions on choice of Rust complex-matrix substrate (ndarray vs nalgebra vs faer), hyperfine v1/v2 split, and whether Lindblad back-validates the linear proxy. Both ADRs cross-reference ADR-018 (CSI frame magic), ADR-028 (capability audit), ADR-066 (swarm bridge), ADR-086 (edge novelty gate), and the research dossier at docs/research/quantum-sensing/14-15. ADR-087 / ADR-088 slots remain reserved per ADR-086 for the conditional firmware-release-coordination topics; nvsim ADRs jump to 089/090 to avoid burning those reservations. Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
parent
436d383c99
commit
5faeddcf47
|
|
@ -0,0 +1,194 @@
|
|||
# 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.
|
||||
|
|
@ -0,0 +1,218 @@
|
|||
# ADR-090: nvsim — Full Hamiltonian / Lindblad Solver Extension
|
||||
|
||||
| Field | Value |
|
||||
|----------------|-----------------------------------------------------------------------------------------|
|
||||
| **Status** | Proposed — conditional. Only built if a pulsed-protocol use case emerges. Default-off, opt-in feature gate. |
|
||||
| **Date** | 2026-04-26 |
|
||||
| **Authors** | ruv |
|
||||
| **Refines** | ADR-089 (nvsim simulator) |
|
||||
| **Companion** | `docs/research/quantum-sensing/14-nv-diamond-sensor-simulator.md` §3.1, `docs/research/quantum-sensing/15-nvsim-implementation-plan.md` §6 |
|
||||
|
||||
## Context
|
||||
|
||||
[ADR-089](ADR-089-nvsim-nv-diamond-simulator.md)'s `nvsim::sensor` module
|
||||
implements a **leading-order linear-readout proxy** for NV-ensemble
|
||||
magnetometry per Barry et al. *Rev. Mod. Phys.* 92, 015004 (2020) §III.A.
|
||||
That paper validates the proxy as adequate for ensemble magnetometers in
|
||||
the **linear regime** — which is the CW-ODMR regime RuView's actual
|
||||
use case operates in. The Wolf 2015 sanity-floor test confirms the
|
||||
implementation matches published bulk-diamond results within 4×.
|
||||
|
||||
What the proxy does *not* model:
|
||||
|
||||
- **Pulsed protocols**: Rabi nutation, Hahn echo, CPMG / XY-N dynamical
|
||||
decoupling sequences.
|
||||
- **Microwave-power saturation**: line-broadening at high CW MW power.
|
||||
- **Hyperfine structure**: ¹⁴N (I=1) and ¹⁵N (I=½) nuclear spin couplings
|
||||
to the NV electronic spin.
|
||||
- **Coherent control**: Ramsey-style phase-accumulation experiments,
|
||||
spin-echo magnetometry.
|
||||
|
||||
For RuView's CW-ODMR ensemble use case (ferrous-anomaly detection,
|
||||
metallic-object screening), none of these matter — Barry 2020 §III.A is
|
||||
explicit that the linear-readout proxy is adequate. For *future* use cases
|
||||
that involve pulsed protocols (e.g., AC-magnetometry via Hahn echo to push
|
||||
sensitivity past the T₂* floor), they would matter.
|
||||
|
||||
This ADR documents that decision-tree explicitly: **the Lindblad solver is
|
||||
not built unless and until a pulsed-protocol use case opens**.
|
||||
|
||||
## Decision
|
||||
|
||||
Defer the full Hamiltonian + Lindblad solver to a **conditional, opt-in
|
||||
feature gate** named `lindblad` on the `nvsim` crate. Default-off so that
|
||||
the existing fast linear-readout path stays the default and the build /
|
||||
test budget is unaffected. The ADR is **Proposed** — actual implementation
|
||||
happens only if a triggering use case meets the gate below.
|
||||
|
||||
### Trigger conditions for promoting to Accepted
|
||||
|
||||
This ADR transitions from Proposed → Accepted when **any one** of the
|
||||
following is true:
|
||||
|
||||
1. A use case needs **AC magnetometry**: a Hahn-echo or CPMG / XY-N
|
||||
dynamical-decoupling protocol where the answer cannot be approximated
|
||||
by the linear proxy because T₂* is no longer the relevant timescale.
|
||||
2. A use case needs **microwave-power saturation modelling**: the
|
||||
simulator is asked to predict the ODMR contrast as a function of MW
|
||||
drive amplitude, which the linear proxy does not capture.
|
||||
3. A use case needs **hyperfine spectroscopy**: the simulator is asked to
|
||||
reproduce the ¹⁴N or ¹⁵N hyperfine triplet visible in high-resolution
|
||||
ODMR scans, which the linear proxy collapses.
|
||||
4. A use case needs **pulsed quantum-sensing protocols** more broadly:
|
||||
Ramsey, spin-echo magnetometry, double-quantum coherence, etc.
|
||||
|
||||
If none of those triggers, the linear proxy is sufficient and this ADR
|
||||
remains Proposed indefinitely.
|
||||
|
||||
### Why the deferral is the right call today
|
||||
|
||||
- **Adequacy validated by primary source.** Barry 2020 §III.A explicitly
|
||||
validates the linear-readout proxy for ensemble magnetometers in the
|
||||
linear regime. nvsim's existing `sensor.rs` matches Wolf 2015 within 4×.
|
||||
We're not under-modelling — we're correctly-modelling.
|
||||
- **3–7 days of focused work.** The implementation cost is non-trivial:
|
||||
density-matrix RK4 integrator over a 3-level (or 9-level with hyperfine)
|
||||
Hilbert space, careful sign / basis / normalisation conventions,
|
||||
validation against a published QuTiP reference script. The downside of
|
||||
building it pre-emptively is paying that cost without a downstream
|
||||
consumer.
|
||||
- **No current downstream consumer.** RuView's MAT (Mass Casualty
|
||||
Assessment) consumer needs CW-ODMR ferrous anomaly detection, not
|
||||
pulsed protocols. ADR-066 swarm-bridge (proposed) is similarly
|
||||
CW-amplitude-only.
|
||||
- **Not blocked.** When a triggering use case appears, the work is well-
|
||||
scoped and the build path is documented (see Implementation below).
|
||||
Deferral is reversible at any time.
|
||||
|
||||
### Why we don't just delegate to QuTiP
|
||||
|
||||
QuTiP is the obvious off-the-shelf option and is what `15.md` §6 originally
|
||||
proposed deferring to. Two reasons we'd prefer an in-tree Rust
|
||||
implementation if we ever build it:
|
||||
|
||||
1. **Determinism**. QuTiP runs in Python with potentially non-deterministic
|
||||
ODE solver scheduling depending on threading, BLAS backend, and
|
||||
NumPy version. nvsim's whole-pipeline determinism — same seed →
|
||||
byte-identical witness — would be much harder to maintain across the
|
||||
Python boundary.
|
||||
2. **CI integration**. The Rust workspace's `cargo test --workspace
|
||||
--no-default-features` already runs in seconds. Adding QuTiP would
|
||||
pull a Python dependency into CI and slow the gate.
|
||||
|
||||
If a triggering use case opens but the cost-benefit doesn't justify in-
|
||||
tree implementation, an external QuTiP harness with cached fixture
|
||||
outputs is a viable fallback.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- **No premature engineering.** 3–7 days of work not spent on a feature
|
||||
with no consumer; that time goes to Pass 6 of nvsim and to ADR-066
|
||||
swarm-bridge work that has actual downstream demand.
|
||||
- **Honest scope.** ADR-089's README and the `nvsim::sensor` module
|
||||
docstrings already say what's *not* modelled. ADR-090 is the
|
||||
formal accountability for that boundary.
|
||||
- **Reversible.** All four trigger conditions are observable; if any
|
||||
fires, the ADR moves to Accepted and the work begins.
|
||||
|
||||
### Negative / risks
|
||||
|
||||
- **Risk of premature commitment if triggers fire.** If pulsed-protocol
|
||||
use cases emerge late in the project (e.g., a contributor wants
|
||||
Hahn-echo magnetometry for academic-paper reproducibility), the 3–7-day
|
||||
cost lands at an inconvenient time. Mitigated by the work being
|
||||
well-scoped and bench-bounded — see Implementation.
|
||||
- **Documentation debt.** Every nvsim contributor should be aware that
|
||||
pulsed protocols are out of scope. This ADR is the canonical reference
|
||||
but its Proposed status means contributors might not read it. Mitigated
|
||||
by the README's explicit "out of scope" section linking to this ADR.
|
||||
|
||||
### Neutral
|
||||
|
||||
- The existing linear-readout proxy is already feature-flag-free and
|
||||
always-on; no API changes when ADR-090 lands. The Lindblad path is
|
||||
additive.
|
||||
|
||||
## Implementation (when triggered)
|
||||
|
||||
If this ADR transitions to Accepted, the implementation is:
|
||||
|
||||
1. **Add `lindblad` feature to `nvsim/Cargo.toml`** — opt-in, default-off.
|
||||
Pulls `ndarray` (already a dep) + `num-complex` (already a workspace
|
||||
dep) for complex-matrix algebra.
|
||||
2. **`src/lindblad.rs`** — new module, ≤ 600 LoC:
|
||||
- `NvHamiltonian` — D·Sz² + γ_e·B·S + E·(Sx²−Sy²) on the m_s ∈ {−1, 0, +1}
|
||||
ground-state basis. Optional ¹⁴N or ¹⁵N hyperfine extension.
|
||||
- `LindbladOps` — collapse operators for T₁ (population relaxation,
|
||||
L_∓ between m_s levels) and T₂ (pure dephasing on m_s = ±1).
|
||||
- `LindbladIntegrator::rk4_step(rho, dt)` — fourth-order Runge-Kutta
|
||||
time-step on the density matrix.
|
||||
- `Pulse` enum — supports CW, square, Gaussian-shaped MW pulses.
|
||||
3. **`src/lindblad_protocols.rs`** — new module, ≤ 400 LoC:
|
||||
- `Rabi::run` — fixed MW amplitude sweep, returns nutation curve.
|
||||
- `HahnEcho::run` — π/2 — τ — π — τ — π/2 detection sequence.
|
||||
- `Cpmg::run` — repeated π pulses for dynamical decoupling.
|
||||
4. **Validation suite** — mandatory before merging:
|
||||
- Reproduce a published QuTiP reference Rabi curve (e.g., from a
|
||||
Doherty 2013 supplementary script) within 1% per-bin error.
|
||||
- Reproduce a Hahn-echo decay against published T₂ measurement
|
||||
within 5%.
|
||||
- Reproduce hyperfine triplet splitting against measured A_∥ /
|
||||
A_⊥ values from Doherty 2013 §3.4.
|
||||
5. **Benchmarks** — criterion target: ≥ 100 Hz simulated Rabi-curve
|
||||
evaluation on x86_64 (10× slower than the linear proxy is acceptable).
|
||||
6. **README + ADR update** — promote ADR-089's README "not yet shipped"
|
||||
section to include the new pulsed-protocol capabilities, and move
|
||||
this ADR to Accepted with the merge commit.
|
||||
|
||||
Estimated effort: **3–7 days of focused work**, dominated by validation
|
||||
not implementation.
|
||||
|
||||
## Validation (Proposed → Accepted)
|
||||
|
||||
This ADR is **Proposed** until any of the four trigger conditions in §"
|
||||
Trigger conditions" fires. When that happens:
|
||||
|
||||
1. Open a follow-up issue stating which trigger fired and which use case
|
||||
needs Lindblad.
|
||||
2. The implementation §1–6 above defines the build.
|
||||
3. Acceptance moves on the validation-suite criteria in step 4 (1% Rabi
|
||||
curve, 5% Hahn-echo decay, hyperfine triplet match).
|
||||
4. Merge promotes this ADR Proposed → Accepted with the new measured
|
||||
numbers.
|
||||
|
||||
## Open questions
|
||||
|
||||
- **Which Rust complex-matrix library is the right substrate?** Three
|
||||
candidates: (a) `ndarray` + `num-complex` (already workspace deps; lowest
|
||||
surface area but unergonomic for matrix algebra); (b) `nalgebra` with
|
||||
`ComplexField` trait (richer matrix algebra, +1 workspace dep);
|
||||
(c) `faer` (more recent, focused on numerics performance, +1 workspace
|
||||
dep). Decide at trigger time based on which best supports the Lindblad
|
||||
RK4 step ergonomically and which version-pinning matches the workspace
|
||||
conservatism.
|
||||
- **Is hyperfine modelling in v1 or v2?** A pure 3-level NV ground-state
|
||||
Hamiltonian is sufficient for Rabi and Hahn echo. ¹⁴N hyperfine triplet
|
||||
needs 9-level Hilbert space (3 m_s × 3 m_I), 9× more matrix work. v1
|
||||
could ship with hyperfine off behind a sub-feature; v2 enables it.
|
||||
- **Should the Lindblad solver back-validate the linear proxy?** Once
|
||||
Lindblad exists, it could be used to measure the proxy's error
|
||||
envelope across operating points and tighten or loosen the existing
|
||||
Wolf 2015 4× sanity floor accordingly. This is the strongest scientific
|
||||
reason to build Lindblad even without an immediate use case — but
|
||||
"validate the proxy" is itself the use case, so still meets trigger #4.
|
||||
|
||||
## Related
|
||||
|
||||
- **ADR-089** — nvsim NV-diamond simulator. The crate this extension
|
||||
attaches to.
|
||||
- **ADR-018** — CSI binary frame format. Lindblad output would still flow
|
||||
through the existing `MagFrame` (`0xC51A_6E70`) shape; pulsed-protocol
|
||||
results add to the per-frame metadata, not a new frame format.
|
||||
- **ADR-028** — ESP32 capability audit. Lindblad is host-side only; ESP32
|
||||
firmware untouched.
|
||||
- **ADR-066** — Swarm bridge. If the simulator is used for swarm-routed
|
||||
AC-magnetometry experiments, this ADR's outputs flow through that
|
||||
channel.
|
||||
Loading…
Reference in New Issue