核心 API¶

QPE 引擎¶

用于分子系统的量子相位估计（QPE）实现。

阶段 2：标准 QPE 电路，包括：- 通过 qml.BasisState 制备 HF 态；- 通过 qml.TrotterProduct 实现受控时间演化；- 通过 qml.adjoint(qml.QFT) 实现逆 QFT。

阶段 4：集成 Catalyst @qjit，支持 JIT 编译。

class q2m3.core.qpe.QPEEngine(n_qubits, n_iterations=8, mapping='jordan_wigner', device='default.qubit', device_type='lightning.qubit', use_catalyst=False, **kwargs)[源代码]¶

基类：object

用于 QM/MM 计算的迭代量子相位估计引擎。

实现面向近期量子设备优化的迭代 QPE 算法，目标为早期容错量子计算机（EFTQC）。

参数:

n_qubits (int)
n_iterations (int)
mapping (str)
device (str)
device_type (str)
use_catalyst (bool)

__init__(n_qubits, n_iterations=8, mapping='jordan_wigner', device='default.qubit', device_type='lightning.qubit', use_catalyst=False, **kwargs)[源代码]¶

初始化 QPE 引擎。

参数:

n_qubits (int) -- 系统量子比特数
n_iterations (int) -- QPE 迭代次数（概念验证使用 5-10 次）
mapping (str) -- 费米子到量子比特的映射（'jordan_wigner' 或 'bravyi_kitaev'）
device (str) -- PennyLane 设备名称（已弃用，改用 device_type）
device_type (str) -- 设备选择策略：- "auto"：自动选择可用的最佳设备 (GPU > lightning.qubit > default.qubit)；- "default.qubit"：标准 PennyLane 模拟器；- "lightning.qubit"：高性能 CPU 模拟器（默认）；- "lightning.gpu"：GPU 加速模拟器（需要 cuQuantum）。
use_catalyst (bool) -- 启用 Catalyst @qjit 编译（需要 pennylane-catalyst）
**kwargs -- 附加设备配置

estimate_ground_state_energy(hamiltonian_data, initial_state=None)[源代码]¶

通过经典模拟估计基态能量（概念验证）。

此经典模拟为概念验证而模拟 QPE 行为。使用 PySCF Hartree-Fock 结果作近似。结果及其模拟收敛过程均标记为 hf_reference。

参数:

hamiltonian_data (dict[str, Any]) -- 包含 PySCF 分子数据的字典
initial_state (ndarray | None) -- 初始量子态制备（经典模拟中不使用）

返回:

energy: 基态能量，单位为 Hartree
convergence: 收敛信息
density_matrix: 电子密度矩阵
method: hf_reference（未进行相位估计测量）

返回类型:

Dictionary containing

static compute_optimal_base_time(energy_estimate, safety_margin=None)[源代码]¶

计算避免 QPE 相位溢出的最优 base_time。

QPE 满足关系 phi = |E| * t / (2*pi)。为避免溢出，需满足 phi < 1，即 t < 2*pi / |E|。

参数:

energy_estimate (float) -- 估计的基态能量（例如 HF 能量）
safety_margin (float) -- 安全系数（默认：PHASE_SAFETY_MARGIN = 0.8）

返回:

避免相位溢出的最优 base_time

返回类型:

float

static compute_shifted_qpe_params(target_resolution=0.001, energy_range=0.2, safety_margin=None)[源代码]¶

计算能量平移 QPE 的最优参数。

能量平移 QPE 将哈密顿量变换为 H' = H - E_ref * I，其中 E_ref 通常为 HF 能量。这使 QPE 测量 ΔE = E - E_ref，而非绝对能量 E，从而更精确地检测微小能量变化，例如 MM 嵌入效应。

物理关系：- QPE 测量相位：φ = |ΔE| * t / (2π)；- 对 n 位精度：resolution = 2π / (2^n * t)；- 能量范围：ΔE_max = 2π / t （用于避免相位溢出）。

此方法计算最优 n_estimation_wires 和 base_time，在覆盖预期能量范围的同时达到目标分辨率。

参数:

target_resolution (float) -- 目标能量分辨率，单位为 Hartree（默认：0.001 Ha ≈ 0.63 kcal/mol）
energy_range (float) -- E_ref 附近的预期能量范围，单位为 Hartree（默认：±0.1 Ha）
safety_margin (float) -- 相位溢出的安全系数（默认：PHASE_SAFETY_MARGIN）

返回:

n_estimation_wires: 达到目标精度所需的估计量子比特数
base_time: 最优基础演化时间
resolution: 实际达到的能量分辨率
max_energy_range: 最大可测能量范围
phase_cycles: 范围边界处 ΔE 对应的相位周期数

