SQD API

SQD API 为可选项。使用 uv sync --frozen --extra sqd 安装。配置与结果类型无需可选采样后端即可导入。环境包含 ffsim 和 qiskit-addon-sqd 时，工作流函数在访问时加载。

公共工作流

q2m3.sqd.orchestrator.run_sqd(symbols, coordinates, *, active_electrons, active_orbitals, charge=0, basis='sto-3g', lucj=None, reference=None, mm_charges=None, mm_coords=None, embedding_mode='diagonal', seed=0, allow_large=False, verbose=True, mode='full')

从以埃为单位的几何结构运行 SQD，并显式指定闭壳层活性空间。

参数:

• symbols (list[str]) -- 原子元素符号。

• coordinates (ndarray) -- 原子坐标，单位为埃。

• active_electrons (int) -- 偶数个活性电子。

• active_orbitals (int) -- 活性空间轨道数。

• charge (int) -- 分子电荷。

• basis (str) -- PySCF 基组名称。

• lucj (LUCJConfig | None) -- 拟设与采样配置。

• reference (ReferenceConfig | None) -- 基线策略和运行共享的资源预算。

• mm_charges (ndarray | None) -- 可选的点电荷，以原子电荷单位表示。

• mm_coords (ndarray | None) -- 点电荷位置，单位为埃。

• embedding_mode (Literal['diagonal', 'full_oneelectron']) -- 固定参考系中的单电子嵌入处理。

• seed (int) -- 传递给所有随机操作的非负随机种子。

• allow_large (bool) -- 在支持的位置传递软策略覆盖设置。现有组件/模型上限仍然有效，包括 8192 MB。

• verbose (bool) -- 打印简明的能量/状态摘要。

• mode (Literal['full', 'reference_only']) -- 完整 SQD 计算或显式请求的仅参考计算。

返回:

已验证的不可变能量、元数据和资源/计时审计记录。

抛出:

• ValueError -- 不支持输入或执行环境。

• ResourceLimitError -- 内存分配量或观测到的进程 RSS 达到上限。

• ReferenceTimeoutError -- 共享的总执行时限到期。

返回类型:

SQDResult

q2m3.sqd.orchestrator.run_sqd_from_integrals(h1, h2, e_core, *, norb, nelec, context, seed_data, lucj=None, reference=None, seed=0, allow_large=False, mode='full')

从实数化学家记号积分和已验证的来源记录运行同一工作流。

参数:

• h1 (ndarray) -- 实数单电子积分，单位为 Hartree。

• h2 (ndarray) -- 化学家记号的实数双电子张量，不再进行任何额外转置。

• e_core (float) -- 核心常数，单位为 Hartree，已包含嵌入修正。

• norb (int) -- 活性空间轨道数。

• nelec (tuple[int, int]) -- 相等的 alpha/beta 电子数。

• context (IntegralContext) -- 积分/参考系标识符及常数分解。

• seed_data (CCSDSeed | None) -- 同一参考系中的 CCSD 初始解。仅在仅参考模式下使用 None。

• lucj (LUCJConfig | None) -- 拟设与采样配置。

• reference (ReferenceConfig | None) -- 基线策略和共享的总资源预算。

• seed (int) -- 非负的运行随机种子。

• allow_large (bool) -- 在现有组件上限内传递受支持的覆盖设置。

• mode (Literal['full', 'reference_only']) -- 完整 SQD 计算或显式指定的仅参考计算。

返回:

已验证的不可变结果，能量中恰好计入一次 e_core。

抛出:

• ValueError -- 所声明的积分契约无效。

• ResourceLimitError -- 预测或实际资源用量超出预算。

• ReferenceTimeoutError -- 共享的总执行时限到期。

返回类型:

SQDResult

配置契约

class q2m3.sqd.LUCJConfig(n_reps=2, shots=100000, interaction_pairs=None)

自旋平衡的拟设与采样配置。

参数:

• n_reps (int)

• shots (int)

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

validate()

验证数量和连接结构，并返回此实例。

返回类型:

LUCJConfig

