Quantum Executor Documentation

Welcome 👋 to the official documentation of Quantum Executor! 🚀

Quantum Executor is a powerful, extensible tool designed to unify how developers, researchers, and industry practitioners interact with quantum computing platforms.

Whether you are a researcher, developer, student, or industry practitioner, Quantum Executor provides a seamless and elegant interface to dispatch, manage, and aggregate quantum computations across multiple providers and platforms — with no code rewriting, no provider lock-in, and full control over advanced workflows.

🧠 For a full project description, visit the GitHub Repository.

✨ Key Features

  • ✅ Unified Execution Interface: One simple, backend-agnostic API for all your quantum needs.

  • 🔄 Zero-Code Backend Switching: Adjust quantum backends purely through configuration—never refactor again.

  • ⚙️ Declarative Workflow Management: Define quantum workflows in a clear, declarative style—no backend complexity.

  • 🧪 Advanced Dispatching: Easily split and manage quantum experiments across multiple providers and backends.

  • 📊 Real-Time Monitoring: Track experiments live and access partial results immediately.

  • 🔌 Extensible by Design: Effortlessly integrate new quantum providers as your needs evolve.

Portable, modular, backend-agnostic quantum computing — by design.

🚀 Quickstart

Getting started with Quantum Executor is fast and simple. In just a few steps, you’ll be ready to execute your quantum workflows across multiple platforms—locally and in the cloud.

🔍 Installation

Install Quantum Executor via pip:

pip install quantum-executor

✅ Ensure cloud credentials are configured via qBraid or provider-specific SDKs.

📚 Usage Examples

Quantum Executor allows you to:

  • Dispatch quantum jobs across multiple providers

  • Execute circuits asynchronously or synchronously, and monitor them in real-time

  • Aggregate and analyse results with customizable policies

Let’s see a small, full working example to appreciate its power.

⚙️ Setting Up a Quantum Workflow

We will:

  • Create circuits in Qiskit and Cirq,

  • Run them on local simulators and IonQ devices,

  • Launch everything asynchronously through a unified interface.

from qiskit import QuantumCircuit
import cirq

# Qiskit circuit
qiskit_circuit = QuantumCircuit(2)
qiskit_circuit.h(0); qiskit_circuit.cx(0, 1); qiskit_circuit.measure_all()

# Cirq circuit
q0, q1 = cirq.LineQubit.range(2)
cirq_circuit = cirq.Circuit(cirq.H(q0), cirq.CNOT(q0, q1), cirq.measure(q0, q1))

Now we’ll define a custom manual dispatch to describe where and how to run each circuit, in a declarative-style. (For more advanced dynamic dispatching examples, check the Usage Guide).

We will:

  • Run cirq_circuit on a local simulator and two IonQ devices,

  • Also run qiskit_circuit on one IonQ device.

💡 In Quantum Executor, the language in which a circuit is defined is completely independent from the backend where it will run.

# Define the dispatch
dispatch = {
    "local_aer": {  # Local Aer provider
        "aer_simulator": [
            {"circuit": cirq_circuit, "shots": 2048},
        ],
    },
    "ionq": {  # IonQ cloud provider
        "qpu.forte-1": [
            {"circuit": cirq_circuit, "shots": 1024},
            {"circuit": qiskit_circuit, "shots": 1024},
        ],
        "qpu.aria-1": [
            {"circuit": cirq_circuit, "shots": 4096},
        ],
    }
}

Quantum Executor allows you to choose between synchronous or asynchronous, blocking or non-blocking execution with just two parameters.

# Import QuantumExecutor
from quantum_executor import QuantumExecutor

# Initialize the QuantumExecutor
executor = QuantumExecutor()

# Run the dispatch asynchronously and non-blocking
results = executor.run_dispatch(
    dispatch=dispatch,
    multiprocess=True,  # Multi-process execution
    wait=False          # Non-blocking call
)

In this example:

  • The three quantum backends (aer_simulator, forte-1, and aria-1) will run their jobs in parallel.

  • On forte-1, the two circuits (cirq_circuit and qiskit_circuit) will be executed sequentially.

Because devices may have different run times, Quantum Executor lets you gather available results progressively, even while some jobs are still running.

# Get all available results
results.get_results()

This retrieves all finished results immediately, without waiting for all jobs to complete.

☁️ Moving the Workflow to the Cloud

If you want to move your entire workflow to the cloud (e.g., IBM Quantum), you only need to modify the dispatch — the rest of your code remains unchanged.

dispatch = {
    "qiskit": {  # IBM Cloud Provider
        "ibm_torino": [
            {"circuit": cirq_circuit, "shots": 2048},
        ],
    },
    "ionq": {
        "qpu.forte-1": [
            {"circuit": cirq_circuit, "shots": 1024},
            {"circuit": qiskit_circuit, "shots": 1024},
        ],
        "qpu.aria-1": [
            {"circuit": cirq_circuit, "shots": 4096},
        ],
    }
}

Everything else stays the same — a fully declarative workflow!

🎯 Summary

Quantum Executor provides:

  • A high-level, unified interface for executing quantum programs across multiple providers,

  • Full backend-agnostic design — switch platforms without rewriting code,

  • Seamless synchronous or asynchronous execution,

  • Advanced dispatching and result aggregation capabilities for maximum flexibility.

Whether you’re a researcher experimenting with quantum algorithms or a developer building production quantum-classical workflows, Quantum Executor accelerates your journey.

🔬 For more advanced examples, see the , including: Dive into our Usage Guide for a more in-depth exploration of the Quantum Executor’s capabilities, including:

  • Advanced dispatching

  • How to dynamically split quantum jobs through a split policy

  • How to analyse and aggregate quantum results through a merge policy

🔎 For an in-depth architectural breakdown, visit How It Works.

💌 Get Involved

We welcome contributions, feature requests, and feedback!

Check out our Contributing Guide to get started.

📖 Citing Quantum Executor

If you use Quantum Executor in your research or projects, please consider to cite us:

@misc{quantumexecutor2025,
  title        = {Quantum Executor: A Unified Interface for Quantum Computing},
  author       = {Giuseppe Bisicchia},
  year         = {2025},
  publisher    = {GitHub},
  journal      = {GitHub repository},
  howpublished = {\url{https://github.com/GBisi/quantum-executor}},
}

⚖️ License

Quantum Executor is open-sourced under the AGPL-3.0 License.

🎉 Join us in shaping the future of quantum computing—start today!

📖 Contents

Contents

Next: Usage Guide →