Metadata-Version: 2.4
Name: hyq
Version: 26.1.4
Summary: HyQ: hybrid quantum algorithms toolkit with backend-agnostic circuits and solvers
Author: HyQ Contributors
Keywords: quantum,vqe,qite,hybrid,quantum-computing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.12,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy<2,>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: torch>=2.0
Requires-Dist: qiskit>=2.0
Requires-Dist: qiskit-aer>=0.17
Requires-Dist: pylatexenc==2.10
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.43; extra == "pennylane"
Requires-Dist: pennylane-lightning>=0.43; extra == "pennylane"
Provides-Extra: tensorcircuit
Requires-Dist: tensorcircuit>=0.12; extra == "tensorcircuit"
Requires-Dist: opt-einsum>=3.4; extra == "tensorcircuit"
Provides-Extra: optional-backends
Requires-Dist: cirq>=1.6; extra == "optional-backends"
Requires-Dist: qulacs>=0.6; extra == "optional-backends"
Requires-Dist: qutip>=5.2; extra == "optional-backends"
Requires-Dist: qutip-qip>=0.4; extra == "optional-backends"
Provides-Extra: chemistry
Requires-Dist: openfermion>=1.7; extra == "chemistry"
Requires-Dist: openfermionpyscf>=0.5; extra == "chemistry"
Requires-Dist: pyscf>=2.8; extra == "chemistry"
Provides-Extra: psi4
Requires-Dist: openfermionpsi4>=0.5; extra == "psi4"
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6.29; extra == "notebooks"
Requires-Dist: matplotlib>=3.8; extra == "notebooks"
Requires-Dist: nbconvert>=7.16; extra == "notebooks"
Requires-Dist: nbclient>=0.10; extra == "notebooks"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: isort>=5.13; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Requires-Dist: mypy>=1.14; extra == "dev"
Provides-Extra: all
Requires-Dist: hyq[chemistry,notebooks,optional-backends,pennylane,tensorcircuit]; extra == "all"

# 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 安装（见下表）

## 安装

```bash
pip install hyq
```

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

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

### 可选依赖（extras）

| Extra | 用途 |
|-------|------|
| `pennylane` | PennyLane 后端 |
| `tensorcircuit` | TensorCircuit 后端（推荐可微分流程） |
| `optional-backends` | Cirq、Qulacs、QuTiP |
| `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` 一致）。

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

验证：

```bash
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')"
```

最小用法：

```python
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 时请：

```bash
# 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]"
```

验证：

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

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

```bash
export PSI4_SCRATCH=/tmp
export TMPDIR=/tmp
```

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

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

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

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

详见仓库内 **`README_HYQ.md`**。

### 常见报错

若出现：

```text
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` 包名一致）：

```python
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
```

## 选择默认后端

```bash
export HYQ_BACKEND=tensorcircuit   # 或 qiskit、pennylane 等
```

```python
from hyq.backends import available_backends, set_backend

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

## 快速示例（VQE）

```python
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)
```

## 哈密顿量格式

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

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

## 包结构

```text
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/` 目录
