Qibo 哈密顿量 API 完全指南¶

本文档详细介绍了 Qibo 框架中所有公开的哈密顿量 API，包括类、方法、参数说明和使用示例。

📚 目录¶

概述
核心概念
Hamiltonian 类 - 矩阵形式
SymbolicHamiltonian 类 - 符号形式
预定义哈密顿量模型
绝热哈密顿量
哈密顿量项（高级用法）
实用示例
最佳实践与性能优化
API 快速参考

概述¶

Qibo 提供了两种主要的哈密顿量实现方式：

Hamiltonian：基于完整矩阵表示，适合小规模系统（≤10 量子比特）
SymbolicHamiltonian：基于符号表达式，适合大规模系统（>10 量子比特）

类继承关系¶

AbstractHamiltonian (抽象基类)
├── Hamiltonian (矩阵哈密顿量)
└── SymbolicHamiltonian (符号哈密顿量)

核心概念¶

什么是哈密顿量？¶

哈密顿量是量子系统的总能量算符，用于描述系统的演化。在量子计算中，哈密顿量用于：

模拟量子系统的动力学演化
定义优化问题的目标函数（如 QAOA）
计算能级和基态
计算期望值

两种表示形式的对比¶

特性	Hamiltonian	SymbolicHamiltonian
存储方式	完整 2ⁿ×2ⁿ 矩阵	符号表达式
内存消耗	高 (O(4ⁿ))	低 (O(项数))
计算速度	快（直接矩阵运算）	较慢（需构建矩阵）
适用规模	≤10 量子比特	>10 量子比特
Trotter 分解	不支持	支持
稀疏矩阵	支持	N/A

Hamiltonian 类 - 矩阵形式¶

类定义¶

from qibo import hamiltonians
import numpy as np

class Hamiltonian(AbstractHamiltonian):
    """基于矩阵表示的哈密顿量"""

初始化¶

`init(self, nqubits, matrix, backend=None)`¶

参数说明：

参数	类型	必需	说明
`nqubits`	int	✅	量子比特数
`matrix`	ndarray	✅	哈密顿量矩阵，形状为 `(2ⁿ, 2ⁿ)`
`backend`	Backend	❌	计算后端（默认为全局后端）

矩阵格式支持： - 稠密矩阵（numpy 数组） - 稀疏矩阵（scipy.sparse，仅 numpy/qibojit 后端） - TF 稀疏张量（tensorflow 后端）

示例：

import numpy as np
from qibo import hamiltonians

# 创建 2 量子比特的哈密顿量矩阵
matrix = np.array([[1, 0, 0, 0],
                   [0, -1, 0, 0],
                   [0, 0, -1, 0],
                   [0, 0, 0, 1]])

ham = hamiltonians.Hamiltonian(nqubits=2, matrix=matrix)

核心方法¶

1. 特征值计算¶

`eigenvalues(k=6)`¶

计算哈密顿量的特征值。

参数： - k (int): 计算的特征值数量（仅稀疏矩阵有效，默认 6）

返回值： ndarray - 特征值数组（升序排列）

示例：

# 计算所有特征值（稠密矩阵）
eigvals = ham.eigenvalues()
print(f"特征值: {eigvals}")

# 计算前 10 个最小特征值（稀疏矩阵）
sparse_ham = hamiltonians.Hamiltonian(nqubits, sparse_matrix)
eigvals = sparse_ham.eigenvalues(k=10)

2. 特征向量计算¶

`eigenvectors(k=6)`¶

计算哈密顿量的特征向量。

参数： - k (int): 计算的特征向量数量

返回值： ndarray - 特征向量矩阵，每列是一个特征向量

示例：

# 计算特征向量
eigvecs = ham.eigenvectors()
ground_state = eigvecs[:, 0]  # 第一列是基态

3. 基态计算¶

`ground_state()`¶

直接返回哈密顿量的基态（最低能量本征态）。

返回值： ndarray - 基态向量

示例：

gs = ham.ground_state()
print(f"基态能量: {ham.expectation(gs)}")

4. 矩阵指数¶

`exp(a)`¶

计算矩阵指数 exp(-i*a*H)，用于时间演化。

参数： - a (complex): 时间参数

返回值： ndarray - 指数矩阵

示例：

# 计算 exp(-i*0.5*H)
U = ham.exp(0.5)

# 应用到状态向量
evolved_state = U @ initial_state

性能说明： - 使用缓存机制，相同参数的重复计算会直接返回结果 - 利用预计算的特征值/特征向量加速计算

5. 期望值计算¶

`expectation(state, normalize=False)`¶

计算给定状态的期望值 <ψ|H|ψ>。

参数： - state (ndarray): 量子态 - 状态向量：形状 (2ⁿ,) - 密度矩阵：形状 (2ⁿ, 2ⁿ) - normalize (bool): 是否归一化（默认 False）

返回值： float - 期望值（实数）

