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

QPI QPU Driver

Python QPU 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 server
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

systemd Service (Linux)

To run qpi-driver persistently on a Linux machine in the background, you can use systemd.

We have provided an interactive bash installer that will automate this entire process for you (installing uv, installing the qpi-driver tool, prompting for your tokens, and registering the systemd service):

# Run the interactive systemd installer script (requires sudo to create the service)
sudo ./install-systemd.sh

Manual systemd Installation

If you prefer to configure it manually, follow these exact steps:

1. Install uv (a fast Python package installer):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   source $HOME/.local/bin/env
   

2. Install qpi-driver as a tool: Make sure to specify the correct extras (e.g. [cli,qblox], [cli,aer]):

   uv tool install "qpi-driver[cli,qblox]"
   

3. Create the systemd unit file: Replace the placeholder <values> with your actual configuration.

   sudo bash -c 'cat > /etc/systemd/system/qpi-driver.service <<EOF
   [Unit]
   Description=QPI Driver Service
   After=network.target
   
   [Service]
   Type=simple
   
   Environment="QPI_ACCESS_TOKEN=<your-qpi-access-token>"
   Environment=PYTHONUNBUFFERED=1
   
   ExecStart=/home/<user>/.local/bin/qpi-driver start \
           --ca-fingerprint <your-fingerprint> \
           --qpi-addr <your-qpi-server-address> \
           --name "<your-qpu-name>" \
           --executor "qblox"
   
   Restart=on-failure
   User=<user>
   
   StandardOutput=journal
   StandardError=journal
   SyslogIdentifier=qpi-driver
   
   [Install]
   WantedBy=multi-user.target
   EOF'
   

4. Start and enable the service:

   sudo systemctl daemon-reload
   sudo systemctl enable qpi-driver.service
   sudo systemctl start qpi-driver.service
   sudo systemctl status qpi-driver.service
   

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

Architecture

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

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

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

CLI Reference

qpi-driver start [OPTIONS]

Options:
  -a, --qpi-addr TEXT          QPI server 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

• Main QPI Repository
• PyPI Project Page

License

MIT — see the main repository for details.