架构

包边界

q2m3 为 QPE、溶剂化、SQD 和片段相互作用能提供独立入口。图中展示主要计算依赖。

        flowchart TB
    accTitle: q2m3 package architecture
    accDescr: Fragment interaction workflows call the integral SQD solver and core resource estimates. Solvation retains a separate Catalyst and Monte Carlo path.

    user["User scripts"]
    fragments["fragments<br/>counterpoise, AVAS, references, reports"]
    sqd["sqd<br/>sampling and subspace diagonalization"]
    core["core<br/>QPE, QM/MM, RDM, resource estimates"]
    interfaces["interfaces<br/>PySCF and PennyLane conversion"]
    solvation["solvation<br/>Catalyst circuits and MC orchestration"]
    sampling["sampling<br/>water geometry, MC moves, MM terms"]
    profiling["profiling<br/>memory, timing, IR diagnostics"]
    utils["utils<br/>I/O and plotting"]

    user --> fragments
    user --> sqd
    user --> core
    user --> solvation
    user --> profiling
    user --> utils
    fragments --> sqd
    fragments --> core
    sqd --> interfaces
    core --> interfaces
    solvation --> core
    solvation --> interfaces
    solvation --> sampling
    solvation --> profiling
    

软件包	职责
q2m3.fragments	片段输入、counterpoise 子体系、活性空间、相互作用能和报告。
q2m3.sqd	LUCJ 采样、子空间求解器、参考等级、输入来源和资源限制。
q2m3.core	QPE 电路、QM/MM 编排、RDM、量子资源估算和设备选择。
q2m3.interfaces	化学数据转换、固定 MO 嵌入和密度矩阵。
q2m3.solvation	Catalyst 电路构建、IR 缓存、MC 执行和溶剂化分析。
q2m3.sampling	经典 MC 移动、水分子几何和 MM 力场辅助函数。
q2m3.profiling	运行时间、内存和编译测量。
q2m3.utils	文件读写和绘图。

片段工作流

q2m3 延迟导出 q2m3.run 和 q2m3.Molecule。它们分别指向 q2m3.fragments.workflow.run 和 q2m3.fragments.molecule.Molecule。工作流接收几何，可指定两个片段的划分。它不调用 QuantumQMMM 或溶剂化编排器。

对于二聚体，counterpoise 在二聚体基组中构建 AB、A 和 B。每个单体以虚原子形式保留另一片段的基函数。单分子使用子体系 M。

        flowchart TD
    accTitle: Fragment interaction energy workflow
    accDescr: Both modes run RHF, validate AVAS spaces, and compute MP2. Full mode adds budgeted CCSD(T), integral SQD, and resource estimates.

    molecule["Molecule + AVAS labels and threshold"]
    cp["RHF: AB, A, B or M"]
    avas["AVAS selection<br/>ghost checks and preflight<br/>dimer-monomer correspondence"]
    classical["HF and frozen-core MP2"]
    mode{"mode"}
    full["budgeted frozen-core CCSD(T)<br/>active-space integrals and context"]
    child["one child interpreter<br/>serial CCSD seeds and integral SQD jobs"]
    resources["QPE cost and SQD resource estimates"]
    result["SubsystemResult or FragmentInteractionResult"]
    report["render_report<br/>derived Markdown report"]

    molecule --> cp --> avas --> classical --> mode
    mode -->|classical_only| result
    mode -->|full| full --> child --> resources --> result
    result --> report
    

两种模式均在关联计算前检查 AVAS 空间。二聚体计算还检查单体空间与二聚体空间的对应关系。不匹配时抛出 ActiveSpaceMismatchError。

classical_only 计算 HF 和冻结芯 MP2，不构建 SQD 执行器。full 需要 SQD extra。它增加以下计算：

1. 预测成本符合 CCSDTBudget 时，计算冻结芯 CCSD(T) 参考。

2. 为各子体系构建活性空间积分和 IntegralContext。

3. 为各子体系构建 CCSD 种子并执行 SQD。

4. 从这些积分估算 QPE 成本、SQD 工作量和内存。

