qutip

QuTiP 5

适用范围

使用 QuTiP 处理有限维量子力学、量子光学、Lindblad 动力学、轨迹、弱耦合 Bloch-Redfield 模型，以及专用的 Floquet、HEOM 和置换不变性方法。它不是硬件执行 SDK。电路和控制功能已移至 QuTiP 系列的独立软件包。

此技能面向 QuTiP 5.3.0，该版本于 2026-05-22 发布。QuTiP 5.3 要求 Python 3.11 或更高版本。其必需发行包包括 NumPy（>=1.23.2）、SciPy（>=1.9.2，不包括 1.16.0 和 1.17.0）以及 packaging。

可复现的 uv 快照

创建专用环境，并固定每个直接依赖发行包的版本：

uv venv --python 3.11
uv pip install "qutip==5.3.0"

绘图所需软件包：

uv pip install "qutip[graphics]==5.3.0"

QuTiP 系列的可选软件包采用独立版本号：

uv pip install "qutip-qip==0.4.2"
uv pip install "qutip-qtrl==0.2.0"
uv pip install "qutip-jax==0.1.1"

• qutip-qip 0.4.2（2026-06-23）是用于电路、量子门和含噪设备仿真的正式稳定版软件包。请从 qutip_qip 导入，而不是 qutip.qip。
• qutip-qtrl 0.2.0（2026-06-23）提供 GRAPE 和 CRAB 量子最优控制。它不是轨迹查看器。请从 qutip_qtrl 导入，而不是 qutip.control；PyPI 仍将其归类为 pre-alpha。
• qutip-jax 0.1.1（2025-05-29）是用于 GPU 和自动微分实验的官方 JAX 数据后端。它明确处于 pre-alpha 阶段。
• qutip-cupy 是 QuTiP 组织的官方仓库，但尚无 PyPI 发行版，其 README 也说明它尚未正式发布。不要在可复现工作流中使用尚未发布的 Git 安装。

如果还必须固定传递依赖的版本，请使用项目锁文件或会生成哈希的 uv pip compile 工作流。

不可妥协的模型约定

求解前，记录以下内容：

1. 单位与约定。 QuTiP 方程通常令 (\hbar=1)。哈密顿量元素的单位为角频率，速率的单位为时间的倒数。使用 (2\pi f) 转换循环频率；切勿混用 Hz 和 rad/s。
2. 子系统顺序。 tensor(A, B, C) 将子系统索引固定为 0, 1, 2。在每个态、算符、塌缩通道和偏迹运算中都保持此顺序。obj.ptrace([0, 2]) 会保留这些子系统，而不是对它们求迹。
3. 态的有效性。 检查量子态矢的范数，或检查密度矩阵的厄米性、迹是否为 1，以及特征值是否高于明确给出的负容差。微小的负值可能来自数值误差；显著的负值会使所声称的量子态失效。
4. 生成元的含义。 速率为 gamma 的 Lindblad 通道应表示为 sqrt(gamma) * A，而不是 gamma * A。明确说明每个速率的含义。例如，sqrt(gamma_phi / 2) * sigmaz() 会产生 exp(-gamma_phi * t) 的相干性衰减。
5. 近似条件。 在使用旋波、Born-Markov、世俗、弱耦合、浴平衡、截断、对称性和初始态因子化假设时，均应予以说明。
6. 数值方法。 说明 Hilbert 空间截断、输出网格、积分方法、容差、轨迹数和随机种子的依据。报告 result.stats。
7. 收敛性。 对每个人为设置的截断参数进行扫描：Fock 空间维数、时间/频率窗口及间距、ODE 容差、轨迹数、Floquet 谐波数、HEOM 深度和浴指数，或适用的 PIQS 表示。

Qobj、维度与张量顺序

优先使用显式导入，并检查形状和结构化维度：

from qutip import basis, qeye, sigmaz, tensor

psi = tensor(basis(2, 0), basis(3, 1))
z_on_first = tensor(sigmaz(), qeye(3))

assert psi.shape == (6, 1)
assert psi.dims == [[2, 3], [1]]
assert z_on_first.dims == [[2, 3], [2, 3]]
rho_first = psi.proj().ptrace(0)  # keep subsystem 0

