Skip to content

Rename NoiseModel to NoiseParameters with a fluent interface - #435

Closed
ciaranra wants to merge 1 commit into
guppy-dem-idle-docsfrom
noise-parameters-rename
Closed

Rename NoiseModel to NoiseParameters with a fluent interface#435
ciaranra wants to merge 1 commit into
guppy-dem-idle-docsfrom
noise-parameters-rename

Conversation

@ciaranra

@ciaranra ciaranra commented Aug 4, 2026

Copy link
Copy Markdown
Member

Summary

Renames the DEM-construction noise dataclass to NoiseParameters, lifts it to the
pecos top level, and gives it a fluent with_* interface in the shape of the
sim() noise builders. Closes #433.

Stacked on #420 — it depends on the shared idle-noise vocabulary introduced there.
Merge #420 first.

Why the rename

NoiseModel collided conceptually with the simulator-side noise models
(GeneralNoiseModel, DepolarizingNoiseModel), which are executable objects that apply
noise during simulation. This one is a parameter bag consumed at DEM construction, and
since #422 it is the shared idle-noise vocabulary for both the Guppy and native-surface
routes — so it was neither a "model" nor surface-code-specific.

  • NoiseParameters is the real name; NoiseModel remains as a deprecated alias
    resolving to the identical class, so no existing code breaks.
  • Exported from pecos top level, beside general_noise() / depolarizing_noise().
    Deliberately not placed in pecos.noise, which holds the legacy simulator error
    models (DepolarModel, XZModel, GatewiseModel); a modern DEM parameter class
    there would read as part of that old machinery.
  • Still importable from pecos.qec.surface.
  • 226 references updated across 29 existing files so only the alias path is deprecated,
    not everyday use.

Fluent interface

noise = (
    NoiseParameters()
    .with_p1(0.002)
    .with_p2(0.02)
    .with_p_idle_linear(0.01, {"X": 0.25, "Y": 0.25, "Z": 0.5})
    .with_p_idle_sin_squared(0.03, {"Z": 1.0})
)

Chained, immutable (every setter returns a new object via dataclasses.replace), and
with no terminal method — matching the sim noise builders, which are passed directly
into .noise(...). The dataclass constructor keeps working; the fluent form is additive.

One mechanical rule: with_<field_name>, no suffix translation. The simulator's
_probability / _rate suffixes were deliberately not mirrored: only four fields
(p1, p2, p_meas, p_prep) have simulator counterparts, so suffix-mirroring would
buy alignment on four methods while adding a translation layer to all thirty. It also
removes a hazard rather than documenting it — the simulator's with_p_idle_linear_rate
refers to what is our deprecated Z-only alias, not to the family scalar
p_idle_linear, so under the mechanical rule no false equivalence is expressible.

One deliberate exception, found by testing rather than by design: the idle families
take their rate and model together, as with_p_idle_linear(rate, model). Separate
setters are impossible in principle here — __post_init__ translates a family into the
canonical per-axis fields and then clears it, so a second call setting only the model
collides with the per-axis values the first call produced. A model without a rate is
inert and rejected anyway, so the two are inherently a pair. The first implementation
had split setters and raised ValueError on the natural usage
.with_p_idle_linear(0.01).with_p_idle_linear_model({"Z": 1.0}).

Verification

  • tests/qec: 1393 passed, 1 skipped, 1 xfailed — this suite exercises most of the
    renamed call sites and is the oracle that behavior did not change.
  • New tests/qec/surface/test_noise_parameters.py: 12 tests covering the equivalence
    oracle, immutability, the family round-trip through for_runtime_idle_time_units(),
    the deprecated alias, import paths, and the paired-setter rule.
  • Repo-wide lint clean on a cold run with .ruff_cache cleared.

@ciaranra ciaranra closed this Aug 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant