Maestro — Unified Quantum Circuit Simulation

Overview

Maestro is a high-performance C++ engine and Python SDK that provides a unified interface and intelligent orchestration layer for quantum circuit simulation. It abstracts the complexity of simulator configuration, enabling seamless execution across CPUs, NVIDIA GPUs, and distributed MPI environments.

• Version: 0.3.1
• License: GPL-3.0
• Organisation: Qoro Quantum

---

Key Features

Feature	Description
Unified Abstraction	Write circuits once (OpenQASM 2.0 / Python builder) and execute across any backend
Multi-Paradigm Simulation	Statevector, Matrix Product State (MPS), Clifford Stabilizer, Tensor Network, and Pauli Propagation
GPU Acceleration	NVIDIA cuStateVec and custom CUDA acceleration for statevector and tensor networks
Distributed HPC	MPI distributed statevectors via QuEST and composite p-block execution
Comprehensive Noise Suite	Analytical, Monte Carlo, CPTP quantum channels, thermal T1/T2, crosstalk, and coherent errors
Python & C++ APIs	Nanobind-based Python API and C++ header interface

---

Architecture

graph TD subgraph User["User Interface"] API["Python SDK (qoro-maestro) · C++ API (maestrolib) · CLI"] end subgraph Frontend["Circuit Layer"] QASM["OpenQASM 2.0 Parser"] IR["Circuit IR & Factory"] PE["Prediction & Analysis Engine"] end subgraph Backends["Simulation Engines"] CPU["CPU — SV · MPS · Stabilizer · TN · Pauli Prop"] GPU["GPU — cuStateVec · CUDA MPS · CUDA TN"] QUEST["QuEST — Distributed MPI Statevector"] COMP["Composite — p-block Distributed State"] end subgraph Noise["Noise Engine"] NM["NoiseModel & CPTP Channels"] MC["Monte Carlo & Analytical Evaluator"] end API --> QASM API --> IR QASM --> IR IR --> PE PE --> CPU PE --> GPU PE --> QUEST PE --> COMP IR --> Noise style User fill:#1a1a2e,stroke:#7c3aed,color:#e0e0e0 style Frontend fill:#16213e,stroke:#7c3aed,color:#e0e0e0 style Backends fill:#0f3460,stroke:#7c3aed,color:#e0e0e0 style Noise fill:#2d132c,stroke:#e94560,color:#fff style GPU fill:#533483,stroke:#e94560,color:#fff style QUEST fill:#1e5631,stroke:#4ecca3,color:#fff

---

Documentation Hub

Documentation Pillar	Description
Python User Guide	Full Python SDK guide, circuits, backends, algorithms, and reference
Noise Simulation Manual	Hardware-realistic noise models, thermal relaxation, and CPTP channels
C++ Developer Tutorial	Complete C++ workflow, memory management, and compilation
HPC & Hardware Acceleration	NVIDIA GPU cuStateVec setup and QuEST MPI cluster deployment
C++ API Reference	C++ module groups, class hierarchies, and structs

---

Quick Start

Python (3 Lines)

import maestro
result = maestro.simple_execute('OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0], q[1]; measure q -> c;', shots=1024)
print(result["counts"])  # {"00": ~512, "11": ~512}

C++ (maestrolib)

#include "maestrolib/Interface.h"
#include <iostream>
 
int main() {
    void* maestro = GetMaestroObject();
    unsigned long sim = CreateSimpleSimulator(2);
    const char* qasm = "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0], q[1]; measure q -> c;";
    char* result = SimpleExecute(sim, qasm, "{\"shots\": 1024}");
    std::cout << result << std::endl;
    FreeResult(result);
    DestroySimpleSimulator(sim);
}

---

Citation

If you use Maestro in your research, please cite:

@article{bertomeu2025maestro,
  title   = {Maestro: Intelligent Execution for Quantum Circuit Simulation},
  author  = {Bertomeu, Oriol and Ghayas, Hamzah and Roman, Adrian and DiAdamo, Stephen},
  organization = {Qoro Quantum},
  year    = {2025}
}

---

License

Maestro is licensed under the GNU General Public License v3.0.