Introduction

Maestro is a high-performance C++ library that provides a unified interface and intelligent orchestration layer for quantum circuit simulation. It automates the complexity of selecting and configuring simulators, enabling researchers and developers to execute quantum circuits efficiently across CPUs, GPUs, and distributed HPC environments — without manual tuning.

Version: 0.2.0.post1
License: GPL-3.0
Organisation: Qoro Quantum

Key Features

Feature	Description
Unified Abstraction	Write your circuit once (Qiskit / OpenQASM) and Maestro compiles it to the native format of the target backend
Prediction Engine	Automatically analyses circuit features (gate density, entanglement, locality) to predict and select the fastest backend
High-Performance	Multi-threading, multi-processing, and optimised state sampling to maximise throughput
GPU Acceleration	Integrated NVIDIA cuStateVec, custom MPS, tensor network, stabiliser, and Pauli propagator GPU kernels
Distributed QC	P-block composite simulation to break the memory ceiling of monolithic simulators
Extensible	New backends can be added by implementing a single C++ interface
Python Bindings	High-performance nanobind-based Python API

Architecture Overview

graph TD subgraph User["User Application"] API["C++ API · Python Bindings · CLI"] end subgraph Frontend["Circuit Frontend"] QASM["QASM / Qiskit"] IR["Circuit IR"] PE["Prediction Engine"] end subgraph Backends["Simulation Backends"] CPU["CPU — SV · MPS · Stabilizer · TN · Pauli Prop"] GPU["GPU — SV · MPS · TN · Pauli Prop"] QUEST["QuEST — Statevector · MPI"] COMP["Composite — p-block"] end subgraph Infra["Infrastructure"] SCHED["Scheduler"] NET["Network — DQC"] EST["Estimators"] end API --> QASM QASM --> IR IR --> PE PE --> CPU PE --> GPU PE --> QUEST PE --> COMP IR --> SCHED SCHED --> NET IR --> EST 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 Infra fill:#1a1a2e,stroke:#7c3aed,color:#e0e0e0 style GPU fill:#533483,stroke:#e94560,color:#fff style QUEST fill:#1e5631,stroke:#4ecca3,color:#fff

API Modules

The documentation is organised into the following thematic modules. Click on a module name to browse its classes, functions, and detailed documentation.

Module	Description
Core API	Core types, orchestration entry point, and library interface
Circuit Representation	Quantum circuit IR — gates, operations, measurements
Simulation Backends	Simulator interfaces and all backend implementations
Distributed Quantum Computing	Distributed quantum computing — hosts, controllers, topology
Tensor Network Simulation	Tensor network simulation and contraction strategies
Job Scheduling	Job scheduling and parallel execution
Runtime Estimation	Runtime estimation and automatic backend selection
OpenQASM Interop	OpenQASM 2.0 parsing and serialisation
Utilities	Thread pool, tensors, logging, and other utilities
Python Bindings	High-performance Python bindings
QuEST Backend	Dynamic QuEST CPU simulator with MPI support
GPU Backend	CUDA-accelerated simulation (closed-source)

Getting Started

Building from Source

git clone https://github.com/QoroQuantum/maestro.git
cd maestro
chmod +x build.sh
./build.sh

For detailed build options (GPU support, optional dependencies, etc.), see the Installation Guide.

C++ Example

#include "maestrolib/Interface.h"
 
int main() {
    // Define a simple Bell-state circuit in OpenQASM
    std::string qasm = R"(
        OPENQASM 2.0;
        include "qelib1.inc";
        qreg q[2];
        creg c[2];
        h q[0];
        cx q[0], q[1];
        measure q -> c;
    )";
 
    // Let Maestro choose the best backend and execute
    MaestroLibrary lib;
    lib.LoadCircuitFromQasm(qasm);
    auto results = lib.Execute(1024);
    // results now contains measurement counts
}

Python Example

import maestro
 