示例：

from qibo import Circuit

# 创建电路并执行
circuit = Circuit(2)
circuit.add(gates.H(0))
circuit.add(gates.CNOT(0, 1))
result = circuit()

# 从状态向量计算期望值
exp_value = ham.expectation(result.state())
print(f"期望值: {exp_value}")

# 从密度矩阵计算
exp_value_dm = ham.expectation(result.density_matrix(), normalize=False)

`expectation_from_samples(freq, qubit_map=None)`¶

从测量样本计算期望值（仅对角可观测量）。

参数： - freq (dict): 测量频率字典，键为二进制字符串 - qubit_map (list): 量子比特映射（默认为 [0, 1, ..., n-1]）

返回值： float - 期望值

示例：

# 模拟测量结果
frequencies = {'00': 100, '01': 50, '10': 30, '11': 20}

# 计算期望值
exp_value = ham.expectation_from_samples(frequencies)
print(f"从样本计算的期望值: {exp_value}")

注意： 此方法仅支持对角哈密顿量（如 Z 算符的线性组合）。

6. 能量涨落¶

`energy_fluctuation(state)`¶

计算能量涨落 √(<H²> - <H>²)。

参数： - state (ndarray): 量子态

返回值： float - 能量涨落值

示例：

fluctuation = ham.energy_fluctuation(state)
print(f"能量涨落: {fluctuation}")

运算符重载¶

Hamiltonian 类支持以下运算符：

运算符	表达式	说明	示例
`+`	`H1 + H2`	哈密顿量相加	`H_total = H1 + H2`
`+`	`H + c`	加常数项（c*I）	`H_shifted = H + 1.5`
`-`	`H1 - H2`	哈密顿量相减	`H_diff = H1 - H2`
`-`	`H - c`	减常数项	`H_shifted = H - 0.5`
`-`	`c - H`	右减常数	`H_new = 2.0 - H`
`*`	`c * H`	标量乘法	`H_scaled = 2.0 * H`
`*`	`H * c`	标量乘法（右侧）	`H_scaled = H * 2.0`
`@`	`H1 @ H2`	矩阵乘法	`H_prod = H1 @ H2`
`@`	`H @ state`	作用到状态	`new_state = H @ state`

示例：

H1 = hamiltonians.X(3)
H2 = hamiltonians.Z(3)

# 组合运算
H_total = H1 + H2           # 加法
H_scaled = 2.5 * H1         # 标量乘法
H_product = H1 @ H2         # 矩阵乘法
H_shifted = H1 - 1.0        # 减常数

# 作用到状态
state = np.random.rand(8)
new_state = H1 @ state

属性¶

属性	类型	说明
`nqubits`	int	量子比特数（可读写）
`matrix`	ndarray	哈密顿量矩阵（可读写）
`backend`	Backend	计算后端

示例：

ham = hamiltonians.X(4)
print(f"量子比特数: {ham.nqubits}")
print(f"矩阵形状: {ham.matrix.shape}")

# 修改矩阵
new_matrix = np.eye(16) * 2
ham.matrix = new_matrix

SymbolicHamiltonian 类 - 符号形式¶

类定义¶

from qibo import hamiltonians
from qibo.symbols import X, Y, Z, I

class SymbolicHamiltonian(AbstractHamiltonian):
    """基于符号表达式的哈密顿量"""

初始化¶

`init(self, form, nqubits=None, backend=None)`¶

参数说明：

参数	类型	必需	说明
`form`	sympy.Expr	✅	哈密顿量的符号表达式
`nqubits`	int	❌	量子比特数（默认自动推断）
`backend`	Backend	❌	计算后端

符号构建：

使用 qibo.symbols 中的符号：

符号	说明
`X(i)`	第 i 个量子比特的 Pauli-X 算符
`Y(i)`	第 i 个量子比特的 Pauli-Y 算符
`Z(i)`	第 i 个量子比特的 Pauli-Z 算符
`I(i)`	第 i 个量子比特的单位算符

示例：

from qibo import hamiltonians
from qibo.symbols import X, Y, Z, I

# 构建海森堡相互作用
form = X(0) * X(1) + Y(0) * Y(1) + Z(0) * Z(1)
ham = hamiltonians.SymbolicHamiltonian(form)

# 横向场伊辛模型
form = sum(Z(i) * Z(i+1) for i in range(4)) + 0.5 * sum(X(i) for i in range(4))
ham = hamiltonians.SymbolicHamiltonian(form, nqubits=4)

核心方法¶

1. 特征值和特征向量¶

`eigenvalues(k=6)`, `eigenvectors(k=6)`, `ground_state()`¶

与 Hamiltonian 类相同，但内部会转换为矩阵形式。

示例：

form = X(0) * X(1) + Z(0) * Z(1)
ham = hamiltonians.SymbolicHamiltonian(form)

