Stim and Sinter

Sinter interface for Maestro quantum circuit simulator.

This module provides MaestroSinterSampler and MaestroCompiledSampler, enabling integration between the Stim/Sinter QEC framework and Maestro’s tensor-network/GPU simulation engine.

class MaestroCompiledSampler(task: Task | Circuit | str, chi: int = 32, use_gpu: bool = False, noise_model: NoiseModel | None = None, device: str | None = None, config: SimulatorConfig | None = None, decoder: str | Decoder | None = None, seed: int | None = None, enable_checkpoint: bool = True, min_single_qubit_gates: int = 1, qubit_order: list[int] | tuple[int, ...] | None = None)

Compiled task sampler that executes shots on Maestro.

sample(suggested_shots: int = 1, shots: int | None = None, seed: int | None = None) → AnonTaskStats

Sample shots on Maestro and return Sinter task statistics.

sample_detection_events(shots: int = 1000, seed: int | None = None) → tuple[ndarray, ndarray]

Sample detection events and actual observables directly.

Parameters:

  • shots – Number of shots to sample.

  • seed – Optional random seed for simulation.

Returns:

A tuple of (detection_events, actual_observables) as boolean numpy arrays. detection_events shape: (shots, num_detectors) actual_observables shape: (shots, num_observables)

sample_measurements(shots: int = 1000, seed: int | None = None) → ndarray

Sample the raw measurement record.

Parameters:

  • shots – Number of shots to sample.

  • seed – Optional random seed for simulation.

Returns:

A boolean numpy array of shape (shots, num_measurements), with columns in Stim measurement-record order.

class MaestroSinterSampler(chi: int = 32, use_gpu: bool = False, noise_model: NoiseModel | None = None, device: str | None = None, config: SimulatorConfig | None = None, decoder: str | Decoder | None = None, seed: int | None = None, enable_checkpoint: bool = True, min_single_qubit_gates: int = 1, qubit_order: list[int] | tuple[int, ...] | None = None)

Sinter Sampler backed by Maestro’s simulation engine.

compiled_sampler_for_task(task: Task) → CompiledSampler

Create a compiled sampler configured for the given task.

class NonCliffordTaskCircuit(circuit_str: str)

Wrapper around a Stim-like circuit that supports non-Clifford gates for Sinter tasks.

compile_detector_sampler()
compile_m2d_converter() → stim.CompiledMeasurementTracker
detector_error_model(*args, **kwargs) → DetectorErrorModel
flattened()
property num_qubits: int
count_nontrivial_prefix_gates(circuit: Circuit | str | Any) → tuple[int, int]

Count non-trivial (two-qubit, single-qubit) operations in a prefix circuit.

Trivial operations include resets to |0> (R, RZ), coordinates (QUBIT_COORDS, SHIFT_COORDS), and ticks (TICK). Non-trivial operations include 2-qubit entangling gates and 1-qubit gates/rotations or non-Z basis resets (RX, RY).

Returns:

A tuple of (num_2q_gates, num_1q_gates).

counts_to_measurements(counts: dict[str, int], num_measurements: int, shots: int, *, storage_width: int | None = None) → ndarray

Strict Maestro bit order: character k is classical bit k.

split_stim_prefix_suffix(circuit: Circuit | str | Any, has_external_noise: bool = False) → tuple[Any, Any, int]

Split a Stim circuit into a deterministic prefix and suffix.

The prefix contains all deterministic operations prior to the first noise channel or stochastic measurement.

Parameters:

  • circuit – A stim.Circuit, circuit string, or wrapper object.

  • has_external_noise – Whether an external noise model applies to gates.

Returns:

A tuple of (prefix_circuit, suffix_circuit, cut_index).

translate_stim_to_maestro(circuit: Circuit | str | Any, *, qubit_order=None) → tuple[QuantumCircuit, NoiseModel, int]

Translate a Stim circuit or circuit string into a Maestro QuantumCircuit and NoiseModel.

Pauli noise channels (DEPOLARIZE1/2, X/Y/Z_ERROR, PAULI_CHANNEL_1/2) become QuantumCircuit.pauli_channel operations and measurement flip probabilities such as M(p) become readout errors, so the circuit carries Stim’s noise exactly. The basis changes inserted for RX, RY, MX, MY, MRX and MRY are marked noiseless, so a NoiseModel adds gate noise only where Stim has gates.

Parameters:

  • circuit – A stim.Circuit, extended gate string, or list of (name, arguments, integer targets) tuples. Correlated (E) and heralded noise, inverted measurements and record-controlled operations reject.

  • qubit_order – Optional complete qubit allocation order. Explicit order initializes these qubits to zero before the supplied instructions.

Returns:

A tuple of (QuantumCircuit, NoiseModel, num_measurements).

validate_shots(shots: int) → int

Validate that shots is a positive integer.