Python User Guide

Overview

Maestro ships high-performance Python bindings built with nanobind. The bindings expose the full simulation pipeline — circuit construction, backend selection, high-performance execution, expectation-value estimation, and hardware-realistic noise modeling — in an ergonomic, Pythonic API.

---

Table of Contents

The Python documentation is structured into the following focused guides:

Guide	Description
Getting Started & Configuration	Installation, SimulatorConfig options, and one-line execution
QuantumCircuit Builder	Programmatic circuit construction, gate set, and measurements
Simulation Backends	Statevector, MPS, Stabilizer, Tensor Networks, and tuning knobs
Algorithms & Observables	Expectation values, mirror fidelity, inner products, and time evolution
Noise Simulation Manual	Analytical, Monte Carlo, CPTP channels, thermal T1/T2, and correlated noise
Sinter Integration (QEC Sampling)	Stim / Sinter interface with MaestroCompiledSampler and MaestroSinterSampler
HPC Acceleration (GPU & QuEST)	NVIDIA cuStateVec GPU acceleration and QuEST MPI distributed simulation
Python API Reference	Enumerations (SimulatorType, SimulationType) and module functions

---

30-Second Quick Start

import maestro
from maestro.circuits import QuantumCircuit
 
# 1. Build a Bell State
qc = QuantumCircuit()
qc.h(0)
qc.cx(0, 1)
qc.measure_all()
 
# 2. Execute on default backend (QCSim Statevector)
result = qc.execute(shots=1024)
print("Measurement counts:", result["counts"])  # {"00": ~512, "11": ~512}
 
# 3. Compute expectation values of Pauli observables directly
estimate = qc.estimate(observables=["ZZ", "XX", "YY"])
print("Expectation values:", estimate["expectation_values"])  # [1.0, 1.0, -1.0]

Explore the subpages above for detailed tutorials and reference guides for each feature area.