qasm = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
h q[0];
cx q[0], q[1];
"""
 
result = maestro.simple_execute(qasm, shots=1024)
print(f"Counts: {result['counts']}")

For a comprehensive walkthrough, see the Tutorial.

Simulation Backends

Maestro integrates or wraps the following simulation technologies:

Category	Technology	Notes
CPU Statevector	QCSim, Qiskit Aer	Full state-vector simulation
CPU MPS	QCSim, Qiskit Aer	Matrix Product State with configurable bond dimension
CPU Stabilizer	QCSim, Qiskit Aer	Efficient Clifford-only simulation
CPU Tensor Network	QCSim, Qiskit Aer	Tensor network contraction
CPU Pauli Propagator	QCSim	Pauli propagation simulation
CPU Extended Stabilizer	Qiskit Aer	Near-Clifford decomposition
GPU Statevector	NVIDIA cuStateVec	Via dynamic GPU library loading
GPU MPS	Custom CUDA	Custom GPU MPS implementation
GPU Tensor Network	Custom CUDA	Tensor network simulation on GPU
GPU Pauli Propagator	Custom CUDA	Pauli propagation simulation on GPU
QuEST	QuEST library	CPU statevector with MPI distribution
Composite	p-block	Distributed state across sub-simulators

Each backend is accessed through a C++ adapter implementing the Simulators::ISimulator interface.

QuEST Backend

Maestro supports the QuEST simulator as an alternative CPU backend. QuEST is loaded dynamically as a shared library (libmaestroquest), so it is available only when the library has been built and installed.

QuEST natively supports MPI-distributed statevector simulation, enabling execution across multiple nodes for larger qubit counts.

QuEST only supports Statevector simulation. Attempting to use it with MPS, Stabilizer, or other simulation types will raise an error.

Initialisation

#include "Simulators/Factory.h"
 
// Initialise QuEST (all platforms)
bool questReady = Simulators::SimulatorsFactory::InitQuestLibrary();
if (questReady)
    std::cout << "QuEST loaded successfully" << std::endl;

Running a Circuit with QuEST

#include "maestrolib/Interface.h"
#include "Simulators/Factory.h"
#include "Simulators/State.h"
 
void* maestro = GetMaestroObject();
Simulators::SimulatorsFactory::InitQuestLibrary();
 
unsigned long int simHandle = CreateSimpleSimulator(2);
 
// Switch to QuEST Statevector
RemoveAllOptimizationSimulatorsAndAdd(
    simHandle,
    static_cast<int>(Simulators::SimulatorType::kQuestSim),
    static_cast<int>(Simulators::SimulationType::kStatevector)
);
 
const char* qasm =
    "OPENQASM 2.0;\n"
    "include \"qelib1.inc\";\n"
    "qreg q[2]; creg c[2];\n"
    "h q[0]; cx q[0], q[1];\n"
    "measure q -> c;\n";
 
char* result = SimpleExecute(simHandle, qasm, "{\"shots\": 1024}");
// result JSON: {"counts": {"00": ~512, "11": ~512}, "simulator": "quest", ...}
 
FreeResult(result);
DestroySimpleSimulator(simHandle);

QuEST in Python

See the Python Guide for QuEST usage from Python, including maestro.init_quest() and maestro.is_quest_available().

GPU Backend

Note: The GPU backend is not included in the open-source version of Maestro. Contact Qoro Quantum for access.

Maestro supports GPU-accelerated simulation via a dynamically-loaded CUDA library (libmaestro_gpu_simulators). The GPU backend is optional and loaded at runtime only when requested.

Unlike QuEST, the GPU backend supports multiple simulation types:

SimulationType	GPU Support
`kStatevector`	✅
`kMatrixProductState`	✅
`kTensorNetwork`	✅
`kPauliPropagator`	✅
`kStabilizer`	❌
`kExtendedStabilizer`	❌

Initialisation

On Linux, GetMaestroObject() automatically attempts to load the GPU library. You can also initialise it explicitly:

#include "Simulators/Factory.h"
 
#ifdef __linux__
bool gpuReady = Simulators::SimulatorsFactory::InitGpuLibrary();
if (gpuReady)
    std::cout << "GPU library loaded" << std::endl;
#endif

Running a Circuit on GPU

#include "maestrolib/Interface.h"
#include "Simulators/State.h"
 
void* maestro = GetMaestroObject();
unsigned long int simHandle = CreateSimpleSimulator(2);
 
// Switch to GPU + Statevector
RemoveAllOptimizationSimulatorsAndAdd(
    simHandle,
    static_cast<int>(Simulators::SimulatorType::kGpuSim),
    static_cast<int>(Simulators::SimulationType::kStatevector)
);
 
const char* qasm =
    "OPENQASM 2.0;\n"
    "include \"qelib1.inc\";\n"
    "qreg q[2]; creg c[2];\n"
    "h q[0]; cx q[0], q[1];\n"
    "measure q -> c;\n";
 
char* result = SimpleExecute(simHandle, qasm, "{\"shots\": 1024}");
// result JSON: {"counts": {...}, "simulator": "gpu_simulator", ...}
 
FreeResult(result);
DestroySimpleSimulator(simHandle);

GPU MPS Example

// Switch to GPU + MPS
RemoveAllOptimizationSimulatorsAndAdd(
    simHandle,
    static_cast<int>(Simulators::SimulatorType::kGpuSim),
    static_cast<int>(Simulators::SimulationType::kMatrixProductState)
);
 
char* result = SimpleExecute(simHandle, qasm, "{\"shots\": 1024}");

GPU in Python

See the Python Guide for GPU usage from Python, including maestro.init_gpu() and maestro.is_gpu_available().

Automatic Backend Selection

Note: Automatic Backend Selection is a closed-source feature and is not included in the open-source release of Maestro. Contact Qoro Quantum for access.

Maestro's prediction engine:

Extracts structural features from the circuit (gate density, entanglement locality, circuit width/depth)
Uses a regression model trained on benchmark data
Estimates relative runtimes across all available backends
Selects the backend expected to be fastest on the current hardware

The model normalises performance features to reduce hardware dependence and can be recalibrated at installation time.

See also: Runtime Estimation

Additional Resources

Page	Description
Python Guide	Comprehensive Python API reference and examples
Installation	Build instructions and optional dependency setup
Tutorial	Step-by-step API usage guide
Contributing	How to contribute to Maestro
Code of Conduct	Community guidelines

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

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for the full text.

Table of Contents

Introduction

Key Features

Architecture Overview

API Modules

Getting Started

Building from Source

C++ Example

Python Example

Simulation Backends

QuEST Backend

Initialisation

Running a Circuit with QuEST

QuEST in Python

GPU Backend

Initialisation

Running a Circuit on GPU

GPU MPS Example

GPU in Python

Automatic Backend Selection

Additional Resources

Citation

License