Metadata-Version: 2.4
Name: hyq
Version: 26.1.0
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 是一个轻量级 Python 工具包，用于构建与后端无关的量子线路并运行混合量子算法，例如 VQE、VarQITE、SA‑QITE、SS‑QITE 和 RITE。它提供：

- 用于构建线路的统一 `QuantumCircuit` 抽象。
- 可插拔的后端接口，支持两种执行模式：
    - 采样模式：返回测量计数，类似于硬件或基于采样的模拟器。
    - 状态向量模式：返回精确状态向量，适用于模拟器和可微分算法。
- 针对 Qiskit、PennyLane 和 TensorCircuit 的后端实现。
- 统一 Hamiltonian 格式表示 qubit Hamiltonian
- 可选化学工具，使用 OpenFermion 和 Psi4 生成分子哈密顿量。
- VQE、VarQITE、QITE 系列求解器，以及 classical reference、Trotter、QPE、QSE、VQD、classical shadow 等算法工具。


## 推荐的仓库结构

```text
.
├── algorithms/
│   ├── __init__.py
│   ├── classical_eigensolvers.py
│   ├── phase_estimation.py
│   ├── qse.py
│   ├── quantum_chemistry.py
│   ├── shadow.py
│   ├── trotter.py
│   └── vqd.py
├── ansatz/
│   ├── __init__.py
│   ├── base.py
│   ├── HEA.py
│   ├── ryrz.py
│   ├── compact.py
│   └── adapt.py
├── backends/
│   ├── __init__.py
│   ├── base.py
│   ├── core.py
│   ├── _matrix_simulator.py
│   ├── Qiskit.py
│   ├── Pennylane.py
│   ├── Tensorcircuit.py
│   ├── Cirq.py
│   ├── Qulacs.py
│   └── Qutip.py
├── chemistry/
│   ├── __init__.py
│   ├── hamiltonian.py
│   ├── molecule.py
│   └── psi4_driver.py
├── solvers/
│   ├── __init__.py
│   ├── base.py
│   ├── vqe.py
│   ├── var_qite.py
│   ├── sa_qite.py
│   ├── ss_qite.py
│   └── rite.py
├── examples/
├── tutorials/
├── environment.yml
├── requirements.txt
└── README_chinese.md
```

## 安装

### 从 PyPI 安装

```bash
pip install hyq
pip install "hyq[qiskit,tensorcircuit]"   # 可选后端
pip install "hyq[all]"                    # 全部可选依赖
```

安装后与导入名一致：`import hyq`，`from hyq.backends import get_backend`。

### 从源码安装（Conda）

团队统一使用 **Conda** 管理环境，保证 clone 后各机器依赖一致。环境定义见 `environment.yml`（Python 3.11、Psi4）；Python 包列表与 `requirements.txt` 同步。

### 首次安装（服务器 / 本机）

需已安装 [Miniconda](https://docs.conda.io/en/latest/miniconda.html) 或 Anaconda。

```bash
git clone <repo-url>
cd hyq-alg-lib

conda env create -f environment.yml
conda activate hyq_alg_lib_env
```

验证：

```bash
python -c "import numpy, torch, qiskit, pennylane, tensorcircuit; print('ok')"
python -c "import psi4; print('psi4', psi4.__version__)"   # 化学模块需要
```

### 更新环境（拉取新代码后）

```bash
conda activate hyq_alg_lib_env
conda env update -f environment.yml --prune
```

### 服务器：conda + pip 分步装（有日志、易排查）

适合 `conda env create` 长时间无输出时：先用 conda 建 Python 和 Psi4，再用 pip 装其余依赖。

```bash
conda create -n hyq_alg_lib_env -c conda-forge python=3.11 psi4=1.10 pip -y
conda activate hyq_alg_lib_env
cd hyq-alg-lib

export TMPDIR=/tmp
pip install -U pip
pip install -v --progress-bar on torch==2.9.1    # 最慢，单独装可看进度
pip install -v --progress-bar on -r requirements.txt 2>&1 | tee pip-install.log
```

### 选择默认后端

至少安装一个后端后，通过环境变量指定默认后端（以下为 Linux / macOS）：

```bash
export HYQ_BACKEND=tensorcircuit   # 可微分状态向量算法（推荐 VQE / VarQITE）
# export HYQ_BACKEND=qiskit        # QASM、采样、线路转换
# export HYQ_BACKEND=pennylane     # 可微分原型
```

Windows PowerShell：`$env:HYQ_BACKEND="tensorcircuit"`

### 维护者：在服务器上固化环境

在目标 Linux 机器上确认教程与测试通过后，可将 `environment.yml` 中 `pip:` 段的版本与线上一致；必要时用精简导出辅助核对：

```bash
conda env export --from-history | head -50
```

## Hamiltonian 标准格式

最新版本统一推荐使用如下格式：

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

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

## 后端能力概览

| 后端 | 采样 `run_sampling` | 状态向量 `get_statevector` | PyTorch 自动微分 | 推荐用途 |
|---|---:|---:|---:|---|
| Qiskit | 支持 | 支持 | 不支持 | 采样、QASM、绘图、编译 |
| PennyLane | 支持 | 支持 | 支持 | 可微分模拟和算法原型 |
| TensorCircuit | 支持 | 支持 | 支持 | VQE / VarQITE 等梯度算法 |
| Cirq | 支持 | 支持 | 不支持 | 备用门级模拟后端 |
| Qulacs | 支持 | 支持 | 不支持 | 快速状态向量模拟 |
| QuTiP | 支持 | 支持 | 不支持 | QuTiP 生态入口和教学 |

可用后端可通过：

```python
from backends import available_backends, set_backend, get_backend

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


## 最小线路示例

```python
import torch
from backends.core import QuantumCircuit
from backends.Tensorcircuit import TensorCircuitBackend

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

backend = TensorCircuitBackend()
state = backend.get_statevector(qc)
print(state)

counts = backend.run_sampling(qc, shots=1024, measure_qubits=[0, 1])
print(counts)
```
## 使用求解器

```python
import torch
from backends.core import QuantumCircuit
from backends.Tensorcircuit import TensorCircuitBackend
from solvers.vqe 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)
```

## 生成分子哈密顿量

```python
from chemistry.hamiltonian import Hamiltonian

