Idle-gate passes and fail-loud idle-noise guard for the Guppy DEM pipeline

[ciaranra]

Summary

Gives the Guppy-to-DEM pipeline first-class idle-gate handling and documents the full
workflow from a Guppy QEC program to decoded logical error counts.

API (pecos.qec.dem)

Both DetectorErrorModel.from_guppy and build_dem_from_guppy gain two keyword-only
pass parameters, applied to the traced circuit after normalization and before metadata
attachment:

• strip_traced_idles=True removes identity-like gates (I, Idle, zero-angle
  rotations) from the trace.
• idle_after_2q_duration=<positive float> inserts an Idle of that duration on both
  qubits after every two-qubit gate. Stripping runs before insertion when both are set.
  Non-finite or non-positive durations are rejected.

New fail-loud guard: supplying any idle-noise parameter (p_idle, t1/t2, or the
p_idle_*_rate family) while the final traced circuit contains no Idle gates now
raises ValueError instead of silently building a DEM without the requested idle noise.
The default Selene runtime emits no idle gates, so this closes a silent no-op that
previously made those parameters inert. No in-repo caller passes idle-noise parameters
to these entry points, so no existing usage breaks.

Both passes reuse the existing Rust TickCircuit passes (remove_identity,
insert_idle_after_two_qubit_gates); no Rust changes.

Docs

docs/user-guide/dem-from-guppy.md gains three sections, every code block an
executable generated doc test:

• Idle Noise — the strip/insert passes, the guard, and time-unit semantics
  (runtime idles are nanosecond TimeUnits; linear/sine rates scale per time unit,
  quadratic rates per time unit squared).
• Exporting the DEM as Stim Text — to_string() is directly Stim-parsable;
  to_string_decomposed() (source-attached, hyperedge-preserving) vs
  to_string_terminal_graphlike_decomposed() (lossy edge projection for graph
  matchers), each parse-checked against stim as the format oracle.
• Decoding: PyMatching, Tesseract, and BP-OSD — one sampled batch through
  SampleBatch.decode_count(...) for all three decoders, plus direct per-shot
  construction via TesseractDecoder.from_dem and
  DemAwareDecoder.from_dem(..., decoder_type="bp_osd"). The direct Tesseract example
  uses preset="fast" to match the decode_count configuration.

docs/user-guide/decoders.md: the Python decoder table now reflects the actual
pecos.decoders re-exports instead of the stale MWPM2D/DummyDecoder-only list.

Tests

• Oracle test: from_guppy(..., idle_after_2q_duration=...) is byte-identical to the
  manual trace -> normalize -> insert-idle -> from_circuit pipeline.
• The guard is mutation-tested across all 15 idle-noise parameters on both entry
  points, plus non-positive/NaN/inf duration rejection.
• Strip mechanism is pinned by a runtime-emitted-idle trace whose idles disappear
  under strip_traced_idles=True (guard then fires), paired with the accept case.
• result_tags coexistence with idle insertion is pinned byte-identical to the
  records form.

Verification

• pytest on test_from_guppy_dem.py, test_from_guppy_result_tags.py,
  test_guppy_dem_build.py, and the regenerated user-guide doc tests: 310 passed (including the Pauli-twirl handoff suite),
  1 xfailed (6 expected DeprecationWarnings from the exercised legacy aliases).
• just lint over the whole repo: clean.

Structured idle-noise interface (three rate+model families)

Engines-consistent structured knobs on both entry points. The unifying
concept: model values are relative rates — per-axis multipliers on the
family rate (r_axis = rate * m_axis); the familiar relative-probability
reading is the special case that holds exactly when the law is linear.

• p_idle_linear + p_idle_linear_model — stochastic, p = rate*m*t.
  Default model uniform {X: 1/3, Y: 1/3, Z: 1/3}, sum-to-1 required (it is
  the engines distribution); scalar alone = total depolarizing rate. The
  engines leakage key "L" is reserved and rejected (DEM cannot represent
  leakage).
• p_idle_sin_squared + p_idle_sin_squared_model — stochastic sine-law
  dephasing, p = sin(rate*m*t)^2. Default model {Z: 1.0} (scalar alone =
  Z dephasing at full rate, the engines stochastic branch); multipliers
  unconstrained in sum.