class q2m3.sqd.ReferenceConfig(wall_budget_s=900.0, rss_budget_mb=8192.0, allowed_tiers=('T0', 'T1', 'T1+', 'T2'), plugins=(), sci_cutoffs=(0.0001, 1e-05))

参考求解器预算、允许的层级和有序的可选插件。

参数:

• wall_budget_s (float)

• rss_budget_mb (float)

• allowed_tiers (tuple[Literal['T0', 'T1', 'T1+', 'T2'], ...])

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

• sci_cutoffs (tuple[float, float])

validate()

验证预算为有限值且截断值严格递减。返回自身。

返回类型:

ReferenceConfig

class q2m3.sqd.SQDConfig(molecule, lucj=<factory>, reference=<factory>, embedding_mode='diagonal', seed=0, allow_large=False, mode='full')

SQD 运行配置。分子保留现有的可变语义。

参数:

• molecule (MoleculeConfig)

• lucj (LUCJConfig)

• reference (ReferenceConfig)

• embedding_mode (Literal['diagonal', 'full_oneelectron'])

• seed (int)

• allow_large (bool)

• mode (Literal['full', 'reference_only'])

validate()

验证分子和运行输入，并返回此实例。

返回类型:

SQDConfig

snapshot()

在调用时获取独立的不可变配置快照。

返回:

适用于运行时来源记录的递归冻结映射。

抛出:

ValueError -- 配置包含非有限值或非 JSON 元数据。

返回类型:

Mapping[str, Any]

class q2m3.sqd.IntegralContext(frame_id, hamiltonian_id, active_indices, n_core_orbitals, vacuum_core_constant, delta_core_constant, embedding_mode, fixed_mo, two_electron_tensor_fixed, hf_reference_kind, source)

描述所提供的固定轨道哈密顿量的不可变元数据。

参数:

• frame_id (str)

• hamiltonian_id (str)

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

• n_core_orbitals (int)

• vacuum_core_constant (float)

• delta_core_constant (float)

• embedding_mode (Literal['vacuum', 'diagonal', 'full_oneelectron'])

• fixed_mo (bool)

• two_electron_tensor_fixed (bool)

• hf_reference_kind (Literal['canonical_rhf', 'fixed_frame_determinant'])

• source (Mapping[str, Any])

class q2m3.sqd.CCSDSeed(t1, t2, hf_energy, ccsd_energy, converged, residual_max_abs_ha, frame_id, hamiltonian_id, solver, solver_version)

已复制的只读 RCCSD 振幅及所声明的求解器来源记录。

参数:

• t1 (ndarray)

• t2 (ndarray)

• hf_energy (float)

• ccsd_energy (float)

• converged (bool)

• residual_max_abs_ha (float)

• frame_id (str)

• hamiltonian_id (str)

• solver (str)

• solver_version (str)

结果契约

字段单位与缺失值规则见 SQD 结果字段。

class q2m3.sqd.SQDResult(schema_version, status, sqd_energy, hf_energy, hf_reference_kind, baseline_energy, iso_active_space_ccsd_energy, iso_ndet_sci_energy, iso_ndet_random_energy, baseline_tier, baseline_method, baseline_uncertainty_mHa, baseline_uncertainty_kind, baseline_downgrade_reason, baseline_untrustworthy, baseline_t1_residual, t1_diagnostic, t2_diagnostics, reference_attempts, delta_mHa, delta_vs_sci_mHa, ratio_sqd_over_sci, unique_dets_vs_shots, active_space, n_reps, shots, seed, subspace_dim, subspace_dims, full_ci_dim, embedding_mode, two_electron_tensor_fixed, fixed_mo, backend, versions, diagnostics, provenance, timings_s, null_reasons, warnings)

完整的 SQD 报告；未执行的工作以 None 和原因表示。

参数:

• schema_version (Literal['sqd.result.v1'])

• status (Literal['completed', 'reference_only'])

• sqd_energy (float | None)

• hf_energy (float)

• hf_reference_kind (str)

• baseline_energy (float)

• iso_active_space_ccsd_energy (float | None)

• iso_ndet_sci_energy (float | None)

• iso_ndet_random_energy (float | None)

• baseline_tier (Literal['T0', 'T1', 'T1+', 'T2'])

• baseline_method (str)

