量子化学扩展
概述
UnitaryLab Chemistry 提供分子电子结构计算、Jordan-Wigner 映射、DMRG 基态求解、DMRG 态到量子线路的转换，以及哈密顿量分组测量。该功能已经从主包 unitarylab.library.chemistry 拆分为独立 Python 包和导入命名空间 unitarylab_chemistry。
Chemistry 的依赖不包含在主模拟器 unitarylab 的默认安装中。普通量子线路的构建与执行不依赖本扩展。
安装与系统支持
UnitaryLab Chemistry 使用 Python 3.10+，通过主包的可选依赖安装：
pip install "unitarylab[chemistry]"支持情况：
| 组件 | Windows | Linux | macOS |
|---|---|---|---|
unitarylab 主模拟器 | 支持 | 支持 | 支持 |
unitarylab-chemistry 扩展 | 不支持 | 支持 | 支持 |
Windows 限制只影响 Chemistry 扩展，不影响主模拟器。Chemistry 工作流依赖 PySCF、OpenFermion、OpenFermion-PySCF、TeNPy、NetworkX、SciPy 和主模拟器；使用可选依赖安装方式可一并解析发布版本声明的依赖。
安装后可验证公开入口：
import unitarylab_chemistry
from unitarylab_chemistry import Molecule, MolecularDMRGWorkflow
print(unitarylab_chemistry.__all__)导入路径与迁移
新代码应直接使用独立命名空间：
from unitarylab_chemistry import (
Molecule,
MolecularDMRGResult,
MolecularDMRGWorkflow,
)旧路径仍保留兼容入口：
# 兼容旧代码，不建议在新代码中使用
from unitarylab.library.chemistry import Molecule, MolecularDMRGWorkflow兼容层只转发 Molecule、MolecularDMRGResult、MolecularDMRGWorkflow。如果没有安装独立扩展，访问这些名称会抛出 ImportError，并提示执行 pip install "unitarylab[chemistry]"。原先直接从 unitarylab.library.chemistry 子模块导入 DMRG、测量或线路转换函数的代码，需要改用下表中的新路径：
| 功能 | 新导入路径 |
|---|---|
| 分子与电子结构 | unitarylab_chemistry.molecule |
| DMRG | unitarylab_chemistry.dmrg |
| DMRG 态线路转换 | unitarylab_chemistry.quantum_circuit_from_dmrg |
| 分组测量与 QASM | unitarylab_chemistry.measurement |
工作流接口
MolecularDMRGWorkflow(
molecule,
*,
shots=10_000,
dmrg_chi0=20,
dmrg_maxdim=100,
dmrg_max_sweeps=100,
dmrg_cutoff=1e-8,
layers=None,
renyi_indices=None,
cvd_maxiter=200,
cvd_restarts=3,
cvd_init_scale=0.5,
workdir=None,
seed=2077,
backend="numpy",
device="cpu",
dtype=np.complex128,
)molecule 必须是 Molecule。workdir=None 表示使用当前工作目录；shots=0 时跳过有限 shots 采样，但仍计算精确能量。DMRG 和 CVD 参数分别控制张量网络求解及线路转换的资源开销。
最小完整工作流
MolecularDMRGWorkflow 按以下顺序执行：
Molecule
-> electronic_structure
-> dmrg
-> cvd_dmrg
-> measurement_QASM下面以 H₂ 为例。完整流程会运行电子结构、DMRG、线路优化和采样，实际耗时取决于活性空间与计算环境：
from unitarylab_chemistry import Molecule, MolecularDMRGWorkflow
molecule = Molecule(
geometry=[
("H", (0.0, 0.0, 0.0)),
("H", (0.0, 0.0, 0.7414)),
],
basis="sto-3g",
charge=0,
multiplicity=1,
active_occupied=1,
active_virtual=1,
)
workflow = MolecularDMRGWorkflow(
molecule,
shots=10_000,
workdir="chemistry-output",
backend="numpy",
device="cpu",
)
result = workflow.run(target="measurement_QASM")
print(result.electronic_structure)
print(result.dmrg)
print(result.cvd.circuit)
print(result.measurement)run(target="measurement_QASM") 可在指定阶段结束。target 的合法值为 "electronic_structure"、"dmrg"、"cvd_dmrg"、"measurement_QASM"；其他值会触发 ValueError。默认值执行到最后一个阶段。返回的 MolecularDMRGResult 包含 molecule，并按实际完成的阶段填充 electronic_structure、dmrg、cvd 和 measurement；尚未执行的阶段为 None。
| 字段 | 完成阶段 | 内容 |
|---|---|---|
molecule | 全部阶段 | 分子几何、基组、电荷和活性空间配置 |
electronic_structure | electronic_structure 起 | 分子积分、轨道和量子比特哈密顿量 |
dmrg | dmrg 起 | DMRG 能量与张量网络态 |
cvd | cvd_dmrg 起 | 转换后的量子线路及优化信息 |
measurement | measurement_QASM | 分组测量与能量估计结果 |
分阶段接口
需要控制中间结果时，可以直接导入各阶段函数：
from unitarylab_chemistry.molecule import electronic_structure
from unitarylab_chemistry.dmrg import dmrg
from unitarylab_chemistry.quantum_circuit_from_dmrg import cvd_dmrg
from unitarylab_chemistry.measurement import measurement_QASM
electronic = electronic_structure(molecule, workdir="chemistry-output")
dmrg_result = dmrg(electronic)
cvd_result = cvd_dmrg(
dmrg_result,
pauli_terms=electronic.pauli_terms,
)
measurement = measurement_QASM(
cvd_result.circuit,
electronic.pauli_terms,
electronic.n_qubits,
shots=10_000,
workdir="chemistry-output",
backend="numpy",
device="cpu",
)Molecule.from_xyz() 可从标准 XYZ 文件创建分子。DMRG 参数、活性空间、CVD 层数与优化轮数会影响精度、内存和运行时间。建议先用 H₂/sto-3g 等小体系验证环境，再扩大问题规模。
注意事项
- Chemistry 输出目录可能包含积分数据、QASM、测量分组和结果文件；请为每次实验使用明确的
workdir。 measurement_QASM的采样结果受shots和seed影响；需要不可复现采样时传入seed=None。- DMRG 和电子结构依赖属于 Chemistry 扩展，不应通过向主模拟器手动补装零散包来代替正式的可选依赖安装。
- CUDA C++ 后端是主模拟器的另一项独立可选能力，与 Chemistry 的系统支持和依赖无关。用户应通过
pip install "unitarylab[cuda]"安装；该 extra 会安装适配当前 Python 与平台的底层unitarylab-cu12wheel。