Universal Node Provider System

The Node Provider System is QCOS's plugin architecture that lets you connect any number of GPUs, QPUs, or custom compute nodes to the DistributedQVM — from a local laptop to a 64-GPU LUMI supercomputer — without changing your application code.

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        Your Application                             │
│         qvm.run(VirtualCircuitSpec)  →  QVMResult                  │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────────┐
│                      DistributedQVM                                 │
│   ShardPlanner  →  NodeExecutor  →  ClassicalReconstructor         │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────────┐
│                       QPURegistry                                   │
│   { node_id → QPUNodeSpec,  node_id → NodeProvider }               │
└──────────┬──────────────────┬──────────────────┬────────────────────┘
           │                  │                  │
┌──────────▼──────┐  ┌────────▼────────┐  ┌──────▼──────────────────┐
│  LocalGPUMPS    │  │  LUMIAMDGPU     │  │  AzureQuantum           │
│  (tensor-net)   │  │  (MI250X ROCm)  │  │  (Rigetti / Quantinuum) │
│  n_nodes=8      │  │  n_nodes=4×8    │  │  targets=[...]          │
│  max_qubits=2000│  │  GCDs=32        │  │  cost=$0.0009/shot      │
└─────────────────┘  └─────────────────┘  └─────────────────────────┘

The key insight: providers are interchangeable. The DistributedQVM only sees QPURegistry — it doesn't care whether the underlying hardware is a laptop, a supercomputer, or a cloud QPU.

---

Built-in Providers

Provider key	Hardware	Max qubits/node	Cost
local_cpu	Qiskit Aer — CPU statevector	30q (exact)	Free
local_gpu_aer	Qiskit Aer — CUDA statevector	32q (exact)	Free
local_gpu_mps	Qiskit Aer — MPS tensor-network	2000q+ (approx.)	Free
local_gpu_cuquantum	NVIDIA cuQuantum via CuPy	36q (A100 80GB)	Free
lumi_amd_gpu	LUMI MI250X — ROCm (8 GCDs/node)	34q SV + 2000q MPS	GPU-hours
azure_quantum	Rigetti Ankaa-3, Quantinuum H2-1, Estimator	56–100q real QPU	From $0.0009/shot
ibm_quantum	IBM Eagle/Heron/Condor	127–1121q	$0.000044/shot
aws_braket	IonQ Aria, Rigetti, IQM Garnet	20–84q	From $0.0009/shot
custom_rest	Any QPU/GPU with /run-circuit HTTP endpoint	Configurable	$0

---

Quickstart (30 seconds)

from network.node_providers import ClusterBuilder
from network.distributed_qvm import DistributedQVM, VirtualCircuitSpec, QVMMode
from qiskit import QuantumCircuit

# 1. Build your cluster — mix and match any providers
registry = (
    ClusterBuilder()
    .add("local_gpu_mps", n_nodes=4, max_qubits=1000)
    .add("local_gpu_aer", n_nodes=8, max_qubits=28)
    .build()
)

# 2. Create the QVM
qvm = DistributedQVM(registry, mode=QVMMode.EMULATED, shots=2048)

# 3. Run any circuit
qc = QuantumCircuit(10)
qc.h(range(10))
qc.measure_all()

result = qvm.run(VirtualCircuitSpec(n_logical_qubits=10, circuit_object=qc))
print(result.counts)

---

Key Concepts

NodeProvider

A NodeProvider is a class that knows how to describe a set of compute nodes. It answers two questions:

1. What nodes exist? → build_nodes(**kwargs) → List[QPUNodeSpec]
2. How do I run a circuit on them? → execute(circuit, shots, node_spec) → Dict[str, int] (optional)

QPURegistry

The QPURegistry holds all registered nodes. It maps node_id → QPUNodeSpec and (optionally) node_id → NodeProvider for custom execution.

ClusterBuilder

The ClusterBuilder is a fluent API that composes multiple providers into a single registry. It is order-independent — the ShardPlanner selects the best node for each shard at execution time.

ShardPlanner

Given a VirtualCircuitSpec, the ShardPlanner partitions it into shards — subcircuits each small enough to fit on one physical node. For a 200-qubit circuit across 8×25q nodes it creates ~8 shards, each running in parallel.

---

Next Steps

Guide	Description
Quickstart	Full working example with real circuits
ClusterBuilder	Fluent API to compose clusters
LUMI GPU Guide	LUMI MI250X supercomputer setup
Azure Quantum Guide	Azure cheapest QPU targets
Custom Providers	Write your own provider in 10 lines
API Reference	Full class and method reference