• baseline_uncertainty_mHa (float | None)

• baseline_uncertainty_kind (str)

• baseline_downgrade_reason (str | None)

• baseline_untrustworthy (bool)

• baseline_t1_residual (T1Residual | None)

• t1_diagnostic (float | None)

• t2_diagnostics (T2Diagnostics | None)

• reference_attempts (tuple[ReferenceAttempt, ...])

• delta_mHa (float | None)

• delta_vs_sci_mHa (float | None)

• ratio_sqd_over_sci (float | None)

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

• active_space (tuple[int, int])

• n_reps (int | None)

• shots (int | None)

• seed (int)

• subspace_dim (int | None)

• subspace_dims (tuple[int, int] | None)

• full_ci_dim (int)

• embedding_mode (str)

• two_electron_tensor_fixed (bool)

• fixed_mo (bool)

• backend (str | None)

• versions (Mapping[str, str])

• diagnostics (Mapping[str, Any])

• provenance (Mapping[str, Any])

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

• null_reasons (Mapping[str, str])

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

validate()

验证数据为有限值、参考结果语义以及执行一致性。

返回:

此不可变结果。

抛出:

ValueError -- 某字段与结果模式或已执行模式冲突。

返回类型:

SQDResult

class q2m3.sqd.ReferenceResult(energy, tier, method, uncertainty_mHa, uncertainty_kind, uncertainty_reason, downgrade_reason, t1_residual, t2, untrustworthy, hamiltonian_id, frame_id, attempts, warnings)

包含明确不确定性和执行来源记录的参考能量。

参数:

• energy (float)

• tier (Literal['T0', 'T1', 'T1+', 'T2'])

• method (str)

• uncertainty_mHa (float | None)

• uncertainty_kind (Literal['exact_active_space', 'solver_estimate', 'unknown'])

• uncertainty_reason (str | None)

• downgrade_reason (str | None)

• t1_residual (T1Residual | None)

• t2 (T2Diagnostics | None)

• untrustworthy (bool)

• hamiltonian_id (str)

• frame_id (str)

• attempts (tuple[ReferenceAttempt, ...])

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

validate()

验证参考元数据和诊断信息，并返回此记录。

返回类型:

ReferenceResult

class q2m3.sqd.ReferenceAttempt(tier, method, outcome, reason, wall_s, peak_rss_mb)

一项可审计的参考选择或执行结果。

参数:

• tier (Literal['T0', 'T1', 'T1+', 'T2'])

• method (str)

• outcome (Literal['selected', 'disabled', 'unavailable', 'out_of_domain', 'over_budget', 'timeout', 'success'])

• reason (str | None)

• wall_s (float)

• peak_rss_mb (float | None)

validate()

验证结果和以十进制 MB 计量的数值，并返回此记录。

返回类型:

ReferenceAttempt

class q2m3.sqd.T1Residual(loose_cutoff, tight_cutoff, loose_energy, tight_energy, loose_residual_mHa, reason)

相邻截断值之间的残差，归于已执行的较宽松截断点。

参数:

• loose_cutoff (float | None)

• tight_cutoff (float)

• loose_energy (float | None)

• tight_energy (float)

• loose_residual_mHa (float | None)

• reason (str | None)

validate()

检查截断值顺序和残差，并返回此记录。

返回类型:

T1Residual

class q2m3.sqd.T2Diagnostics(t1_diagnostic, ccsd_converged, triples_correction_ha, ccsd_correlation_energy_ha, triples_ratio, high_t1, ccsd_not_converged, high_triples, ratio_reason)

T2 基线的独立耦合簇可靠性标志。

参数:

• t1_diagnostic (float)

• ccsd_converged (bool)

• triples_correction_ha (float)

• ccsd_correlation_energy_ha (float)

• triples_ratio (float | None)

• high_t1 (bool)

• ccsd_not_converged (bool)

• high_triples (bool)

• ratio_reason (str | None)

validate()

逐一根据对应诊断检查各标志，并返回此记录。

返回类型:

T2Diagnostics

经来源验证的积分构建

这些底层函数生成 run_sqd_from_integrals 所需的来源记录。积分张量使用实数化学家顺序。求解器只加一次 e_core。

