Metadata-Version: 2.4
Name: hyq
Version: 26.1.1
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
Provides-Extra: qiskit
Requires-Dist: qiskit>=2.0; extra == "qiskit"
Requires-Dist: qiskit-aer>=0.17; extra == "qiskit"
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: openfermionpsi4>=0.5; extra == "chemistry"
Requires-Dist: pyscf>=2.8; extra == "chemistry"
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"
Requires-Dist: pylatexenc>=2.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,qiskit,tensorcircuit]; extra == "all"

# HyQ

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

- **Python**：3.10、3.11（见 `requires-python`）
- **核心依赖**（随 `pip install hyq` 自动安装）：NumPy、SciPy、PyTorch
- **量子后端与化学功能**：通过可选 extra 安装（见下表）

## 安装

```bash
pip install hyq
```

至少安装一个后端后再使用线路与求解器（推荐）：

```bash
pip install "hyq[tensorcircuit]"              # VQE / VarQITE 等可微分算法
pip install "hyq[qiskit]"                     # 采样、QASM、线路转换
pip install "hyq[qiskit,tensorcircuit]"       # 常用组合
pip install "hyq[all]"                        # 全部可选 Python 依赖（体积较大）
```

### 可选依赖（extras）

| Extra | 用途 |
|-------|------|
| `qiskit` | Qiskit / Aer 后端 |
| `pennylane` | PennyLane 后端 |
| `tensorcircuit` | TensorCircuit 后端（推荐可微分流程） |
| `optional-backends` | Cirq、Qulacs、QuTiP |
| `chemistry` | OpenFermion、PySCF 等（分子哈密顿量） |
| `notebooks` | 运行 notebook 的辅助包 |
| `dev` | pytest、black 等开发工具 |
| `all` | 上述除 `dev` 外的组合 |

> **Psi4** 不在 PyPI 上，无法通过 `pip` 安装。需要 Psi4 时请用 Conda 单独安装，并参考仓库内的开发文档。

## 导入方式

安装后统一从 `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/` 目录
