接口 API¶

PySCF/PennyLane 桥接¶

PySCF-PennyLane 双向转换接口。

class q2m3.interfaces.pyscf_pennylane.UnifiedDensityMatrix(dm_data, source='pyscf')[源代码]¶

基类：object

用于量电混合数据交换的统一密度矩阵接口。

此接口在 PySCF 与 PennyLane 表示之间转换。

参数:

dm_data (np.ndarray)
source (str)

__init__(dm_data, source='pyscf')[源代码]¶

初始化统一密度矩阵。

参数:

dm_data (ndarray) -- 密度矩阵数据
source (str) -- 源格式（'pyscf' 或 'pennylane'）

to_pennylane_observable()[源代码]¶

转换为 PennyLane 可观测量格式。

返回:: PennyLane Hermitian 可观测量
返回类型:: Any

from_quantum_state(quantum_state)[源代码]¶

根据量子态向量更新密度矩阵。

参数:: quantum_state (ndarray) -- 来自 QPE 的量子态向量
返回类型:: None

class q2m3.interfaces.pyscf_pennylane.PySCFPennyLaneConverter(basis='sto-3g', mapping='jordan_wigner')[源代码]¶

基类：object

用于在 PySCF 与 PennyLane 之间转换分子积分和哈密顿量的转换器。

参数:

basis (str)
mapping (str)

__init__(basis='sto-3g', mapping='jordan_wigner')[源代码]¶

初始化转换器。

参数:

basis (str) -- 计算使用的基组
mapping (str) -- 费米子到量子比特的映射方案

pyscf_to_pennylane_hamiltonian(symbols, coords, charge=0, active_electrons=None, active_orbitals=None)[源代码]¶

将分子结构转换为 PennyLane 量子比特哈密顿量。

参数:

symbols (list[str]) -- 原子符号列表 ['O', 'H', 'H', 'H']
coords (ndarray) -- 以埃为单位的原子坐标，形状为 (n_atoms, 3) 或 (n_atoms*3,)
charge (int) -- 分子总电荷，默认为 0
active_electrons (int | None) -- 活性空间中的活性电子数（可选）
active_orbitals (int | None) -- 活性空间中的活性轨道数（可选）

返回:

(hamiltonian, n_qubits, hf_state) - hamiltonian: PennyLane 哈密顿量算符 - n_qubits: 所需量子比特数 - hf_state: numpy 数组形式的 Hartree-Fock 参考态

返回类型:

tuple

抛出:

ValueError -- symbols 与 coords 的维度不匹配时

示例

>>> converter = PySCFPennyLaneConverter()
>>> symbols = ["H", "H"]
>>> coords = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.74]])
>>> H, n_qubits, hf_state = converter.pyscf_to_pennylane_hamiltonian(
...     symbols, coords, charge=0
... )

pyscf_to_pennylane_hamiltonian_with_mm(symbols, coords, charge=0, mm_charges=None, mm_coords=None, active_electrons=None, active_orbitals=None, energy_shift=None, embedding_mode='diagonal')[源代码]¶

构建带 MM 点电荷嵌入的 PennyLane 哈密顿量。

使用微扰方法：1. 从 molecular_hamiltonian 获取真空哈密顿量（具有正确的本征谱）；2. 计算单电子积分的 MM 修正；3. 将 MM 修正作为 Pauli 算符加入真空哈密顿量；4. 可选地施加能量平移，以提高 QPE 精度。

此方法在加入 MM 静电效应时，保留 molecular_hamiltonian 的正确本征谱结构。

energy_shift 参数启用“平移 QPE”，其中 H' = H - E_ref * I。这使 QPE 测量 ΔE = E - E_ref，而非绝对能量 E，从而更精确地检测微小能量变化（例如 MM 效应），并避免 QPE 电路中的相位溢出。

参数:

symbols (list[str]) -- 原子符号列表 ['O', 'H', 'H', 'H']
coords (ndarray) -- 以埃为单位的原子坐标，形状为 (n_atoms, 3)
charge (int) -- 分子总电荷
mm_charges (ndarray | None) -- MM 点电荷数组
mm_coords (ndarray | None) -- 以埃为单位的 MM 电荷坐标，形状为 (n_mm, 3)
active_electrons (int | None) -- 活性电子数
active_orbitals (int | None) -- 活性轨道数
energy_shift (float | None) -- 从哈密顿量中减去的参考能量（可选）。若提供此值，返回的哈密顿量为 H' = H - E_shift * I。这使 QPE 能够以更高精度测量 ΔE。
embedding_mode (Literal['diagonal', 'full_oneelectron']) -- MM 嵌入模式。"diagonal" 保留原有的 Identity/Z 系数更新路径。"full_oneelectron" 将完整的固定 MO 单电子微扰作为固定算符哈密顿量加入。

返回:

(hamiltonian, n_qubits, hf_state)

返回类型:

tuple

build_qmmm_hamiltonian(qm_mol, mm_charges, mm_coords)[源代码]¶

