基于采样的量子对角化（SQD）¶
SQD 使用 ffsim 采样以 CCSD 为种子的 LUCJ 态。它用 qiskit-addon-sqd 求解恢复的子空间。两个公开入口均返回 SQDResult，其中各项对比使用同一哈密顿量。这种经典模拟不证明量子优势或硬件执行。
安装与平台¶
在 Linux x86_64 上使用此源码仓库运行 SQD 实现和示例：
uv sync --frozen --extra sqd
export OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1
export NUMEXPR_NUM_THREADS=1 JAX_PLATFORMS=cpu
公开监督执行器使用 /proc 及带 fork 的 multiprocessing，因此要求 Linux x86_64。它会在执行前拒绝其他平台。
sqd extra 安装 ffsim 和 qiskit-addon-sqd。Catalyst 为可选项。使用 uv.lock 复现依赖版本。
src/q2m3/sqd/resource_calibration.json 定义实测资源模型和依赖版本。模型不覆盖其他平台或任意依赖版本。若安装 Catalyst，其版本必须匹配校准版本。也可以不安装 Catalyst。
按 SQD：H₂、甘氨酸与嵌入 依次运行示例。函数签名和配置类型见 SQD API。
普通 import q2m3 仍导入 PennyLane。SQD 算法不调用 PennyLane 或 Catalyst。SQD 工作流导出在访问时加载。缺少可选依赖时，它们抛出带安装命令的 ImportError。检查可用性时，测试 "run_sqd" in q2m3.__all__。不要使用 hasattr，因为它可能触发该错误。配置和结果类型不导入 ffsim 或 Qiskit。
两个可运行的公开入口¶
将任一 Python 代码块保存为文件。完成上述安装后，运行 uv run --no-sync python FILE.py。两者均使用 0.74 Å/STO-3G 的 H₂，并显式指定 (2 electrons, 2 spatial orbitals)，对应四个系统量子比特。小规模 128 次采样冒烟案例使用种子 31 和两次 LUCJ 重复，达到完整的四行列式空间。与 CASCI 一致属于回归检查，不能证明采样优于经典求解器。
几何入口构建积分及同轨道框架的 CCSD 种子：
import numpy as np
from q2m3 import run_sqd
from q2m3.sqd import LUCJConfig
result = run_sqd(
["H", "H"],
np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.74]]),
active_electrons=2,
active_orbitals=2,
basis="sto-3g",
lucj=LUCJConfig(n_reps=2, shots=128),
seed=31,
verbose=False,
)
result.validate()
assert result.baseline_tier == "T0"
assert abs(result.sqd_energy - result.baseline_energy) < 1e-10
print(result.sqd_energy, result.baseline_method, result.delta_mHa)
积分入口接受已组装的 chemist 顺序张量。本示例使用具有资源保护的生成函数，提供经过认证的轨道框架和 CCSD 数据。host_available_mb 是保守内存上限，不是要求分配等量内存。此处以当前 Linux 可用内存限制它。
from pathlib import Path
from q2m3.molecule import MoleculeConfig
from q2m3.sqd import LUCJConfig, run_sqd_from_integrals
from q2m3.sqd.ansatz import build_ccsd_seed
from q2m3.sqd.integrals import build_integrals
available_kib = next(
int(line.split()[1])
for line in Path("/proc/meminfo").read_text().splitlines()
if line.startswith("MemAvailable:")
)
cap_mb = min(4096.0, available_kib * 1024 / 1e6)
molecule = MoleculeConfig(
name="H2", symbols=["H", "H"],
coords=[[0.0, 0.0, 0.0], [0.0, 0.0, 0.74]],
charge=0, active_electrons=2, active_orbitals=2,
)
data = build_integrals(molecule, host_available_mb=cap_mb)
seed_data = build_ccsd_seed(data, host_available_mb=cap_mb)
result = run_sqd_from_integrals(
data.h1, data.h2, data.e_core,
norb=data.norb, nelec=data.nelec,
context=data.context, seed_data=seed_data,
lucj=LUCJConfig(n_reps=2, shots=128), seed=31,
)
result.validate()
assert result.baseline_tier == "T0"
assert abs(result.sqd_energy - result.baseline_energy) < 1e-10
print(result.sqd_energy, result.baseline_method, result.delta_mHa)
在实测配置中，两个示例均得到约 −1.13728383449 Ha。run_sqd_from_integrals 要求传入 context。裸 t1/t2 数组不能替代 CCSDSeed。求解器检查以下输入：
形状
有限数值
平衡电子数
哈密顿量 / 轨道框架标识
HF/CCSD 能量
CCSD 残差
种子失败或未收敛时抛出错误。有意仅运行基准时，设置 mode="reference_only"，并在积分入口设置 seed_data=None。工作流绝不会静默用 HF 替代失败的 SQD 运行。
固定轨道框架与 MM 嵌入¶
坐标包括 mm_coords，单位为 Å。mm_charges 单位为元电荷。能量和积分常数单位为 Hartree。高层入口接受两组 MM 数组，以及 embedding_mode="diagonal"``（默认）或 ``"full_oneelectron"。后者要求 MM 电荷。真空分子轨道框架和双电子张量保持不变。对角模式仅添加活性空间对角单电子项，完整模式还保留非对角项。
各求解分支共享活性空间、哈密顿量、框架和芯常数。e_core 已包含 MM 核贡献，底层入口不得再次添加。底层 h2 使用化学家顺序，不再次转置。在嵌入的固定框架中，hf_energy 表示参考行列式期望值，不是弛豫嵌入 SCF 最小值。测试覆盖静态 MM 和 H₂O 适配器。此实现不包含 SQD MC 集成、关联 RDM 反馈或可极化 MM。
参考阶梯与结果使用方¶
ReferenceConfig 默认设置为 900 秒和 8192 十进制 MB。参考阶梯的各次尝试共享剩余预算：
层级 |
方法 |
含义 |
|---|---|---|
T0 |
|
在该有限活性哈密顿量内精确 |
T1 |
选择 CI |
严格截断结果。截断差异不能界定其误差 |
T1+ |
显式启用的插件 |
求解器特定近似与不确定性 |
T2 |
CCSD(T) |
带诊断和可信性标记的近似后备计算 |
不得通过禁用 T0 强制降级。仅在明确不可用、预算耗尽或受控超时时，才允许尝试较低层级。工作流必须报告数值失败。每个非 T0 结果均包含 baseline_downgrade_reason 和警告。
不确定性未知时，结果记录 None 及原因，不得记录零。T2 报告 T1 诊断、收敛、三重激发校正及三重激发 / 相关能比值。标记可将它判为不可信。T0 不确定性为零不包含基组、模型或实验误差。
使用 baseline_energy、baseline_method、baseline_tier、baseline_uncertainty_mHa、baseline_downgrade_reason、warnings 和 null_reasons。输出模式 sqd.result.v1 有 40 个字段，只写入规范的 baseline_* 键。旧 shci_energy 数值本身无法说明它来自 CASCI 还是 SHCI。读取方必须要求显式方法、层级、单位和不确定性含义，并拒绝冲突别名。
delta_mHa = 1000 * (sqd_energy - baseline_energy) 和 delta_vs_sci_mHa = 1000 * (sqd_energy - iso_ndet_sci_energy)：正值表示 SQD 更差。ratio_sqd_over_sci 仅在 T0 及有效非零 SCI 误差下定义。SCI 和随机分支匹配每种自旋的子空间维数。subspace_dim 是其笛卡尔积。unique_dets_vs_shots 统计采样对，是另一种量。
仅参考输出对未执行的采样 / 对照字段记录 None 和明确原因。q2m3.utils.io 中的 save_json_results 接受完整数据类，并保留这些字段。它拒绝非有限 JSON 值。
资源限制¶
校准后的 Linux 模型要求串行执行和平衡闭壳层。适用域允许：
2–10 个活性轨道。
每个自旋最多 252 个行列式，总计最多 63504 个行列式对。
最多 36 个 UCJ 因子、两个批次、两次迭代和 100000 次采样。
各阶段的其他输入与适用域检查仍然有效。公开对角化使用两个批次、两次迭代，每批 min(300, shots) 个样本。未知或域外边界会在分配前抛出 ResourceModelDomainError。allow_large 无法绕过适用域、主机上限或硬上限。
分配策略在 2048 MB 发出警告，通常在 8192 MB 拒绝。其绝对上限为 12288 MB。公开执行器另设 8192 MB 组件上限。有效限制取组件、主机和用户上限的最小值。预测达到有效限制时，程序在分配前拒绝。allow_large 无法绕过该限制。
所有限制使用十进制 MB。历史基准判据为 peak_bytes < 2_000_000_000。