返回类型:

Dictionary containing

示例

>>> params = QPEEngine.compute_shifted_qpe_params(
...     target_resolution=0.001,  # 0.63 kcal/mol
...     energy_range=0.2,         # ±0.1 Ha range
... )
>>> print(f"Use {params['n_estimation_wires']} estimation qubits")
Use 7 estimation qubits
>>> print(f"base_time = {params['base_time']:.4f}")
base_time = 49.0874

draw_qpe_circuit(hamiltonian, hf_state, n_estimation_wires=4, base_time=0.3, n_trotter_steps=5, max_display_wires=8, use_pennylane_draw=True)[源代码]¶

生成 QPE 电路结构的文本可视化。

使用 qml.draw()，并设置 decimals=None 和 level=0，以清楚显示电路结构，避免参数干扰。

参数:

hamiltonian (LinearCombination) -- PennyLane 分子哈密顿量
hf_state (ndarray) -- HF 参考态的二进制数组
n_estimation_wires (int) -- 估计量子比特数
base_time (float) -- 基础演化时间
n_trotter_steps (int) -- 每次演化的 Trotter 步数
max_display_wires (int) -- 完整电路显示的最大线路数（默认：8）
use_pennylane_draw (bool) -- 使用 qml.draw() 可视化（默认：True）

返回:

电路的字符串表示

返回类型:

str

QM/MM 系统¶

用于分子模拟的 QM/MM 系统构建器。

class q2m3.core.qmmm_system.Atom(symbol, position, charge=0.0, is_qm=True)[源代码]¶

基类：object

表示具有位置和属性的原子。

参数:

symbol (str)
position (ndarray)
charge (float)
is_qm (bool)

class q2m3.core.qmmm_system.QMMMSystem(qm_atoms, mm_model='tip3p', solvation_shells=1, num_waters=8)[源代码]¶

基类：object

构建并管理水环境中 H3O+ 的 QM/MM 系统。

此类划分 QM 与 MM 区域，并为量子计算准备嵌入势。

参数:

qm_atoms (list[Atom])
mm_model (str)
solvation_shells (int)
num_waters (int)

__init__(qm_atoms, mm_model='tip3p', solvation_shells=1, num_waters=8)[源代码]¶

初始化 QM/MM 系统。

参数:

qm_atoms (list[Atom]) -- QM 区域中的原子列表（H3O+）
mm_model (str) -- MM 区域的水模型
solvation_shells (int) -- 溶剂化壳层数
num_waters (int) -- MM 区域中的水分子数

get_embedding_potential()[源代码]¶

计算 MM 电荷产生的嵌入势。

返回:: MM 点电荷的 (charges, coordinates) 元组
返回类型:: tuple[ndarray, ndarray]

get_total_charge()[源代码]¶

获取系统总电荷。

返回类型:: int

get_qm_coords()[源代码]¶

以 numpy 数组形式获取 QM 原子坐标。

返回类型:: ndarray

to_pyscf_mol()[源代码]¶

转换为 PySCF 分子格式。

返回:: 包含原子位置与基组信息的字典
返回类型:: dict[str, Any]

量子 QM/MM 编排器¶

整合所有组件的主要 Quantum-QM/MM 接口。

class q2m3.core.quantum_qmmm.QuantumQMMM(qm_atoms, mm_waters=8, qpe_config=None, use_catalyst=False, rdm_config=None)[源代码]¶

基类：object

Quantum-QM/MM 计算的主要接口。

协调 PySCF 经典计算、PennyLane 量子电路和 QM/MM 嵌入之间的工作流。

参数:

qm_atoms (list[Atom])
mm_waters (int)
qpe_config (dict[str, Any])
use_catalyst (bool)
rdm_config (dict[str, Any] | None)

__init__(qm_atoms, mm_waters=8, qpe_config=None, use_catalyst=False, rdm_config=None)[源代码]¶

初始化 Quantum-QM/MM 计算器。

参数:

qm_atoms (list[Atom]) -- QM 区域中的原子
mm_waters (int) -- MM 区域中的水分子数
qpe_config (dict[str, Any]) -- QPE 算法配置
use_catalyst (bool) -- 为 QPE 电路启用 Catalyst @qjit 编译
rdm_config (dict[str, Any] | None) -- RDM 测量配置（默认：启用并使用默认值）- enabled: 启用 RDM 测量（默认：True）- n_shots: 测量次数（默认：1000）- include_off_diagonal: 测量非对角元素（默认：True）- symmetrize: 强制满足厄米对称性（默认：True）

compute_ground_state(include_resource_estimation=False)[源代码]¶

