片段相互作用 API

片段 API 计算双片段二聚体的 counterpoise 校正相互作用能。run 与 Molecule 也是 q2m3 的顶层导出。mode="classical_only" 只需要核心安装。mode="full" 需要 sqd extra 与 Linux x86_64。完整运行见 片段相互作用能。

工作流

q2m3.fragments.run(molecule, *, avas_labels, avas_threshold, basis='cc-pvdz', mode='full', references=None, seed=0, lucj=None, reference=None, ccsd_t_budget=None)

计算 molecule 的 counterpoise 校正相互作用能。

二聚体返回 FragmentInteractionResult。单分子返回子体系 "M" 的 SubsystemResult。两种模式都选择 AVAS 活性空间。对二聚体，两种模式都在任何关联计算之前检查活性空间的对应关系。两种模式都计算 HF 与冻结芯 MP2。mode="classical_only" 从不构造 SQD 阶段的 runner。mode="full" 还执行下列步骤：预估成本在 ccsd_t_budget（默认 CCSDTBudget()）内时运行冻结芯 CCSD(T) 参考；构造活性空间积分；在一个子解释器中对全部子体系运行 SQD；估计 QPE 与 SQD 资源。CCSD(T) 被拒绝时，e_ccsd_t 为空，并写明原因。

references 含参考文件与 ExternalReference 记录。参考文件由 import_references 按本次运行的片段标识与 basis 读取。它们构成二聚体结果的活性空间误差、基组误差与模型误差。

抛出:

• TypeError -- avas_labels 不是字符串序列，avas_threshold 不是实数，或 references 是单个字符串或路径。

• ValueError -- mode 不是 "full" 或 "classical_only"，某个 AVAS 标签格式错误或不匹配任何 AO，或对单分子传入了 references。

• ImportError -- mode="full" 且缺少可选的 sqd 后端。

• ReferenceImportError -- 参考文件不符合导入格式，或两条参考属于同一类别。

• FragmentWorkflowError -- 某个子体系的 RHF 或 CCSD 不收敛，或标签解析、鬼原子守卫或预检拒绝了某个活性空间。

• ActiveSpaceMismatchError -- 单体活性空间与二聚体活性空间不对应。

参数:

• molecule (Molecule)

• avas_labels (Sequence[str])

• avas_threshold (float)

• basis (str)

• mode (str)

• references (Sequence[str | PathLike[str] | ExternalReference] | None)

• seed (int)

• lucj (Any)

• reference (Any)

• ccsd_t_budget (Any)

返回类型:

FragmentInteractionResult | SubsystemResult

class q2m3.fragments.Molecule(symbols, coordinates_angstrom, fragments, charges, multiplicities, name=None)

以埃为单位的几何，可选地划分为两个片段。

charges 与 multiplicities 每个片段一项；单分子（fragments is None）时只有一项。

参数:

• symbols (tuple[str, ...])

• coordinates_angstrom (tuple[tuple[float, float, float], ...])

• fragments (tuple[tuple[int, ...], tuple[int, ...]] | None)

• charges (tuple[int, ...])

• multiplicities (tuple[int, ...])

• name (str | None)

classmethod from_xyz(source, *, fragments=None, charges=None, multiplicities=None, name=None)

从 XYZ 文件路径或以埃为单位的 XYZ 文本构造分子。

不含换行符的字符串按文件路径读取。

抛出:

ValueError -- XYZ 文本格式错误；元素未知；片段不是恰好两个划分全部原子的非空集合；电荷数或多重度数与片段数不符；或某个多重度不是 1。

参数:

• source (str | PathLike[str])

• fragments (Sequence[Sequence[int]] | None)

• charges (Sequence[int] | None)

• multiplicities (Sequence[int] | None)

• name (str | None)

返回类型:

Molecule

property charge: int

分子的总电荷。

geometry_sha256()

几何与片段定义的小写十六进制 SHA-256。

摘要的字节是键已排序的紧凑 ASCII JSON（json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True)）。载荷的键为 symbols、coordinates_angstrom（Python float 的列表）、fragments（原子下标的列表，或 null）、charges 与 multiplicities。name 不参与摘要。

返回类型:

str

结果契约

class q2m3.fragments.result.FragmentInteractionResult(*, schema_version='fragments.result.v1', fragment_id, mode, basis, subsystems, delta_e, references, errors, correspondence, provenance, null_reasons, warnings=())

一个片段二聚体的 counterpoise 校正相互作用能，单位为 Ha。

delta_e 把 ENERGY_LAYERS 的每一层映射到 E(AB) - E(A) - E(B)，三项都在二聚体基组中计算。delta_e 与 errors 的空值在 null_reasons 中有条目，键为带点的名字，例如 delta_e.casci 与 errors.model。

