md-analysis-planner

MD 解析プランナー

目的

後処理コードを書く前に、適切な MD 軌跡解析とその前提条件を選択します。

要件

• Python 3.10+
• 外部依存関係なし
• Linux、macOS、Windows で動作

収集する入力

入力	説明	例
システム	材料または分子系	oxide glass、liquid water
目標	解析の目標	rdf,diffusion,coordination
軌跡形式	Dump、DCD、XYZ、H5MD など	LAMMPS dump
速度	速度が保存されているかどうか	true
応力	応力／ビリアルが保存されているかどうか	true
アンラップが必要	原子が PBC をまたぐかどうか	true
時間刻み	保存フレームあたりの fs	10

判断の指針

• 局所構造の解析には RDF と配位数 を使用します。
• 拡散の解析には MSD を使用します。ただし、軌跡をアンラップし、拡散領域にあることを確認してください。
• 速度または信頼できる有限差分速度がある場合に限り、VACF／VDOS を使用します。
• 応力／ビリアルと変形履歴がある場合に限り、応力–ひずみ解析 を使用します。
• 輸送特性または熱力学的特性をフィッティングする前に、必ず平衡化を確認してください。

スクリプトの出力

scripts/md_analysis_planner.py は、以下のフィールドを出力します（results 内の JSON）。

フィールド	説明
analysis_plan	目標ごとに 1 件。goal、method、status を含みます
required_data	すべての目標で必要なデータをソートし、重複を除いたもの
equilibration_checks	フィッティング前に行う標準的な平衡化チェックリスト
pbc_handling	unwrap_needed、minimum_action、format_note
warnings	安全上重要な注意事項とブロッカー

ステータス値

status は、重大度の高い順に blocked > needs time axis > needs review > ready のいずれかです。重大度の高いステータスが、重大度の低いステータスに引き下げられることはありません。たとえば、速度が保存されていない VACF／VDOS の目標は、時間刻みも不足している場合でも blocked と報告されます（どちらの警告も出力されます）。

デフォルト（非 JSON）出力

--json を指定しない場合、スクリプトはプランの行、Required data: リスト、1 行の PBC: メモ、および Warnings: セクションを出力します（警告は stderr にも出力されます）。これにより、stdout がパイプに接続されている場合でも、安全上重要な注意事項を確認できます。

ワークフロー

python3 skills/simulation-workflow/md-analysis-planner/scripts/md_analysis_planner.py \
  --system "oxide glass" \
  --goals rdf,coordination,bond-angle \
  --trajectory-format dump \
  --unwrap-needed \
  --timestep-fs 10 \
  --json

エラー処理

速度、応力、または時間刻みの情報が不足している場合、該当する解析の評価を下げ、警告を報告します。無効な入力（システムが空、目標がない、時間刻みが正でないか有限でない、または以下のサイズ上限を超える入力）の場合、スクリプトはコード 2 で終了し、stderr にメッセージを出力します。

制限事項

このスキルは解析と前提条件を計画しますが、大きな軌跡を直接解析することはありません。

検証チェックリスト

以下の該当項目をそれぞれプランナー自身の出力に照らして記録するまで、トラジェクトリから得られた結果を信用しないでください。

• scripts/md_analysis_planner.py を実行し、analysis_plan の項目に blocked または needs time axis がないことを確認してください。needs review の目標と、カスタム解析をどのように解決したかを記録してください。
• 対応する解析を実行する前に、プランナーの required_data リストにあるすべての項目がトラジェクトリに実際に含まれていることを確認してください（例：VACF/VDOS には velocities、応力-ひずみ解析には stress or virial と strain history）。
• 拡散/MSD について：拡散係数 D = lim MSD/(2dt) を示す前に、MSD 対時間の両対数プロットの傾きを記録し、フィッティング区間で傾きが約 1（拡散領域）であることを確認してください。その際、弾道的／サブ拡散的な過渡状態は除外してください。
• 拡散/MSD について：Yeh-Hummer の 1/L 有限サイズ補正を適用し、使用したボックス長 L とせん断粘度 eta を記録してください（D_0 = D_PBC + k_BTxi/(6pieta*L)、立方体ボックスでは xi~=2.837）。
• pbc_handling.unwrap_needed が true の場合の変位ベース解析では、変位を計算する前に cell + image flags を使って位置のアンラップが行われたことを確認してください（ラップされた生の座標は使用しないでください）。
• プランナーの equilibration_checks を実施してください。起動時の過渡状態を破棄し、温度／圧力のプラトーを確認し、輸送特性／熱力学特性のフィッティング前に物性推定値を前半と後半で比較してください。
• 報告するすべての輸送特性／熱力学特性について、単一ウィンドウの点推定値ではなく、ブロック平均化（または独立したトラジェクトリ）による不確かさを報告してください。

よくある落とし穴と誤った正当化