使用 QPE 计算基态性质。

参数:

include_resource_estimation (bool) -- 若为 True，在输出中包含 EFTQC 资源估计。使用 PennyLane 的 DoubleFactorization 估计逻辑量子比特数、Toffoli 门数和 QPE 迭代次数。默认：False。

返回:

energy: 基态能量 (Hartree)
energy_hf: HF 参考能量 (Hartree)
energy_difference: |E_QPE - E_HF| (Hartree)
density_matrix: 电子密度矩阵
atomic_charges: Mulliken 电荷
convergence: 收敛信息
eftqc_resources: 请求时提供的 EFTQC 资源估计（可选）
timing: 用于性能分析的细分计时

返回类型:

Dictionary containing

draw_circuits()[源代码]¶

生成 QPE 与 RDM 电路的文本可视化。

返回:

"qpe": QPE 电路可视化
"rdm": RDM 测量电路可视化

返回类型:

Dictionary with keys

约化密度矩阵¶

从量子态估计约化密度矩阵（RDM）。

对费米子算符进行 Jordan-Wigner 变换后，使用 Pauli 期望值测量 1-RDM。

关键公式:

Diagonal: gamma_pp = <a_p†a_p> = (1 - <Z_p>) / 2
Off-diagonal (p < q):
    gamma_pq = 1/4 * [<X_p Z... X_q> + <Y_p Z... Y_q>
                      + i(<X_p Z... Y_q> - <Y_p Z... X_q>)]

性能优化（阶段 7）：- 批量测量：单个 QNode 返回所有可观测量（执行次数从 120x 降至 1x）；- 通过 device_utils 实现 GPU 加速；- 支持 Catalyst @qjit。

class q2m3.core.rdm.RDMEstimator(n_qubits, n_electrons, config=None)[源代码]¶

基类：object

使用 Pauli 期望值从量子态测量 1-RDM。

从 Trotter 时间演化制备的量子态测量单粒子约化密度矩阵（1-RDM）。使用 Jordan-Wigner 变换将费米子算符转换为 Pauli 可观测量。

性能优化：使用批量测量（单个 QNode），而非每个可观测量单独使用 QNode，可获得 10-50x 加速。

参数:

n_qubits (int)
n_electrons (int)
config (dict[str, Any] | None)

__init__(n_qubits, n_electrons, config=None)[源代码]¶

初始化 RDM 估计器。

参数:

n_qubits (int) -- 自旋轨道数（Jordan-Wigner 映射中的量子比特数）
n_electrons (int) -- 系统中的电子数
config (dict[str, Any] | None) -- 可选配置字典，包含以下键：- n_shots: 测量次数（默认：1000）；- include_off_diagonal: 测量非对角元素（默认：True）；- symmetrize: 强制满足厄米对称性（默认：True）；- output_basis: "spin" 或 "spatial"（默认："spin"）。

measure_1rdm(hamiltonian, hf_state, base_time, n_trotter_steps, device_type='default.qubit', use_catalyst=False)[源代码]¶

通过批量测量，从 Trotter 演化态测量 1-RDM。

制备 |HF>，施加 TrotterProduct 时间演化，再在单个 QNode 中将所有 1-RDM 元素测为 Pauli 期望值。

参数:

hamiltonian (LinearCombination) -- PennyLane 分子哈密顿量
hf_state (ndarray) -- Hartree-Fock 参考态的二进制数组
base_time (float) -- Trotter 演化时间
n_trotter_steps (int) -- Trotter 步数
device_type (str) -- 设备选择策略：- "auto"：自动选择最佳设备 (GPU > lightning.qubit > default.qubit)；- "default.qubit"：标准 PennyLane 模拟器；- "lightning.qubit"：高性能 CPU 模拟器；- "lightning.gpu"：GPU 加速模拟器。
use_catalyst (bool) -- 启用 Catalyst @qjit 编译

返回:

numpy 数组形式的 1-RDM，形状为 (n_qubits, n_qubits)

返回类型:

ndarray

build_rdm_observables()[源代码]¶

构建所有 1-RDM 元素的 Pauli 可观测量（旧接口）。

返回:: 将 (p, q) 索引映射到 PennyLane 可观测量的字典。p == q 时为粒子数算符可观测量；p < q 时为包含 4 个 Pauli 可观测量的元组，分别用于实部和虚部。
返回类型:: dict[tuple[int, int], Any]

enforce_physical_constraints(rdm_raw)[源代码]¶

强制 1-RDM 满足物理约束。

约束：1. 厄米性：γ_pq = γ_qp*；2. 半正定性：所有本征值 >= 0；3. 迹归一化：Tr(γ) = N_electrons。

