Maestro: Unified Interface for Quantum Circuit Simulation

Introduction

Welcome to the Maestro documentation! Maestro is 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.

Getting Started

If you're new to Maestro, we recommend starting with:

• Installation Guide - How to build and install Maestro
• Tutorial - Usage examples and API overview

Key Features

Maestro addresses the fragmentation of the current simulator ecosystem by providing a single entry point to various simulation methods:

• Unified Abstraction Layer: Write your circuit once (e.g., in Qiskit) and Maestro compiles it to the native format of the target backend
• Intelligent Prediction Engine: Automatically analyzes circuit features (gate density, entanglement, locality) to predict and select the fastest simulation backend for your specific workload
• High-Performance Optimizations: Transparently applies multi-threading, multi-processing, and optimized state sampling to increase throughput
• GPU Acceleration: Integrated support for GPU-accelerated Statevector and custom Matrix Product State (MPS) execution
• Distributed Quantum Computing (DQC): Supports p-block simulation (Composite mode) to simulate distributed quantum networks and break the memory ceiling of monolithic simulations
• Backend-agnostic: Allows new simulators to be added easily

Architecture Overview

The Maestro pipeline consists of:

1. Circuit Ingestion - Qiskit/QASM input
2. Conversion - To Maestro's Intermediate Representation
3. Feature Extraction - Gate density, entanglement locality, structure
4. Prediction Engine - Runtime estimation and backend routing
5. Execution - On one of the supported backends:
   • CPU statevector
   • GPU statevector
   • CPU/GPU MPS
   • Tensor networks
   • Clifford/stabilizer
   • Composite p-block distributed simulation

API Overview

The documentation is organized into the following main modules:

• Circuits - Circuit representation and quantum gate operations
• Simulators - Simulator interfaces and implementations
• Network - Distributed quantum computing components
• TensorNetworks - Tensor network simulation methods
• Schedulers - Job scheduling and execution management
• Estimators - Runtime estimation and prediction
• Utils - Utility classes and helper functions

Python

Maestro includes high-performance Python bindings built with nanobind. These bindings allow you to leverage Maestro's orchestration and simulation capabilities directly from Python.

To install the Python bindings:

pip install .

Basic usage example:

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

For more details, see the Tutorial.

Simulation Backends

Maestro integrates or wraps the following simulators:

• CPU statevector (Qiskit Aer, QCSim, custom implementations)
• GPU statevector (NVIDIA cuStateVec)
• CPU MPS (multiple libraries)
• GPU MPS (custom CUDA implementation)
• Tensor network simulators
• Stabilizer/Clifford simulators
• p-block composite simulation for DQC

Each backend is accessed through a C++ adapter that maps Maestro's IR to the simulator's native API.

Automatic Backend Selection

Maestro includes a prediction engine that:

• Extracts structural features from the circuit
• Uses a regression model trained on benchmark data
• Estimates relative runtimes across all backends
• Selects the backend expected to run fastest on the current hardware

The model normalizes performance features to reduce hardware dependence and can be recalibrated on installation.

Quick Start

To build Maestro:

chmod +x build.sh
./build.sh

For detailed build instructions, see INSTALL.md.

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. You may copy, distribute, and modify this software under the terms of the GPL-3.0 license. A copy of the license text is available in the LICENSE file.