Dense Evolution

高性能量子模拟工具包 包含带编译、噪声、VQE、QEC、化学和 Agent 原生工具的 Statevector/MPS 引擎。

下载 Dense Evolution Dashboard（Streamlit）
Windows（.bat） · macOS / Linux（.sh）

---

目录

• 项目简介
• 安装
• 快速开始
• 主要功能
• 基准测试
• Composer 和 MCP 服务
• 重要资源

▍ 项目简介

无需担心崩溃，即可在约 3 秒内运行最多 28 个量子比特。Dense Evolution 通过 JAX XLA 对 statevector 电路进行 JIT 编译，自动分块；即使超过 RAM 上限，也会在内存耗尽时将数据转存到磁盘，让真实模拟持续运行，而不是因 OOM 崩溃。

📖 完整文档、API 参考和示例 →

此外还包含本地 Streamlit 仪表板和基于 Web 的 Composer 编辑器——请参阅下文的 Composer 和 MCP 服务。

---

▍ 安装

pip install dense-evolution  # JAX is a core dependency, installed by default

# full stack: GPU · dashboard · Qiskit/PennyLane interop
pip install dense-evolution[full]

# just the interop bridge
pip install dense-evolution[qiskit]
pip install dense-evolution[pennylane]

# native Hartree-Fock (basis-set data)
pip install dense-evolution[hf]

# Composer's local kernel (see "Composer" below)
pip install dense-evolution[composer]

# MCP server for the Composer kernel (see "MCP Server" below)
pip install dense-evolution[mcp]

# development
git clone https://github.com/tatopenn-cell/Dense-Evolution.git
cd Dense-Evolution && pip install -e .[full]

⚠️ macOS + dense-evolution[qiskit] 用户

已知 Qiskit 自身的 QuantumCircuit.__init__ 会在 macOS/arm64 上导致整个进程发生段错误（这是 Qiskit 上游的 bug，并非 Dense-Evolution 能从自身一侧修复的问题；完整复现请参阅 release v8.1.43）。现在，首次在 sys.platform == 'darwin' 时使用 Qiskit 桥接功能，dense_evolution/interop.py 会发出警告（RuntimeWarning，每个进程仅一次），但不会阻止操作——某些 Qiskit/macOS 组合可能运行正常。如果遇到崩溃，pip install dense-evolution[pennylane] 可提供相同的电路互操作功能，且不会构造任何 Qiskit 对象。

Google Colab（3 行）：

!git clone https://github.com/tatopenn-cell/Dense-Evolution.git
%cd Dense-Evolution
!pip install -e .

---

▍ 快速入门

from dense_evolution import DenseSVSimulator, QASMParser

