Circuit Simulation

◐ 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.

qalgora-Q bundles several simulator families. Pick one with set_target based on qubit count, entanglement, and noise needs.

State-vector simulators

Target	Use case	Status
`qpp-cpu`	CPU statevector — small circuits, no GPU	Available in reference build
`gpu`	Single-GPU statevector	Planned
`gpu` (`mgpu`)	Statevector pooled across multiple GPUs/nodes	Planned

Tensor-network simulators

Target	Use case	Status
`tensornet`	Large, low-entanglement circuits	Planned
`tensornet-mps`	Matrix-product-state ansätze, 1D systems	Planned

Noisy & photonic

Target	Use case	Status
`density-matrix-cpu`	Exact noisy simulation (2^N×2^N = 4^N memory)	Available in reference build
`stim`	Fast Clifford / stabilizer circuits (QEC)	Planned
`photonics`	Qudit / photonic operations (beam splitter, phase shift)	Planned

Only qpp-cpu (alias cpu) and density-matrix-cpu run on the open reference build today; the GPU, tensor-network, Stim and photonic targets are the specified interface and are not included yet.

import qalgora
qalgora.set_target("qpp-cpu")          # runnable today
print(qalgora.sample(small_kernel))

# Planned (spec interface — not in the open reference build):
# qalgora.set_target("tensornet-mps")
# print(qalgora.sample(large_1d_kernel))

How each method scales

Method	Memory	Best when	Status
Statevector	2^N complex amplitudes	Any entanglement; reachable qubit count is set by RAM/VRAM and precision (a 30-qubit complex64 statevector ≈ 8 GB, complex128 ≈ 16 GB)	`qpp-cpu` available; GPU statevector planned
Tensor network	Depends on bond dimension	Low entanglement / shallow circuits, 100s of qubits	Planned
Matrix product state	Linear in N · bond²	1D, low-entanglement systems	Planned
Density matrix	2^N×2^N = 4^N	Exact noise, small N	`density-matrix-cpu` available
Stabilizer (Stim)	N² (Clifford only)	QEC, very large Clifford circuits	Clifford-only; planned

Precision

The reference CPU statevector runs in double precision (complex128). Single (fp32) vs. double (fp64) selection is a GPU-backend option (planned): fp32 halves memory and is faster; fp64 is safer for tight-tolerance chemistry.

import qalgora
qalgora.set_target("qpp-cpu")                    # reference build runs double precision

# Planned (GPU backend, spec interface — not in the open reference build):
# qalgora.set_target("gpu", option="fp64")       # double precision
# data = np.array([...], dtype=qalgora.complex())  # match the target's width

Specification API — not in the open reference build yet

This example shows a qalgora-Q specification API (or a third-party library) that the open reference build does not bundle today. It documents the intended interface; to run code now, use the reference build’s supported core API.

Choosing a simulator

Start on the CPU statevector (the open reference build runs qpp-cpu today; gpu is a planned backend). Hit a memory wall? The planned options are pooling with mgpu, or switching to tensornet/tensornet-mps when entanglement is low. Need noise? Use density-matrix-cpu (small); trajectory sampling on gpu (large) is planned. Pure Clifford? stim (planned).

电路模拟

◐ 设计接口

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

qalgora-Q 内置了多套模拟器，可以根据量子比特数、纠缠程度和是否需要噪声，用 set_target 挑选合适的后端。

态矢量模拟器

目标后端	适用场景	当前状态
`qpp-cpu`	CPU 态矢量——适合小规模电路，无需 GPU	参考实现可用
`gpu`	单 GPU 态矢量	规划中
`gpu` (`mgpu`)	把态矢量摊到多块 GPU 或多个节点上	规划中

张量网络模拟器

目标后端	适用场景	当前状态
`tensornet`	大规模低纠缠电路	规划中
`tensornet-mps`	矩阵乘积态拟设、一维系统	规划中

噪声与光子

目标后端	适用场景	当前状态
`density-matrix-cpu`	精确噪声模拟（2^N×2^N = 4^N 内存）	参考实现可用
`stim`	快速 Clifford / 稳定子电路（QEC）	规划中
`photonics`	多能级量子位（qudit）与光子操作（分束器、移相）	规划中

当前只有 qpp-cpu（别名 cpu）与 density-matrix-cpu 能在开放参考实现上运行；GPU、张量网络、Stim 与光子目标属于规范接口，参考实现暂未包含。

import qalgora
qalgora.set_target("qpp-cpu")          # 当前可运行
print(qalgora.sample(small_kernel))

# 规划中（规范接口——参考实现暂未包含）：
# qalgora.set_target("tensornet-mps")
# print(qalgora.sample(large_1d_kernel))

各方法能撑多大规模

方法	内存	适用条件	当前状态
态矢量	2^N 个复振幅	任意纠缠度；可达的量子比特数取决于内存/显存与精度（30 量子比特 complex64 态矢量约 8 GB，complex128 约 16 GB）	`qpp-cpu` 可用；GPU 态矢量规划中
张量网络	取决于键维数	低纠缠 / 浅层电路，数百量子比特	规划中
矩阵乘积态	随 N · 键维数² 线性增长	一维低纠缠系统	规划中
密度矩阵	2^N×2^N = 4^N	N 较小时的精确噪声模拟	`density-matrix-cpu` 可用
稳定子（Stim）	N²（仅限 Clifford）	QEC、超大规模 Clifford 电路	仅限 Clifford；规划中

精度

参考实现的 CPU 态矢量采用双精度（complex128）。单精度（fp32）与双精度（fp64）的切换是 GPU 后端的选项（规划中）：fp32 内存减半、速度更快；fp64 更稳，适合对容差要求严格的化学计算。

import qalgora
qalgora.set_target("qpp-cpu")                    # 参考实现以双精度运行

# 规划中（GPU 后端，规范接口——参考实现暂未包含）：
# qalgora.set_target("gpu", option="fp64")       # double precision
# data = np.array([...], dtype=qalgora.complex())

规范接口 · 参考实现暂未包含

此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。

如何选择模拟器

先从 CPU 态矢量起步（参考实现当前运行 qpp-cpu；gpu 为规划中后端）。内存不够了？规划中的方案是用 mgpu 摊到多卡，或者趁纠缠度低切到 tensornet/tensornet-mps。要做噪声模拟？规模小就用 density-matrix-cpu；规模大时在 gpu 上做轨迹采样（规划中）。纯 Clifford 电路？用 stim（规划中）。

Previous上一页← Backends & Simulators后端与模拟器 Next下一页State Vector Simulators态矢量模拟器后端 →