 ██████╗ ██████╗ ██╗
██╔═══██╗██╔══██╗██║
██║   ██║██████╔╝██║
██║▄▄ ██║██╔═══╝ ██║
╚██████╔╝██║     ██║
 ╚══▀▀═╝ ╚═╝     ╚═╝

QPI Hardware Driver

Python hardware driver for the QPI quantum computing platform. Runs on isolated hardware nodes controlling the QPU via multiple executor backends.

📚 Read the Documentation

Install

Base package (mock executor)

pip install qpi-driver

With CLI support

pip install "qpi-driver[cli]"

With Qiskit Aer simulator

pip install "qpi-driver[aer]"

With Quantify/Qblox hardware support

pip install "qpi-driver[quantify]"

Requires Python ≥ 3.12, < 3.13.

Quick Start

CLI

# Connect a mock QPU to the orchestrator
qpi-driver start \
  --qpi-addr http://localhost:8090 \
  --token <qpu-access-token> \
  --ca-fingerprint <fingerprint> \
  --name qpu_sim_01 \
  --executor mock \
  --data-dir ./data

Environment variables are also supported:

export QPI_ADDR=http://localhost:8090
export QPI_ACCESS_TOKEN=<token>
export QPI_CA_FINGERPRINT=<fingerprint>
export QPU_NAME=qpu_sim_01
export DRIVER_BACKEND=mock
qpi-driver start

Python API

from qpi_driver import run_driver

run_driver(
    qpi_addr="http://localhost:8090",
    token="<qpu-access-token>",
    ca_fingerprint="<fingerprint>",
    name="qpu_sim_01",
    executor="mock",
    data_dir="./data",
)

Custom executor

from qpi_driver import Executor, run_driver
from qpi_driver.executors.mock import MockExecutor

class MyCustomExecutor(Executor):
    def execute(self, payload):
        # Your QPU-specific execution logic
        ...

run_driver(
    qpi_addr="http://localhost:8090",
    token="<token>",
    ca_fingerprint="<fingerprint>",
    name="my_qpu",
    executor="custom",
    custom_executor=MyCustomExecutor(),
)

Executor Backends

Backend	Description	Extra
`mock`	Qiskit BasicSimulator (default)	—
`qiskit_aer`	Qiskit Aer simulator	`[aer]`
`quantify`	Quantify-scheduler + Qblox instruments	`[quantify]`
`qblox`	Qblox scheduler (legacy)	`[qblox]`

Architecture

The driver uses Python's multiprocessing library to isolate responsibilities:

Main Process: NNG PULL listener, receives commands from orchestrator
Worker Process: Executes quantum circuits via the configured executor
Result Sender Process: NNG PUSH, sends results back to orchestrator

┌─────────────┐     NNG PUSH      ┌─────────────────┐
│ Orchestrator│ ────────────────> │  Main Process   │
│  Dispatcher │                   │  (PULL listener)│
└─────────────┘                   └────────┬────────┘
                                           │
                              multiprocessing.Queue
                                           │
                                           ▼
                                   ┌───────────────┐
                                   │ Worker Process│
                                   │  (Executor)   │
                                   └───────┬───────┘
                                           │
                              multiprocessing.Queue
                                           │
                                           ▼
                                   ┌───────────────┐
                                   │Result Sender  │
                                   │  (PUSH)       │
                                   └───────┬───────┘
                                           │ NNG PUSH
                                           ▼
                                   ┌───────────────┐
                                   │  Orchestrator │
                                   │   Listener    │
                                   └───────────────┘

CLI Reference

qpi-driver start [OPTIONS]

Options:
  -a, --qpi-addr TEXT          QPI orchestrator URL [env: QPI_ADDR]
  -t, --token TEXT             QPU access token [env: QPI_ACCESS_TOKEN]
  -n, --name TEXT              QPU name [env: QPU_NAME]
  -e, --executor TEXT          Backend: mock, qiskit_aer, quantify, qblox, presto [env: DRIVER_BACKEND]
  -d, --data-dir PATH          Data directory [env: QPI_DATA_DIR]
  --is-dummy                   Run in dummy/simulation mode
  --quantify-hardware-config PATH  Quantify hardware config [env: QPI_QUANTIFY_HARDWARE_CONFIG]
  --quantify-device-config PATH    Quantify device config [env: QPI_QUANTIFY_DEVICE_CONFIG]
  --job-timeout INTEGER        Job timeout in seconds [env: QPI_JOB_TIMEOUT]
  --ca-file PATH               Path to the CA root certificate [env: QPI_CA_FILE]
  --ca-fingerprint TEXT        Fingerprint to verify the CA root certificate [env: QPI_CA_FINGERPRINT]
  --help                       Show this message and exit.

Documentation

License

MIT — see the main repository for details.