参数:: rdm_raw (ndarray) -- 测量得到的原始 1-RDM
返回:: 满足物理约束的 1-RDM
返回类型:: ndarray

draw_rdm_circuit(hamiltonian, hf_state, base_time, n_trotter_steps, max_observables=4, use_pennylane_draw=True)[源代码]¶

生成 RDM 测量电路的文本可视化。

使用 qml.draw()，并设置 decimals=None 和 level=0，以清楚显示电路结构，避免参数干扰。

参数:

hamiltonian (LinearCombination) -- PennyLane 分子哈密顿量
hf_state (ndarray) -- HF 参考态的二进制数组
base_time (float) -- Trotter 演化时间
n_trotter_steps (int) -- Trotter 步数
max_observables (int) -- 显示的最大可观测量数（默认：4）
use_pennylane_draw (bool) -- 使用 qml.draw() 可视化（默认：True）

返回:

电路的字符串表示

返回类型:

str

spin_to_spatial_rdm(spin_rdm)[源代码]¶

将自旋轨道 1-RDM 转换为空间轨道 1-RDM。

对于限制性体系，空间 RDM = alpha 与 beta 自旋块之和。

参数:: spin_rdm (ndarray) -- 自旋轨道基下的 1-RDM，形状为 (2*n_spatial, 2*n_spatial)
返回:: 空间轨道基下的 1-RDM，形状为 (n_spatial, n_spatial)
返回类型:: ndarray

active_mo_to_ao_rdm(active_spatial_rdm, mo_coeff, mo_occ, active_electrons, active_orbitals)[源代码]¶

将活性空间的空间轨道 1-RDM 转换到 AO 基。

步骤：1. 将活性空间 RDM 嵌入完整 MO RDM；2. 从 MO 基变换到 AO 基：P_AO = C @ P_MO @ C^T。

参数:

active_spatial_rdm (ndarray) -- 活性 MO 基下的 1-RDM，形状为 (active_orbitals, active_orbitals)
mo_coeff (ndarray) -- HF 的 MO 系数矩阵，形状为 (n_ao, n_mo)
mo_occ (ndarray) -- HF 的 MO 占据数，形状为 (n_mo,)
active_electrons (int) -- 活性电子数
active_orbitals (int) -- 活性轨道数

返回:

AO 基下的 1-RDM，形状为 (n_ao, n_ao)

返回类型:

ndarray

q2m3.core.rdm.measure_rdm_from_qpe_state(hamiltonian, hf_state, n_electrons, base_time, n_trotter_steps, config=None, device_type='default.qubit', use_catalyst=False)[源代码]¶

从类似 QPE 的态测量 1-RDM 的便捷函数。

参数:

hamiltonian (LinearCombination) -- PennyLane 分子哈密顿量
hf_state (ndarray) -- Hartree-Fock 参考态
n_electrons (int) -- 电子数
base_time (float) -- 演化时间
n_trotter_steps (int) -- Trotter 步数
config (dict[str, Any] | None) -- 可选 RDM 配置
device_type (str) -- PennyLane 设备选择
use_catalyst (bool) -- 启用 Catalyst @qjit 编译

返回:

1-RDM numpy 数组

返回类型:

ndarray

资源估计¶

EFTQC 资源估计模块。

此模块封装 PySCFPennyLaneConverter.estimate_qpe_resources()，也直接从活性空间积分估计资源。它以结构化数据类返回早期容错量子计算机（EFTQC）的资源估计结果。

class q2m3.core.resource_estimation.EmbeddingDiagnostics(active_indices, delta_h_diag_fro, delta_h_offdiag_fro, delta_h_offdiag_to_diag, delta_h_hermitian_max_abs, delta_h_trace_ha, delta_nuclear_mm_ha, delta_core_constant_ha, fixed_mo, two_electron_tensor_fixed)[源代码]¶

基类：object

MM 单电子嵌入资源结果的标量诊断信息。

参数:

active_indices (tuple[int, ...])
delta_h_diag_fro (float)
delta_h_offdiag_fro (float)
delta_h_offdiag_to_diag (float | None)
delta_h_hermitian_max_abs (float)
delta_h_trace_ha (float)
delta_nuclear_mm_ha (float)
delta_core_constant_ha (float)
fixed_mo (bool)
two_electron_tensor_fixed (bool)

active_indices¶

用于活性块的真空分子轨道索引。

类型:: tuple[int, ...]

delta_h_diag_fro¶

活性空间微扰对角部分的 Frobenius 范数。

类型:: float

delta_h_offdiag_fro¶

非对角微扰的 Frobenius 范数。

