qoro-maestro 0.2.0

Python bindings for Maestro - A unified interface for quantum circuit simulation

Maestro: The Interface to Quantum Circuit Simulation

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.

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.
• Expectation Value Estimation: Direct calculation of observables (e.g., Pauli strings) for VQA workflows.
• 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)
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, MPS, Pauli propagation, Clifford/stabilizer
   • GPU: statevector, MPS, Pauli propagation, tensor network simulation, (limited) Clifford/stabilizer
   • Composite p-block distributed simulation

Simulation Backends

Maestro integrates or wraps the following:

CPU Backends

• Statevector (Qiskit Aer, QCSim, custom implementations)
• MPS (multiple libraries)
• Pauli propagation
• Clifford/stabilizer simulators

GPU Backends

• Statevector (NVIDIA cuStateVec)
• MPS (custom CUDA implementation)
• Tensor network simulation
• Pauli propagation
• (Limited) Clifford/stabilizer

Distributed Simulation

• 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.

Documentation

• Installation Guide: Detailed build and installation instructions.
• Tutorial: Usage examples and API overview, including Python bindings.
• Python Examples: Python scripts demonstrating usage.

API Documentation

To generate the API documentation using Doxygen:

# Ensure Doxygen is installed
cd build
cmake ..
make doc

The documentation will be generated in docs/html/index.html.

Building Maestro

Quick start:

chmod +x build.sh
./build.sh

For detailed instructions, see INSTALL.md.

Citation

An Article detailing Maestro will be published shorty. This reference can be used for citation.

@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 and at:

https://www.gnu.org/licenses/gpl-3.0.en.html