# 计算特征值（内部转换为矩阵）
eigvals = ham.eigenvalues()

2. 矩阵指数¶

`exp(a)`¶

与 Hamiltonian 相同。

3. 期望值计算¶

`expectation(state, normalize=False)`¶

从状态向量或密度矩阵计算期望值。

`expectation_from_samples(freq, qubit_map=None)`¶

从测量样本计算期望值（仅 Z 型哈密顿量）。

`expectation_from_circuit(circuit, nshots=1000)` ⭐ 新增¶

从电路执行计算期望值，支持非对角可观测量！

参数： - circuit (Circuit): 量子电路 - nshots (int): 测量次数（默认 1000）

返回值： float - 期望值

示例：

from qibo import Circuit, gates
from qibo.symbols import X, Y, Z

# 创建包含 X 和 Y 的哈密顿量
form = X(0) * Y(1) + Z(0) * Z(1)
ham = hamiltonians.SymbolicHamiltonian(form)

# 创建电路
circuit = Circuit(2)
circuit.add(gates.H(0))
circuit.add(gates.CNOT(0, 1))

# 从电路计算期望值（会自动添加必要的基变换门）
exp_value = ham.expectation_from_circuit(circuit, nshots=10000)
print(f"期望值: {exp_value}")

工作原理： 1. 将哈密顿量项按可对易性分组 2. 为每组添加适当的基变换门（如 X→H，Y→S†H） 3. 执行电路并测量 4. 从测量频率计算每项的期望值 5. 汇总所有贡献

4. Trotter 分解¶

`circuit(dt, accelerators=None)`¶

生成实现 Trotter 时间演化的量子电路。

参数： - dt (float): 时间步长 - accelerators (dict): 分布式执行的加速器配置

返回值： Circuit - 量子电路对象

示例：

form = X(0) * X(1) + Z(0) * Z(1)
ham = hamiltonians.SymbolicHamiltonian(form)

# 生成 Trotter 电路
trotter_circuit = ham.circuit(dt=0.01)

# 执行演化
result = trotter_circuit()

实现细节： - 使用二阶 Trotter 分解（对称分解） - exp(dt*H) ≈ ∏ exp(dt/2 * Hi) ∏ exp(dt/2 * Hi)（反向） - 自动对可交换项分组优化

5. 状态演化¶

`apply_gates(state, density_matrix=False)`¶

将哈密顿量的所有门应用到状态。

参数： - state (ndarray): 量子态 - density_matrix (bool): 是否为密度矩阵模式

返回值： ndarray - 演化后的状态

示例：

form = Z(0) + Z(1)
ham = hamiltonians.SymbolicHamiltonian(form)

state = np.array([1, 0, 0, 0])
new_state = ham.apply_gates(state)

属性¶

属性	类型	说明
`nqubits`	int	量子比特数
`form`	sympy.Expr	符号表达式（可读写）
`dense`	Hamiltonian	密集矩阵表示（计算时警告）
`terms`	list[SymbolicTerm]	哈密顿量的项列表
`diagonal_terms`	list[list]	可同时对角化的项组

示例：

form = X(0) * X(1) + Z(0) * Z(1)
ham = hamiltonians.SymbolicHamiltonian(form)

# 查看项
print(f"哈密顿量包含 {len(ham.terms)} 项")
for term in ham.terms:
    print(f"  系数: {term.coefficient}, 因子: {term.factors}")

# 查看可对角化分组
print(f"可对角化分组: {len(ham.diagonal_groups)}")

# 转换为矩阵（会警告）
dense_ham = ham.dense

运算符重载¶

与 Hamiltonian 相同，支持 +, -, *, @。

示例：

from qibo.symbols import X, Y, Z

H1 = hamiltonians.SymbolicHamiltonian(X(0) * X(1))
H2 = hamiltonians.SymbolicHamiltonian(Z(0) * Z(1))

H_total = H1 + H2          # 符号相加
H_scaled = 2.0 * H1        # 标量乘法
H_prod = H1 @ H2           # 矩阵乘法

预定义哈密顿量模型¶

Qibo 提供了一系列预定义的常见物理模型和优化问题哈密顿量。

导入¶

from qibo import hamiltonians

1. 单体泡利哈密顿量¶

`X(nqubits, dense=True, backend=None)`¶

Pauli-X 哈密顿量：H = -Σₖ Xₖ

参数： - nqubits (int): 量子比特数 - dense (bool): True 返回 Hamiltonian，False 返回 SymbolicHamiltonian - backend (Backend): 计算后端

示例：

# 矩阵形式
X_ham = hamiltonians.X(nqubits=4)

# 符号形式
X_ham_symbolic = hamiltonians.X(nqubits=10, dense=False)

`Y(nqubits, dense=True, backend=None)`¶

Pauli-Y 哈密顿量：H = -Σₖ Yₖ

`Z(nqubits, dense=True, backend=None)`¶

