Maestro
A unified interface for quantum circuit simulation. Write your circuit once — Maestro picks the best backend and runs it on CPU, GPU, or distributed HPC.
Features
- One API, many backends — compile from Qiskit / QASM to any supported simulator
- Automatic backend selection — a prediction engine analyzes your circuit and routes it to the fastest backend
- CPU simulation — statevector, MPS, MPO, Pauli propagation, path integral, Clifford/stabilizer, extended stabilizer, density matrix
- GPU acceleration — statevector (cuStateVec), MPS (custom CUDA and cuTensorNet), MPO (cuTensorNet, cuBlas and custrom CUDA) tensor network (cuTensorNet), Pauli propagation (cuPauliProp), density matrix (cuDensityMatrix)
- Distributed simulation — p-block composite mode for distributed quantum computing
- Expectation values — direct observable estimation (Pauli strings) for VQA workflows
- Performance optimizations — automatic multi-threading, multi-processing, and optimized sampling
Quick Start
pip install qoro-maestro # Linux, macOS & Windows
Or build from source:
chmod +x build.sh
./build.sh
For detailed build instructions, see INSTALL.md.
How It Works
Qiskit / QASM circuit
↓
Maestro Intermediate Representation
↓
Feature extraction → Prediction engine → Backend selection
↓
Execution (CPU / GPU / Distributed)
- Ingest — accepts circuits from Qiskit or QASM
- Convert — compiles to Maestro's intermediate representation
- Analyze — extracts features (gate density, entanglement, locality)
- Route — prediction engine estimates runtimes and selects the fastest backend
- Execute — runs on the chosen backend with automatic performance tuning
Backends
| Type | Backends |
|---|---|
| CPU | Statevector (Aer, QCSim), MPS, Pauli propagation, Clifford/stabilizer |
| GPU | Statevector (cuStateVec), MPS (CUDA), tensor network, Pauli propagation |
| Distributed | p-block composite simulation |
Each backend is accessed through a C++ adapter that maps Maestro's IR to the simulator's native API.
Documentation
| Resource | Link |
|---|---|
| Installation | INSTALL.md |
| Tutorial & API | TUTORIAL.md |
| Python examples | maestro-examples |
To generate API docs with Doxygen:
cd build
cmake ..
make doc
# Opens at docs/html/index.html
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
GPL-3.0 — see LICENSE or https://www.gnu.org/licenses/gpl-3.0.en.html.
Distributed GPU statevectors (local multi-GPU and MPI) are documented in docs/distributed_gpu.md.
1 maintainer
Metadata
1 maintainer
Release files for qoro-maestro 0.3.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| qoro_maestro-0.3.4.tar.gz | 755.6 kB | Details |
Built distributions (wheels)
Total release size: 228.9 MB
Release files / qoro_maestro-0.3.4.tar.gz
| Download URL | qoro_maestro-0.3.4.tar.gz |
|---|---|
| Size | 755.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
686879bddecb9a1d2c0c0fef02b117cb6a37dc6ce3d6c8db2b0ae28e7e8334eb
|
|
BLAKE2b-256 checksum How to use checksums |
f676ca13a842778830eff2016843f6bb66f59df01e2a4e9b6d3afab6116809a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp314-cp314-win_amd64.whl
| Download URL | qoro_maestro-0.3.4-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 13.3 MB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
a223f11a5d1b746755566c7cd777ba89cbbc8e215a3a55b575e361f832ad19af
|
|
BLAKE2b-256 checksum How to use checksums |
4d69d9286738cac97b0bf3173f3079a724846869c79b156a3de25238031a98ca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | qoro_maestro-0.3.4-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 18.9 MB |
| Tags | CPython 3.14 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
cf29f29341947c7872a1b11d1323001f77db82a6806cdef602890d880a1ed551
|
|
BLAKE2b-256 checksum How to use checksums |
cc311d1f92c6850bd9b69e559dd6305a07ae467da929678ad49fd510ed439ed9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp314-cp314-macosx_14_0_arm64.whl
| Download URL | qoro_maestro-0.3.4-cp314-cp314-macosx_14_0_arm64.whl |
|---|---|
| Size | 13.6 MB |
| Tags | CPython 3.14 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
328f728792d189d0499eb466b285fed1a544e55a5574b2c07b195ed338308c9f
|
|
BLAKE2b-256 checksum How to use checksums |
35502ded13f944b762a4e2380d552bfb8172e9ed2f11a5f7abece6020bbab2d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp313-cp313-win_amd64.whl
| Download URL | qoro_maestro-0.3.4-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 13.0 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
544ab902444ed61e5cb0be790547367a4fdb0050028bf88b626a6959ab5d4dde
|
|
BLAKE2b-256 checksum How to use checksums |
bf542d14dca9baa8af8c8e7e1083b0c566577c9dd26c359449794647d1f14ac6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | qoro_maestro-0.3.4-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 18.9 MB |
| Tags | CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
1504925c4d135fab919c7837e1d4020cbd089bab23c10556d1ad6bbd690db5b5
|
|
BLAKE2b-256 checksum How to use checksums |
d6de229907cc25ba3334708475a281f4e2dbad90f35d7a00e47c19dea154572a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp313-cp313-macosx_14_0_arm64.whl
| Download URL | qoro_maestro-0.3.4-cp313-cp313-macosx_14_0_arm64.whl |
|---|---|
| Size | 13.6 MB |
| Tags | CPython 3.13 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
2411c40b2cf6e553f8c67f87455aa401ec98f22a2ed5b09e5c874791b6fa58f3
|
|
BLAKE2b-256 checksum How to use checksums |
e1ddab25df7496013b0b8ffbe0cebb0d194cd295e2a6e0a8bdb55a52b27a8036
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp312-cp312-win_amd64.whl
| Download URL | qoro_maestro-0.3.4-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 13.0 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
6ac2ed7654c11991a1d0843b0a11aaaf9fd2742e1ea6aa58672cfc0766c21374
|
|
BLAKE2b-256 checksum How to use checksums |
f8f4598602bd3710a4b1c0600eb242fd1478d29afb8c244e081226e229d49593
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | qoro_maestro-0.3.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 18.9 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
a31ff4ca37d1f174ada1181bdc873fdc98b0d389958b16f9c27a7466398c0db5
|
|
BLAKE2b-256 checksum How to use checksums |
a1de37be10564aac170fd2365a3533fa823c98b117d8358ced0d0630fefc0432
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp312-cp312-macosx_14_0_arm64.whl
| Download URL | qoro_maestro-0.3.4-cp312-cp312-macosx_14_0_arm64.whl |
|---|---|
| Size | 13.6 MB |
| Tags | CPython 3.12 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f3f5a574a9d80dbf1e44149498f49c115d0f12d9bccf6a184cdb49b21ba1fa18
|
|
BLAKE2b-256 checksum How to use checksums |
885f9aad338c479f45fc4d4e772dddf8cc576144e610ab008f28e6b597e913be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp311-cp311-win_amd64.whl
| Download URL | qoro_maestro-0.3.4-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 13.0 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
bdcf701e2b8033eec9780ed1f2515a3dbec06e09f829dcdf0bdde00d17466446
|
|
BLAKE2b-256 checksum How to use checksums |
7dba8dfaab1c6bed295da04b1cc57986130922e507d158b0bb8f99177625fef2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | qoro_maestro-0.3.4-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 18.9 MB |
| Tags | CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
570476cb9d9d4b458e2b86511b7424eed6dbae11a3ab4c0b570edaf42a819325
|
|
BLAKE2b-256 checksum How to use checksums |
9859df839b818c7e1c0081f5243ffc10f07ef97f578a563aca735fd2c29939af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp311-cp311-macosx_14_0_arm64.whl
| Download URL | qoro_maestro-0.3.4-cp311-cp311-macosx_14_0_arm64.whl |
|---|---|
| Size | 13.6 MB |
| Tags | CPython 3.11 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d6a97b1169b810e7778057b754088c5d5d6bb058f0db2af5ed33d8cb30074981
|
|
BLAKE2b-256 checksum How to use checksums |
60952c9cb2e6d688bcada3792bb8eaf3abfac07922839cc464e85978154f2117
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp310-cp310-win_amd64.whl
| Download URL | qoro_maestro-0.3.4-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 13.0 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
31db7ea86779b456900b71e4c2d604d37f4b87a2888827d2f3ec220bedebe4de
|
|
BLAKE2b-256 checksum How to use checksums |
07609cb53ac322be24763bf2b38edf1969410df6578932f0b56e4292a99e36df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | qoro_maestro-0.3.4-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 18.9 MB |
| Tags | CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
c837287f3b97fe8944a4dda7e2a3d689952ffa69f99372d51dfc2b05fac385b2
|
|
BLAKE2b-256 checksum How to use checksums |
997e02979fb558da60aceb96fb6ca54cd70a34f0434fd6f96cc4607e86d87cf4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / qoro_maestro-0.3.4-cp310-cp310-macosx_14_0_arm64.whl
| Download URL | qoro_maestro-0.3.4-cp310-cp310-macosx_14_0_arm64.whl |
|---|---|
| Size | 13.6 MB |
| Tags | CPython 3.10 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4587345b3296f8b350d8e807ea4a87804c7cac27d8e37366130004b688f82257
|
|
BLAKE2b-256 checksum How to use checksums |
dac4b82210b5e2ea122ef8e32a5be052842f1517cf5bda758682364de808515b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency log
