kpleo/pyraimd

Pyramid 是什么？

Pyramid（Python 包装的从头算分子动力学）是一个 Python 框架，它将第一性原理量子力学（如 DFT）与快速的机器学习势（MLIPs）相结合，以运行分子动力学（MD）模拟。它协调何时调用昂贵的参考计算（例如，Quantum ESPRESSO）以及何时使用快速的替代模型（例如，MACE），使用力误差方法来决定何时需要精度。

核心思想

• 参考引擎（例如，QE、PySCF）提供准确的能量和力。
• 替代势（例如，MACE）速度快但近似。
• Pyramid 的力误差方法预测力误差如何远离已知构型增长，并测量其能量影响（有符号的残余功）。这指导何时运行参考计算。

安装

• 需要 Python 3.12+。
• 核心安装仅需要 NumPy 和 ASE（无重依赖）。
• 从源码安装：pip install . 或 pip install -e '.[dev]'。
• 可选后端：pip install '.[pyscf]'（分子参考），pip install '.[mace]'（MACE 替代）。
• Python 导入为 pyraimd2；命令行界面为 pyramid。

主要特性

• 自适应 MD：在运行中决定何时调用参考引擎。
• 多时间步长（MTS）：实验性的固定调度方法，每个外步评估一次参考。
• 验证层：三个级别——配置检查、环境检查和后端探测——在运行前发现问题。
• 检查点/恢复：安全停止（Ctrl-C）和恢复，带有事件日志重放和身份检查。
• 比较工具：pyramid compare 用于离线比较两个完成的运行。
• 插件：通过入口点添加您自己的 ASE 计算器或后端包。
• 暂存管理：可选的统一临时根目录，用于求解器暂存文件。
• 持久密度保留：只读检查密度生成。

典型工作流程

1. 初始化：pyramid init --template harmonic --output my_run（或其他模板）。
2. 验证：pyramid validate run.toml（配置），--check-environment（先决条件），--probe-backends（计算）。
3. 运行：pyramid run run.toml。
4. 检查/恢复/导出：pyramid inspect，pyramid resume，pyramid export。

当前范围

• 任务：单点、弛豫（FIRE/BFGS）、MD（NVE、NVT），支持仅参考、仅替代或自适应模式。
• 动力学：固定晶胞的 NVE 和 NVT（Langevin），带有 FixAtoms。不支持可变晶胞或其他约束。
• 后端：QE、PySCF、MACE、解析谐波，以及通用 ASE 适配器。
• 能量一致性：力必须是报告能量的负梯度；检查跨类型组合。
• 示例：离线演示（谐波、Lennard-Jones、QE+MACE 骨架）和真实材料示例（Si、Al 板）。

文档

• 用户指南：docs/user_guide.md
• 配置参考：docs/configuration.md
• 架构：docs/architecture.md
• API：docs/api.md

备注

• README 强调示例参数仅用于演示，并非精度建议。
• 在线模型更新仅通过 Python API 可用，而非 TOML 配置。
• 项目版本为 0.8.5（截至 README）。