类型:: float

delta_h_offdiag_to_diag¶

非对角部分范数与对角部分范数之比。

类型:: float | None

delta_h_hermitian_max_abs¶

最大的反厄米残差。

类型:: float

delta_h_trace_ha¶

活性空间微扰的迹，单位为 Hartree。

类型:: float

delta_nuclear_mm_ha¶

MM 引起的核常数差，单位为 Hartree。

类型:: float

delta_core_constant_ha¶

冻结核单电子项与核 MM 常数之和。

类型:: float

fixed_mo¶

微扰是否在真空 MO 框架中表示。

类型:: bool

two_electron_tensor_fixed¶

双电子张量是否保持真空值。

类型:: bool

class q2m3.core.resource_estimation.EFTQCResources(hamiltonian_1norm, logical_qubits, toffoli_gates, n_terms, target_error, n_system_qubits, basis, n_mm_charges, embedding_mode='none', embedding_diagnostics=None, walk_operator_calls=None)[源代码]¶

基类：object

单个 EFTQC 配置的资源估计结果。

参数:

hamiltonian_1norm (float)
logical_qubits (int)
toffoli_gates (int)
n_terms (int | None)
target_error (float)
n_system_qubits (int)
basis (str)
n_mm_charges (int)
embedding_mode (str)
embedding_diagnostics (EmbeddingDiagnostics | None)
walk_operator_calls (int | None)

hamiltonian_1norm¶

哈密顿量的 Lambda（1-范数），单位为 Hartree。

类型:: float

logical_qubits¶

所需逻辑量子比特数。

类型:: int

toffoli_gates¶

整次 QPE 运行的非 Clifford（Toffoli）门总数（PennyLane DoubleFactorization.gates）。

类型:: int

n_terms¶

哈密顿量项数。使用 DoubleFactorization 资源估计时为 None，因为该方法不构建完整的 PennyLane Hamiltonian 对象。

类型:: int | None

target_error¶

目标能量误差，单位为 Hartree。

类型:: float

n_system_qubits¶

系统寄存器大小 = n_orbitals * 2（Jordan-Wigner）。

类型:: int

basis¶

使用的基组，例如 "sto-3g"。

类型:: str

n_mm_charges¶

MM 点电荷数。真空时为 0。

类型:: int

embedding_mode¶

实际嵌入状态（"none"、"diagonal" 或 "full_oneelectron"）。

类型:: str

embedding_diagnostics¶

固定 MO 单电子嵌入的可选标量诊断信息。

类型:: q2m3.core.resource_estimation.EmbeddingDiagnostics | None

walk_operator_calls¶

QPE 中量子比特化游走算符的调用次数，ceil(pi * lambda / (2 * target_error)) （PennyLane DoubleFactorization.estimation_cost）。仅供参考：这些调用已计入 toffoli_gates。

类型:: int | None

class q2m3.core.resource_estimation.ResourceComparisonResult(vacuum, solvated, delta_lambda_percent, delta_gates_percent)[源代码]¶

基类：object

真空与溶剂化系统的 EFTQC 资源比较。

参数:

vacuum (EFTQCResources)
solvated (EFTQCResources)
delta_lambda_percent (float)
delta_gates_percent (float)

vacuum¶

无 MM 嵌入时的资源估计。

类型:: q2m3.core.resource_estimation.EFTQCResources

solvated¶

带 MM 点电荷嵌入的资源估计。

类型:: q2m3.core.resource_estimation.EFTQCResources

delta_lambda_percent¶

溶剂化引起的哈密顿量 1-范数百分比变化：(solvated - vacuum) / vacuum * 100。

类型:: float

delta_gates_percent¶

溶剂化引起的 Toffoli 门数百分比变化：(solvated - vacuum) / vacuum * 100。

类型:: float

q2m3.core.resource_estimation.estimate_resources(symbols, coords, charge=0, basis='sto-3g', active_electrons=None, active_orbitals=None, target_error=0.0016, mm_charges=None, mm_coords=None, embedding_mode='full_oneelectron')[源代码]¶

估计分子系统的 EFTQC 资源需求。

封装 PySCFPennyLaneConverter.estimate_qpe_resources()，返回结构化、不可变的 EFTQCResources 数据类，而非原始字典。

参数:

