Skip to content

Experiment mitigation API

Module: scpn_quantum_control.hardware.experiment_mitigation

The module exposes six orchestration functions. Each requires an existing HardwareRunner and returns a dictionary. Importing the module has no provider or filesystem side effect.

kuramoto_4osc_zne_experiment

kuramoto_4osc_zne_experiment(
    runner: HardwareRunner,
    shots: int = 10000,
    dt: float = 0.1,
    scales: list[int] | None = None,
) -> dict[str, Any]

Uses default scales [1, 3, 5] when scales is None. Returns the scales, per-scale order parameters and standard deviations, linear zero-noise estimate, classical reference, and fit residual.

noise_baseline_experiment

noise_baseline_experiment(
    runner: HardwareRunner,
    shots: int = 10000,
) -> dict[str, Any]

Runs the fixed four-qubit near-identity baseline. Returns measured/classical order parameters and X/Y/Z expectation vectors. Requests a runner-managed save to noise_baseline.json.

kuramoto_8osc_zne_experiment

kuramoto_8osc_zne_experiment(
    runner: HardwareRunner,
    shots: int = 10000,
    dt: float = 0.1,
    scales: list[int] | None = None,
) -> dict[str, Any]

Uses the same scale and extrapolation contract as the four-oscillator workflow with an eight-oscillator circuit and an explicit n_oscillators field.

upde_16_dd_experiment

upde_16_dd_experiment(
    runner: HardwareRunner,
    shots: int = 20000,
    trotter_steps: int = 1,
) -> dict[str, Any]

Submits raw and dynamical-decoupling X/Y/Z batches. Returns both measured order parameters, the classical reference, and decoupled expectation vectors. Requests a runner-managed save to upde_16_dd.json.

zne_higher_order_experiment

zne_higher_order_experiment(
    runner: HardwareRunner,
    shots: int = 10000,
    dt: float = 0.1,
    scales: list[int] | None = None,
    poly_order: int = 2,
) -> dict[str, Any]

Uses default scales [1, 3, 5, 7, 9] and reports a named extrapolation record for each order from one through poly_order.

decoherence_scaling_experiment

decoherence_scaling_experiment(
    runner: HardwareRunner,
    shots: int = 10000,
    qubit_counts: list[int] | None = None,
) -> dict[str, Any]

Uses default qubit counts [2, 4, 6, 8, 10, 12]. Returns per-count depth and measured/classical order parameters plus the fitted decay coefficient and coefficient of determination. Fewer than two positive ratios return NaN for both fit metrics.

Full autodoc

ZNE, dynamical decoupling, and noise characterisation experiments.

kuramoto_4osc_zne_experiment(runner, shots=10000, dt=0.1, scales=None)

4-oscillator Kuramoto with ZNE error mitigation.

Runs the evolution at multiple noise scales via unitary folding, then extrapolates to zero noise.

Returns

dict with keys:
    experiment (str): Experiment name identifier.
    scales (list[int]): Noise scale factors used.
    R_per_scale (list[float]): Measured R at each scale.
    zne_R (float): Zero-noise extrapolated R.
    classical_R (float): Exact order parameter.
    fit_residual (float): Polynomial fit residual.

noise_baseline_experiment(runner, shots=10000)

4-qubit near-identity circuit for calibration drift detection.

Single Trotter step at dt=0.01 (near-identity). Measures R + per-qubit expectations. Compare Feb->Mar to detect backend drift.

Returns

dict with keys:
    experiment (str): Experiment name identifier.
    n_qubits (int): Number of qubits.
    dt (float): Time step size (0.01, near-identity).
    hw_R (float): Hardware order parameter.
    hw_R_std (float): Shot-noise std of R.
    classical_R (float): Exact order parameter.
    classical_R_std (float): Always 0.0 (exact).
    hw_exp_x (list[float]): Per-qubit X expectations.
    hw_exp_y (list[float]): Per-qubit Y expectations.
    hw_exp_z (list[float]): Per-qubit Z expectations.

kuramoto_8osc_zne_experiment(runner, shots=10000, dt=0.1, scales=None)

8-oscillator Kuramoto with ZNE error mitigation.

Gate-fold at each noise scale, Richardson extrapolation to zero noise. Extends the 4-osc ZNE result to depth-233 territory.

Returns

dict with keys:
    experiment (str): Experiment name identifier.
    n_oscillators (int): Number of oscillators.
    scales (list[int]): Noise scale factors used.
    R_per_scale (list[float]): Measured R at each scale.
    zne_R (float): Zero-noise extrapolated R.
    classical_R (float): Exact order parameter.
    fit_residual (float): Polynomial fit residual.

upde_16_dd_experiment(runner, shots=20000, trotter_steps=1)

16-layer UPDE with dynamical decoupling.

Same structure as upde_16_snapshot but applies DD (XY4) to each basis circuit before submission. Compares R(DD) vs R(no-DD) vs classical.

Returns

dict with keys:
    experiment (str): Experiment name identifier.
    n_layers (int): Number of UPDE layers (16).
    dt (float): Time step size.
    trotter_steps (int): Number of Trotter repetitions.
    hw_R_raw (float): Hardware R without DD.
    hw_R_dd (float): Hardware R with dynamical decoupling.
    classical_R (float): Exact order parameter.
    hw_exp_x_dd (list[float]): Per-qubit X expectations (DD).
    hw_exp_y_dd (list[float]): Per-qubit Y expectations (DD).
    hw_exp_z_dd (list[float]): Per-qubit Z expectations (DD).

zne_higher_order_experiment(runner, shots=10000, dt=0.1, scales=None, poly_order=2)

ZNE with extended noise scales and higher-order polynomial extrapolation.

Default: scales=[1,3,5,7,9], quadratic fit. Tests whether 5-point polynomial extrapolation recovers more signal than the 3-point linear version (kuramoto_4osc_zne).

Science: systematic ZNE study -- linear vs quadratic vs cubic on the same data. Determines optimal extrapolation order for XY evolution on Heron r2.

Returns

dict with keys:
    experiment (str): Experiment name identifier.
    scales (list[int]): Noise scale factors used.
    R_per_scale (list[float]): Measured R at each scale.
    extrapolations (dict): Per-order dicts with zne_R, fit_residual.
    classical_R (float): Exact order parameter.

decoherence_scaling_experiment(runner, shots=10000, qubit_counts=None)

Systematic decoherence scaling: R vs circuit depth across qubit counts.

Runs 1-Trotter-step evolution at fixed dt=0.1 for each qubit count, records depth, R, and exact R. Provides data for fitting R_hw = R_exact * exp(-gamma * depth).

Science: extracts per-gate depolarization rate gamma from a single calibration run. Enables predictive modelling of experiment fidelity.

Returns

dict with keys:
    experiment (str): Experiment name identifier.
    dt (float): Time step size.
    data_points (list[dict]): Per-qubit-count dicts with n_qubits,
        depth, hw_R, classical_R.
    fit_gamma (float): Fitted per-gate depolarization rate.
    fit_r_squared (float): R-squared of exponential fit.