Metadata-Version: 2.4
Name: qpi-driver
Version: 0.0.15
Summary: Quantum Processing Interface (QPI) Hardware Driver
Author-email: Martin Ahindura <team.sopherapps@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/sopherapps/qpi
Project-URL: Repository, https://github.com/sopherapps/qpi
Project-URL: Documentation, https://sopherapps.github.io/qpi/driver/
Project-URL: Issues, https://github.com/sopherapps/qpi/issues
Project-URL: Changelog, https://github.com/sopherapps/qpi/blob/main/CHANGELOG.md
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.0
Requires-Dist: xarray>=2024.1.0
Requires-Dist: pynng>=0.8.0
Requires-Dist: requests>=2.31.0
Requires-Dist: qiskit>=1.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: qiskit_qasm3_import
Provides-Extra: cli
Requires-Dist: typer>=0.9.0; extra == "cli"
Provides-Extra: aer
Requires-Dist: qiskit-aer>=0.14.0; extra == "aer"
Provides-Extra: quantify
Requires-Dist: quantify-scheduler; extra == "quantify"
Requires-Dist: qblox-instruments; extra == "quantify"
Provides-Extra: qblox
Requires-Dist: qblox-scheduler>=1.0.0b1; extra == "qblox"
Requires-Dist: qblox-instruments; extra == "qblox"
Dynamic: license-file

<pre align="center">
 ██████╗ ██████╗ ██╗
██╔═══██╗██╔══██╗██║
██║   ██║██████╔╝██║
██║▄▄ ██║██╔═══╝ ██║
╚██████╔╝██║     ██║
 ╚══▀▀═╝ ╚═╝     ╚═╝
</pre>

<h1 align="center">QPI Hardware Driver</h1>

<p align="center">
  <a href="https://badge.fury.io/py/qpi-driver"><img src="https://badge.fury.io/py/qpi-driver.svg" alt="PyPI version"></a>
  <a href="https://github.com/sopherapps/qpi/actions/workflows/ci.yml"><img src="https://github.com/sopherapps/qpi/actions/workflows/ci.yml/badge.svg" alt="CI/CD Workflow"></a>
  <a href="https://github.com/sopherapps/qpi/releases"><img src="https://img.shields.io/github/v/tag/sopherapps/qpi?label=version" alt="GitHub Tag"></a>
  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
</p>

<p align="center">
  Python hardware driver for the <a href="https://github.com/sopherapps/qpi">QPI</a> quantum computing platform.
  Runs on isolated hardware nodes controlling the QPU via multiple executor backends.
</p>

<p align="center">
  <strong><a href="https://sopherapps.github.io/qpi/driver/">📚 Read the Documentation</a></strong>
</p>

---

## Install

### Base package (mock executor)

```bash
pip install qpi-driver
```

### With CLI support

```bash
pip install "qpi-driver[cli]"
```

### With Qiskit Aer simulator

```bash
pip install "qpi-driver[aer]"
```

### With Quantify/Qblox hardware support

```bash
pip install "qpi-driver[quantify]"
```

Requires **Python ≥ 3.12, < 3.13**.

---

## Quick Start

### CLI

```bash
# 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:

```bash
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

```python
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

```python
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

- [Main QPI Repository](https://github.com/sopherapps/qpi)
- [PyPI Project Page](https://pypi.org/project/qpi-driver/)

---

## License

MIT — see the [main repository](https://github.com/sopherapps/qpi/blob/main/LICENSE) for details.
