【创新应用】新增 Lindblad 动力学的随机 Magnus 变分模拟算法#26
Open
clzoc wants to merge 7 commits into
Open
Conversation
实现 Huang et al., PRX Quantum 6, 040312 (2025) 提出的基于随机 Magnus 展开 与 McLachlan 变分原理的开量子系统变分量子模拟框架。算法核心完全基于 pyqpanda3（变分量子线路构造 + 态矢量模拟），数值部分仅依赖 numpy/scipy， 不引入其它量子计算框架。 新增模块 pyqpanda_alg/LindbladMagnus： - magnus.py：随机 Magnus 积分器 Scheme I-IV 与 Euler-Maruyama - ansatz.py：VariationalAnsatz 与 HardwareEfficientAnsatz（基于 pyqpanda3 的 RX/RY/RZ/RZZ/RXX/RYY 参数化门，theta=0 时为恒等） - variational.py：面向非厄米 H_eff 的 McLachlan 变分原理（实部/虚部方程 联立最小二乘求解）+ Euler / RK4 时间积分 - lindblad.py：LindbladMagnusSolver 顶层求解器，支持轨迹并行与 ensemble 平均，以及函数式 solve 接口 - models.py：FMO 光合复合体、阻尼 TFIM、自由基对（RPM）模型 + 基于 Liouvillian 的精确求解器 mesolve（替代 qutip.mesolve） 应用案例与测试： - example/QAlgBase/testeg_Lindblad_TFIM.py、testeg_Lindblad_FMO.py - test/11-LindbladMagnus/demo notebook - test/LindbladMagnus/ 20 个 pytest 用例（全部通过） 参考实现 Furthermore-F/LindbladMagnus（qiskit + qutip）的算法思路，但具体 电路与数值实现完全基于 pyqpanda3 生态。
从开发者与用户两个角度系统性改进，新增 686 行 / 删除 125 行。 ## 用户体验改进 1. **LindbladResult 结果容器**（lindblad.py） - solve() 不再只返回 (mean, std) tuple，而是返回结构化的 dataclass - 包含 expect / std / norms / traj_num / seeds / solver_info 等字段 - 方便后续分析与可视化 2. **进度反馈** - 支持 verbose='tqdm' 显示进度条（可选依赖 tqdm） - verbose=True 用 logging 模块记录轨迹进度 - 自动检测 tqdm 是否安装并优雅降级 3. **参数调优提示**（README.md） - 新增专题 README 给出快速上手、模块结构、参数调优建议 - 包含 dt / layers / traj_num / eps 的推荐取值范围 4. **示例脚本与 notebook** - 全部适配新的 Result API - 添加 logging 进度提示 ## 代码质量改进 1. **Ansatz pickle 支持**（ansatz.py） - 实现 __getstate__/__setstate__，支持多进程并行 - 将 _gates 从存储 pyqpanda3 门工厂（PyCapsule）改为存储名称字符串 - 新增 _GATE_REGISTRY 注册表统一管理支持的门 - 这是并行执行的关键修复——之前 _worker 访问私有属性 _qvm 的方式不可靠 2. **公开 to_qprog() 方法** - 用户可获取 concrete QProg 用于绘制、转译、导出 3. **改进初态准备** - _prepare_state_prog 对非计算基态初态抛出明确 ValueError - 之前会静默返回空程序导致用户困惑 4. **输入验证** - H 与 ansatz 比特数一致性检查 - c_ops / e_ops 形状匹配检查 - tlist 严格递增检查 - init_params 长度检查 - 初态一致性自动警告（ansatz(init_params) 与 psi0 的 overlap） 5. **暴露 eps 正则化参数** - 用户可在出现 LinAlgError 时调大 eps 解决数值病态 6. **__repr__ 方法** - ansatz 和 solver 都有清晰的 repr，便于调试 7. **并行执行修复** - 不再访问私有属性 _qvm - 不再 deepcopy 整个 solver（浪费内存） - 失败时优雅回退到串行执行 8. **清理代码** - ansatz.py 移除 15+ 个未使用的 import - magnus.py 优化 aij 计算避免构造 1000×1000 对角矩阵 - lindblad.py 移除未使用的变量和 import ## 新增测试（test/LindbladMagnus/Test_api.py，13 个用例） - pickle 往返一致性 - __repr__ 信息正确性 - LindbladResult 属性 - 函数式 solve API - tlist / H 维度 / c_ops 形状 / init_params 长度验证 - 并行与串行结果一致性 - to_qprog 返回类型 全部 33 个测试通过，mypy 类型检查无新增错误。
通过 3 轮系统性审查发现并修复以下问题： ## 正确性修复 1. **nonlinear_corr predictor-corrector 实现 bug**（lindblad.py） - 之前的实现完全用预测态 psi_corr 替换原始态 psi_pred 构建 H_eff - 参考实现是用 0.5*(<L>_psi + <L>_psi_p) 平均 drift expectations - 修复为调用 effective_hamiltonian(nonlinear_corr=True, psi=psi_pred, psi_p=psi_corr) - 启用 nonlinear_corr=True 现在产生与默认不同的（正确的）结果 2. **rpm_model 返回 6x6 非 2^n 维矩阵**（models.py） - RPM 物理模型有 6 个基矢，但 solver 要求 2^n_qubits 维 - 之前返回的 H 无法直接用于 LindbladMagnusSolver - 修复为像 fmo_model 一样 padding 到 8x8（3 qubits） - 同时将参数归一化（omega=1.0 而非 2π×10^7）以便默认 solver 设置可用 - 更新 docstring 明确说明归一化版本 ## UX 与代码质量改进 3. **并行进度条不平滑**（lindblad.py _run_parallel） - 之前按 futures 提交顺序获取结果，慢轨迹会阻塞进度条 - 改用 concurrent.futures.as_completed 让进度条按完成顺序更新 - 同时修复了 mypy 类型错误（变量类型不一致） 4. **_validate_initial_state 静默吞所有异常**（lindblad.py） - 之前 except Exception: pass 导致验证失败时用户完全无感知 - 改为 emit debug 级别日志便于诊断 5. **LindbladResult.norms docstring 不准确**（lindblad.py） - 之前声称 nonlinear QSD 的 norms 'stays close to 1.0' - 实际上 nonlinear QSD 的 norms 也会因 H_eff 非厄米性而偏离 1 - 修正为准确的诊断语义说明 6. **nonlinear_corr + linear QSD 无意义组合**（lindblad.py） - nonlinear_corr 只对 nonlinear QSD 有意义 - 添加构造时 warning 提示用户 ## 新增回归测试（test/LindbladMagnus/Test_regression.py，10 个用例） - test_nonlinear_corr_averages_drift_expectations: 验证 corrector 平均行为 - test_solver_nonlinear_corr_runs_and_differs: corrector 与 plain 结果不同 - test_nonlinear_corr_with_linear_qsd_is_noop: 无效组合的 warning - test_rpm_model_is_power_of_two: RPM 维度 = 2^n - test_rpm_model_works_with_solver: RPM 端到端 - test_rpm_model_mesolve_consistency: RPM mesolve 自洽 - test_solver_handles_single_step: 两点时间网格 - test_mesolve_handles_no_c_ops: 无耗散退化为幺正 - test_solver_euler_integrator_runs: Euler 积分器 - test_fmo_model_padded_to_8: FMO padding 与零子空间 全部 43 个测试通过，mypy 类型检查无错误。
将 demo01-LindbladMagnus-TFIM_FMO.ipynb 从 14 个 cell 扩展到 46 个 cell （24 markdown + 22 code），覆盖完整的算法原理、工程使用与参数调优。 ## 教程结构（10 章） 1. **引言**：论文信息、学习目标、模块在 pyqpanda-algorithm 中的位置 2. **理论框架**：Lindblad 主方程 → QSD unravelling → 随机 Magnus 展开 → McLachlan 变分原理 → 整体算法流程（含 LaTeX 公式与 Scheme I-IV 对比表） 3. **环境准备**：依赖说明与模块结构速查表 4. **精确参考 mesolve**：单比特振幅阻尼验证 + Liouvillian trace-preserving 自检 5. **案例一 TFIM**：物理背景 → ansatz 构造与恒等性验证 → 端到端模拟 → 双面板可视化（布居演化 + 误差曲线） 6. **案例二 FMO**：7 个 Lindblad 算符的物理来源 → 短时传输动力学 7. **算法内部探析**： - H_eff 的 Hermitian/anti-Hermitian 分解（热图可视化） - Magnus 阶数 0/1/2 精度对比 - Linear vs Nonlinear QSD 方差对比 - 单轨迹参数演化 θ(t) 与 norm 诊断 8. **高级用法**：LindbladResult 元数据、自定义 ansatz、并行执行（含 spawn 限制提示）、predictor-corrector 9. **参数调优指南**：dt 选择公式、ansatz 层数扫描、轨迹数收敛扫描、 eps 正则化扫描（全部带数值输出） 10. **RPM 拓展**：归一化单位的自由基对模型端到端 demo 11. **总结**：本教程覆盖清单 + 进阶建议表 + BibTeX 引用 ## 质量保证 - 所有 22 个 code cell 端到端执行通过（0 错误） - nbformat 验证通过（无 warning，cell id 齐全） - 所有数值结果合理：TFIM err 0.07、layers=3 降至 0.04、parallel == serial - 使用 LaTeX 公式、对比表格、热图、进度条等专业呈现
通过系统性全面检查发现并修复 5 个问题。
## 正确性修复
1. **magnus_order=0 (Euler-Maruyama) 漂移公式与参考不一致**（magnus.py）
- 之前 order=0 和 order>=1 使用相同的 _drift_operator，即 Magnus 漂移
-0.5(L†+L)L + 2Re(⟨L⟩)L
- 参考实现中 order=0 用的是标准 linear-QSD 漂移
-0.5L†L + conj(⟨L⟩)L
- 两者对 nilpotent lowering 算符（L²=0，如 TFIM 的 σ_-）恰好相同，
但对 Hermitian dephasing 算符（如 FMO 的 √a|k⟩⟨k|）差因子 2
- 新增 _euler_maruyama_drift 函数，order=0 使用正确的 Euler-Maruyama 漂移
- 经验证：FMO 系统下 order=0 与 order=1 的 H_eff 现在有 1.5e-3 的差异
（正好对应 a=3e-3 的 dephasing 算符下两公式的差）
2. **_channel_expectations 性能优化**（magnus.py）
- 从 trace(|ψ⟩⟨ψ| @ L)（O(d³)）改为 vdot(L @ ψ, ψ)（O(d²)）
- 对 d=8 的 FMO 提速约 8 倍
## 文档修复
3. **sample_wiener_integrals docstring 键名不匹配**（magnus.py）
- docstring 列了 'mus' 但实际未返回（mus 只是局部变量）
- 实际返回的 'etas' 和 'alpha_p' 未在 docstring 中列出
- 修正为完整的 7 个键说明
## 代码质量
4. **_PARAM_GATE_NAMES 死代码**（ansatz.py）
- 定义了但从未使用的变量，且定义逻辑混乱（嵌套集合推导式无意义）
- 直接删除
5. **odeint 未使用的 import**（models.py）
- 从 scipy.integrate 导入了 odeint 但只用了 solve_ivp
- 删除 odeint
## 新增回归测试（test/LindbladMagnus/Test_final_review.py，7 个用例）
- test_euler_maruyama_uses_standard_linear_drift: FMO 下 order=0 ≠ order=1
- test_euler_maruyama_coincides_with_magnus_for_lowering_ops: TFIM 下两者相同
- test_euler_maruyama_drift_matches_reference_formula: 手工验证漂移公式
- test_sample_wiener_integrals_returns_documented_keys: 返回键名完整
- test_channel_expectations_matches_trace_formula: vdot 优化后正确性
- test_no_dead_code_param_gate_names: 死代码已移除
- test_no_unused_odeint_import: 未使用 import 已移除
全部 50 个测试通过，mypy 类型检查无错误。
## 正确性修复 1. **__init__.py docstring 示例过时**（第 34 行） - solve() 已从返回 (mean, std) tuple 改为返回 LindbladResult - 旧示例 'expect, std = solver.solve(...)' 会 TypeError - 修正为 'result = solver.solve(...)' 并添加 shape 断言 2. **VariationalAnsatz docstring 示例缺少 import**（ansatz.py 第 91 行） - 示例用了 H/RY/RZ/CNOT 但未 import，用户运行会 NameError - 添加 'from pyqpanda3.core import H, RY, RZ, CNOT' ## 术语统一（专业性） 3. **wave-function（连字符）→ wavefunction（一个词）** — 17 处 - 4 个文件混用了 'wave-function'（连字符）和 'statevector'（一个词） - 统一为现代量子计算社区惯例的单词形式 - 涉及 ansatz.py(7处)、lindblad.py(5处)、variational.py(5处)、magnus.py(4处) 4. **state-vector（连字符）→ statevector（一个词）** — 4 处 - 与 pyqpanda3 的 get_state_vector API 命名风格一致 5. **'Lindblad operators' → 'collapse operators'** — models.py 第 165 行 - 与模块其他 8 处 'collapse operators' 保持统一 ## 验证 - 所有 4 个 docstring 示例手动执行通过（__init__/Solver/Ansatz/HEAnsatz） - 全部 50 个 pytest 测试通过 - mypy 类型检查无错误
通过两轮系统性严格复审（专业、清晰、美观），共发现并修复 1 个正确性 缺陷 + 若干文档/集成/健壮性问题。新增关键回归测试以封堵历史盲区。 ## 正确性修复 1. **_channel_expectations 返回 conj(<ψ|L|ψ>) 而非 <ψ|L|ψ>**（magnus.py） - 060449b 把实现从 trace(|ψ><ψ| @ L) 改为 vdot(L @ ψ, ψ)，内联注释声称 两者等价——实际 vdot(L@ψ, ψ) = <ψ|L†|ψ> = conj(<ψ|L|ψ>)，注释失真 - 改为 vdot(ψ, L @ ψ) 得到真正的 <ψ|L|ψ>，并加注释说明参数顺序的陷阱 - 影响：Magnus Scheme I–IV（默认，只用 Re(⟨L⟩)）不受影响；但 Euler-Maruyama (order=0) 反馈项 conj(⟨L⟩)·L 之前因双层共轭变成 ⟨L⟩·L，在 Im(⟨L⟩)≠0 时符号错误——现已随主修复一并正确 ## 新增回归测试（Test_final_review.py） 2. **修复两个“自验证错误量”的掩膜测试** - test_channel_expectations_matches_trace_formula：密度矩阵由错误的 outer(ψ.conj(), ψ)（即 ρᵀ）改回正确的 outer(ψ, ψ.conj()) - test_euler_maruyama_drift_matches_reference_formula：改用复数 ⟨L⟩ 态 (|0⟩+i|1⟩)/√2 并加 imag≠0 守卫，使其真正能 catch 共轭 bug 3. **补 Hermitian 跳跃算符的端到端精度盲区**（本轮最重要） - 此前唯一端到端精度测试用 TFIM 幂零 lowering 算符（L²=0），而该情形下 Magnus 漂移 -½(L†+L)L 与标准 -½L†L 恰好相等，最易暴露漂移错误的 Hermitian 算符（FMO dephasing）完全无回归保护 - 新增 _exact_trajectory_ensemble：用精确矩阵指数传播裸波函数（绕过 ansatz） 再系综平均，对纯 dephasing 与 lowering 两类算符验证 unraveling 复现 mesolve - 经独立实验确证 Magnus 漂移公式正确（Hermitian 误差 0.012，仅 MC 噪声） ## 文档修复 4. **predictor-corrector 注释纠错**（lindblad.py）："Euler half-step" → "full forward-Euler step"（代码用的是整步 dt） 5. **Magnus 漂移溯源注释**（magnus.py _drift_operator）：加 note 说明 -½(L†+L)L 是论文 Scheme I–IV 的特定漂移（-½L² 项由 L dξ 扩散项补偿）， 区别于 Scheme 0 的标准 -½L†L，避免熟悉经典 QSD 的读者困惑 6. **models.py**：lowering 算符注释 |1><0| → |0><1|；FMO docstring “5-site/3-site”矛盾统一为“5-state（3 激子位点 + ground + sink）” 7. **Notebook FMO 口径诚实化**：cell[18] 改为明确警告默认配置典型误差 ~0.7 （即便 layers=3/traj=40/dt=0.5 仍 ~0.28），本节仅演示工作流，并给出精度建议 8. **模块 README**：应用案例路径改为相对仓库根，补上单元测试位置 ## 工程集成与健壮性 9. **pytest.ini**：testpaths 加入 LindbladMagnus（新测试原先不被默认 pytest 收集），并修既有 QRAM→QARM 笔误 10. **dt>0 校验**：effective_hamiltonian / sample_wiener_integrals（原负 dt 静默产 NaN） 11. **add_gate qubit 索引范围校验**（ansatz.py，原越界延迟到 pyqpanda3 抛不透明错误） 12. **mesolve 检查 solve_ivp.success**（models.py，失败时抛带 message 的 RuntimeError） ## 美观/风格 13. **清除全部 91+51 处 docstring 的 `` \n `` napoleon hack**，6 个模块文件改标准写法 14. **magnus.py**：np.abs(comm_ij).sum() != 0 → np.any(comm_ij) 15. **requirements.txt**：numpy>=1.17 → >=1.21 16. **Notebook 执行输出**：定位到 import pyqpanda3 会把 matplotlib 后端强制设为 Agg（覆盖 %matplotlib inline），把 magic 移到 import 之后并重新执行—— 现 22/22 cell 已带输出，6 张图全部嵌入 ## 验证 - pytest test/LindbladMagnus/：52 passed（50 + 2 新增） - mypy：Success, no issues - notebook：nbformat 校验通过，22 cell 全执行，6 图，0 错误
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概述
实现论文 Towards Robust Variational Quantum Simulation of Lindblad Dynamics via Stochastic Magnus Expansion（Huang et al., PRX Quantum 6, 040312 (2025), arXiv:2503.22099）提出的开量子系统变分量子模拟算法，并以 Fenna-Matthews-Olson (FMO) 光合复合体 作为主要应用案例。
算法核心 100% 基于 pyqpanda3（变分量子线路构造 + 态矢量模拟），数值部分仅依赖
numpy/scipy，不引入 qiskit / qutip 等其它量子计算框架。参考实现Furthermore-F/LindbladMagnus（基于 qiskit + qutip）的算法思路，但电路与数值实现完全基于 pyqpanda3 生态。新增模块
pyqpanda_alg/LindbladMagnusmagnus.pyH_effansatz.pyVariationalAnsatz与HardwareEfficientAnsatz，基于 pyqpanda3 的RX/RY/RZ与两比特RZZ/RXX/RYY参数化门；theta=0时整体为恒等variational.pyH_eff的 McLachlan 变分原理（实部 / 虚部方程联立最小二乘求解）+ Euler / RK4 时间积分lindblad.pyLindbladMagnusSolver顶层求解器，支持轨迹并行与 ensemble 平均；并导出函数式solve接口models.pymesolve（替代 qutip.mesolve）应用案例
example/QAlgBase/testeg_Lindblad_TFIM.py— TFIM 阻尼模型的端到端演示（误差 < 0.07，30 轨迹）example/QAlgBase/testeg_Lindblad_FMO.py— FMO 光合复合体能量传输模拟，支持命令行参数test/11-LindbladMagnus/demo01-LindbladMagnus-TFIM_FMO.ipynb— 完整 demo notebook测试
test/LindbladMagnus/下 20 个 pytest 用例覆盖：mesolve与解析解 / 闭系统幺正演化 / 振幅阻尼的对比LindbladMagnusSolver端到端短时运行（轨迹形状、初态精度、误差界）PYTHONPATH=pyqpanda-algorithm python3 -m pytest test/LindbladMagnus/ -v # 20 passed in 3.66s实现要点
H_eff，将复方程A·dθ/dt = -iB拆为实部 / 虚部两个实方程Re(A)·dθ/dt = Im(B)与Im(A)·dθ/dt = -Re(B)，联立最小二乘求解。RZZ/RXX/RYY作为参数化两比特门，使 ansatz 在theta=0时为恒等，从而保证初态条件。mesolve：基于 Liouvillian 超算符向量化 +scipy.integrate.solve_ivp，完全替代 qutip.mesolve。验证
TFIM with amplitude damping（30 trajectories, dt=0.05, 2-layer HE ansatz）：
兼容性
pyqpanda3>=0.3.0,numpy,scipy,matplotlib--ignore-missing-imports）