ありがちな近道	それが誤りである理由／対処方法
「MSD 対時間のグラフが直線に見えるので、拡散的です。直線をフィットすればよいだけです。」	直線に見える MSD にも、弾道的／サブ拡散的な過渡状態が含まれている場合があります。まずフィッティング区間で両対数プロットの傾きが約 1 であることを確認し、その後 D = lim MSD/(2dt) をフィットしてください。
「シミュレーションから得られた D が拡散係数です。」	PBC の自己拡散係数は系のサイズに依存します。実際のボックス長 L と粘度 eta を使って Yeh-Hummer の 1/L 補正を適用し、D_PBC ではなく D_0 を報告してください。
「座標がダンプにあるので、MSD は問題ありません。」	ラップされた座標では原子がボックスをまたいで飛び、変位が破損します。unwrap_needed が true の場合は、変位解析を行う前に cell + image flags を使ってアンラップしてください。
「速度は保存されていませんが、位置から VACF/VDOS を求められます。」	プランナーが VACF/VDOS を blocked とするのは、速度がない場合に理由があります。有限差分による速度推定を行う場合は、フレーム間隔とエイリアシングについて明示的に正当化する必要があります。そうでなければ結果の信頼性はありません。
「実行が完了したので、トラジェクトリ全体で輸送特性をフィットできます。」	実行の完了は平衡化を意味しません。フィッティングの前に、起動時の過渡状態を破棄し、温度／圧力のプラトーを確認してください（equilibration_checks）。
「1 つのウィンドウできれいな値が得られたので、誤差範囲は不要です。」	単一のウィンドウでは、相関に起因する分散が見えません。ブロック平均化または独立したトラジェクトリを使い、すべての輸送特性／熱力学特性の値に不確かさを付けてください。

セキュリティ

入力検証

入力はスカラー値の CLI 引数とブール値のみです。plan_md_analysis は使用前にすべてのフィールドを検証して範囲を制限します。違反があれば ValueError を発生させ、main がこれを捕捉して stderr にメッセージを出力し、終了コード 2 で終了します。

• system は空であってはなりません（前後の空白を除去した後）。また、256 文字以下である必要があります。
• 許可される目標は最大 64 個です。各目標は 256 文字以下である必要があります。
• trajectory_format は 256 文字以下である必要があります。
• timestep_fs が指定されている場合は、正の有限数である必要があります（math.isfinite かつ > 0）。

目標は許可リストで制限されていません。認識されない目標は拒否されず、ステータス needs review と「unknown goal」の警告とともに報告されます。--has-velocities、--has-stress、--unwrap-needed フラグは通常のブール値であり、検証は不要です。

ファイルアクセス

このスクリプトはファイルの読み書きを行いません。すべての入出力は stdin/args -> stdout（プレーンテキストまたは JSON）で、警告は追加で stderr にも出力されます。パス引数は受け取らず、軌跡ファイルや出力ファイルも開かないため、ファイルシステムのサンドボックス化に関する懸念はありません。読み込むファイルがないため、ファイルごとのサイズ制限はありません。入力サイズは代わりに、上記のフィールドおよび目標の上限によって制限されます。

ツールの制限

Frontmatter の allowed-tools は Read, Bash, Write, Grep, Glob です。

• Bash は、同梱されている scripts/md_analysis_planner.py の実行にのみ使用されます。
• Read、Write、Grep、Glob は、分析計画の作成時に、このスキル自身のファイル（スクリプト、リファレンス、SKILL.md）の確認、編集、検索にのみ使用されます。軌跡データには使用されません。

安全対策

• eval、exec、os.system、動的インポートは使用しません。
• スクリプトはサブプロセスを起動せず、外部の分析プログラムも実行しません。引数の解析には argparse のみを使用し、プランはプロセス内で計算します。
• 出力は json.dumps で生成される構造化 JSON（または決定論的なプレーンテキスト）であり、シェル補間は行いません。
• サービス拒否攻撃を防ぐ上限（MAX_GOALS = 64、MAX_SYSTEM_LEN = 256、MAX_FIELD_LEN = 256）によって、プランニングヘルパーが異常な入力を処理しないようにしています。

リファレンス

• 分析の前提条件と失敗モードについては、references/md_analysis_checks.md を参照してください。

バージョン履歴

• 1.2.0: 3 つすべての eval ケースに決定論的な script_checks を追加し、プランナーの出力（ステータス、ソート済みの required_data、PBC に関する注記、拡散領域／Yeh-Hummer／blocked を降格しないことに関する特定の警告）を厳密に固定して、スキルと記憶に基づくベースラインとを eval で区別できるようにしました。
• 1.1.0: ステータスの降格を修正（blocked が needs time axis に降格されないよう変更）し、非 JSON モードでも警告、必要なデータ、PBC を表示するようにしました。また、拡散領域と Yeh-Hummer の有限サイズに関するガイダンスを追加し、文書化された入力上限を適用しました。
• 1.0.0: MD 分析プランニングスキルの初版。