class q2m3.sqd.integrals.IntegralData(h1, h2, e_core, norb, nelec, mo_coeff, hf_energy, context)

不可变的化学家记号哈密顿量、完整 MO 快照及其来源记录。

hf_energy 是前 nelec[0] 个活性轨道的期望值，包含 e_core。它不是经 MM 松弛的 SCF 极小值。此处不构建 CCSD 振幅。下游初始解求解器必须使用同一个哈密顿量。

参数:

• h1 (ndarray)

• h2 (ndarray)

• e_core (float)

• norb (int)

• nelec (tuple[int, int])

• mo_coeff (ndarray)

• hf_energy (float)

• context (IntegralContext)

q2m3.sqd.integrals.build_integrals(molecule, *, mm_charges=None, mm_coords=None, embedding_mode='diagonal', host_available_mb, rss_budget_mb=8192.0, allow_large=False)

在分子唯一的真空 RHF 参考系中构建带保护检查的哈密顿量。

参数:

• molecule (MoleculeConfig) -- 以埃为单位的分子几何结构和显式指定的闭壳层空间。

• mm_charges (ndarray | None) -- 可选的非空点电荷数组，单位为元电荷。

• mm_coords (ndarray | None) -- 对应坐标，单位为埃。

• embedding_mode (Literal['diagonal', 'full_oneelectron']) -- 对角或完整活性空间单电子微扰。

• host_available_mb (float) -- 执行器为整次运行设置的保守内存上限，以十进制 MB 计。

• rss_budget_mb (float) -- 用户为整次运行设置的内存上限，以十进制 MB 计。

• allow_large (bool) -- 仅覆盖标准的资源软拒绝边界。

返回:

只读积分/MO，以及同一参考系中包含来源记录的 HF 期望值。

抛出:

• ValueError -- 输入格式错误、缺少辅助参考系或积分无效。

• RuntimeError -- RHF 未收敛。

• ResourceLimitError -- 分配前估计值达到运行上限。

• ResourceModelDomainError -- 实数 AO 工作超出有界资源清单的范围。

返回类型:

IntegralData

必须使用外部进程树 RSS 监控器和墙钟超时。首先构建分子基组元数据以统计 AO 数。随后在任何 RHF 或积分变换之前运行资源清单保护检查。其估计值记录在 source 中，不能据此确认后续采样/参考阶段或任意主机的资源安全性。

q2m3.sqd.integrals.hamiltonian_id(h1, h2, e_core, *, norb, nelec)

使用 q2m3.hamiltonian.v1 字节格式对实际积分计算哈希。

摘要输入依次以版本号和 NUL、紧凑 ASCII JSON [norb,[nalpha,nbeta]] 和 NUL 开头。h1、h2、e_core 各字段均含紧凑的 [name,shape,"<f8"] JSON 头和 NUL，随后是小端 float64 的 C 顺序字节。e_core 是形状为 [] 的标量。标签均不参与摘要计算。

参数:

• h1 (ndarray) -- 实数单电子矩阵，单位为 Hartree。

• h2 (ndarray) -- 化学家记号的实数双电子张量，单位为 Hartree。

• e_core (float) -- 核心加核常数，单位为 Hartree。

• norb (int) -- 活性空间轨道数。

• nelec (tuple[int, int]) -- 平衡的自旋电子数。

返回:

小写 SHA256 十六进制摘要，不受存储顺序和字节序影响。

抛出:

ValueError -- 形状、自旋电子数或实数/有限值表示无效。

返回类型:

str

q2m3.sqd.ansatz.build_ccsd_seed(data, *, host_available_mb, rss_budget_mb=8192.0, allow_large=False, max_cycle=200)

在所提供的固定参考系中求解 RCCSD，不重新运行 SCF。

参数:

• data (IntegralData) -- 不可变哈密顿量和完整的分子参考系来源记录。

• host_available_mb (float) -- 执行器为整次运行设置的上限，以十进制 MB 计。

• rss_budget_mb (float) -- 用户为整次运行设置的上限，以十进制 MB 计。

• allow_large (bool) -- 仅覆盖资源软边界。