Pauli-Z 哈密顿量：H = -Σₖ Zₖ

2. 横向场伊辛模型 (TFIM)¶

`TFIM(nqubits, h=0.0, dense=True, backend=None)`¶

横向场伊辛模型：H = -Σₖ (Zₖ⊗Zₖ₊₁ + h·Xₖ)

采用周期性边界条件（Zₙ⊗Z₁）。

参数： - nqubits (int): 量子比特数（必须 ≥ 2） - h (float): 横向场强度（默认 0.0） - h=0: 纯经典伊辛模型 - h>0: 引入量子涨落 - dense (bool): 返回类型 - backend (Backend): 计算后端

示例：

# 经典伊辛模型（h=0）
tfim_classical = hamiltonians.TFIM(nqubits=10, h=0.0)

# 量子伊辛模型（h=1.0）
tfim_quantum = hamiltonians.TFIM(nqubits=10, h=1.0)

# 使用符号形式（大规模）
tfim_large = hamiltonians.TFIM(nqubits=20, h=0.5, dense=False)

应用场景： - 量子相变研究 - 量子退火算法 - QAOA 初态哈密顿量

3. 最大割问题 (MaxCut)¶

`MaxCut(nqubits, dense=True, adj_matrix=None, backend=None)`¶

最大割问题哈密顿量：H = -½ Σⱼₖ (1 - Zⱼ⊗Zₖ)

参数： - nqubits (int): 量子比特数（图节点数） - dense (bool): 返回类型 - adj_matrix (ndarray): 图的邻接矩阵 - 默认 None：全连接图，所有边权重为 1.0 - 形状：(nqubits, nqubits) - backend (Backend): 计算后端

示例：

# 默认全连接图
maxcut_default = hamiltonians.MaxCut(nqubits=5)

# 自定义图
import numpy as np
adj_matrix = np.array([
    [0, 1, 1, 0],
    [1, 0, 1, 1],
    [1, 1, 0, 1],
    [0, 1, 1, 0]
])
maxcut_custom = hamiltonians.MaxCut(nqubits=4, adj_matrix=adj_matrix)

# 大规模图（符号形式）
maxcut_large = hamiltonians.MaxCut(nqubits=50, dense=False)

应用场景： - QAOA 算法测试 - 组合优化问题 - 网络设计优化

4. 海森堡模型¶

`Heisenberg(nqubits, coupling_constants, external_field_strengths, dense=True, backend=None)`¶

通用海森堡模型：

H = -Σₖ (Jₓ·Xₖ·Xₖ₊₁ + Jᵧ·Yₖ·Yₖ₊₁ + J_z·Zₖ·Zₖ₊₁)
    -Σₖ (hₓ·Xₖ + hᵧ·Yₖ + h_z·Zₖ)

参数： - nqubits (int): 量子比特数 - coupling_constants (float | list[3]): 耦合常数 {Jₓ, Jᵧ, J_z} - external_field_strengths (float | list[3]): 外部磁场 {hₓ, hᵧ, h_z} - dense (bool): 返回类型 - backend (Backend): 计算后端

示例：

# 各向同性（Jₓ=Jᵧ=J_z=1）
heisenberg_iso = hamiltonians.Heisenberg(
    nqubits=8,
    coupling_constants=1.0,
    external_field_strengths=[0.5, 0, 0]
)

# 各向异性（Jₓ=1, Jᵧ=1, J_z=0.5）
heisenberg_aniso = hamiltonians.Heisenberg(
    nqubits=8,
    coupling_constants=[1.0, 1.0, 0.5],
    external_field_strengths=0.2
)

`XXX(nqubits, coupling_constant=1, external_field_strengths=[0.5, 0, 0], dense=True, backend=None)`¶

各向同性 XXX 模型。

参数： - coupling_constant (float): 耦合常数 J - external_field_strengths (list): 外部磁场 {hₓ, hᵧ, h_z}

示例：

xxx_ham = hamiltonians.XXX(
    nqubits=6,
    coupling_constant=1.5,
    external_field_strengths=[0.3, 0, 0]
)

`XXZ(nqubits, delta=0.5, dense=True, backend=None)`¶

XXZ 模型：H = Σₖ (Xₖ·Xₖ₊₁ + Yₖ·Yₖ₊₁ + δ·Zₖ·Zₖ₊₁)

参数： - delta (float): Z 方向各向异性参数 - δ=1: XXX 模型 - δ=0: XY 模型 - δ≠1: XXZ 各向异性

示例：

# XXZ 模型
xxz_ham = hamiltonians.XXZ(nqubits=10, delta=0.5)

# XY 模型
xy_ham = hamiltonians.XXZ(nqubits=10, delta=0)

5. 低自相关二元序列 (LABS)¶

`LABS(nqubits, dense=True, backend=None)`¶

低自相关二元序列问题哈密顿量。

