---

name: noise-experiments description: "Construct and validate PyQuil noise channels, readout corrections, Pauli observables, and experiment settings while keeping model construction separate from backend execution." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Noise experiments

Use this sub-skill when the task involves any of the following:

• Kraus gate noise, assignment/readout matrices, decoherence, or noise pragmas.
• PauliTerm/PauliSum algebra, grouping, exponentiation, or observable bases.
• ExperimentSetting, Experiment, calibration, readout symmetrization, or ExperimentResult interpretation.
• Preparing an experiment for a QuantumComputer without claiming that a QVM, QPU, QCS, or other service was reached.

Route before acting

• Constructing or inspecting a Program, gates, declarations, measurements, or Quil text belongs in program-authoring.
• Compiling, submitting jobs, configuring QVM/QPU/QCS clients, or consuming raw QAM results belongs in compile-execute.
• Statevector/density-matrix simulation and numerical simulator internals belong in simulation.
• Processor topology and ISA construction belongs in processor-isa.

Read noise-models.md for API selection, shapes, channel formulas, and the legacy/new boundary. Read pauli-and-experiment-api.md for exact object contracts. Read workflows.md before composing a model or experiment. Use troubleshooting.md when a validation or execution boundary fails.

Core operating rules

1. Treat pyquil.noise.KrausModel and pyquil.noise.NoiseModel as the supported public, legacy Kraus/QVM surface in 4.18.0. A model contains definitions; it is not evidence that any backend executed them.
2. Build a map with square complex operators. For n qubits each operator is (2**n, 2**n) and a trace-preserving map satisfies sum(K.conj().T @ K) = eye(2**n). Check this before attaching pragmas.
3. tensor_kraus_maps(k1, k2) combines independent maps on different qubits; combine_kraus_maps(k1, k2) composes maps on the same qubits with k2 first and k1 second. append_kraus_to_gate post-multiplies a gate by each Kraus operator (K @ U).
4. apply_noise_model(program, model) returns a new transformed Program with definitions and PRAGMA ADD-KRAUS/READOUT-POVM headers. Inspect its Quil; do not call this transformation a run or a physical calibration.
5. Keep the two legacy readout representations distinct. A READOUT-POVM/estimate_assignment_probs conditional matrix is laid out as [[p00, 1-p11], [1-p00, p11]] (observed rows, prepared columns), while the legacy NoiseModel.assignment_probs produced by decoherence helpers stores [[p00, 1-p00], [1-p11, p11]] and the header reconstructs the POVM from its diagonals. The probability tensor has one length-2 axis per measured bit in the same order as the shot columns.
6. Pauli coefficients used for measured expectations must be real. Bits map to eigenvalues as 0 -> +1 and 1 -> -1; an n-bit joint expectation is the product over selected columns.
7. Experiment defaults to exhaustive symmetrization and plus-eigenstate calibration. These increase backend work. Explicitly choose shots, the symmetrization level, and calibration policy for reproducibility.
8. In 4.18.0 QuantumComputer.run_experiment compiles and executes through its configured backend and rejects grouped settings (len(settings) > 1). pyquil.operator_estimation.measure_observables remains importable and can process grouped settings, but still needs a usable QuantumComputer and backend. Stop at the service boundary if those are unavailable.

Minimal local validation

For a service-free smoke check, run the bundled helper when you need to validate Kraus completeness, readout tensor correction, and transformed Quil:

python scripts/noise_model_smoke.py --help
python scripts/noise_model_smoke.py

The helper uses tiny deterministic arrays and a two-qubit Program; it never starts a service, reads credentials, compiles, submits, or downloads anything. Its successful output proves construction/transformation only. For a detailed manual workflow, use workflows.md.

Handoff checklist

Before handing an operating plan to another agent, record:

• model family (legacy public Kraus versus private/new quax channel), channel dimensions, completeness/CP-TP checks, and qubit/operand ordering;
• supported gate/parameter matches and whether noise was applied once or twice;
• which legacy readout representation is in use (internal NoiseModel.assignment_probs versus POVM/calibration matrix), axis/qubit ordering, correction conditioning, shot count, and any negative or out-of-range corrected probabilities;
• Pauli settings, grouping method, compatible preparation/measurement bases, symmetrization level and trial expansion, calibration denominator, and result uncertainty;
• exact next execution owner and missing QVM/QPU/QCS/compiler credentials or services. Never report a constructed model or generated Program as an executed experiment.