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

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 process \
  --qpi-addr http://localhost:8090 \
  --token <qpu-access-token> \
  --ca-fingerprint <fingerprint> \
  --name qpu_sim_01 \
  --device mock \
  -o data_dir=./data

Environment variables are also supported for the universal flags:

export QPI_ADDR=http://localhost:8090
export QPI_ACCESS_TOKEN=<token>
export QPI_CA_FINGERPRINT=<fingerprint>
export QPI_DRIVER_NAME=qpu_sim_01
export QPI_DEVICE=mock
qpi-driver process

systemd Service (Linux)

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

We have provided a standalone interactive bash installer that automates the entire process (installing uv, installing the qpi-driver tool, prompting for your tokens/addresses, and registering the systemd service):

# Run the interactive systemd installer script directly via curl
sudo bash -c "$(curl -LsSf https://raw.githubusercontent.com/sopherapps/qpi/main/qpi-driver/install-systemd.sh)"

Alternatively, you can run the installer non-interactively by specifying all environment variables:

curl -LsSf https://raw.githubusercontent.com/sopherapps/qpi/main/qpi-driver/install-systemd.sh | sudo \
  QPI_TOKEN="<your-qpi-access-token>" \
  QPI_ADDR="http://127.0.0.1:8090" \
  CA_FINGERPRINT="<fingerprint>" \
  QPU_NAME="rigetti-aspen-1" \
  OPERATION="process" \
  DEVICE="qblox" \
  bash

Manual systemd Installation

If you prefer to configure it manually, follow these 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/rigetti-aspen-1.qpi-driver.service <<EOF
   [Unit]
   Description=QPI Driver Service (rigetti-aspen-1)
   After=network.target
   
   [Service]
   Type=simple
   
   Environment="QPI_ACCESS_TOKEN=<your-qpi-access-token>"
   Environment="QPI_CA_FILE=/var/qpi-driver/rigetti-aspen-1/qpi.ca.pem"
   Environment=PYTHONUNBUFFERED=1
   
   ExecStart=/home/<user>/.local/bin/qpi-driver process \
           --ca-fingerprint <your-fingerprint> \
           --qpi-addr <your-qpi-server-address> \
           --name "rigetti-aspen-1" \
           --device "qblox" \
           -o data_dir=/var/qpi-driver/rigetti-aspen-1 \
           -o quantify_device_config=/var/qpi-driver/rigetti-aspen-1/quantify.device.yml \
           -o quantify_hardware_config=/var/qpi-driver/rigetti-aspen-1/quantify.hardware.json
   
   Restart=on-failure
   User=<user>
   
   StandardOutput=journal
   StandardError=journal
   SyslogIdentifier=rigetti-aspen-1.qpi-driver
   
   [Install]
   WantedBy=multi-user.target
   EOF'
   

4. Start and enable the service:

   sudo systemctl daemon-reload
   sudo systemctl enable rigetti-aspen-1.qpi-driver.service
   sudo systemctl start rigetti-aspen-1.qpi-driver.service
   sudo systemctl status rigetti-aspen-1.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

A driver is run by its operation subcommand — process (a QPU) or monitor (e.g. a cryostat) — on a specific --device. Both share the same universal options; each device's own settings are passed as repeatable -o key=value.

qpi-driver process|monitor [OPTIONS]

Universal options:
  -a, --qpi-addr TEXT     QPI server URL [env: QPI_ADDR]
  -t, --token TEXT        Access token identifying the driver [env: QPI_ACCESS_TOKEN]
  -n, --name TEXT         Human-readable driver name [env: QPI_DRIVER_NAME]
  -d, --device TEXT       Backend within the operation, e.g. mock, qblox, bluefors_gen1 [env: QPI_DEVICE]
  -o, --option KEY=VALUE  Operation-specific config, repeatable
  --ca-file PATH          Path to the CA root certificate [env: QPI_CA_FILE]
  --ca-fingerprint TEXT   Fingerprint pinning the CA root certificate [env: QPI_CA_FINGERPRINT]
  --help                  Show this message and exit.

process -o options: data_dir, is_dummy, job_timeout, quantify_hardware_config,
                     quantify_device_config, use_sdk
monitor -o options (bluefors_gen1): channels (required), base_url, api_key,
                     poll_interval, timeout

Documentation

• Main QPI Repository
• PyPI Project Page

License

MIT — see the main repository for details.