参数： - nqubits (int): 序列长度（必须 > 2） - dense (bool): 返回类型 - backend (Backend): 计算后端

示例：

labs_ham = hamiltonians.LABS(nqubits=20)

绝热哈密顿量¶

概述¶

绝热哈密顿量实现形式为 H(t) = (1-s(t/T))·H₀ + s(t/T)·H₁ 的时间依赖哈密顿量。

创建¶

from qibo import hamiltonians

# 创建初始哈密顿量 H0 和目标哈密顿量 H1
h0 = hamiltonians.X(nqubits=4, dense=False)
h1 = hamiltonians.TFIM(nqubits=4, h=1.0, dense=False)

# 创建绝热哈密顿量（自动选择类型）
adiabatic_ham = hamiltonians.AdiabaticHamiltonian(h0, h1)

使用¶

1. 设置调度函数¶

# 定义调度函数 s(t)
def linear_schedule(t):
    """线性调度"""
    return t

def quadratic_schedule(t):
    """二次调度"""
    return t**2

def s_schedule(t):
    """S 形调度（平滑过渡）"""
    return t**2 * (3 - 2*t)

2. 创建绝热演化模型¶

from qibo import models

# 创建绝热演化模型
evolution = models.AdiabaticEvolution(
    h0, h1,
    lambda t: t,  # 线性调度
    dt=1e-2,
    solver="exp"
)

# 执行演化
final_state = evolution(final_time=10)

3. 直接使用绝热哈密顿量¶

# 设置总时间和调度函数
adiabatic_ham.total_time = 10.0
adiabatic_ham.schedule = linear_schedule

# 获取 t 时刻的哈密顿量
H_t = adiabatic_ham(t=5.0)  # T/2 时刻

# 生成 Trotter 电路（仅符号形式）
if isinstance(adiabatic_ham, hamiltonians.SymbolicAdiabaticHamiltonian):
    trotter_circuit = adiabatic_ham.circuit(dt=0.01)

类型说明¶

根据输入的 H₀ 和 H₁ 类型，自动选择：

BaseAdiabaticHamiltonian：当 H₀ 和 H₁ 都是 Hamiltonian 时
不支持 Trotter 电路
使用完整矩阵指数
SymbolicAdiabaticHamiltonian：当 H₀ 和 H₁ 都是 SymbolicHamiltonian 时
支持 Trotter 电路
支持分布式执行
内存效率高

重要： H₀ 和 H₁ 必须是相同类型！

哈密顿量项（高级用法）¶

概述¶

SymbolicHamiltonian 内部由 HamiltonianTerm 或 SymbolicTerm 对象列表构成。高级用户可以直接操作这些项。

SymbolicTerm 类¶

创建¶

from qibo.hamiltonians.terms import SymbolicTerm
from qibo.symbols import X, Y

# 创建单项
term1 = SymbolicTerm(coefficient=1.0, factors=X(0) * X(1))
term2 = SymbolicTerm(coefficient=2.0, factors=Y(0) * Y(1))

主要方法¶

`commute(term) -> bool`¶

检查是否与另一项对易。

term1 = SymbolicTerm(1.0, X(0) * X(1))
term2 = SymbolicTerm(1.0, Z(0) * Z(1))

print(term1.commute(term2))  # False（反对易）

`copy()`¶

创建项的副本。

new_term = term.copy()

TermGroup 类¶

多个 HamiltonianTerm 的集合，用于 Trotter 分解优化。

使用¶

from qibo.hamiltonians.terms import TermGroup, SymbolicTerm

# 创建项列表
terms = [
    SymbolicTerm(1.0, X(0) * X(1)),
    SymbolicTerm(1.0, Z(0) * Z(1)),
    SymbolicTerm(0.5, X(0) * Z(1))
]

# 分组
groups = TermGroup.from_terms(terms)

# 每组可合并为单个项
for group in groups:
    merged_term = group.term
    print(f"组目标比特: {group.target_qubits}")

实用示例¶

示例 1：创建自定义哈密顿量¶

from qibo import hamiltonians
from qibo.symbols import X, Y, Z
import numpy as np

# 方法 1：使用符号表达式
form = 2.0 * X(0) * X(1) + 1.5 * Y(0) * Y(1) - 0.5 * Z(0) * Z(1)
ham_symbolic = hamiltonians.SymbolicHamiltonian(form)

# 方法 2：直接构造矩阵
# 构造 4x4 矩阵（2 量子比特）
matrix = np.array([
    [1, 0, 0, 0],
    [0, -1, 2, 0],
    [0, 2, -1, 0],
    [0, 0, 0, 1]
])
ham_matrix = hamiltonians.Hamiltonian(nqubits=2, matrix=matrix)

示例 2：计算基态和能谱¶

from qibo import hamiltonians

# 创建 TFIM 模型
ham = hamiltonians.TFIM(nqubits=8, h=1.0)

# 计算基态
ground_state = ham.ground_state()