• p_idle_coherent + p_idle_coherent_model — coherent rotations,
  angle = rate*m*t. Default model {RZ: 1.0}; keys RX/RY/RZ with "U"
  reserved. DEM v1 represents RZ only (stored as its exact Pauli twirl,
  sin(rate/2)^2 per unit idle time via an equivalent T2 — coherent
  cross-location accumulation is the EEG pipeline's domain); nonzero RX/RY
  fail loud.
• The p_idle shorthand is removed from these two entry points (explicit
  p_idle_linear only); the low-level Rust from_circuit keeps its
  primitive p_idle.
• Combinations the Rust NoiseConfig would silently clobber fail loud:
  p_idle_coherent with p_idle or t1/t2 (set_idle_rz replaces
  them), and p_idle with t1/t2 (the T1/T2 channel shadows the
  depolarizing base channel).
• The bare Z-only aliases p_idle_linear_rate, p_idle_quadratic_rate, and
  p_idle_quadratic_sine_rate are deprecated with explicit replacements;
  ambiguous structured + low-level combinations fail loud.
• These parameters match the engines runtime application semantics; the
  GeneralNoiseModelBuilder additionally rescales its public inputs, so
  builder inputs are not directly interchangeable.

Consistency follow-ups filed

The twirl/native-surface route and lower layers are aligned in follow-up issues rather
than this PR: #422 (native-surface NoiseModel port), #423 (layer-2 idle-channel
vocabulary + EEG alignment), #424 (engines GeneralNoiseModel deprecation ramp), #425
(non-idle GeneralNoiseModel surfaces), #426 (bug: from_circuit silently ignores or
overwrites combined idle parameters — the Python-level guards added here are the model
for the binding-level fix). In-repo twirl coherence fixes included here: the Pauli-twirl
handoff test now uses the explicit per-axis names, and a misleading idle-insertion
comment in examples/surface/validate_dem_generators.py is corrected.