• max_cycle (int) -- 迭代次数上限，范围为 0..200。设为零时检验不收敛拒绝路径。

返回:

已收敛的只读振幅，包含经独立验证、以 Ha 为单位的残差。

抛出:

• CCSDConvergenceError -- 迭代失败或物理残差不可接受。

• ProvenanceMismatchError -- 所提供的哈密顿量/参考系/能量不一致。

• ResourceLimitError -- 资源清单保护检查拒绝分配内存。

返回类型:

CCSDSeed

q2m3.sqd.ansatz.build_ccsd_seed_from_integrals(h1, h2, e_core, *, norb, nelec, context, host_available_mb, rss_budget_mb=8192.0, allow_large=False, max_cycle=200)

按底层积分契约，在固定轨道框架中求解 RCCSD。

只根据数组重算 context 的哈密顿量哈希。框架摘要不重建，所以 context 与积分之间的 frame_id 绑定由调用方负责。

参数:

• h1 (ndarray) -- 声明框架中的实数单电子积分。

• h2 (ndarray) -- 声明框架中的实数化学家记号双电子张量。

• e_core (float) -- 同一哈密顿量的核心常数，单位为 Hartree。

• norb (int) -- 活性空间轨道数。

• nelec (tuple[int, int]) -- 平衡的自旋电子数。

• context (IntegralContext) -- 框架与哈密顿量的来源记录。source 可以为空。

• host_available_mb (float) -- 执行器为整次运行设置的上限，以十进制 MB 计。

• rss_budget_mb (float) -- 用户为整次运行设置的上限，以十进制 MB 计。

• allow_large (bool) -- 仅覆盖资源软边界。

• max_cycle (int) -- 迭代次数上限，范围为 0..200。设为零时检验不收敛拒绝路径。

返回:

已收敛的只读振幅，带有 context 的标识。

抛出:

• CCSDConvergenceError -- 迭代失败或物理残差不可接受。

• ProvenanceMismatchError -- 积分与 context 的哈密顿量哈希不一致。

• ResourceLimitError -- 资源清单保护检查拒绝分配内存。

返回类型:

CCSDSeed

结果传输

这两个函数把冻结的 SQD 记录编码为带标签的元组。这些元组不需要自定义 reducer 就能 pickle。函数还能在另一个进程中重建记录。

q2m3.sqd.transport.encode_result(value)

把值编码为嵌套的带标签元组。这些元组不需要自定义 reducer 就能 pickle。

数据类记录变为 ("record", module, name, fields)。映射（含只读快照）变为普通字典，所以解码时记录的构造函数必须再次冻结它们。

参数:

value (Any) -- 数据类记录、映射、元组、列表或普通值。

返回:

value 的带标签编码。

返回类型:

tuple

q2m3.sqd.transport.decode_result(value, *, cancelled=None)

重建由 encode_result() 编码的值。

记录经其构造函数重建，所以校验会再次运行。只重建定义在 q2m3.sqd. 下的记录类型。这一限制约束可构造的类型，但不能使不可信的载荷变得安全。调用方只能反序列化父进程写入其私有目录或管道的载荷。

SQDConfig 不能解码：它的 molecule 字段是 q2m3.molecule.MoleculeConfig。

参数:

• value (tuple) -- 带标签的编码。

• cancelled (Event | None) -- 重建每个节点之前检查的标志。

返回:

重建后的值。

抛出:

• ReferenceTimeoutError -- 重建期间 cancelled 被置位。

• ValueError -- 记录类型定义在 q2m3.sqd. 之外。

返回类型:

Any

资源策略

q2m3.sqd.resources.estimate_rss_mb(norb, nelec, *, stage, subspace_dims=None, retained_mb=0.0, solver_method=None, model)

估计单个串行阶段同时驻留的总内存。

参数:

• norb (int) -- 活性空间轨道。

• nelec (tuple[int, int]) -- 平衡的 alpha/beta 电子数。

• stage (Literal['integrals', 'ccsd', 'prepare', 'sample', 'diagonalize', 'reference', 'comparison']) -- 即将分配内存的操作。

• subspace_dims (tuple[int, int] | None) -- 候选自旋扇区大小；固定空间必须提供。