# 计算基态能量
gs_energy = ham.expectation(ground_state)
print(f"基态能量: {gs_energy}")

# 计算前 5 个激发态能量
eigenvalues = ham.eigenvalues()
print(f"前 5 个能级: {eigenvalues[:5]}")

示例 3：使用 QAOA 求解 MaxCut¶

from qibo import models, hamiltonians
import numpy as np

# 定义 MaxCut 问题
nqubits = 5
ham = hamiltonians.MaxCut(nqubits=nqubits)

# 创建 QAOA 模型
n_layers = 2
qaoa = models.QAOA(ham, n_layers)

# 优化
best_params, best_energy = qaoa.minimize(
    initial_parameters=np.random.uniform(0, 2*np.pi, 2*n_layers)
)

print(f"最优参数: {best_params}")
print(f"最优能量: {best_energy}")

示例 4：时间演化模拟¶

from qibo import hamiltonians, Circuit, gates
import numpy as np

# 创建哈密顿量
ham = hamiltonians.TFIM(nqubits=6, h=0.5, dense=False)

# 初始状态
circuit = Circuit(6)
circuit.add(gates.H(i) for i in range(6))
initial_state = circuit().state()

# 时间演化
T = 1.0
dt = 0.01
n_steps = int(T / dt)

state = initial_state.copy()
for _ in range(n_steps):
    # 使用 Trotter 分解
    trotter_circuit = ham.circuit(dt)
    state = trotter_circuit(initial_state=state).state()

# 计算可观测量
exp_z = sum(hamiltonians.Z(6).expectation(state) for _ in range(1))
print(f"Z 期望值: {exp_z}")

示例 5：从测量样本计算期望值¶

from qibo import Circuit, gates
from qibo.symbols import Z

# 创建电路
circuit = Circuit(3)
circuit.add(gates.H(0))
circuit.add(gates.CNOT(0, 1))
circuit.add(gates.CNOT(1, 2))

# 执行并测量
result = circuit(nshots=10000)
frequencies = result.frequencies()

# 创建哈密顿量（Z₁ + Z₂）
from qibo import hamiltonians
ham = hamiltonians.Z(3)  # -ΣZᵢ

# 从样本计算期望值
exp_value = ham.expectation_from_samples(frequencies)
print(f"期望值: {exp_value}")

示例 6：绝热演化¶

from qibo import models, hamiltonians

# 定义问题
nqubits = 6
h0 = hamiltonians.X(nqubits, dense=False)
h1 = hamiltonians.TFIM(nqubits, h=1.0, dense=False)

# 定义调度函数
def schedule(t):
    return t**2  # 二次调度

# 创建绝热演化模型
adiabatic = models.AdiabaticEvolution(
    h0, h1,
    schedule,
    dt=0.01,
    solver="exp"
)

# 执行演化
final_energy = final_time=5.0
final_state = adiabatic(final_time=5.0)

# 计算最终能量
final_energy = h1.expectation(final_state)
print(f"最终能量: {final_energy}")

示例 7：混合运算符¶

from qibo import hamiltonians
from qibo.symbols import X, Y, Z

# 创建哈密顿量
H1 = hamiltonians.SymbolicHamiltonian(X(0) * X(1))
H2 = hamiltonians.SymbolicHamiltonian(Y(0) * Y(1))
H3 = hamiltonians.SymbolicHamiltonian(Z(0) * Z(1))

# 组合运算
H_total = H1 + H2 + H3
H_scaled = 2.5 * H_total
H_shifted = H_total - 1.0

# 矩阵乘法
H_product = H1 @ H2

# 作用到状态
import numpy as np
state = np.array([1, 0, 0, 0])
new_state = H1 @ state

最佳实践与性能优化¶

1. 选择合适的哈密顿量类型¶

使用 `Hamiltonian`（矩阵形式）当：¶

✅ 量子比特数 ≤ 10-12
✅ 需要频繁计算特征值/特征向量
✅ 需要完整矩阵运算
✅ 内存充足

使用 `SymbolicHamiltonian`（符号形式）当：¶

✅ 量子比特数 > 12
✅ 使用变分算法（VQE、QAOA）
✅ 内存受限
✅ 需要 Trotter 分解
✅ 主要进行态向量演化

2. 避免重复计算¶

# ❌ 不好：重复计算特征值
for _ in range(100):
    eigvals = ham.eigenvalues()  # 每次都重新计算

# ✅ 好：利用缓存
eigvals = ham.eigenvalues()  # 计算一次并缓存
for _ in range(100):
    eigvals = ham.eigenvalues()  # 使用缓存结果

3. 使用稀疏矩阵¶

from scipy.sparse import csr_matrix

# 创建稀疏矩阵
sparse_matrix = csr_matrix((data, (row, col)), shape=(2**n, 2**n))

# 用于哈密顿量（仅 numpy/qibojit 后端）
ham = hamiltonians.Hamiltonian(nqubits, sparse_matrix)