Workflow guide (seeds the #414 structure)

docs/workflows/guppy-dem-decoding.md — the first task-oriented workflow page
(new "Workflows" nav section, direction of #414 without migrating existing
pages). It walks one story in five stages, each its own code block: define the
code in Guppy (a hand-written three-qubit repetition-code memory, chosen over
the surface-code generator so the Guppy program stays in view), define typed
detectors and observables with result_ref, generate the DEM with a custom
Z-biased linear idle distribution plus Z-only sine-law dephasing, sample it two
ways, and decode.

Stage 4 shows both sampling paths: dem.to_sampler() for error-model sampling,
and executing the program under sim(...) with build.evaluate_result_columns()
mapping the run's tagged result columns into a SampleBatch. The page is
explicit that the two paths carry different noise (the default Selene runtime
emits no idle gates), so they are not a like-for-like comparison.

Supporting fix: <!--continuation--> was documented in
scripts/docs/generate_doc_tests.py but parsed into a field that was never
read, so multi-block narratives silently generated broken tests. It now
accumulates the preceding visible blocks in the chain. The five decorative
markers in docs/user-guide/fault-catalog.md (whose blocks are self-contained
via <!--setup-->) were removed, keeping that page's behavior unchanged.
mkdocs build --strict is clean; a stale pre-existing proposals/README.md nav
entry was removed.

Typed-spec ergonomics

Detector and Observable now accept a bare tag string as shorthand for
result_ref(tag), so Detector("s0_r0", "s0_r1") replaces
Detector(result_ref("s0_r0"), result_ref("s0_r1")). Strings previously raised
TypeError in that position, so the change is purely additive; rec[-k] and
the explicit result_ref(..., occurrence=...) form are unchanged and can be
mixed freely in one call. Mistyped tags already fail loudly
(ValueError: result_ref 's0_typo' is absent from the compiled Guppy program),
which is the matching check that makes the plain-string spelling safe.

Defect fixes folded in (issues closed by this PR)

Reviewing this work surfaced real bugs; they are fixed here rather than deferred.

• from_circuit silently ignores or overwrites idle-noise parameters when p_idle, t1/t2, and idle_rz are combined #426 (critical) — from_circuit silently resolved conflicting idle
  parameters. set_t1_t2 makes T1/T2 the base channel that shadows p_idle,
  and set_idle_rz zeroes p_idle and overwrites T1/T2. The guard now lives in
  apply_noise_options, the shared helper behind DetectorErrorModel.from_circuit,
  DemBuilder.with_noise, DemSampler.from_circuit, DemSampler.with_detectors,
  and DemSamplerBuilder.with_noise, so every ingest path is covered.
  Verified by mutation: with the guard removed and the extension rebuilt,
  p_idle=0.4 alongside t1/t2 produced a DEM byte-identical to t1/t2
  alone — the requested rate silently discarded — and the mutation failed exactly
  the two tests that target that guard.
• DemAwareDecoder silently wraps observable bits past 64 (no width guard) #430 (critical) — DemAwareDecoder wrapped observable bits past 64. It had
  no width guard and packed with 1 << i into a u64, so observable 70 set bit 6
  in release builds. It now uses the wide ObsMask path and returns an
  arbitrary-precision Python integer; masks that fit in 64 bits are unchanged.
• Decoder surface defects: same-named decode() with different encodings, missing re-export, stale stub, drifted registry #431 (high) — decoder surface defects. FusionBlossomDecoder.from_dem
  exposed (the Rust method existed but was unreachable), DemAwareResult
  re-exported, the stale .pyi stub refreshed, and the two decoder registries
  reconciled — including making perturbed delegate to its inner decoder, since
  perturbed:inner=TYPE wraps an arbitrary decoder and a fixed classification is
  wrong for half its uses.
• Port the structured idle-noise families to the native-surface NoiseModel (twirl/threshold route) #422 — the idle-noise vocabulary fork closed. The translator moved to a
  shared pecos/qec/_idle_noise.py, and the native-surface NoiseModel now
  accepts the same three families as the Guppy entry points, so the twirl and
  threshold routes inherit the same conflicts, deprecations, and validation.

Semantics characterization

tests/qec/test_record_vs_meas_id_semantics.py pins that records[-k] and
meas_ids name the same measurement on every fixture available, using the
builder's redundancy rule as the oracle. A two-arm design review had reported
these as divergent coordinate systems; that claim was derived rather than
executed and does not reproduce. The test includes a negative case so it cannot
pass vacuously, and it fails loudly if a future reordering runtime separates them.

Verification (final)

• tests/qec plus the full generated doc-test suite: 1585 passed, 11
  skipped, 1 xfailed, 2 failed — both failures pre-existing and unrelated
  (qec-guppy transversal-CNOT blocks hit a HUGR execution stall; reproduced
  with and without this branch's changes and filed as Doc tests for qec-guppy transversal-CNOT examples fail with a HUGR execution stall #427).
• mkdocs build --strict: clean.
• Repo-wide lint: clean on a cold run with .ruff_cache cleared. Note that
  just lint ends with a Go formatting step, so its exit status does not reflect
  the Python hooks; these runs were verified by hook output text.

Consistency follow-ups filed

The twirl/native-surface route and lower layers are aligned in follow-up issues
rather than this PR: #422 (native-surface NoiseModel port), #423 (layer-2
idle-channel vocabulary + EEG alignment), #424 (engines GeneralNoiseModel
deprecation ramp), #425 (non-idle GeneralNoiseModel surfaces), #426 (bug:
from_circuit silently ignores or overwrites combined idle parameters — the
Python-level guards added here are the model for the binding-level fix), #427
(pre-existing qec-guppy doc-test stall). In-repo twirl coherence fixes included
here: the Pauli-twirl handoff test now uses the explicit per-axis names, and a
misleading idle-insertion comment in examples/surface/validate_dem_generators.py
is corrected.

[ciaranra]

We should have a BpOsdDecoder or a LdpcDecoder...

[ciaranra]

We should think about having a nice convenience function for each of these decoders that looks nice/same name...

[ciaranra]

What is the 1?

[ciaranra]

do the general_noise().with_idle_after_2q(...) ignore other idles by default like the DEM builder does... should we have and option to not ignore other idles?