kpleo/pyraimd

Pyramid とは？

Pyramid（Python ラップ ab initio 分子動力学）は、第一原理量子力学（DFT など）と高速な機械学習ポテンシャル（MLIP）を組み合わせて分子動力学（MD）シミュレーションを実行する Python フレームワークです。高価な参照計算（例：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、CLI は pyramid です。

主な機能

• 適応型 MD：参照エンジンをいつ呼び出すかをオンザフライで決定します。
• 多重時間刻み（MTS）：実験的な固定スケジュール方式で、外側のステップごとに参照を 1 回評価します。
• 検証レイヤー：3 つのレベル（設定チェック、環境チェック、バックエンドプローブ）で、実行前に問題を検出します。
• チェックポイント/再開：安全な停止（Ctrl-C）と再開、イベントログの再生と ID チェック付き。
• 比較ツール：pyramid compare で 2 つの完了した実行をオフライン比較します。
• プラグイン：エントリポイントを介して独自の ASE 計算機やバックエンドパッケージを追加できます。
• スクラッチ管理：ソルバーのスクラッチファイル用のオプションの統一 tmp ルート。
• 永続的な密度保持：密度生成の読み取り専用検査。

典型的なワークフロー

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 時点）。