Deprecation ramp: align pecos-engines GeneralNoiseModel idle-noise API with the structured vocabulary

[ciaranra]

Goal

Align the idle-noise surface of GeneralNoiseModel / GeneralNoiseModelBuilder in
crates/pecos-engines (and its PyO3 fluent builder in
python/pecos-rslib/src/engine_builders.rs) with the structured idle-noise vocabulary
(PR #420 layer-1 families; #423 layer-2 channels) — via a staged deprecation ramp,
because this API has external users.

Ramp

1. Additive release: new structured setters (family-style or with_idle_channels(...))
   alongside the existing methods; nothing existing changes behavior.
2. Warning release: legacy idle methods emit deprecation warnings. Each warning must
   state the numerically equivalent new spelling, not just the new name — see units
   below.
3. Removal / major release: legacy methods removed or explicitly re-documented as
   low-level primitives, per what usage telemetry and downstream feedback allow.

Unit trap (the reason the ramp needs care)

The builder rescales its public inputs before they reach the runtime fields
(crates/pecos-engines/src/noise/general/builder.rs, ~line 1006): square-root scaling on
the quadratic rate, a p_idle_coherent_to_incoherent_factor * 0.5 adjustment on the
stochastic branch, and a cycles-to-radians conversion. The structured vocabulary matches
the runtime application semantics (general.rs), not these builder input units. A naive
"use p_idle_sin_squared instead of p_idle_quadratic_rate" migration would silently
change the physics; the conversion formulas must be documented and embedded in the
warnings.

Alignment notes

• The linear family maps cleanly: engines already uses rate + SingleQubitWeightedSampler
  over X/Y/Z/L — the same alphabet the structured models adopted (including first-class
  L).
• The p_idle_coherent: bool interpretation switch is replaced by law-in-the-name
  families / channel types.
• p_idle_coherent_to_incoherent_factor (default 1.5) is an engines-only calibration
  knob; it should get an explicit, documented identity rather than being folded silently
  into any migration.
• Related: Port the structured idle-noise families to the native-surface NoiseModel (twirl/threshold route) #422 (native-surface NoiseModel port), Layer-2 typed idle-channel vocabulary and EEG coherent-route alignment #423 (layer-2 vocabulary + EEG
  alignment). Same standing principle: one idle-noise vocabulary at every level of PECOS,
  capability and units enforced loudly, never silently approximated.

[ciaranra]

Concrete divergence found while renaming the noise-builder setters: after-two-qubit-gate idle noise.

The two sides both offer "idle noise around two-qubit gates" and express it incompatibly:

	DEM side	engines side
knob	with_idle_after_2q(duration) on the Guppy DEM builder	with_p2_idle(probability) on general_noise()
mechanism	inserts explicit Idle(duration) gates after every two-qubit gate; the idle-noise families then attach to those gates	applies the linear idle stochastic noise directly after every two-qubit gate
duration	caller's choice	hardcoded 1.0 at the application site (crates/pecos-engines/src/noise/general.rs, apply_idle_linear_stochastic_noise(self.p2_idle, 1.0, ...))
axis distribution	from the family model the caller sets	from p_idle_linear_model

So the DEM path separates where and how long (a circuit pass) from how noisy (the noise families), while engines fuses both into one probability with an implicit unit duration. Its field doc calls it a convenience — "this may be useful for memory sweeping" (general.rs:285-289).

Practical consequence: a user configuring "idle noise around two-qubit gates" writes a duration on one side and a probability on the other, and the numbers are not transferable without knowing the hidden 1.0. Any convergence needs to decide whether p2_idle becomes duration-aware, or is documented as the deliberate shorthand for duration = 1.

Related and still open on this issue: the simulator's p_idle_linear_rate is a family rate paired with p_idle_linear_model — semantically the DEM's p_idle_linear — while the DEM side also has a deprecated Z-only field literally named p_idle_linear_rate. That name collision is why every idle-rate setter was deliberately excluded from the probability-setter rename.

[ciaranra]

Traced both paths end to end and verified the arithmetic, so the conversion formulas this issue asks for can be written down concretely.

Verified formulas

Let S = scale, I = idle_scale, f = coherent_to_incoherent_factor (default 1.5), d = idle duration.

engines, linear: P(event) = R_lin * S * I * d, then one categorical Pauli sample from the normalized model.

engines, quadratic/sine (incoherent): the builder rescales the rate before the runtime sees it --
r = R_quad * sqrt(S*I) * (f/2) * 2*pi (general/builder.rs:1029-1038) -- and the runtime then computes
P(Z) = sin^2(r * d) (general.rs:893-920). With defaults this is P(Z) = sin^2(1.5 * pi * R_quad * d).

DEM, per axis: a_P = clamp(R*m_P*d + sin^2(S*n_P*d)), renormalized only if the axis total exceeds 1
(dem_builder/types.rs:3057-3100). No 2*pi, no 0.5, no f analogue.

So the sine-law conversion is: R_quad_engines = R_sin_squared_dem / (f/2 * 2*pi), i.e. divide by 1.5*pi at the default factor.

Worked example, DEM p_idle_sin_squared=0.03 at d=1: pass 0.03 / (1.5*pi) = 0.0063661977236758134 to
with_p_idle_quadratic_rate, and engines reproduces sin^2(0.03) exactly. This translation is now exercised
by the stage-4 snippet in docs/workflows/guppy-dem-decoding.md.

Divergence table

Quantity	engines	DEM
Sine rate unit	cycles/time (* 2*pi)	radians/time
Incoherent conversion	* f/2, default f=1.5	none
Coherent mode	p_idle_coherent: bool switches the same rate to an RZ	nonzero coherent family is rejected outright
Scaling	linear S*I; quadratic sqrt(S*I)	no analogue
Linear model dict	normalized distribution	normalized distribution (agree)
Sine model dict	does not exist -- incoherent quadratic is Z-only	unnormalized relative multipliers over X/Y/Z
Same-axis linear + sine	independent sequential draws; two Zs can cancel	summed into one axis probability before emission
Time unit	rate docs say seconds	TimeUnits; traced-QIS replay is nanoseconds

Three things worth adding to the ramp

1. engines has no sine model dictionary. Incoherent quadratic dephasing is hardcoded Z-only
   (general.rs:902-920), so a DEM p_idle_sin_squared_model with nonzero X or Y has no engines spelling at
   all. The ramp needs to add per-axis sine support, not just rename the rate.

2. The DEM vocabulary is internally inconsistent about its dictionaries -- the linear family requires a
   normalized distribution (require_normalized=True) while the sine family takes relative multipliers
   (require_normalized=False), both in _idle_noise.py. Whichever convention engines adopts, that
   asymmetry should be resolved first or it gets copied across.

3. engines idle noise is on by default: p_idle_linear_rate: 0.001 (general/default.rs:85, alongside
   p1: 0.001, p2: 0.01, p_prep: 0.01). A user translating a DEM configuration has to zero what they did
   not ask for. Worth an explicit note in the migration guidance.

Related: the same idle-treatment alignment was applied to pecos-engines and exp/pecos-neo in #420.