hyq 26.1.5

HyQ: hybrid quantum algorithms toolkit with backend-agnostic circuits and solvers

HyQ

HyQ（pip install hyq）是用于混合量子算法的 Python 工具包：后端无关的线路抽象、可插拔模拟器，以及 VQE / QITE 系列求解器与常用算法工具。

• Python：3.10、3.11（见 requires-python）
• 核心依赖（随 pip install hyq 自动安装）：NumPy、SciPy、PyTorch、Qiskit、qiskit-aer、pylatexenc（2.10，示例/线路 LaTeX 相关）
• 其他后端与化学功能：通过可选 extra 安装（见下表）

安装

pip install hyq

默认可用 Qiskit 后端（线路构建、采样、QASM 等）。若需要可微分或其它模拟器，可加装 extras：

pip install "hyq[tensorcircuit]"              # VQE / VarQITE 等可微分算法
pip install "hyq[tensorcircuit,pennylane]"    # 常用组合
pip install "hyq[all]"                        # 全部可选 Python 依赖（3.10/3.11 均可；体积较大）

可选依赖（extras）

Extra	用途
pennylane	PennyLane 后端（3.10 解析为 0.42.x，3.11 可为 0.43+ 并含 lightning）
tensorcircuit	TensorCircuit 后端（推荐可微分流程）
optional-backends	Cirq、Qulacs、QuTiP（3.10 上 Cirq 解析为 1.5.x，3.11 可为 1.6+）
chemistry	OpenFermion、PySCF（分子哈密顿量，默认 PySCF）
psi4	仅 openfermionpsi4 桥接包；须已 conda install psi4
notebooks	运行 notebook 的辅助包
dev	pytest、black 等开发工具
all	上述除 dev 外的组合

pip install hyq 和 pip install "hyq[chemistry]" 的区别

安装命令	自动安装的内容	能否用 hyq.chemistry
pip install hyq	NumPy、SciPy、PyTorch、Qiskit、qiskit-aer、pylatexenc	不能（缺 OpenFermion / PySCF）
pip install "hyq[chemistry]"	上述 加上 openfermion、openfermionpyscf、pyscf（不含 openfermionpsi4）	可以（走 PySCF）
pip install "hyq[chemistry,psi4]"	再加 openfermionpsi4；还须 Conda 安装 psi4 程序	使用 Psi4 后端

只做 VQE、QPE、线路编译等 不需要 [chemistry]。运行 examples/hamiltonian.ipynb 或 from hyq.chemistry import Hamiltonian 需要 [chemistry]。

量子化学安装（hyq.chemistry）

hyq.chemistry 用 OpenFermion 生成分子/qubit 哈密顿量。计算时会优先尝试 Psi4，若未安装 Psi4 程序则 自动改用 PySCF（多数用户只需 PySCF 即可）。

方式一：仅 pip（推荐，无需 Psi4）

Python 版本须为 3.10 或 3.11（与 hyq 一致）。

pip install -U pip
pip install "hyq[chemistry]"

验证：

python -c "import hyq; from hyq.chemistry import Hamiltonian; print('hyq', hyq.__version__)"
python -c "from openfermionpyscf import run_pyscf; import pyscf; print('PySCF ok')"

最小用法：

from hyq.chemistry import Hamiltonian

ham = Hamiltonian(
    symbols=["H", "H"],
    geometry=[[0.0, 0.0, 0.0], [0.0, 0.0, 0.74]],
    basis="sto-3g",
)
terms, n_qubits, n_electrons = ham.get_processed_hamiltonian(
    n_active_electrons=2,
    n_active_orbitals=2,
    mapping="jw",
)

方式二：使用 Psi4（可选，需 Conda）

Psi4 本体不在 PyPI。默认 hyq[chemistry] 不会安装 openfermionpsi4（避免仅有 Python 包、没有 psi4 命令时触发第三方库 bug）。需要 Psi4 时请：

# 1. 用 Conda 安装 Psi4（示例）
conda create -n hyq_chem python=3.11 psi4=1.10 pip -y
conda activate hyq_chem

# 2. 再装 hyq：化学 + Psi4 桥接
pip install "hyq[chemistry,psi4]"

验证：

python -c "import psi4; print('psi4', psi4.__version__)"
python -c "from openfermionpsi4 import run_psi4; print('openfermionpsi4 ok')"

可选环境变量（磁盘/权限异常时）：

export PSI4_SCRATCH=/tmp
export TMPDIR=/tmp

运行时会使用当前目录下的 .psi4_temp_data/ 存放临时文件。

从源码开发（Conda 一键环境）

克隆仓库后可用 environment.yml（已包含 Psi4 + PySCF + 全部 pip 依赖）：

conda env create -f environment.yml
conda activate hyq_alg_lib_env
pip install -e .

详见仓库内 README_HYQ.md。

常见报错

若出现：

ImportError: 需要安装 openfermionpyscf/pyscf，或安装 openfermionpsi4 并配置 Psi4。

表示当前环境 未安装 hyq[chemistry]。请执行 pip install "hyq[chemistry]"。

若出现 UnboundLocalError: process（来自 openfermionpsi4），说明曾安装 openfermionpsi4 但 没有 psi4 可执行文件：请 pip uninstall openfermionpsi4，或改用 26.1.4+ 的 hyq（默认不再拉取该包），或按上文安装 Conda 版 Psi4 后使用 hyq[chemistry,psi4]。

导入方式

安装后统一从 hyq 命名空间导入（与 pip 包名一致）：

import hyq
print(hyq.__version__)

from hyq.backends import get_backend, available_backends, set_backend
from hyq.backends.core import QuantumCircuit
from hyq.backends.Tensorcircuit import TensorCircuitBackend
from hyq.solvers import VQESolver
from hyq.algorithms import exact_diagonalization, build_qpe_circuit
from hyq.ansatz import HEAAnsatz, UCCSD
from hyq.chemistry import Hamiltonian

选择默认后端

export HYQ_BACKEND=tensorcircuit   # 或 qiskit、pennylane 等

from hyq.backends import available_backends, set_backend

print(available_backends())
backend = set_backend("tensorcircuit")

快速示例（VQE）

import torch
from hyq.backends.core import QuantumCircuit
from hyq.backends.Tensorcircuit import TensorCircuitBackend
from hyq.solvers import VQESolver

backend = TensorCircuitBackend()
solver = VQESolver(backend)

def ansatz(params):
    qc = QuantumCircuit(2)
    qc.ry(0, params[0])
    qc.cx(0, 1)
    return qc

hamiltonian = [(-1.0, "ZI"), (-1.0, "IZ"), (0.5, "XX")]
init_params = torch.tensor([0.1], dtype=torch.float64)

energy, params, history = solver.solve(
    ansatz, init_params, hamiltonian, steps=100, lr=0.1
)
print(energy, params)

哈密顿量格式

hamiltonian = [
    (-1.0, "ZI"),
    (-1.0, "IZ"),
    (0.5, "XX"),
]

字符串中第 i 个字符对应第 i 个 qubit，支持 I / X / Y / Z。

包结构

hyq/
├── algorithms/   # QPE、Trotter、QSE、VQD、shadow 等
├── ansatz/       # HEA、UCCSD、ADAPT 等
├── backends/     # 线路抽象与各模拟器后端
├── chemistry/    # 分子与哈密顿量（可选）
└── solvers/      # VQE、VarQITE、SA-QITE、SS-QITE、RITE

链接

• PyPI：https://pypi.org/project/hyq/
• 问题与示例 notebook：请使用项目 Git 仓库的 Issues / examples/ 目录