核心概念¶

q2m3 结合量子化学、量子算法和分子力学。术语表定义下文使用的术语。

QM/MM 分区¶

QM/MM 将体系分为量子力学区域和分子力学环境。q2m3 目前使用 PySCF 完成经典量子化学计算，并以 TIP3P/SPC/E 式点电荷表示显式水环境。q2m3 内部以 Hartree 存储能量，仅在显式转换后使用 kcal/mol。

当前嵌入模型为静电点电荷嵌入，不包含可极化 MM 力场或高级溶剂响应模型。

QPE 工作流¶

QPE 估计时间演化算符的本征相位，再将相位转换为能量。PennyLane QPE 路径制备 HF 态，执行受控 Trotter 时间演化和逆 QFT，然后解码相位。没有 PennyLane 哈密顿量时，经典后备路径可测试 QM/MM 数据管线。

        flowchart LR
    accTitle: QPE Energy Flow
    accDescr: The q2m3 QPE path prepares a reference state, applies controlled time evolution, reads out a phase, and converts the phase to an energy.

    hamiltonian["PySCF and PennyLane Hamiltonian"]
    hf_state["HF reference state"]
    qpe["QPE circuit"]
    phase["Estimated phase"]
    energy["Energy in Hartree"]

    hamiltonian --> qpe
    hf_state --> qpe
    qpe --> phase
    phase --> energy

活性空间¶

活性空间截断可缩小模拟规模。报告活性电子数、空间轨道数和量子比特数。Jordan-Wigner 映射中，每个空间轨道对应两个自旋轨道量子比特。

体系	典型活性空间	系统量子比特数	说明
H2	2 个电子，2 个轨道	4	首次运行验证路径
H3O+	4 个电子，4 个轨道	8	可选离子溶剂化诊断
甘氨酸	6、8 或 10 个电子，轨道数与电子数相同	12、16 或 20	SQD 规模扩展教程。每个活性空间都有独立的哈密顿量和参考计算

完整 H3O+ STO-3G 空间大于默认示例。因此，公开 H3O+ 脚本采用保守的活性空间和 Trotter 设置。

基于采样的量子对角化¶

SQD 使用 ffsim 采样以 CCSD 为种子的 LUCJ 态。它在恢复的行列式子空间中对角化哈密顿量。结果包含 HF、活性空间 CCSD、选择 CI、随机子空间和参考能量。所有比较使用同一哈密顿量。参考策略见基于采样的量子对角化（SQD）。

主要带符号误差为 1000 * (E_SQD - E_reference)，单位 mHa；正值表示 SQD 高于参考能量。只有 T0 活性空间内精确结果才支持精确误差声明。种子离散程度是描述性统计，不是置信区间。采样行列式比例也不等于模拟器内存节省比例，因为 ffsim 仍表示完整的固定粒子数态。

SQD 在经典模拟器上运行。它不执行量子硬件计算，也不证明量子优势。

片段相互作用能¶

片段工作流为二聚体计算 E(AB) - E(A) - E(B)。Counterpoise 在三个计算中均使用二聚体基组。AVAS 根据显式原子壳层标签和阈值选择活性轨道。工作流检查二聚体与单体活性空间的对应关系。

classical_only 计算 HF 和冻结芯 MP2。full 增加受预算限制的 CCSD(T)、活性空间 SQD 和资源估算。只有 T0 exact-CASCI 参考提供 CASCI 能量。缺失的参考值保留为空并附带原因。完整计算见片段相互作用能。

这些相互作用能描述固定几何，不代表溶剂系综或溶剂化自由能。

相位解码与能量平移¶

QPE 测量模一相位，因此较大的负分子能量可能产生相位回绕。必要时，q2m3 使用平移后的 QPE 参数，估计相对 Hartree-Fock 参考的较小能量差。

当前代码存在两种相位提取约定：

路径	实现	解释
采样 QPE	`QPEEngine._extract_energy_from_samples()`	使用测量中频率最高的位串
解析溶剂化	`q2m3.solvation.phase_extraction`	使用概率加权的期望离散箱

比较这些路径时，必须说明解码约定和采样模型。

RDM 测量¶

单粒子约化密度矩阵（1-RDM）连接量子态与经典可观测量。q2m3 估算 1-RDM，用于 Mulliken 布居和电荷检查。SQD/MM 尚未实现关联 RDM 反馈。

RDM 值必须满足厄米性、电子数和非负占据等物理约束。测量噪声可能破坏这些约束，因此估计器提供投影工具以获得物理有效矩阵。

资源估计¶

q2m3.core.resource_estimation API 估计哈密顿量 1-范数、逻辑量子比特数、Toffoli 门数、系统量子比特数和目标误差等 EFTQC 资源。这些估计用于规划量子硬件资源，与 Catalyst 编译内存或 LLVM IR 大小不同。

H2 资源示例表明，MM 点电荷主要改变单电子项。在小规模 H2/STO-3G 运行中，双电子积分主导资源估计，因此真空和溶剂化估计接近。

固定分子轨道完整单电子嵌入¶

显式 MM 点电荷扰动单电子哈密顿量。q2m3 为该扰动提供两种公开资源估计模式：

模式	纳入的活性空间扰动	预期用途
`diagonal`	仅包含对角 `Delta h_pp` 项	与动态系数更新工作流兼容的结果行
`full_oneelectron`	完整的固定分子轨道 `Delta h_pq` 矩阵	资源结果行及固定哈密顿量算符支撑

两种模式均为固定分子轨道模型，复用真空分子轨道框架，并将双电子张量固定在真空值。它们不计算轨道弛豫、可极化 MM 响应或弛豫后的溶剂化能。诊断量 delta_h_offdiag_fro 报告活性空间非对角扰动的 Frobenius 范数；diagonal 模式忽略该扰动，full_oneelectron 模式包含它。

Catalyst 使用建议¶

重复执行可复用编译电路时使用 Catalyst。MC 溶剂化在仅改变哈密顿量系数时可复用电路。单次执行可能无法抵消编译成本。

使用场景	建议路径
H2 首次验证	标准 PennyLane 或现有示例脚本
固定真空哈密顿量的 MC	使用 IR 缓存的 Catalyst fixed 模式
运行时 MM 嵌入的 MC	Catalyst dynamic 模式，作为较高成本诊断
固定完整单电子嵌入	仅固定哈密顿量 / 算符路径
H3O+ 高精度或 Trotter 扫描	在大内存机器上运行的可选诊断

三种溶剂化模式¶

模式	能量模型	用途
`fixed`	`E_QPE(H_vac) + E_MM`	编译一次的快速基线
`hf_corrected`	`E_HF(R) + E_MM`，并按间隔执行 QPE 诊断	兼顾吞吐量的中间模式
`dynamic`	`E_QPE(H_eff) + E_MM`	运行时对角 MM 嵌入

q2m3 利用 fixed 与 dynamic 模式的电子相关行为差异，研究电子相关与极化耦合项 delta_corr-pol。

当前动态运行时系数路径更新对角系数。它不接受 embedding_mode="full_oneelectron"，因为非对角单电子项可能改变 Catalyst 为给定电路编译的算符支撑。