• retained_mb (float) -- 模型工作负载资源清单之外仍在使用的额外输入。

• solver_method (str | None) -- 所需参考求解器的标识。

• model (ResourceModel) -- 已根据运行环境检查的带版本模型。

返回:

以十进制 MB 计的有限值，包括导入、工作区和保留的输入。

抛出:

• ValueError -- 数量或保留内存的格式错误。

• ResourceModelDomainError -- 缺少维度、不支持该阶段或边界无效。

返回类型:

float

q2m3.sqd.resources.guard_allocation(norb, nelec, *, stage, model, host_available_mb, subspace_dims=None, retained_mb=0.0, solver_method=None, rss_budget_mb=None, allow_large=False)

在分配工作空间之前拒绝不安全的操作。

参数:

• norb (int) -- 活性空间轨道。

• nelec (tuple[int, int]) -- 平衡的 alpha/beta 电子数。

• stage (Literal['integrals', 'ccsd', 'prepare', 'sample', 'diagonalize', 'reference', 'comparison']) -- 即将运行的阶段。

• model (ResourceModel) -- 适用的经验模型。

• host_available_mb (float) -- 执行器提供的保守运行总上限。

• subspace_dims (tuple[int, int] | None) -- 实际候选，或经证明的调用前维度上界。

• retained_mb (float) -- 资源清单之外同时在用的额外内存。

• solver_method (str | None) -- 参考求解器标识（如适用）。

• rss_budget_mb (float | None) -- 可选的用户上限。覆盖设置绝不会绕过此上限。

• allow_large (bool) -- 允许估计值超过默认软拒绝边界。

返回:

检查后的估计值，以十进制 MB 计。

抛出:

• ResourceLimitError -- 估计值达到任一适用的拒绝边界。

• ResourceModelDomainError -- 不存在适用的上界，即使启用覆盖设置也不例外。

返回类型:

float

q2m3.sqd.resources.load_resource_model(path=None, *, versions=None, profile=None)

加载已验证的模型，并拒绝不兼容的依赖项或工作负载。

参数:

• path (str | Path | None) -- 校准产物。默认为随包提供的系数文件。

• versions (Mapping[str, str] | None) -- 完整且明确的清单，或已安装分发包的版本。检查安装时，仅允许可选的 Catalyst 缺失。若已安装 Catalyst，其版本仍必须与校准记录匹配。

• profile (Mapping[str, object] | None) -- 需要根据校准产物的有界配置检查的工作负载覆盖设置。

返回:

不可变模型。执行器必须遵守记录的在用数组调度、求解器设置和配置。不涵盖任意几何结构/AO 基组工作。

抛出:

ResourceModelDomainError -- 产物缺失、模型未经验证或运行环境不匹配。

返回类型:

CalibratedResourceModel

异常

可选数值后端共用的带类型 SQD 失败。

exception q2m3.sqd.exceptions.ResourceLimitError

基类：RuntimeError

运行超出允许的资源预算。

exception q2m3.sqd.exceptions.ResourceModelDomainError

基类：ResourceLimitError

没有适用于所请求操作的已校准资源上界。

exception q2m3.sqd.exceptions.CCSDConvergenceError

基类：RuntimeError

拟设初始解未收敛。

exception q2m3.sqd.exceptions.BaselineUnavailableError

基类：RuntimeError

没有获准使用的参考求解器能提供基线。

exception q2m3.sqd.exceptions.ReferenceUnavailableError

基类：RuntimeError

可选的参考求解器不可用。

exception q2m3.sqd.exceptions.ReferenceTimeoutError

基类：TimeoutError

参考求解耗尽时间预算。

exception q2m3.sqd.exceptions.ReferenceNumericalError

基类：RuntimeError

参考求解未通过数值验收检查。

exception q2m3.sqd.exceptions.SamplingIntegrityError

基类：RuntimeError

样本违反采样契约。

exception q2m3.sqd.exceptions.ComparisonUnavailableError

基类：RuntimeError

无法生成所需的匹配比较。

exception q2m3.sqd.exceptions.ProvenanceMismatchError

基类：ValueError

输入对应不同的轨道参考系或哈密顿量。