通过经典模拟构建带 MM 嵌入的 QM/MM 哈密顿量。

参数:

qm_mol (Any) -- PySCF 分子对象
mm_charges (ndarray) -- MM 区域的点电荷
mm_coords (ndarray) -- MM 电荷坐标

返回:

包含 QPE 模拟所需分子数据的字典

返回类型:

dict[str, Any]

extract_molecular_orbitals(scf_result)[源代码]¶

从 PySCF 提取分子轨道系数。

参数:: scf_result (Any) -- PySCF RHF 计算结果
返回:: 分子轨道系数矩阵的副本
抛出:: TypeError -- scf_result 不是闭壳层 RHF 结果
返回类型:: ndarray

compute_overlap_integrals(mol)[源代码]¶

计算 Mulliken 分析所需的重叠积分。

参数:: mol (Any) -- PySCF 分子对象
返回:: 重叠矩阵
返回类型:: ndarray

estimate_qpe_resources(symbols, coords, charge=0, mm_charges=None, mm_coords=None, active_electrons=None, active_orbitals=None, target_error=0.0016, embedding_mode='full_oneelectron')[源代码]¶

使用 PennyLane 估计 QPE 算法的 EFTQC 资源。

使用 PennyLane 的 qml.estimator.DoubleFactorization 估计分子系统量子相位估计所需的量子计算资源（Toffoli 门和逻辑量子比特）。

支持真空哈密顿量和 MM 嵌入（溶剂化）哈密顿量。提供 mm_charges/mm_coords 时，单电子积分包含 QM-MM 静电相互作用项。默认的 embedding_mode="full_oneelectron" 通过加入完整的固定 MO 活性空间 Delta h 矩阵，保留原有的资源估计行为。使用 embedding_mode="diagonal" 可请求仅含对角项的兼容结果，对应当前 QPE 系数路径。

参数:

symbols (list[str]) -- 原子符号列表，例如 ['O', 'H', 'H', 'H']
coords (ndarray) -- 以埃为单位的原子坐标，形状为 (n_atoms, 3)
charge (int) -- 分子总电荷，默认为 0（中性）
mm_charges (ndarray | None) -- MM 点电荷数组（可选，用于溶剂化哈密顿量）
mm_coords (ndarray | None) -- 以埃为单位的 MM 电荷坐标，形状为 (n_mm, 3)
active_electrons (int | None) -- 活性空间中的电子数（可选）
active_orbitals (int | None) -- 活性空间中的空间轨道数（可选）
target_error (float) -- 目标能量误差，单位为 Hartree（默认：0.0016 = 1 kcal/mol）
embedding_mode (Literal['diagonal', 'full_oneelectron']) -- 资源结果的 MM 嵌入模式。"full_oneelectron" 加入完整的活性空间微扰。"diagonal" 仅加入其对角项。未提供 MM 电荷时忽略此参数，但仍验证其取值。

返回:

logical_qubits: EFTQC 的逻辑量子比特数
toffoli_gates: 整次 QPE 运行的 Toffoli 总数 (DoubleFactorization.gates = estimation_cost * unitary_cost)
hamiltonian_1norm: Lambda（哈密顿量的 1-范数），单位为 Hartree
qpe_iterations: 游走算符调用次数 (= ceil(πλ/2ε))。仅供参考：这些调用已计入 toffoli_gates
trotter_steps: 建议的 Trotter 步数（启发式：10 × n_orbitals）
target_error: 目标误差，单位为 Hartree
n_electrons: 系统中的电子数
n_orbitals: 空间轨道数
basis: 使用的基组
mm_embedded: 是否施加了 MM 嵌入
n_mm_charges: MM 点电荷数（真空时为 0）
active_electrons: 传给估计器的活性空间电子数
active_orbitals: 传给估计器的活性空间轨道数
embedding_mode: 实际嵌入状态（真空时为 "none"）
requested_embedding_mode: 请求的 MM 模式，真空时为 None
fixed_mo: 是否使用了固定 MO 的 MM 微扰
two_electron_tensor_fixed: 双电子张量是否取自真空
active_indices: 活性空间所含的真空 MO 索引
delta_h_*：MM 单电子微扰的诊断信息

返回类型:

Dictionary containing

抛出:

ValueError -- coords 形状与 symbols 数量不匹配时

示例

>>> converter = PySCFPennyLaneConverter()
>>> symbols = ['H', 'H']
>>> coords = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.74]])
>>> # Vacuum Hamiltonian
>>> result = converter.estimate_qpe_resources(symbols, coords)
>>> # Solvated Hamiltonian with MM charges
>>> mm_charges = np.array([-0.834, 0.417, 0.417])
>>> mm_coords = np.array([[3.0, 0.0, 0.0], [3.5, 0.8, 0.0], [3.5, -0.8, 0.0]])
>>> result_mm = converter.estimate_qpe_resources(
...     symbols, coords, mm_charges=mm_charges, mm_coords=mm_coords
... )