qalgora-Q Docs Hub量子文档 ✦ Ask AI✦ 问问文档
/

State Vector Simulator Backends

◐ Design-level API
This page documents qalgora-Q API design, architecture, or adaptation workflows. Code examples illustrate intended usage and are not guaranteed to run in the current reference implementation.

A state-vector simulator stores the full 2N amplitude vector and applies each gate as a dense linear-algebra update. The open reference build ships one: a CPU statevector simulator (qpp-cpu, alias cpu). The single-GPU and multi-GPU/multi-node engines described below are part of the specification and are not included in the reference build yet.

CPU — the cpu target

A NumPy-based CPU statevector reference simulator, the default when no accelerator is selected. It is exact and double-precision (complex128); whether it uses multiple threads depends on the underlying NumPy/BLAS build. The reachable qubit count is set by available RAM — memory grows as 2N.

import qalgora
qalgora.set_target("qpp-cpu")   # "cpu" is an alias; runnable today
Specification — not in the open reference build
The GPU and multi-GPU/multi-node sections below, their environment variables, the MPI distribution path, the high qubit caps and the qalgora++ driver document the intended interface. The open reference build is a pure-NumPy CPU simulator and does not include them, so the set_target calls in these sections are shown commented out.

Single GPU — the gpu target (planned)

Backed by the GPU state-vector engine. It would default to single precision (fp32), switching to double with the fp64 option. Single precision halves the memory per amplitude, so a given amount of GPU memory holds roughly one more qubit than fp64 does.

# Planned GPU backend — spec interface, not in the open reference build:
# qalgora.set_target("gpu")                 # fp32 by default
# qalgora.set_target("gpu", option="fp32")
# qalgora.set_target("gpu", option="fp64")  # double precision

Gate fusion and memory behaviour are tunable through environment variables — the most useful ones:

VariableMeaning
QALGORA_FP_TYPEOverride the floating-point precision (float32/float64).
QALGORA_FUSION_MAX_QUBITSLargest gate-fusion block; raise for deep circuits, lower to save memory.
QALGORA_FUSION_DIAGONAL_GATE_MAX_QUBITSDiagonal-gate fusion limit (-1 auto, 0 off).
QALGORA_MAX_GPU_MEMORY_GBCap on GPU memory the simulator may claim.
QALGORA_ENABLE_MEMPOOLReuse a device memory pool across runs.

Multi-GPU, multi-node — the mgpu option (planned)

For circuits too large for one device, the mgpu option would distribute a single state vector across every GPU in the job, communicating over MPI. The program is launched with an MPI runner; process and node counts must be powers of two. The option order is irrelevant — "mgpu,fp64" and "fp64,mgpu" are equivalent.

# Planned multi-GPU spec interface — not in the open reference build:
# qalgora.set_target("gpu", option="mgpu,fp64")
# Planned, not in the open reference build:
# one process per GPU
# mpiexec -np 2 python3 program.py --target gpu --target-option mgpu,fp64

# tune the fusion block size for the distributed run
# QALGORA_MGPU_FUSE=5 mpiexec -np 2 python3 program.py --target gpu --target-option mgpu,fp64

The C++ flow is the same idea through the qalgora++ driver:

# Planned, not in the open reference build:
# qalgora++ --target gpu --target-option mgpu,fp64 program.cpp -o program.x
# mpiexec -np 2 ./program.x

Distribution kicks in only past QALGORA_MGPU_NQUBITS_THRESH (25 by default); below that the communication overhead is not worth it and a single device is used. Other knobs — QALGORA_MGPU_COMM_PLUGIN_TYPE, QALGORA_GPU_FABRIC, QALGORA_DATA_TRANSFER_BUFFER_BITS — tune the transport for your interconnect.

Tip
Today only qpp-cpu (alias cpu) runs on the open reference build, suited to tiny circuits and CI. The planned design is to move to gpu once VRAM allows larger statevectors, and to gpu + mgpu only when one GPU's memory is exhausted.

状态矢量模拟器后端

◐ 设计接口
本页描述的是 qalgora-Q 的接口设计、架构设计或适配工作流。相关代码用于说明预期用法，当前参考实现不保证可以直接运行。

