快速开始¶

使用 Python 3.11 或更新版本及 uv 从源码安装 q2m3。运行较大的 SQD 或 Catalyst 计算前，先运行 H2 示例。

安装¶

git clone https://github.com/yjmaxpayne/q2m3.git
cd q2m3
uv sync --frozen

uv run 使用项目的 .venv，无需手动激活。核心依赖包括 PySCF、PennyLane、NumPy、SciPy、Matplotlib 和 Rich。

按工作流添加 extras：

工作流	命令
开发	`uv sync --frozen --extra dev`
SQD	`uv sync --frozen --extra sqd`
Catalyst 溶剂化	`uv sync --frozen --extra catalyst --extra solvation`
文档	`uv sync --frozen --extra docs --extra sqd --extra catalyst --extra solvation --extra viz`

gpu extra 要求兼容的 NVIDIA 驱动和 CUDA 运行时。CPU 示例无需该 extra。

uv run python examples/qpe/h2_qpe_validation.py
uv run python examples/resources/h2_resource_estimation.py

第一个脚本对比真空与 MM 嵌入体系的 HF 和 QPE 能量。检查每一行 [OK] 和 [FAIL]。其退出状态不反映检查失败。第二个脚本估算量子硬件资源。结果解释见 H2 QPE 验证和 H2 资源估计。

内部能量单位为 Hartree。报告 kcal/mol 前须显式转换：

>>> round(HARTREE_TO_KCAL_MOL * KCAL_TO_HARTREE, 12)
1.0

工作流	要求与范围
H2 MC 溶剂化	需要 catalyst 和 solvation extras。建议至少 8 GB 内存。
SQD：H₂、甘氨酸与嵌入	需要 SQD extra、Linux x86_64 和串行原生线程。
片段相互作用能	`classical_only` 只需核心安装。`full` 需要 SQD extra 和 Linux x86_64。
H3O+ MC 诊断	需要 catalyst 和 solvation extras。建议至少 16 GB 内存。
8 位 QPE 与动态 Trotter 诊断	建议至少 30 GB 内存。使用脚本提供的内存限制。

建议内存不是实测上限。诊断脚本路径见教程。Catalyst 编译取决于估算线数、Trotter 深度和哈密顿量项数。

现象	操作
缺少 `catalyst` 或 `jax`	安装 `catalyst` 和 `solvation` extras。
缺少 `ffsim` 或 `qiskit_addon_sqd`	安装 `sqd` extra。
SQD 拒绝平台、线程或内存请求	检查基于采样的量子对角化（SQD）。`allow_large` 无法绕过适用域或硬上限。
首次 MC 运行缓慢	等待编译完成。后续运行可复用兼容的 IR。
H3O+ 运行超出内存	先运行 H2。降低 Trotter 深度或增加可用内存。
GPU 设备不可用	检查 `q2m3.core.device_utils`。CPU 可选 `lightning.qubit` 或 `default.qubit`。
QPE–HF 差值较大	检查估算线数、`base_time`、能量偏移和 Trotter 深度。

从化学角度解释能量差前，先阅读核心概念。