symbols (list[str]) -- 原子符号列表，例如 ['H', 'H']。
coords (ndarray) -- 以埃为单位的原子坐标，形状为 (n_atoms, 3)。
charge (int) -- 分子总电荷，默认为 0。
basis (str) -- 基组名称，默认为 "sto-3g"。
active_electrons (int | None) -- 活性空间电子数（可选）。
active_orbitals (int | None) -- 活性空间轨道数（可选）。
target_error (float) -- 目标能量误差，单位为 Hartree（默认：0.0016 = 1 kcal/mol）。
mm_charges (ndarray | None) -- MM 点电荷数组（可选，启用溶剂化哈密顿量）。
mm_coords (ndarray | None) -- 以埃为单位的 MM 电荷坐标，形状为 (n_mm, 3)。
embedding_mode (str) -- 资源结果的 MM 嵌入模式。默认保留原有的完整固定 MO 单电子资源估计行为。

返回:

所有资源字段均已填充的 EFTQCResources 数据类。

返回类型:

EFTQCResources

q2m3.core.resource_estimation.estimate_qpe_resources_from_integrals(h1, h2, *, basis, target_error=0.0016)[源代码]¶

估计给定活性空间积分对应哈密顿量的 EFTQC 资源。

估计值是该哈密顿量的双因子分解成本，DoubleFactorization 的设置与 estimate_resources 相同。不运行任何电路。

参数:

h1 (ndarray) -- 实对称单电子积分，形状为 (norb, norb)。
h2 (ndarray) -- 化学家记号 (pq|rs) 的实数双电子积分，形状为 (norb, norb, norb, norb)。
basis (str) -- 写入结果的基组名称。
target_error (float) -- 目标能量误差，单位为 Hartree（默认：0.0016 = 1 kcal/mol）。

返回:

真空活性空间哈密顿量的 EFTQCResources。

抛出:

ValueError -- 形状不匹配，或积分不满足实数化学家记号的置换对称性。

返回类型:

EFTQCResources

q2m3.core.resource_estimation.compare_vacuum_solvated(symbols, coords, charge=0, basis='sto-3g', active_electrons=None, active_orbitals=None, mm_charges=None, mm_coords=None, target_error=0.0016, embedding_mode='full_oneelectron')[源代码]¶

比较真空与溶剂化系统的 EFTQC 资源需求。

此函数调用 estimate_resources() 两次：一次不使用 MM 电荷（真空），另一次使用 MM 电荷（溶剂化）。随后计算百分比变化。

参数:

symbols (list[str]) -- 原子符号列表。
coords (ndarray) -- 以埃为单位的原子坐标，形状为 (n_atoms, 3)。
charge (int) -- 分子总电荷，默认为 0。
basis (str) -- 基组名称，默认为 "sto-3g"。
active_electrons (int | None) -- 活性空间电子数（可选）。
active_orbitals (int | None) -- 活性空间轨道数（可选）。
mm_charges (ndarray | None) -- 溶剂化估计所用的 MM 点电荷。
mm_coords (ndarray | None) -- 溶剂化估计所用的 MM 电荷坐标，单位为埃。
target_error (float) -- 目标能量误差，单位为 Hartree（默认：0.0016）。
embedding_mode (str) -- 溶剂化资源结果的 MM 嵌入模式。

返回:

包含两项估计及其变化量的 ResourceComparisonResult。

返回类型:

ResourceComparisonResult

q2m3.core.resource_estimation.derive_t_resources(toffoli_gates)[源代码]¶

从 Toffoli 门数推导 T 门数和保守的 T 深度。

DoubleFactorization 返回 Toffoli 门数与逻辑量子比特数，但不返回表面码类分析所需的 T 深度。使用标准容错关系 T-count = 7 * Toffoli-count，并使用深度的保守串行上界。

参数:

toffoli_gates (int) -- DoubleFactorization 给出的 Toffoli 门总数。

返回:

t_count: 7 * toffoli_gates
toffoli_depth: 保守串行上界 (= toffoli_gates)
t_depth: T_PER_TOFFOLI * toffoli_depth（串行上界）

返回类型:

Dict with

q2m3.core.resource_estimation.surface_code_distance(logical_qubits, toffoli_gates, p_phys=0.001, failure_budget=0.01)[源代码]¶

使整次运行的失败概率低于 failure_budget 的最小奇数表面码距离。

此函数使用 Litinski (Quantum 3, 128 (2019), Eq. 10) 的逻辑错误模型：每个逻辑量子比特在每个码周期的错误率为 p_L(d) = 0.1 * (100 * p_phys) ** ((d + 1) / 2)。假设每个 Toffoli 对每个逻辑量子比特均占用一个逻辑时间步，每步为 d 个码周期。

参数:

logical_qubits (int) -- 逻辑（数据）量子比特数。
toffoli_gates (int) -- 算法的串行 Toffoli 总数。
p_phys (float) -- 每个门／码周期的物理错误率。
failure_budget (float) -- 可接受的总逻辑失败概率。

返回:

码距 d （[3, 99] 内的奇数）。

抛出:

ValueError -- 不存在小于 101 且满足预算的码距时。

返回类型:

int

q2m3.core.resource_estimation.estimate_eftqc_runtime(toffoli_gates, logical_qubits, p_phys=0.001, t_cycle_microseconds=1.0, t_react_microseconds=10.0, n_factories=1, failure_budget=0.01)[源代码]¶

估计 EFTQC QPE 运行的实际时间与物理资源占用。

表面码模型：runtime = toffoli_gates * tick，其中 tick = max(t_react, 5.5 * d * t_cycle / n_factories)。每个工厂每 5.5 d 个码周期产出一个 CCZ（Gidney & Fowler, Quantum 3, 135 (2019); Babbush et al., PRX Quantum 2, 010103 (2021), Eq. 6），且 tick 不低于经典反应时间（Lee et al., PRX Quantum 2, 030305 (2021)）。

toffoli_gates 是整个算法的**总**门数。PennyLane DoubleFactorization.gates / EFTQCResources.toffoli_gates 返回的正是此值。它已包含 ceil(pi*lambda/(2*eps)) 次相位估计重复。因此，此函数不再乘以迭代次数。

参数:

toffoli_gates (int) -- 算法的 Toffoli 总数。
logical_qubits (int) -- 逻辑量子比特数（决定码距）。
p_phys (float) -- 物理错误率（默认 1e-3，采用超导假设）。
t_cycle_microseconds (float) -- 表面码周期时间（默认 1 us）。
t_react_microseconds (float) -- 经典反应时间下限（默认 10 us）。
n_factories (int) -- 并行 CCZ 工厂数。默认为 1（串行上界）。Lee 2021 FeMoco 使用 4 个。
failure_budget (float) -- 可接受的总逻辑失败概率。

返回:

字典，包含 code_distance、tick_microseconds、regime （"factory" 或 "reaction"）、runtime_{microseconds,seconds,hours,days}、physical_qubits （每个逻辑量子比特 2(d+1)^2，加上每个工厂 15d x 8d），并回传输入假设。

返回类型:

dict[str, float | int | str]

设备工具¶

量子设备选择与管理工具。

为 QPE 与 RDM 模块提供统一的设备选择逻辑，支持 GPU 加速并兼容 Catalyst。

重要：q2m3 有两套独立的 GPU 支持系统：

PennyLane Lightning GPU (cuQuantum/CUDA)：- 用于标准 QPE 电路（不使用 @qjit）；- 通过 HAS_LIGHTNING_GPU 标志检测；- 需要 pennylane-lightning[gpu]、cuQuantum 和 CUDA。
JAX/Catalyst GPU (jaxlib[cuda])：- 用于 Catalyst @qjit 编译电路；- 通过 HAS_JAX_CUDA 标志检测；- 需要 jax[cuda11_pip] 或 jax[cuda12_pip]。

启用 Catalyst @qjit 时，即使设备为 lightning.gpu，实际执行后端也由 JAX 决定，而非 PennyLane。若 JAX 不支持 CUDA，无论设备名称为何，Catalyst 均在 CPU 上运行。

q2m3.core.device_utils.get_best_available_device()[源代码]¶

返回当前最佳可用设备的名称。

优先级：lightning.gpu > lightning.qubit > default.qubit

返回:: 设备名称字符串
返回类型:: str

q2m3.core.device_utils.get_catalyst_backend_info()[源代码]¶

获取 Catalyst 执行后端的详细信息。

重要：Catalyst @qjit 使用 JAX 作为执行后端，该后端独立于 PennyLane 设备选择。即使 device="lightning.gpu"，若 JAX 不支持 CUDA，Catalyst 仍在 CPU 上运行。

返回:

jax_backend: JAX 默认后端（"cpu"、"cuda"、"gpu"）
has_jax_cuda: JAX 是否支持 CUDA
effective_device: Catalyst 的实际执行设备
warning: 期望使用 GPU 但 GPU 不可用时的可选警告信息

返回类型:

Dictionary with

q2m3.core.device_utils.get_effective_catalyst_device_label()[源代码]¶

获取 Catalyst 执行的实际设备标签。

get_best_available_device() 返回 PennyLane 设备名称；此函数返回 Catalyst 实际运行的设备（由 JAX 后端决定为 CPU 或 GPU）。

返回:: CPU)" 或 "lightning.gpu (JAX: GPU)"
返回类型:: Human-readable label like "lightning.gpu (JAX

q2m3.core.device_utils.get_catalyst_effective_backend()[源代码]¶

获取便于阅读的 Catalyst 执行后端标签。

