Metadata-Version: 2.4
Name: westquant-bluequbit
Version: 0.1.0
Summary: WestQuant Execution Representation Scheduling on BlueQubit compute
Author: WestQuant
License: Apache-2.0
Project-URL: Homepage, https://github.com/WestQuantOpen/westquant-bluequbit
Project-URL: Documentation, https://github.com/WestQuantOpen/westquant-bluequbit#readme
Keywords: quantum,scheduling,optimization,bluequbit,representation,mps,pauli-path
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy<2,>=1.24
Provides-Extra: bluequbit
Requires-Dist: bluequbit>=0.18; extra == "bluequbit"
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0; extra == "qiskit"
Provides-Extra: all
Requires-Dist: bluequbit>=0.18; extra == "all"
Requires-Dist: qiskit>=1.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# westquant-bluequbit

**WestQuant Execution Representation Scheduling on BlueQubit compute.**

WestQuant learns to map `(algorithm, circuit structure, accuracy target)` to `(representation, simulator, parameters)` on BlueQubit's multi-backend compute platform.

```
WestQuant
    │
circuit / problem
    │
┌───▼───────────┐
│ Representation│
│    Search     │
└───┬───────────┘
    │
┌───┴───────────────┐
│ Circuit rep        │  Execution rep
│ gates/layout/basis  │  CPU / GPU / MPS / Pauli-path / QPU
│ transpilation       │  bond dimension / truncation threshold
└───┬───────────────┘
    ▼
BlueQubit
    │
    ▼
cost / runtime / accuracy
    │
    ▼
WQT training data
```

## Why not just a wrapper?

BlueQubit exposes multiple ways to solve the same quantum computation: CPU, GPU, MPS (CPU/GPU), Pauli-path, and QPU. Each has tunable parameters (MPS bond dimension, Pauli-path truncation threshold, shots, transpilation level).

This means WestQuant can search over:

```
a = (R_c, D, P, θ)
```

where `R_c` = circuit representation, `D` = device/simulator, `P` = preprocessing/transpilation, `θ` = simulator parameters.

The optimization target is:

```
min(T, C, E)  subject to  E < ε
```

where `T` = runtime, `C` = cost, `E` = approximation error.

## Installation

```bash
pip install westquant-bluequbit[bluequbit,qiskit]
```

## Quick Start

```python
from westquant_bluequbit import BlueQubitSearch

search = BlueQubitSearch()

result = search.optimize(
    circuit,
    objectives=["runtime", "cost", "error"],
    devices=["cpu", "gpu", "mps.gpu", "pauli-path"],
    mps_bond_dimensions=[4, 8, 16, 32, 64],
    pauli_path_thresholds=[1e-1, 1e-3, 1e-5],
)

# Pareto-optimal execution configurations
for config in result["pareto_front"]:
    print(f"{config['device']}: {config['runtime_ms']:.0f}ms, ${config['cost']:.4f}")
```

## CLI

```bash
# Search across devices
wq-bq search --circuit ghz --n-qubits 24 --devices cpu,gpu,mps.gpu

# MPS bond dimension sweep
wq-bq mps-sweep --circuit qaoa --n-qubits 28 --chi 4,8,16,32,64 --target-fidelity 0.999

# Pauli-path truncation sweep
wq-bq pps-sweep --circuit pauli --n-qubits 32 --thresholds 1e-1,1e-3,1e-5

# Full benchmark suite
wq-bq benchmark --families ghz,qft,qaoa,vqe,random,pauli --n-qubits 8,16,24 --devices cpu,gpu

# Cost estimate
wq-bq estimate --circuit ghz --n-qubits 32 --device mps.gpu
```

## Architecture

### Core Modules

| Module | Purpose |
|--------|---------|
| `provider.py` | BlueQubit SDK wrapper with ledger tracking |
| `executor.py` | Circuit execution with wall-clock timing |
| `representation.py` | Circuit + execution representation dataclasses |
| `device_search.py` | Multi-device Pareto search |
| `mps_search.py` | MPS bond dimension sweep |
| `pauli_path_search.py` | Pauli-path truncation threshold sweep |
| `cost_model.py` | Learned cost/runtime prediction |
| `verification.py` | Fidelity, JS divergence, TV distance |
| `metrics.py` | Circuit features, Pareto front, hypervolume |
| `training_data.py` | WQT policy record generation |
| `cli.py` | Command-line interface |

### Benchmark Suite

| Family | What it tests |
|--------|--------------|
| GHZ | Low entanglement, ideal MPS candidate |
| QFT | Dense global structure |
| QAOA | Graph optimization |
| VQE | Hardware-efficient ansatz |
| Random Clifford | Stabilizer correctness baseline |
| Random Universal | Generic hard simulation |
| Pauli Evolution | Pauli-path relevant |

Default qubit counts: 8, 12, 16, 20, 24, 28, 32, 36, 40.

### WQT Training Data

Each execution produces a policy record:

```json
{
  "circuit_features": {"n_qubits": 24, "n_gates": 120, "n_2q_gates": 45, "depth": 30},
  "representation": "mps.gpu_chi64",
  "action": {"device": "mps.gpu", "options": {"mps_bond_dimension": 64}},
  "prediction": {"estimated_runtime_ms": 820, "estimated_cost": 0.04},
  "result": {"runtime_ms": 734, "cost": 0.037, "fidelity": 0.99991},
  "reward": {"accuracy": 0.99991, "runtime": 734, "cost": 0.037}
}
```

## Five WestQuant Experiments

### A. Backend Router
Learn `f(circuit) → {CPU, GPU, MPS, PPS}`. Which simulator representation is best for this circuit?

### B. MPS Bond-Dimension Scheduler
Search `χ ∈ {2, 4, 8, 16, 32, 64, 128}`. Measure `(χ, fidelity, runtime, cost)`. Learn `χ* = f(C, ε)`.

### C. Pauli-Path Threshold Scheduler
Search thresholds `10^{-1}` to `10^{-5}`. Get the accuracy-vs-compute curve.

### D. Circuit Representation × Simulator Representation
Not just `C → D`, but `(C, R) → (C', D)`. WestQuant changes gate decomposition, routing, basis — then selects the simulator. Same algorithm, different classical cost.

### E. Learned Cost Model
Compare BlueQubit's `estimate()` against actual runtime. Train `T̂_WQ(C, R, D)` — a representation-aware cost model.

## BlueQubit Devices

| Device | Cost | Use Case |
|--------|------|----------|
| `cpu` | Free | Small circuits, exact statevector |
| `gpu` | $0.20/job | Medium circuits, fast exact simulation |
| `mps.cpu` | Free | Large circuits, approximate |
| `mps.gpu` | $0.20/job | Large circuits, fast approximate |
| `pauli-path` | varies | Observable estimation, large circuits |
| `quantum` | varies | Real QPU execution |

## License

Apache-2.0

## Links

- [GitHub](https://github.com/WestQuantOpen/westquant-bluequbit)
- [WestQuant Open](https://github.com/WestQuantOpen)
- [BlueQubit](https://bluequbit.io)