态矢量模拟器会存储完整的 2N 振幅向量，并将每个门操作视为一次稠密线性代数更新来施加。开放参考实现只内置一种：CPU 态矢量模拟器（qpp-cpu，别名 cpu）。下文描述的单 GPU 与多 GPU/多节点引擎属于规范，参考实现暂未包含。

CPU——cpu 目标

这是一个基于 NumPy 的 CPU 态矢量参考模拟器，在未选择加速器时作为默认选项。它精确且采用双精度（complex128）；是否使用多线程取决于底层的 NumPy/BLAS 构建。可达的量子比特数由可用内存决定——内存随 2N 增长。

import qalgora
qalgora.set_target("qpp-cpu")   # "cpu" 是其别名；当前可运行
规范——开放参考实现暂未包含
下文的 GPU 与多 GPU/多节点章节及其环境变量、MPI 分布式路径、高量子比特上限以及 qalgora++ 驱动器描述的都是预期接口。开放参考实现是纯 NumPy 的 CPU 模拟器，并不包含这些功能，因此这些章节中的 set_target 调用均以注释形式给出。

单 GPU——gpu 目标（规划中）

由 GPU 态矢量引擎驱动。将默认采用单精度（fp32），可通过 fp64 选项切换为双精度。单精度将每个振幅的内存占用减半，因此在给定的 GPU 内存容量下，比 fp64 大致可多容纳一个量子比特。

# 规划中的 GPU 后端——规范接口，参考实现暂未包含：
# qalgora.set_target("gpu")                 # fp32 by default
# qalgora.set_target("gpu", option="fp32")
# qalgora.set_target("gpu", option="fp64")  # double precision

门融合和内存行为都能用环境变量来调——下面是最常用的几个：

变量含义
QALGORA_FP_TYPE覆盖浮点精度（float32/float64）。
QALGORA_FUSION_MAX_QUBITS最大门融合块；对深层电路可调高，为节省内存可调低。
QALGORA_FUSION_DIAGONAL_GATE_MAX_QUBITS对角门融合上限（-1 表示自动，0 表示关闭）。
QALGORA_MAX_GPU_MEMORY_GB限制模拟器可占用的 GPU 内存上限。
QALGORA_ENABLE_MEMPOOL在多次运行之间复用设备内存池。

多 GPU、多节点——mgpu 选项（规划中）

对于单个设备无法容纳的大型电路，mgpu 选项会将单个状态矢量分布到作业中的每个 GPU 上，并通过 MPI 进行通信。用你的 MPI 启动器来跑程序即可；进程数和节点数都必须是 2 的幂。选项的先后顺序不影响结果——"mgpu,fp64" 和 "fp64,mgpu" 完全等价。

# 规划中的多 GPU 规范接口——参考实现暂未包含：
# qalgora.set_target("gpu", option="mgpu,fp64")
# 规划中，开放参考实现暂未包含：
# one process per GPU
# mpiexec -np 2 python3 program.py --target gpu --target-option mgpu,fp64

# tune the fusion block size for the distributed run
# QALGORA_MGPU_FUSE=5 mpiexec -np 2 python3 program.py --target gpu --target-option mgpu,fp64

C++ 的工作流程是同样的思路，通过 qalgora++ 驱动器实现：

# 规划中，开放参考实现暂未包含：
# qalgora++ --target gpu --target-option mgpu,fp64 program.cpp -o program.x
# mpiexec -np 2 ./program.x

只有量子比特数超过 QALGORA_MGPU_NQUBITS_THRESH（默认 25）才会真正启用分布式；低于这个阈值时通信开销得不偿失，会自动退回单设备。其余几个可调项——QALGORA_MGPU_COMM_PLUGIN_TYPE、QALGORA_GPU_FABRIC、QALGORA_DATA_TRANSFER_BUFFER_BITS——则用来按你的互连网络调优数据传输。

提示
当前只有 qpp-cpu（别名 cpu）能在开放参考实现上运行，适合小电路与 CI。规划中的设计是：待显存允许更大态矢量时切到 gpu，只有单张 GPU 内存不够用了才上 gpu + mgpu。