返回:: 类似 "GPU (JAX CUDA)" 或 "CPU (JAX)" 的字符串
返回类型:: str

q2m3.core.device_utils.select_device(device_type, n_wires, use_catalyst=False, seed=None)[源代码]¶

根据 device_type 参数选择量子设备。

注意：自 PennyLane v0.43 起，在设备上设置 shots 已弃用。改为对 QNode 使用 qml.set_shots() 变换。

参数:

device_type (str) -- 设备选择策略：- "auto"：自动选择可用的最佳设备 (GPU > lightning.qubit > default.qubit)；- "default.qubit"：标准 PennyLane 模拟器；- "lightning.qubit"：高性能 CPU 模拟器；- "lightning.gpu"：GPU 加速模拟器（需要 cuQuantum）。
n_wires (int) -- 量子比特数
use_catalyst (bool) -- 若为 True，确保回退设备兼容 Catalyst（使用 lightning.qubit，而非 default.qubit）
seed (int | None) -- 可选的设备随机种子，用于可复现的有限次数测量采样

返回:

PennyLane 设备实例

哈密顿量工具¶

PennyLane 哈密顿量算符工具。

提供辅助函数，用于分解 PennyLane Sum/Hamiltonian 对象（兼容 PennyLane 0.44+），以及构建算符索引映射，以高效更新 QM/MM 模拟中的系数。

q2m3.core.hamiltonian_utils.decompose_hamiltonian(H)[源代码]¶

从 PennyLane Sum/Hamiltonian 提取 (coeffs, ops)。

PennyLane 0.44+ 的 qml.qchem.molecular_hamiltonian 返回由 SProd 组成的 Sum。qml.dot(coeffs, ops) 需要分离的系数与算符。

参数:: H -- PennyLane 哈密顿量（SProd 算符之和）
返回:: (coefficients, operators) 元组，其中 coefficients 为浮点数，operators 为 PennyLane 算符实例。
返回类型:: tuple[list[float], list]

q2m3.core.hamiltonian_utils.build_operator_index_map(ops, n_system_qubits, coeffs)[源代码]¶

扫描 ops，查找 Identity 与单个 Z(wire) 的索引，用于 MM 系数更新。

若 range(n_system_qubits) 中任一 wire 缺少 Z(wire)，则追加 coeff=0.0 的占位项，确保所有自旋轨道都能接收 MM 修正。

参数:

ops (list) -- PennyLane 算符列表（来自 decompose_hamiltonian）
n_system_qubits (int) -- 系统量子比特数 (= 2 * active_orbitals)
coeffs (list[float]) -- 对应的系数列表（可能扩展）

返回:

index_map: {"identity_idx": int, "z_wire_idx": {wire: idx, ...}}
extended_coeffs: 追加所有缺失 Z 项后的系数
extended_ops: 追加所有缺失 Z 项后的算符

返回类型:

Tuple of (index_map, extended_coeffs, extended_ops) where

求解器扩展点¶

用于基态能量估计的量子求解器接口。

QM/MM 模拟中量子求解器的抽象基类。具体实现（QPE、VQE 等）位于独立模块中。

此模块可独立使用，不从 core/__init__.py 导出。未来的 VQE/QAOA 求解器可直接导入:

from q2m3.core.quantum_solver import QuantumSolver, SolverResult

class q2m3.core.quantum_solver.SolverResult(energy, phase, raw_measurements, metadata=<factory>)[源代码]¶

基类：object

量子求解器的通用结果容器。

参数:

energy (float)
phase (float)
raw_measurements (Any)
metadata (dict)

energy¶

估计的基态能量，单位为 Hartree。

类型:: float

phase¶

QPE 估计的相位值。

类型:: float

raw_measurements¶

算法特有的测量数据。

类型:: Any

metadata¶

算法特有的附加信息。

类型:: dict

class q2m3.core.quantum_solver.QuantumSolver[源代码]¶

基类：ABC

量子基态求解器的抽象基类。

实现应提供：- solve()：执行算法并返回能量估计；- compile()：预编译电路以便重复执行。

abstractmethod solve(hamiltonian_data)[源代码]¶

估计哈密顿量的基态能量。

参数:: hamiltonian_data (dict) -- 包含哈密顿量算符、HF 态、量子比特数和参考能量的字典。
返回:: 包含能量和测量数据的 SolverResult。
返回类型:: SolverResult

abstractmethod compile(**kwargs)[源代码]¶

预编译电路以便重复执行。

某些求解器（例如 QPE）支持电路预编译，以便在采用相同哈密顿量的不同 MC 步骤间复用。

参数:: kwargs (Any)
返回类型:: None