片段相互作用能¶

两个水分子之间的相互作用会改变它们的总能量。本教程计算 S22 水二聚体的这一能量变化。你将定义两个片段，选择活性空间，再用一次计算比较五种电子结构方法。

从片段到相互作用能¶

每个水分子构成一个片段。我们用 A 和 B 表示两个片段，用 AB 表示完整二聚体。对每种方法，q2m3 按下式计算相互作用能：

\[\Delta E = E(AB) - E(A) - E(B).\]

负值表示二聚体的能量低于相同几何下两个独立片段的能量之和。三次计算都使用二聚体基组。计算单体时，另一片段的原子保留基函数，但不贡献原子核或电子。这些原子称为*鬼原子*。这一过程给出 counterpoise 校正后的相互作用能。

工作流先计算 Hartree–Fock（HF）和二阶 Møller–Plesset 微扰理论（MP2）能量。随后，它在选定的活性空间内比较两种方法。第一种是完全活性空间组态相互作用（CASCI）。第二种是基于采样的量子对角化（SQD）。工作流估计冻结核 CCSD(T) 的成本。若成本符合计算预算，该计算提供全轨道空间参考。

准备计算¶

本例使用默认的 mode="full" 和 cc-pVDZ 基组。在仓库根目录安装可选的 SQD 后端：

uv sync --frozen --extra sqd

SQD 后端支持 Linux x86_64。若只安装了核心依赖，请在下方的 run 调用中使用 mode="classical_only"。该模式返回 HF、MP2 能量及选定的活性空间。它跳过 CASCI、SQD、CCSD(T) 和资源估计。

将 water-dimer.xyz 下载到工作目录。坐标单位为埃。原子索引从零开始，因此原子 0–2 构成片段 A，原子 3–5 构成片段 B。

6
S22 water dimer (system 2), Angstrom; fragment A = atoms 0-2, fragment B = atoms 3-5
O  -1.551007  -0.114520   0.000000
H  -1.934259   0.762503   0.000000
H  -0.599677   0.040712   0.000000
O   1.350625   0.111469   0.000000
H   1.680398  -0.373741  -0.758561
H   1.680398  -0.373741   0.758561

选择活性空间¶

CASCI 和 SQD 显式处理相同的选定电子与轨道。原子价活性空间（AVAS）方法根据你指定的原子壳层选择这些轨道。avas_labels 参数指定壳层，avas_threshold 控制选择。两个参数都需要显式赋值。

本例使用 avas_labels=["O 2p", "H 1s"] 和 avas_threshold=0.7。得到的活性空间如下：

子体系	活性电子数	活性轨道数	SQD 量子比特数
二聚体 AB	12	8	16
单体 A	6	4	8
单体 B	6	4	8

"O 2p" 这样的元素标签会选择每个氧原子的相应壳层。"0 O 2p" 这样的索引标签仅指向完整几何中的原子 0。q2m3 将相同标签应用于三个子体系。对每个单体，它仅保留真实原子上的标签。

当前工作流允许每个子体系最多有 10 个活性轨道。对于这些标签，PySCF 默认阈值 0.2 会为二聚体选择 12 个轨道。本例使用 0.7，以得到上表中的较小空间。计算相关能量前，q2m3 还会检查单体活性空间与二聚体活性空间的对应关系。

计算并显示能量¶

在包含 water-dimer.xyz 的目录中运行以下 Python 代码。Molecule.from_xyz 将原子分配到两个片段。run 计算相互作用能。render_report 将结果格式化为 Markdown。

>>> from q2m3 import Molecule, run
>>> from q2m3.fragments import render_report
>>> dimer = Molecule.from_xyz("water-dimer.xyz", fragments=[(0, 1, 2), (3, 4, 5)], name="water-dimer")
>>> result = run(dimer, avas_labels=["O 2p", "H 1s"], avas_threshold=0.7)
>>> print(render_report([result]))
# 片段相互作用能报告
...
## 片段 water-dimer（模式 full，基组 cc-pvdz）
...
| HF | -0.005868 | -3.682 | |
| MP2 | -0.006272 | -3.935 | |
| CASCI | -0.005695 | -3.574 | |
| SQD | -0.005669 | -3.557 | |
| CCSD(T) | -0.00589... | -3.699 | |
...

报告目前使用中文标题。能量列以 Hartree（Ha）和 kcal/mol 给出 \(\Delta E\)。本例中，每种方法都得到负的相互作用能。SQD 给出约 −3.557 kcal/mol，接近同一活性空间内 CASCI 的 −3.574 kcal/mol。

result 对象还保存 AB、A、B 的能量、活性空间和资源估计。使用 result.delta_e 可读取 Hartree 单位的相互作用能。继续阅读解读片段相互作用能报告，了解方法差异和资源估计。

调整计算¶

对于另一个二聚体，先替换几何和片段索引。再为相关壳层选择 AVAS 标签。比较不同几何的能量前，检查选定的活性空间。

若选定的单体与二聚体活性空间不对应，q2m3 会抛出 ActiveSpaceMismatchError。请重新检查整个二聚体的标签和阈值。FragmentWorkflowError 也可能表示活性空间不受支持。例如，空间中没有活性虚轨道，或轨道数超过 10 个。异常消息会指出子体系和未满足的条件。

若要与参考计算比较，请在 run 调用中添加 references=["refs.csv"]。CSV 需要以下列：

列名	内容
`fragment_id`	分子名称，本例为 `water-dimer`
`method`	参考方法
`basis`	参考基组
`delta_e`	参考相互作用能
`unit`	`Ha`、`kcal/mol` 或 `kJ/mol`

请使用相同几何和相互作用能定义的参考。q2m3 将基组与当前计算相同的行归为同基组参考。它将使用其他基组的行归为外部参考。每类最多提供一个参考。下一篇教程解释这些参考如何参与能量比较。

请随结果保存几何和计算设置。result.provenance 记录几何哈希、基组、AVAS 设置、种子、软件包版本和线程设置。重复计算或比较不同环境的结果时，请使用这些记录。