symbols = ["H", "H"]
geometry = [[0.0, 0.0, 0.0], [0.0, 0.0, 0.74]]

ham = Hamiltonian(symbols, geometry, charge=0, multiplicity=1, basis="sto-3g")
terms, n_qubits, n_electrons = ham.get_processed_hamiltonian(
    n_active_electrons=2,
    n_active_orbitals=2,
    mapping="jw",
    reverse_endian=False,
)
```

## VQE 示例

```python
import torch
from backends.core import QuantumCircuit
from backends.Tensorcircuit import TensorCircuitBackend
from solvers.vqe 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)
print(params)
```

## Quantum Phase Estimation

```python
import numpy as np
from backends.core import QuantumCircuit
from algorithms import build_qpe_circuit, phases_from_counts

phi = 0.375
unitary = QuantumCircuit(1)
unitary.p(0, 2 * np.pi * phi)

qpe = build_qpe_circuit(unitary, n_ancilla=3)
print(qpe)

# 后端采样后：
# counts = backend.run_sampling(qpe, shots=2048, measure_qubits=[0, 1, 2])
# result = phases_from_counts(counts, n_ancilla=3)
```

## QSE：Quantum Subspace Expansion

```python
import numpy as np
from algorithms import quantum_subspace_expansion

reference_state = np.array([1.0, 0.0], dtype=np.complex128)
hamiltonian = [(1.0, "Z"), (0.2, "X")]
excitation_terms = [[(1.0, "X")]]

result = quantum_subspace_expansion(
    reference_state=reference_state,
    hamiltonian=hamiltonian,
    excitation_terms=excitation_terms,
    n_qubits=1,
)

print(result.energies)
print(result.kept_subspace_dimension)
```

## VQD：Variational Quantum Deflation 辅助工具

```python
import numpy as np
from algorithms import deflated_eigensystem, vqd_objective_from_matrix

H = np.diag([0.0, 1.0, 2.0]).astype(np.complex128)
ground_state = np.array([1.0, 0.0, 0.0], dtype=np.complex128)

vals, vecs = deflated_eigensystem(H, previous_states=[ground_state], betas=[5.0])
print(vals)

breakdown = vqd_objective_from_matrix(
    H,
    candidate_state=vecs[:, 0],
    previous_states=[ground_state],
    betas=[5.0],
)
print(breakdown)
```

## Classical Shadow

```python
from algorithms import ClassicalShadow

shadow = ClassicalShadow(
    backend=backend,
    circuit=qc,
    seed=123,
)

shadow.collect(5000)
print(shadow.estimate_observable("XX"))

hamiltonian = [(1.0, "II"), (0.5, "XX"), (-0.3, "ZZ")]
print(shadow.estimate_hamiltonian(hamiltonian))
```

## 量子化学辅助函数

```python
import numpy as np
from algorithms import (
    fci_reference_energy,
    chemical_accuracy_error,
    mp2_energy_from_integrals,
    state_fidelity,
    particle_number_expectation,
    spin_z_expectation,
)

hamiltonian = [(1.0, "Z"), (0.2, "X")]
ref = fci_reference_energy(hamiltonian, n_qubits=1)
print(ref)
print(chemical_accuracy_error(estimated_energy=-1.018, reference_energy=ref))

state = np.array([0.0, 0.0, 0.0, 2.0], dtype=np.complex128)
print(particle_number_expectation(state, n_qubits=2))
print(spin_z_expectation(state, n_qubits=2))
```


