SQD：H₂、甘氨酸与嵌入¶
依次运行这些示例，检查几何输入、积分输入和固定电荷嵌入。基于采样的量子对角化（SQD） 说明安装限制、参考等级和结果解释。
前提条件¶
在 Linux x86_64 源码仓库中使用 Python 3.11 或更新版本运行。生产监督执行器使用 /proc 和 fork，其校准资源模型不覆盖其他平台。已发布基准配置使用 Python 3.12。安装锁定版本的 SQD 和开发环境：
uv sync --frozen --extra sqd --extra dev
export OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1
export NUMEXPR_NUM_THREADS=1 JAX_PLATFORMS=cpu
在 Python 启动前设置线程变量。SQD 使用 CPU，不需要 Catalyst 或 GPU。以下命令使用 512 次采样，以便快速演示。examples/sqd/README.md 中的实测基准使用 100,000 次采样。
备注
每条命令在 data/output/examples/ 下新建目录并打印路径。需要可预期的位置时，使用 --output NEW_PATH。该路径必须尚不存在。
1. 建立 H₂ 约定¶
从最小完整活性空间开始：
uv run --no-sync python -m examples.sqd.h2_ground_state --shots 512
脚本调用 q2m3.sqd.run_sqd，计算 H₂/STO-3G，使用 CAS(2e,2o)、四个系统量子比特、两次 LUCJ 重复和种子 31。采样得到的四个行列式覆盖完整固定粒子数空间。预期 T0 exact_casci 参考计算完成，且 SQD 在接近数值精度的范围内与其一致。
该结果验证张量约定、能量常数、采样转换和结果序列化。恢复全空间不能证明采样优势。
2. 运行稀疏甘氨酸 SQD¶
演示使用最小甘氨酸活性空间：
uv run --no-sync python -m examples.sqd.glycine_ground_state \
--active-space 6 --shots 512
甘氨酸可选 CAS(6e,6o)、CAS(8e,8o) 和 CAS(10e,10o)，分别使用 12、16 和 20 个系统量子比特。完整闭壳层行列式空间分别包含 400、4,900 和 63,504 个 alpha/beta 对。每种选择构建不同的哈密顿量和参考计算，因此跨行总能量不能衡量 SQD 收敛性。
3. 测量种子离散程度¶
对 CAS(6e,6o) 运行五个连续种子：
uv run --no-sync python -m examples.sqd.glycine_active_space_scan \
--active-spaces 6 --shots 512
扫描对每个点启动新解释器，并串行运行。它立即保存每个成功点，记录失败；只要请求的任一点失败，就以非零状态退出。不带 --active-spaces 的默认命令运行全部三个活性空间，共 15 次计算。
使用 statistics.json 查看已执行 T0 行的均值、样本标准差和范围。这些是五个确定种子选择的描述性统计，不是置信区间。缺失或降级点不会进入精确参考曲线。
4. 验证积分适配器¶
底层入口仅在同时提供经过认证的轨道框架和种子时，才接受已组装的哈密顿量：
uv run --no-sync python -m examples.sqd.glycine_from_integrals \
--active-space 6 --shots 512
示例通过 build_integrals 创建 IntegralData，再通过 build_ccsd_seed 创建同轨道框架的 CCSDSeed。它将 h1、chemist 顺序的 h2、e_core、IntegralContext 和种子传给 run_sqd_from_integrals。脚本还运行几何入口，并比较六个报告能量字段。数值必须在绝对容差 1e-8 Ha 内一致。仅当两个结果都报告 None 时，字段才可以为 None。轨道框架、哈密顿量和活性轨道索引标识必须完全一致。
两个入口共用同一 SQD 求解器。一致结果验证适配器和组装的一致性，不构成独立数值判据。不要转置 h2 或再次添加 e_core。裸 t1 和 t2 数组不能替代 CCSDSeed。
积分和 CCSD 预处理发生在底层引擎调用前，因此不计入该调用的 timings_s["total"] 和内嵌峰值 RSS。需要覆盖此边界时，使用完整进程监测器：
uv run --no-sync python - <<'PY'
import sys
from pathlib import Path
from q2m3.profiling import measure_command
record = measure_command(
[
sys.executable,
"-m",
"examples.sqd.glycine_from_integrals",
"--active-space",
"6",
"--shots",
"512",
],
Path("data/output/examples/tutorial-monitor"),
)
print(record)
if not (record["exit_code"] == 0 and record["reason"] is None):
raise RuntimeError(f"Command failed: {record}")
PY
从仓库根目录运行该示例，以便 Python 导入 examples。包 API 本身不要求源码仓库。每次运行选择新的监测路径。只检查监测器而不做科学计算时，将命令列表替换为 [sys.executable, "-c", "print('monitor check')"]。
监测器每 10 ms 轮询 Linux /proc。它测量命令进程及每次轮询可见的后代，覆盖导入、序列化和绘图。测量不包括观察者进程。轮询可能漏掉短暂峰值。
监测器复制调用者环境，将 OMP、MKL、OpenBLAS 和 NumExpr 线程数设为 1，并设置 JAX_PLATFORMS=cpu。显式 env 映射按键覆盖这些默认值。默认 cwd 是调用者工作目录。默认预算为 900 秒和 8192 十进制 MB。
返回值和 resources.json 恰好包含以下十个键：
键 |
含义 |
|---|---|
|
命令参数列表 |
|
子进程退出码 |
|
监测器终止原因，或 |
|
观测到的实际经过时间，单位秒 |
|
采样到的最大进程树 RSS，单位十进制 MB |
|
轮询间隔，单位秒： |
|
RSS 预算，单位十进制 MB |
|
实际时间预算，单位秒 |
|
观测的进程范围 |
|
采样限制 |
新目录还包含将 stderr 合并到 stdout 的 stdout.log，以及记录 [elapsed_seconds, rss_bytes] 样本的 rss.jsonl。仅当退出码和原因均表示成功时，才接受科学输出。
5. 比较固定分子轨道嵌入模式¶
水分子验证使用两个非对称人工点电荷，比较对角嵌入和完整单电子嵌入：
uv run --no-sync python -m examples.qmmm.h2o_sqd_validation --shots 512
甘氨酸示例在同一个真空分子轨道框架内比较真空、对角和完整单电子处理：
uv run --no-sync python -m examples.qmmm.glycine_sqd_embedding \
--active-space 6 --shots 512
嵌入运行中，坐标单位为 Å，点电荷单位为元电荷，能量单位为 Hartree。两种模式均保持真空分子轨道框架和双电子张量不变。diagonal 仅添加活性空间 Delta h_pp；full_oneelectron 保留完整 Delta h_pq 扰动。e_core 已包含 MM 引起的核能和冻结核心校正。
分别解读两种效应：
baseline_energy(mode) - baseline_energy(vacuum)为固定哈密顿量参考能量平移，其质量取决于各参考计算。delta_mHa(mode) - delta_mHa(vacuum)为 SQD 求解器残差的变化。
这些电荷是固定测试环境。示例不包含轨道弛豫、MM 极化、溶剂采样、相关 RDM 反馈、SQD-MC 循环或溶剂化自由能。
读取产物¶
H₂、甘氨酸、积分和甘氨酸嵌入运行写入 input.json、完整结果 JSON、summary.json、summary.csv，以及 PNG 和 SVG 能量 / 成本图。H₂O 验证则写入 report.json、各模式结果和下游包装器 JSON、汇总及比较图。扫描为每个点添加子目录和日志，并生成 statistics.json。积分示例还添加 assembly.json 和 consistency.json。失败时保留已完成产物，并写入 failure.json。
关键结果字段如下：
字段 |
解释 |
|---|---|
|
|
|
采样子空间能量，单位 Hartree（仅参考运行时缺失） |
|
实际参考路径。只有 T0 在活性空间内精确 |
|
|
|
采样笛卡尔积行列式空间和完整固定粒子数空间 |
|
有序求解器选择 / 执行审计 |
|
配置、轨道框架、哈密顿量、种子及输入来源 |
|
各阶段计时，并明确说明未运行阶段的原因 |
|
轮询的引擎进程 RSS 范围、上限和计时边界 |
|
缺失值或降级值的必要说明 |
保留完整 SQDResult 或其序列化 sqd.result.v1 对象。没有方法、层级、活性空间、轨道框架、哈密顿量、单位和不确定性含义的能量，不能作为可审计结果。
资源失败与仅参考运行¶
ReferenceConfig 设置统一的实际时间截止点和十进制 MB RSS 预算。执行器取用户预算、当前主机可用内存及 8192 MB 组件硬上限中的最低值。预测值达到上限时，会在分配前拒绝。观测进程树 RSS 达到上限时，监督执行器终止运行。allow_large=True 只能跨越软策略边界，不能绕过校准域、主机可用量或硬上限。
需要有意仅计算基准而不采样时，传入 mode="reference_only"。结果记录缺失采样字段及原因。失败的完整运行不会静默变成仅参考运行，也不会用 HF 替代 SQD。