预算拒绝 CCSD(T) 时，参考值保持缺失并附带原因。QPE 估算使用双因子分解，不执行 QPEEngine 电路。

执行与结果边界

SubprocessSQDRunner 为所有子体系任务启动一个子解释器。子解释器串行执行任务。其 OpenMP、MKL、OpenBLAS 和 Rayon 线程数均为一。父进程保留原线程设置。

子解释器在调用 run_sqd_from_integrals 前构建各 CCSD 种子。SQD 使用自身的监督执行器、资源上限和参考策略。首个任务失败后不再执行后续任务。父进程传递失败并清理本阶段进程。

各能量层均以 Hartree 计算 E(AB) - E(A) - E(B)。任一子体系能量缺失时，该相互作用能也缺失。只有 T0 exact_casci 基准可提供 e_casci。结果保留各完整 SQDResult、来源记录、警告和缺失原因。

误差分解区分算法、活性空间、基组和模型差异。同基组参考优先使用计算得到的 CCSD(T)。CCSD(T) 缺失时使用导入参考。输入缺失时，相应误差保持缺失。render_report 从结果生成 Markdown 报告。导入的实验 Ks 值与结果并列展示，不附带统计结论。

可选片段工具

以下工具需要显式调用。run 不调用它们：

• structure 读取实验二聚体、规范 X-H 键长，并支持 DFT-D3(BJ) 几何优化。

• external.psi4 使用外部 Psi4 解释器执行 HF counterpoise 对照。

• diagnostics.entropy 计算 DMRG 轨道熵和互信息。

importers 读取 CSV 或 QCSchema 参考能量。调用者传入参考文件路径时，run(references=...) 调用该导入器。

这些工作流不实现可极化 MM 或 SQD-MC 循环。片段相互作用能不是溶剂化自由能。

QPE 与溶剂化

QuantumQMMM.compute_ground_state 通过 PySCF/PennyLane 转换器构建哈密顿量。它调用 QPEEngine 估算能量，也可请求 RDM 测量。没有 PennyLane 哈密顿量时，经典回退路径用于检查 QM/MM 数据流程。

溶剂化使用独立编排器，支持 fixed、hf_corrected 和 dynamic 模式。Catalyst 编译电路结构以供重复执行。IR 缓存键包含分子、基组、活性空间、估算线数、Trotter 深度、电路类型和嵌入模式。动态更新只改变对角系数。非对角项可能改变算符集合，因此完整单电子嵌入要求固定哈密顿量。能量模型和物理限制见 核心概念。

device_type="auto" 选择可用的 PennyLane 设备。Catalyst 执行另由 JAX/Catalyst 后端决定。仅有 Lightning GPU 设备名称，不能证明编译电路在 GPU 上执行。

SQD 入口

几何入口构建真空 RHF 框架、活性空间积分和 CCSD 种子。积分入口接收这些数据及经过认证的 IntegralContext 和 CCSDSeed。片段工作流将 AVAS 选择的子体系哈密顿量交给积分入口。两个入口共享 SQD 执行器。

执行器检查框架和哈密顿量哈希、张量形状、对称性、常数、能量和残差。它使用共享墙钟截止时间，轮询进程树 RSS。调用 run_sqd_from_integrals 前的预处理不在该调用的资源测量范围内。平台与校准限制见 基于采样的量子对角化（SQD）。

源码位置

以下路径相对于 src/q2m3。

职责	源码
片段公开入口与编排	__init__.py, fragments/workflow.py
几何、counterpoise 和 AVAS 检查	fragments/molecule.py, fragments/counterpoise.py, fragments/active_space.py
积分组装与经典参考	fragments/integrals.py, fragments/references.py
SQD 子进程与数据传递	fragments/sqd_stage.py, fragments/_sqd_child.py, sqd/transport.py
结果、导入参考与报告	fragments/result.py, fragments/importers.py, fragments/report.py
资源估算	fragments/resources.py, core/resource_estimation.py, sqd/resources.py
QPE 与溶剂化入口	core/quantum_qmmm.py, solvation/orchestrator.py