4. 优化期望值计算¶

# 对于符号哈密顿量，优先使用 expectation_from_circuit
ham = hamiltonians.SymbolicHamiltonian(form)

# ✅ 好：使用电路（支持非对角）
exp_value = ham.expectation_from_circuit(circuit, nshots=10000)

# ⚠️ 限制：expectation_from_samples 仅支持对角
if all_z_hamiltonian:
    exp_value = ham.expectation_from_samples(frequencies)

5. 批量操作¶

# ❌ 不好：多次创建电路
for i in range(100):
    circuit = ham.circuit(dt)

# ✅ 好：创建一次，重复使用
trotter_circuit = ham.circuit(dt)
for i in range(100):
    result = trotter_circuit()

6. 内存管理¶

# 对于大规模系统，避免转换为密集矩阵
large_ham = hamiltonians.TFIM(nqubits=20, h=1.0, dense=False)

# ❌ 不好：会消耗大量内存
dense = large_ham.dense  # 会记录警告

# ✅ 好：使用符号运算
eigvals = large_ham.eigenvalues()  # 只在需要时转换

7. 后端选择¶

from qibo import set_backend

# 根据任务选择后端
# numpy：稳定，兼容性好
set_backend("numpy")

# tensorflow：GPU 加速
set_backend("tensorflow")

# pytorch：灵活性高
set_backend("pytorch")

8. 分布式计算¶

# 配置加速器用于大规模电路
accelerators = {'/GPU:0': 2, '/GPU:1': 2}

circuit = ham.circuit(dt=0.01, accelerators=accelerators)

API 快速参考¶

Hamiltonian 类¶

方法	参数	返回值	说明
`__init__`	nqubits, matrix, backend	Hamiltonian	初始化
`eigenvalues`	k=6	ndarray	计算特征值
`eigenvectors`	k=6	ndarray	计算特征向量
`ground_state`	-	ndarray	返回基态
`exp`	a	ndarray	矩阵指数
`expectation`	state, normalize=False	float	期望值
`expectation_from_samples`	freq, qubit_map=None	float	样本期望值
`energy_fluctuation`	state	float	能量涨落

SymbolicHamiltonian 类¶

方法	参数	返回值	说明
`__init__`	form, nqubits, backend	SymbolicHamiltonian	初始化
`eigenvalues`	k=6	ndarray	计算特征值
`eigenvectors`	k=6	ndarray	计算特征向量
`ground_state`	-	ndarray	返回基态
`exp`	a	ndarray	矩阵指数
`expectation`	state, normalize=False	float	期望值
`expectation_from_samples`	freq, qubit_map=None	float	样本期望值
`expectation_from_circuit`	circuit, nshots=1000	float	电路期望值
`circuit`	dt, accelerators=None	Circuit	Trotter 电路
`apply_gates`	state, density_matrix=False	ndarray	应用门

预定义模型¶

函数	参数	说明
`X`	nqubits, dense, backend	Pauli-X 哈密顿量
`Y`	nqubits, dense, backend	Pauli-Y 哈密顿量
`Z`	nqubits, dense, backend	Pauli-Z 哈密顿量
`TFIM`	nqubits, h, dense, backend	横向场伊辛模型
`MaxCut`	nqubits, dense, adj_matrix, backend	最大割问题
`Heisenberg`	nqubits, coupling, field, dense, backend	海森堡模型
`XXX`	nqubits, coupling, field, dense, backend	XXX 模型
`XXZ`	nqubits, delta, dense, backend	XXZ 模型
`LABS`	nqubits, dense, backend	低自相关序列

运算符¶

运算符	功能	示例
`+`	加法	`H1 + H2`, `H + c`
`-`	减法	`H1 - H2`, `H - c`, `c - H`
`*`	标量乘法	`2.0 * H`
`@`	矩阵乘法	`H1 @ H2`, `H @ state`

附录：错误处理¶

常见异常¶

异常	原因	解决方法
`ValueError`	矩阵形状不匹配	检查矩阵是否为 2ⁿ×2ⁿ
`ValueError`	量子比特数不匹配	确保 H₀ 和 H₁ 的 nqubits 相同
`TypeError`	后端类型不一致	使用相同的后端初始化
`NotImplementedError`	不支持的操作	如对角哈密顿量的 expectation_from_samples
`RuntimeError`	未设置调度函数	先设置 total_time 和 schedule

调试技巧¶

# 检查哈密顿量类型
print(type(ham))
print(ham.__class__.__name__)

# 检查属性
print(f"量子比特数: {ham.nqubits}")
print(f"矩阵形状: {ham.matrix.shape}")

# 检查项（符号哈密顿量）
if hasattr(ham, 'terms'):
    print(f"项数: {len(ham.terms)}")
    for i, term in enumerate(ham.terms):
        print(f"  项 {i}: {term}")