参数:

• schema_version (str)

• fragment_id (str)

• mode (str)

• basis (str)

• subsystems (Mapping[str, SubsystemResult])

• delta_e (Mapping[str, float | None])

• references (tuple[ExternalReference, ...])

• errors (ErrorDecomposition)

• correspondence (CorrespondenceReport | None)

• provenance (Mapping[str, Any])

• null_reasons (Mapping[str, str])

• warnings (tuple[str, ...])

validate()

重算相互作用能，并检查空值原因。

抛出:

ValueError -- 子体系不是 AB、A、B；classical-only 结果含 SQD 记录，或 full 结果缺少 SQD 记录；来源记录缺少必需的键；存储的相互作用能或误差项与重算值之差超过 DELTA_E_TOLERANCE_HA；模型误差不等于活性空间误差与基组误差之和；记录的同基组参考来源不是实际使用的来源；参考类别未知或重复；或某个空值没有原因。

返回类型:

FragmentInteractionResult

class q2m3.fragments.result.SubsystemResult(*, name, real_atoms, ghost_atoms, n_ao, e_hf, e_mp2, e_ccsd_t, e_casci, e_sqd, active_space, sqd, resources, null_reasons)

一个子体系的能量与记录：AB、A、B 或 M（单分子）。

每个 None 字段在 null_reasons 中以字段名为键有一个条目；缺少的资源估计用 resources.<qpe|sqd> 为键。每个资源槽位只存放该槽位估计器的估计。e_sqd 与 e_casci 由 promote_sqd_energies() 从 sqd 导出。

参数:

• name (Literal['AB', 'A', 'B', 'M'])

• real_atoms (tuple[int, ...])

• ghost_atoms (tuple[int, ...])

• n_ao (int)

• e_hf (float | None)

• e_mp2 (float | None)

• e_ccsd_t (float | None)

• e_casci (float | None)

• e_sqd (float | None)

• active_space (ActiveSpaceRecord | None)

• sqd (SQDResult | None)

• resources (Mapping[str, ResourceEstimate | None])

• null_reasons (Mapping[str, str])

validate()

检查空值原因、资源槽位与 SQD 记录。

抛出:

ValueError -- 某个空值字段在 null_reasons 中没有条目；资源键不是 qpe 或 sqd；资源槽位存放的不是该槽位估计器的估计；sqd 不恰好是 SQDResult，或未通过自身的校验；活性空间不是 SQD 运行所用的空间；或 e_sqd、e_casci 与从 sqd 导出的值不同。

返回类型:

SubsystemResult

参考与报告

q2m3.fragments.import_references(path, *, fragment_id, basis)

从 CSV 或 QCSchema JSON 文件读取 fragment_id 的参考。

基组等于 basis（不区分大小写）的参考是同基组全空间参考，其余为外部参考。返回值的单位为 Ha。

抛出:

ReferenceImportError -- 文件既不是 .csv 也不是 .json；缺少某个 CSV 列；单位不是 Ha、kcal/mol 或 kJ/mol；某个值不是数字；没有一行 CSV 的片段为 fragment_id；或 QCSchema 记录缺少字段，或指向另一个片段。

参数:

• path (str | PathLike[str])

• fragment_id (str)

• basis (str)

返回类型:

tuple[ExternalReference, ...]

class q2m3.fragments.result.ExternalReference(fragment_id, method, basis, delta_e, category)

导入的一个片段二聚体的相互作用能，单位为 Ha。

basis 等于工作流基组时，category 为 "same_basis_full_space"，否则为 "external"。

参数:

• fragment_id (str)

• method (str)

• basis (str)

• delta_e (float)

• category (str)

q2m3.fragments.render_report(results, *, ks_table=None)

为一次调用的全部片段结果返回一份 Markdown 报告。

参数:

• results (Sequence[FragmentInteractionResult]) -- 要报告的片段结果，按报告顺序排列。

• ks_table (Mapping[str, float] | None) -- 实验标签到导入 Ks 值的映射。按传入顺序列出。

抛出:

ValueError -- 报告含 BANNED_TERMS 中的词。

返回类型:

str

异常

片段相互作用能工作流抛出的类型化异常。

exception q2m3.fragments.errors.FragmentWorkflowError

片段工作流不能为输入给出有效结果。

exception q2m3.fragments.errors.ActiveSpaceMismatchError

单体活性空间与二聚体活性空间不对应。

exception q2m3.fragments.errors.ReferenceImportError

导入的参考表不符合要求的格式。

exception q2m3.fragments.errors.ExternalProgramError

外部量子化学程序不可用，或没有运行完成。