仅检查矩阵形状是不够的：两个对象可能都是 6×6，但其张量分解方式不同。构建复合系统、超算符或通道模型前，请阅读 references/core_concepts.md。

根据物理特性选择求解器

模型	当前 API	必要依据
封闭、纯态、幺正	sesolve	哈密顿量为厄米算符；无耗散
Lindblad／开放或混合态	mesolve	马尔可夫完全正模型和通道速率
量子跳跃	mcsolve	展开方法、轨迹收敛性、随机种子
微观弱耦合浴	brmesolve	Born-Markov／弱耦合、谱、世俗近似的选择
扩散测量	ssesolve、smesolve	监测或未监测的通道
周期驱动	FloquetBasis、fsesolve、fmmesolve	已验证的周期和 Floquet 收敛性
结构化非马尔可夫浴	qutip.solver.heom	浴展开和层级收敛性
对称自旋系综	qutip.piqs	置换对称性和基底选择

不要仅仅因为存在更专用的求解器就选择它。

确定性开放系统示例

QuTiP 5.3 使用普通选项字典。求解器控制项、e_ops 和 args 只能作为关键字参数传入；旧的可变选项对象已移除。

import numpy as np
from qutip import basis, mesolve, sigmam, sigmaz

omega = 2.0
gamma = 0.15
tlist = np.linspace(0.0, 20.0, 401)
excited = basis(2, 0)

result = mesolve(
    0.5 * omega * sigmaz(),
    excited,
    tlist,
    c_ops=[np.sqrt(gamma) * sigmam()],
    e_ops={"sigma_z": sigmaz(), "excited": excited.proj()},
    options={
        "method": "adams",
        "atol": 1e-10,
        "rtol": 1e-8,
        "store_final_state": True,
        "progress_bar": "",
    },
)

population = np.asarray(result.e_data["excited"])
assert np.max(np.abs(population - np.exp(-gamma * tlist))) < 2e-6
assert isinstance(result.stats, dict)

如果问题具有刚性，可比较 bdf 或 lsoda；更换积分器后，必须重新运行 容差和不变量检查。QuTiP 5.3 还支持在 mesolve 中使用 options={"matrix_form": True}；将其设为默认选项前，请先进行基准测试并验证。

含时系统

优先使用可信的 Python 风格可调用对象或数值系数数组。不要根据用户输入创建 系数源代码字符串。

import numpy as np
from qutip import QobjEvo, sigmax, sigmaz

def envelope(t, amplitude, center, width):
    return amplitude * np.exp(-0.5 * ((t - center) / width) ** 2)

H = QobjEvo(
    [0.5 * sigmaz(), [sigmax(), envelope]],
    args={"amplitude": 0.2, "center": 5.0, "width": 1.0},
)
instantaneous_H = H(5.0)
H.arguments(amplitude=0.1)

旧的 f(t, args) 系数签名在 5.3 中已弃用，计划在 5.5 中移除。请参阅 references/time_evolution.md。

轨迹和随机求解器

import numpy as np
from qutip import basis, mcsolve, sigmam, sigmaz

tlist = np.linspace(0.0, 10.0, 201)
result = mcsolve(
    0.5 * sigmaz(),
    basis(2, 0),
    tlist,
    [np.sqrt(0.2) * sigmam()],
    e_ops=[basis(2, 0).proj()],
    ntraj=400,
    seeds=20260723,
    options={"keep_runs_results": False, "progress_bar": ""},
)

报告 ntraj、result.seeds、不确定性或不同随机种子下的敏感性，以及 是否保留了各次单独运行的结果。仅在有意配对轨迹时，才使用 seeds=previous_result.seeds。ssesolve 和 smesolve 使用布尔型的 heterodyne 参数，而不是旧版整数噪声代码。

稳态、谱和相空间

import numpy as np
from qutip import QFunc, liouvillian, operator_to_vector, qfunc, steadystate

rho_ss = steadystate(H, c_ops, method="direct")
residual = (liouvillian(H, c_ops) * operator_to_vector(rho_ss)).norm()
assert residual < 1e-9

xvec = np.linspace(-5.0, 5.0, 151)
Q_once = qfunc(rho_ss, xvec, xvec)
q_many = QFunc(xvec, xvec)
Q_again = q_many(rho_ss)
assert Q_once.shape == (len(xvec), len(xvec))