参考资源¶

Qibo 官方文档: https://qibo.readthedocs.io/
Qibo GitHub: https://github.com/qiboteam/qibo
示例教程: src/qibo/tests/ 目录下的测试文件

文档版本: 1.0 最后更新: 2026-01-09 适用 Qibo 版本: qibo-master

Qibo 哈密顿量 API 完全指南¶

📚 目录¶

概述¶

类继承关系¶

核心概念¶

什么是哈密顿量？¶

两种表示形式的对比¶

Hamiltonian 类 - 矩阵形式¶

类定义¶

初始化¶

__init__(self, nqubits, matrix, backend=None)¶

核心方法¶

1. 特征值计算¶

eigenvalues(k=6)¶

2. 特征向量计算¶

eigenvectors(k=6)¶

3. 基态计算¶

ground_state()¶

4. 矩阵指数¶

exp(a)¶

5. 期望值计算¶

expectation(state, normalize=False)¶

expectation_from_samples(freq, qubit_map=None)¶

6. 能量涨落¶

energy_fluctuation(state)¶

运算符重载¶

属性¶

SymbolicHamiltonian 类 - 符号形式¶

类定义¶

初始化¶

__init__(self, form, nqubits=None, backend=None)¶

核心方法¶

1. 特征值和特征向量¶

eigenvalues(k=6), eigenvectors(k=6), ground_state()¶

2. 矩阵指数¶

exp(a)¶

3. 期望值计算¶

expectation(state, normalize=False)¶

expectation_from_samples(freq, qubit_map=None)¶

expectation_from_circuit(circuit, nshots=1000) ⭐ 新增¶

4. Trotter 分解¶

circuit(dt, accelerators=None)¶

5. 状态演化¶

apply_gates(state, density_matrix=False)¶

属性¶

运算符重载¶

预定义哈密顿量模型¶

导入¶

1. 单体泡利哈密顿量¶

X(nqubits, dense=True, backend=None)¶

Y(nqubits, dense=True, backend=None)¶

Z(nqubits, dense=True, backend=None)¶

2. 横向场伊辛模型 (TFIM)¶

TFIM(nqubits, h=0.0, dense=True, backend=None)¶

3. 最大割问题 (MaxCut)¶

MaxCut(nqubits, dense=True, adj_matrix=None, backend=None)¶

4. 海森堡模型¶

Heisenberg(nqubits, coupling_constants, external_field_strengths, dense=True, backend=None)¶

XXX(nqubits, coupling_constant=1, external_field_strengths=[0.5, 0, 0], dense=True, backend=None)¶

XXZ(nqubits, delta=0.5, dense=True, backend=None)¶

5. 低自相关二元序列 (LABS)¶

LABS(nqubits, dense=True, backend=None)¶

绝热哈密顿量¶

概述¶

创建¶

使用¶

1. 设置调度函数¶

2. 创建绝热演化模型¶

3. 直接使用绝热哈密顿量¶

类型说明¶

哈密顿量项（高级用法）¶

概述¶

SymbolicTerm 类¶

创建¶

主要方法¶

commute(term) -> bool¶

copy()¶

TermGroup 类¶

使用¶

实用示例¶

`init(self, nqubits, matrix, backend=None)`¶

`eigenvalues(k=6)`¶

`eigenvectors(k=6)`¶

`ground_state()`¶

`exp(a)`¶

`expectation(state, normalize=False)`¶

`expectation_from_samples(freq, qubit_map=None)`¶

`energy_fluctuation(state)`¶

`init(self, form, nqubits=None, backend=None)`¶

`eigenvalues(k=6)`, `eigenvectors(k=6)`, `ground_state()`¶

`exp(a)`¶

`expectation(state, normalize=False)`¶

`expectation_from_samples(freq, qubit_map=None)`¶

`expectation_from_circuit(circuit, nshots=1000)` ⭐ 新增¶

`circuit(dt, accelerators=None)`¶

`apply_gates(state, density_matrix=False)`¶

`X(nqubits, dense=True, backend=None)`¶

`Y(nqubits, dense=True, backend=None)`¶

`Z(nqubits, dense=True, backend=None)`¶

`TFIM(nqubits, h=0.0, dense=True, backend=None)`¶

`MaxCut(nqubits, dense=True, adj_matrix=None, backend=None)`¶

`Heisenberg(nqubits, coupling_constants, external_field_strengths, dense=True, backend=None)`¶

`XXX(nqubits, coupling_constant=1, external_field_strengths=[0.5, 0, 0], dense=True, backend=None)`¶

`XXZ(nqubits, delta=0.5, dense=True, backend=None)`¶

`LABS(nqubits, dense=True, backend=None)`¶

`commute(term) -> bool`¶

`copy()`¶

使用 `Hamiltonian`（矩阵形式）当：¶

使用 `SymbolicHamiltonian`（符号形式）当：¶