# parse any OpenQASM 2.0 / 3.0 string -- single-qubit rotations, a barrier
# (a real OpenQASM synchronization marker: parsed like hardware would, no
# effect on the simulated state), then an entangling layer
qasm = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[3];
rx(pi/3) q[0];
ry(pi/4) q[1];
h q[2];
barrier q;
cx q[0], q[1];
cx q[1], q[2];
rz(pi/6) q[2];
"""

parser = QASMParser()
circuit = parser.parse(qasm)

sim = DenseSVSimulator(n_qubits=3)
sim.run_circuit_jit(circuit.to_tuples())

probs = sim.get_probabilities()
sv    = sim.get_statevector()
# probs = [0.3201 0.3201 0.0549 0.0549 0.0183 0.0183 0.1067 0.1067]

噪声：

import numpy as np
from dense_evolution import DenseSVSimulator, QASMParser, NoiseModel

qasm = 'OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; h q[0]; cx q[0],q[1];'
circuit = QASMParser().parse(qasm)

sim = DenseSVSimulator(n_qubits=2)
sim.run_circuit_jit(circuit.to_tuples())

noisy_sv = NoiseModel.apply_to_sv(np.asarray(sim.sv), n=2, model='depolarizing', p=0.05, rng=np.random.default_rng(0))
np.abs(noisy_sv) ** 2
# [0.   0.5  0.5  0.  ]

VQE：

import jax
import jax.numpy as jnp
from dense_evolution import QASMParser, circuit_to_energy_fn

qasm = 'OPENQASM 2.0; include "qelib1.inc"; qreg q[1]; ry(0.0) q[0];'
circuit = QASMParser().parse(qasm)
energy_fn, n_params = circuit_to_energy_fn(circuit, n_qubits=1)
h = jnp.array([[1.0, 0.0], [0.0, -1.0]], dtype=jnp.complex128)  # Pauli Z

theta = jnp.array([0.1])
grad_fn = jax.value_and_grad(energy_fn, argnums=0, has_aux=True)
for _ in range(40):
    (energy, sv), grad = grad_fn(theta, h)
    theta = theta - 0.5 * grad
# energy = -1.0, theta = [3.14159265]

缓解（ZNE）：

import dense_evolution as de

e1, e2, e3 = 1.234, 0.876, 0.611  # values at 1x, 2x, 3x noise
de.zero_noise_extrapolation([e1, e2, e3], [1.0, 2.0, 3.0])
# 1.622

仪表板（本地，Streamlit）：

pip install "dense-evolution[dashboard]"  # JAX already included by default
streamlit run tools/dashboard/app.py

大型电路的防 OOM 功能：

from dense_evolution import Chunk, QASMParser

qasm = 'OPENQASM 2.0; include "qelib1.inc"; qreg q[27]; h q[0:27];'
circuit = QASMParser().parse(qasm)

sim = Chunk(27)
sim.run_chunk(circuit.to_tuples(), chunk_size_gates=500)

---

▍ 主要功能

• JIT 融合的态矢量引擎。 无需克罗内克积开销——通过 JAX XLA 编译的步长切片线性内核融合，无需更改代码即可调度真实 GPU/TPU。模拟器 · 适用于大规模低纠缠电路的 MPS 后端。
• 防 OOM 的 Chunk 引擎。 电路过大、无法装入单个数组时，可动态拆分，并根据实际计算设备自身的可用内存调整大小——超出此上限时还可溢出到磁盘。Chunk 指南。
• 真实噪声，真实缓解。 随机 Kraus 通道、从 Qiskit 后端导入的真实设备噪声，以及零噪声外推；可将采样预算最优地分配给各个噪声因子，并提供单量子比特布洛赫向量变体，始终返回有效状态以进行校正。噪声 · 缓解 · 噪声、缓解与修复分别指什么。
• 从零开始的可微分 VQE。 circuit_to_energy_fn 与实际分子 VQE 运行所用的引擎相同，可通过 JAX 求导——支持真实 Hartree-Fock 哈密顿量、UCCSD/硬件高效 ansatz，以及 Adam 优化。自动微分。
• 在 Windows、macOS 和 Linux 上使用 libcint 积分。 pip install dense-evolution 会安装针对各系统编译的 libcint：0.32 秒即可计算乙醇在 6-31G* 基组下的完整双电子张量。支持使用 UHF 和 ROHF 计算开壳层分子（run_uhf、run_cuhf）。native_hf。
• 可逆算术。 支持寄存器加法、减法、比较和模算术，直至模幂运算；既可作为精确的基态置换应用，也可表示为 OPENQASM 2.0 门电路（Cuccaro、Draper 和 Beauregard 加法器、受控模乘法），最高支持使用一个控制量子比特进行 Shor 阶查找。算术。
• 后选择。 保留测得量子比特为 |0>、|1>、|±> 或 |±i> 的分支，并给出其概率。后选择。
• 支持双向 OpenQASM 2.0/3.0。 提供真正的解析器，以及 Qiskit/PennyLane 互操作桥接。QASM 解析器 · 互操作。
• 与代码无关的 QEC 解码、Majorana/Jordan-Wigner 费米子映射、为 PennyLane 自带基组未涵盖的元素从头实现 Hartree-Fock、受可穿越虫洞启发的量子隐形传态协议，以及真实的 QM/MM 区域划分（环安全 BFS、基于 Diffuse2Seg 的相关性传播）——请参阅完整 API 参考了解全部内容。

▍ 基准测试

在 Windows 上测得，仅使用 CPU、8 GB RAM — PennyLane 的 default.qubit 会分配完整的状态向量；Dense Evolution 的 Chunk 无论量子比特数是多少，都会保持约 2 GB 的固定内存占用。

量子比特数	希尔伯特空间	PennyLane	Dense Evolution	分块几何
26	67,108,864	✅ 1,074 MB	✅ 2,050 MB	1× (2²⁷)
28	268,435,456	❌ OOM	✅ 2,050 MB	2× (2²⁷)
32	4,294,967,296	❌ OOM	✅ 2,048 MB	32× (2²⁷)

在 Google Colab（12 GB RAM）上，n=28 的端到端运行时间约为 3 秒（经 JIT 编译，num_chunks=2）——多分块路径速度很快，不只是能避免 OOM。超过实际 RAM 上限后（仅 Chunk 就会干净地引发 MemoryPressureError，而不是导致进程崩溃），allow_disk_overflow=True 会回退到较慢的磁盘支持路径，而不是直接失败——优先保证正确性，目前尚未进行速度基准测试。完整的实测表：docs/api/chunk.md。

▍ Composer 与 MCP 服务

在你自己的机器上运行的真实电路编辑器（图形界面或 OpenQASM），以及一个提供 22 个工具的 MCP 服务，可让 Agent（Claude Code、Claude Desktop 等）直接操控它。Composer · MCP 服务。

▍ 关键资源

• 完整文档与 API 参考
• 入门指南
• 示例详解
• 问题跟踪器

---

▍ 更新日志

📜 完整更新日志与版本发布 — 按最新版本优先列出所有版本。

---

▍ 许可证

GNU Affero 通用公共许可证 v3.0 或更高版本。 可按需提供商业许可证。

截至 8.3.2 的版本均以 Business Source License 1.1 发布：LICENSE-BUSL-1.1-until-8.3.2.md

完整文本：LICENSE

---

▍ 引用本文

如果 Dense-Evolution 对学术研究有帮助，请通过 CITATION.cff 中的元数据引用它（GitHub 自带的“引用此仓库”按钮以及支持 Citation File Format 的参考文献管理器均可识别）。

已存档于 Zenodo：

• 概念 DOI（始终指向最新版本）：10.5281/zenodo.21855643
• 此版本（v8.2.0）：10.5281/zenodo.22818319

---