对于 wigner、qfunc 和 QFunc，数组元素 [j, k] 分别对应 yvec[j]、xvec[k]。在 QuTiP 5.3 中，QFunc 使用固定坐标初始化，并以一个态作为调用参数；它没有 .eval 方法。此技能不会使用 Python 动态代码执行。请优先使用 plot_wigner、Result.plot_expect，或根据 references/visualization.md 中的说明显式创建 Matplotlib 坐标轴。

直接调用 spectrum 得到的是稳态谱。对有限相关函数进行 FFT 时，必须明确检查尾部衰减、时间步长混叠、频率分辨率、窗口敏感性和变换约定。请参阅 references/analysis.md。

高级功能边界

• 从 qutip.solver.heom 导入 HEOM；旧版 QuTiP 4 的 nonmarkov HEOM 命名空间已过时。
• 使用 FloquetBasis 获取模式和准能量。通过数值计算验证 H(t + T) == H(t)，并遍历不同的基底／截断选择。
• 使用 from qutip import piqs 访问 PIQS。Dicke.pisolve 仅适用于经过 优化的对角态／对角哈密顿量路径；一般的 Dicke 基底动力学应使用 Liouvillian 和 mesolve。
• brmesolve 可能会破坏正性，尤其是在未进行世俗近似时。请检查 随时间变化的密度矩阵本征值。
• QIP 和最优控制属于扩展包范畴。切勿将本地模拟说成是在量子硬件上执行。

关于 HEOM、Floquet、PIQS、随机方法和扩展包的边界，请参阅 references/advanced.md。

安全的本地 CLI

所有捆绑工具仅限本地运行，输出严格的 JSON，拒绝非有限 JSON 和未知键，并且绝不加载 pickle 文件或可执行模型代码。模拟相关导入采用延迟加载，因此即使未安装 QuTiP，所有 --help 命令也都能正常运行。

脚本	用途
scripts/qobj_model_validator.py	验证受限的 Qobj 模型 JSON、维度、状态、速率和角色兼容性
scripts/two_level_simulation.py	运行受限的二能级 Lindblad 或跳跃模拟
scripts/solver_config_planner.py	选择当前求解器并制定选项／检查清单计划
scripts/convergence_sweep.py	对合成模型扫描容差／网格大小或轨迹数量
scripts/result_audit.py	在不反序列化 Python 对象的情况下审计 JSON 输出
scripts/steady_state_spectrum_planner.py	规划受限的稳态和直接／FFT 频谱检查

示例：

python skills/qutip/scripts/two_level_simulation.py --help
python skills/qutip/scripts/two_level_simulation.py \
  --decay-rate 0.2 --t-final 10 --time-points 201 \
  --output two-level.json
python skills/qutip/scripts/result_audit.py two-level.json

完成检查清单

• 记录单位、(\hbar)、张量顺序、初始状态、通道和模型假设。
• 验证厄米性、范数／迹、正定性、维度和生成元单位。
• 固定 QuTiP 和直接扩展的版本；记录平台、Python、NumPy 和 SciPy。
• 检查结果选项和统计信息；不要假定状态已被存储。
• 执行截断、网格、容差／积分器和随机收敛扫描。
• 将可移植的数值／配置摘要保存为 JSON 或文本。不要加载不可信的 QuTiP 对象／结果文件，因为对象序列化可能会执行代码。

参考资料

• references/core_concepts.md — Qobj、维度、张量积、状态、通道和单位约定
• references/time_evolution.md — 当前求解器签名、选项、结果、QobjEvo、轨迹和数值控制
• references/analysis.md — 物理状态审计、稳态、关联、频谱和收敛性
• references/visualization.md — Wigner、Q 函数、QFunc、Bloch、结果和矩阵图
• references/advanced.md — Bloch-Redfield、随机、Floquet、HEOM、PIQS 以及 QuTiP 系列软件包的边界

标注日期的官方来源

已于 2026-07-23 验证：

• QuTiP 5.3.0 PyPI 元数据
• QuTiP 5.3.0 版本发布
• QuTiP 5.3 更新日志
• QuTiP 5.3 API
• QuTiP 第 5 版教程
• qutip-qip PyPI 页面
• qutip-qtrl PyPI 页面
• qutip-jax PyPI 页面
• 官方未发布的 qutip-cupy 仓库