deltakit-maestro

Qoro Maestro simulator backend for Riverlane Deltakit QEC circuits.

A thin adapter over maestro.sinter. A Deltakit Circuit is converted to Stim with as_stim_circuit():

The result comes back as raw measurements, detection events, or Sinter statistics.

Every run is simulated by Maestro. With the default simulation_type=None the simulation type follows the noise:

backend.config_for(noise_type, **noise).simulation_type says which one a run uses. Pauli frames sample a Clifford circuit with Pauli noise as fast as Stim does; coherent over-rotations, which no Clifford simulator can run, need the matrix product state.

Install

Needs Python 3.10–3.13 (deltakit requires <3.14).

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install -e ".[examples]"     # examples extra adds pymatching

Verify:

python -c "from deltakit_maestro import MaestroBackend; print(MaestroBackend())"

Quick start

# Import deltakit before pymatching: the other way round, Deltakit's circuit builders fail.
from deltakit.circuit.gates import PauliBasis
from deltakit.explorer.codes import RotatedPlanarCode, css_code_memory_circuit
from deltakit.explorer.qpu import QPU, SI1000Noise
import sinter

from deltakit_maestro import MaestroBackend

code = RotatedPlanarCode(width=3, height=3)
circuit = css_code_memory_circuit(code, num_rounds=3, logical_basis=PauliBasis.Z)
noisy = QPU(circuit.qubits, noise_model=SI1000Noise(p=0.01)) \
            .compile_and_add_noise_to_circuit(circuit)

backend = MaestroBackend()   # Stabilizer for Pauli runs, MPS (χ=32) for coherent ones

# 1. Detection events straight from Maestro
sampler = backend.compile_sampler(noisy, seed=1)
dets, obs = sampler.sample_detection_events(1000)
# decode against sampler.task.detector_error_model

# 2. Sinter
stats = sinter.collect(
    num_workers=4,
    tasks=[backend.as_sinter_task(noisy, json_metadata={'p': 0.01})],
    custom_decoders=backend.sinter_decoders(decoder='pymatching'),
    max_shots=10_000,
)

# 3. Raw measurements (and detection events) in one call
result = backend.simulate(noisy, shots=1000)
result.measurements       # (1000, n_meas) uint8, Stim record order

# 4. Coherent noise, and its Pauli twirl to compare against
coherent = backend.simulate(noisy, shots=300, noise_type='coherent')
twirl = backend.simulate(backend.twirled_circuit(noisy, noise_type='coherent'), shots=100_000)

The guide covers each of these in depth: sampling and Sinter, the noise modes, the decoder's detector error model, and coherent noise with the bond dimension it needs.

Learn more

• Documentation:
  • Guide: sampling and Sinter, how each run is simulated, the noise modes and overrides, the decoder's detector error model, coherent noise and its calibration against SI1000, the MPS bond dimension, performance, and gotchas.
  • Examples: a notebook with plots of coherent noise on the d=3 surface code, and scripts for the noise modes, a plain Stim circuit, coherent noise on a repetition code, a surface code sweep, every Deltakit code family, and the bond dimension, each shown with its output.
  • API reference.
• Maestro docs.
• Changelog.
• Contributing: running the tests and building the docs.

License

GPL-3.0, like Maestro. See LICENSE.