Multi-QPU Platform — Asynchronous Distribution
mqpu) and the multi-GPU state-vector mode (mgpu) are planned capabilities, not included in the CPU-only reference build. The code on this page documents the intended interface and is commented out because it is not currently runnable.The multi-QPU platform exposes several parallel virtual QPUs at once and lets
you dispatch independent circuits to them asynchronously. A virtual QPU here is a simulator work
unit — one per GPU/worker — not a physical QPU. This differs from mgpu, which spreads one big
state vector across multiple GPUs for a single circuit; with mqpu each worker runs its own
circuit in parallel.
Enabling the platform
Select the mqpu option and query how many virtual QPUs you have — one per visible GPU:
# Planned interface (mqpu) — not runnable in the CPU-only reference build:
# import qalgora
#
# qalgora.set_target("gpu", option="mqpu") # mqpu = many virtual QPUs (simulator work units)
# target = qalgora.get_target()
# qpu_count = target.num_qpus()
# print("Number of QPUs:", qpu_count)Asynchronous sampling across QPUs
Every execution entry point has an *_async sibling that returns a future immediately and runs
on the QPU you name with qpu_id. Submit to all of them, then collect:
# Planned interface (mqpu async dispatch) — not runnable today:
# @qalgora.kernel
# def kernel(qubit_count: int):
# q = qalgora.qvector(qubit_count)
# h(q)
# mz(q)
#
# count_futures = []
# for qpu in range(qpu_count):
# count_futures.append(qalgora.sample_async(kernel, 5, qpu_id=qpu))
#
# for counts in count_futures:
# print(counts.get())Distributing an expectation value over MPI
For variational workloads the platform can split the terms of a Hamiltonian — or batches of parameters —
across processes. Initialise MPI, pass execution=qalgora.parallel.mpi to observe,
and only the root rank holds the reduced result:
# Planned interface (mqpu + MPI) — not runnable today:
# import qalgora
# from qalgora import spin
#
# qalgora.mpi.initialize()
# qalgora.set_target("gpu", option="mqpu")
#
# @qalgora.kernel
# def kernel(angle: float):
# q = qalgora.qvector(2)
# x(q[0])
# ry(angle, q[1])
# x.ctrl(q[1], q[0])
#
# hamiltonian = 5.907 - 2.1433 * spin.x(0) * spin.x(1) \
# - 2.1433 * spin.y(0) * spin.y(1) + .21829 * spin.z(0) - 6.125 * spin.z(1)
#
# exp_val = qalgora.observe(kernel, hamiltonian, 0.59,
# execution=qalgora.parallel.mpi).expectation()
# if qalgora.mpi.rank() == 0:
# print("Expectation value:", exp_val)
#
# qalgora.mpi.finalize()mgpu = one big state vector split across multiple GPUs — use it when a single circuit
is too big for one GPU's memory. mqpu = many independent tasks dispatched across QPU/GPU
workers — use it when you have many independent circuits (parameter sweeps, gradient shots,
Hamiltonian batching) to run side by side. A virtual QPU is a simulator work unit, not a physical QPU;
both modes are planned and not in the reference build.
多 QPU 平台 异步任务分发
mqpu）与多 GPU 态矢量模式（mgpu）均属规划中能力，CPU-only 的参考实现并未包含。本页代码仅用于说明预期接口，因当前不可运行而以注释形式给出。多 QPU 平台可同时暴露多个并行虚拟 QPU，让你以异步方式将相互独立的线路分发到这些 QPU 上执行。这里的虚拟 QPU 是一个模拟器工作单元（每块 GPU/工作进程对应一个），并非物理 QPU。它与 mgpu 不同：mgpu 是把单条线路的一个庞大态矢量切分到多块 GPU 上；而在 mqpu 下，每个工作单元并行运行各自的线路。
启用平台
选择 mqpu 选项，并查询当前可用的虚拟 QPU 数量，每块可见 GPU 对应一个 QPU：
# 规划接口（mqpu）当前 CPU-only 参考实现不可运行：
# import qalgora
#
# qalgora.set_target("gpu", option="mqpu") # mqpu = 多个虚拟 QPU（模拟器工作单元）
# target = qalgora.get_target()
# qpu_count = target.num_qpus()
# print("Number of QPUs:", qpu_count)跨 QPU 的异步采样
每个执行入口都有一个对应的 *_async 版本，它会立即返回一个 future，并在你通过 qpu_id 指定的 QPU 上运行。先将任务提交到所有 QPU，再统一收集结果：
# 规划接口（mqpu 异步分发）当前不可运行：
# @qalgora.kernel
# def kernel(qubit_count: int):
# q = qalgora.qvector(qubit_count)
# h(q)
# mz(q)
#
# count_futures = []
# for qpu in range(qpu_count):
# count_futures.append(qalgora.sample_async(kernel, 5, qpu_id=qpu))
#
# for counts in count_futures:
# print(counts.get())通过 MPI 分布式计算期望值
对于变分类工作负载，平台可以将哈密顿量的各项，或成批的参数，拆分到多个进程上。初始化 MPI 后，向 observe 传入 execution=qalgora.parallel.mpi，最终只有根进程持有归约后的结果：
# 规划接口（mqpu + MPI）当前不可运行：
# import qalgora
# from qalgora import spin
#
# qalgora.mpi.initialize()
# qalgora.set_target("gpu", option="mqpu")
#
# @qalgora.kernel
# def kernel(angle: float):
# q = qalgora.qvector(2)
# x(q[0])
# ry(angle, q[1])
# x.ctrl(q[1], q[0])
#
# hamiltonian = 5.907 - 2.1433 * spin.x(0) * spin.x(1) \
# - 2.1433 * spin.y(0) * spin.y(1) + .21829 * spin.z(0) - 6.125 * spin.z(1)
#
# exp_val = qalgora.observe(kernel, hamiltonian, 0.59,
# execution=qalgora.parallel.mpi).expectation()
# if qalgora.mpi.rank() == 0:
# print("Expectation value:", exp_val)
#
# qalgora.mpi.finalize()mgpu = 把单条线路的一个庞大态矢量切分到多块 GPU 上——当单条线路过大、超出单块 GPU 显存时使用。mqpu = 把大量相互独立的任务分发到多个 QPU/GPU 工作单元上——当你有大量相互独立的线路（参数扫描、梯度采样、哈密顿量分批）并希望它们并排运行时使用。虚拟 QPU 是模拟器工作单元，并非物理 QPU；两种模式均属规划中，参考实现尚未包含。