企业官网建设流程全解析

做分子动力学模拟，能量差一个 Hartree、步长差一个数量级，整条轨迹就会全盘报废。Pyramid（包名pyraimd2）是一个 Python 写的从头算分子动力学框架：参考方法负责算能量和力，机器学习势负责推进原子运动，框架再决定何时检查、校验和更新模型。它的核心亮点之一是energetic force-error 方法——把"力算得准不准"直接和"原子怎么动"关联起来。对新手来说，理解它的单位体系和**能量-力一致性（energy-force consistency）**检查，是少走弯路的第一步。

🧭 30 秒认识 Pyramid (pyraimd2)

一句话：把第一性原理引擎（PySCF、Quantum ESPRESSO）、机器学习原子间势（MLIP，如 MACE）和 MD 循环装进同一个可扩展的 Python 框架里。

• Python import 名是pyraimd2，命令行工具是pyramid（别名pyraimd2）
• 核心安装只需要 NumPy 和 ASE，不需要 torch、PySCF 或外部程序
• 新手路径见 docs/user_guide.md，五分钟上手流程在 README.md

一个完全离线、几秒跑完的玩具示例在 examples/harmonic_adaptive/，建议先跑它再碰单位。

📏 Pyramid 单位体系：五个固定单位，写在字段名里

Pyramid 最省心的设计是：单位直接编码在配置字段名里，而且全项目固定不变，不允许你另外指定：

这个约定在 docs/configuration.md 中明确写出："Units are part of the field names and fixed everywhere"，代码层面同样是全局契约（见 src/pyraimd2/config.py）。

好处很直接：你看到timestep_fs = 1.0，它就是 1 飞秒，不用再去查某个引擎的默认单位是秒还是飞秒。这也是 API 层的统一承诺——docs/api.md 开头就声明公开接口使用 Å、eV、eV/Å、fs 和 K。

新手最该记住的几个带单位字段

• timestep_fs：MD 步长（fs），MTS（respa）里它是内层步长
• temperature_K：NVT 浴的目标温度（K）
• friction_per_fs：NVT 必需的浴耦合系数，注意单位是"每飞秒"
• fmax_eV_A：几何优化收敛阈值（eV/Å，默认 0.05）
• force_budget_eV_A：自适应 MD 的力误差接受预算（eV/Å）
• max_wall_hours：唯一的"小时"字段，是墙钟预算而非物理时间

完整字段表在 docs/configuration.md 的 Configuration reference 一节。

🔀 引擎边界上的单位换算：Hartree、Bohr、Rydberg 都去哪了

底层引擎各说各话：PySCF 内部用Hartree/Bohr，Quantum ESPRESSO 用Rydberg。Pyramid 的做法是在引擎边界处一次性换算成 ASE 单位，之后全链路只流通 eV 和 Å：

• PySCF 引擎：位置除以units.Bohr送进去，能量乘以units.Hartree、力乘以units.Hartree / units.Bohr换回来，见 src/pyraimd2/engines/pyscf_engine.py
• QE 引擎：RY_EV = units.Hartree / 2.0，力从 Ry/Bohr 换算到 eV/Å，见 src/pyraimd2/engines/qe_engine.py
• 后端边界统一约定写在 docs/architecture.md 的 "Units and configurations" 一节

给自写后端的启示：实现引擎协议时，"convert units at that boundary and return energies consistent with the forces"——换算发生在你的边界上，返回的能量必须和力自洽（架构文档原话，见 docs/architecture.md）。

✅ 能量-力一致性：如何检查"力真的是能量的负梯度"

力误差预算再小，前提是力来自一个保守势：F = -∇E。如果某个模型的力和能量对不上，能量学检查（锚定能量、端点功）就没有意义。Pyramid 用两种机制兜底：

1. 能力声明（capabilities）。每个后端必须声明force_consistent、forces_conservative等属性。内置的谐振子玩具后端就诚实声明了两项全真（src/pyraimd2/backends/harmonic.py）；跨能量类型（如参考端报free_energy、代理端报energy）的组合，要求双方都声明force_consistent=True且forces_conservative=True，否则拒绝运行。

2. 有限差分一致性检查。在线更新代理模型时，GuardedUpdater会对候选模型做"扰动探针"：沿两个内部方向（相对坐标"呼吸"模 + 可复现伪随机方向）做 ±step 有限差分，比较数值导数与−F·u，取最坏偏差：

• 有限差分步长energy_force_fd_step_A，默认 1e-3 Å
• 绝对容差energy_force_atol_eV，默认 1e-3 eV
• 相对容差energy_force_rtol，默认 0.05
• 超差即以energy_force_inconsistent拒绝候选并回滚父模型

代码见 src/pyraimd2/loop/online.py 与默认参数定义 src/pyraimd2/loop/online.py。

有个精巧的细节值得新手品味：探针刻意不用整体平移方向。因为平移不变势的力总和为零，只查平移方向会漏掉"整体缩放力但能量不变"的作弊模型——文档注释里写得很直白（src/pyraimd2/loop/online.py）。

⚠️ 新手避坑清单

1. 不要猜单位，看字段名。Pyramid 的字段名自带单位，写timestep_fs = 1就是 1 fs；如果你从别的软件抄配置（步长常以 ps 给出），先换算。
2. NVT 必须给friction_per_fs。它是"每飞秒"的耦合系数，漏写会在 validate 阶段直接报错。
3. calibrate-scale的配对数据要带force_unit = "eV/angstrom"，即力的单位必须是 eV/Å（examples/calibrate_scale/，流程见 docs/user_guide.md）。
4. 比较轨迹时时间必须精确匹配：pyramid compare按物理时间逐点对齐，容差是 1e-9 fs 级绝对容差，且只读已完成轨迹（docs/api.md）。
5. 未知字段是错误，不是静默忽略。配置里写错字段名（比如timestep_fs2）会在加载时立刻报出点号字段名和修复建议，这是 src/pyraimd2/config.py 的设计原则。

📖 继续深入

• 五分钟离线跑通：examples/harmonic_adaptive/
• 配置字段与 CLI 语义：docs/configuration.md
• 架构与单位/边界约定：docs/architecture.md
• 公开 API 与单位声明：docs/api.md
• 能量学方法（力误差 → 原子运动）：docs/energetic_force_error.md

掌握"五个固定单位 + 字段名即单位 + 力必须是能量负梯度"这三件事，你在 Pyramid 里就不会再被单位坑到了。🚀