simulation-validator

シミュレーション検証ツール

目標

材料シミュレーションのための3段階検証プロトコルを提供します。実行前チェック、実行時モニタリング、実行後検証を行います。

要件

• Python 3.10+
• 外部依存関係なし（Python 標準ライブラリのみを使用）
• Linux、macOS、Windows で動作

収集する入力情報

検証スクリプトを実行する前に、ユーザーから以下の情報を収集してください。

入力	説明	例
設定ファイル	シミュレーション設定（JSON/YAML）	simulation.json
ログファイル	実行時の出力ログ	simulation.log
メトリクスファイル	実行後のメトリクス（JSON）	results.json
必須パラメーター	存在が必須のパラメーター	dt,dx,kappa
有効範囲	パラメーターの境界値	dt:1e-6:1e-2

判断の指針

各段階を実行するタイミング

Is simulation about to start?
├── YES → Run Stage 1: preflight_checker.py
│         └── BLOCK status? → Fix issues, do NOT run simulation
│         └── WARN status? → Review warnings, document if accepted
│         └── PASS status? → Proceed to run simulation
│
Is simulation running?
├── YES → Run Stage 2: runtime_monitor.py (periodically)
│         └── Alerts? → Consider stopping, check parameters
│
Has simulation finished?
├── YES → Run Stage 3: result_validator.py
│         └── Failed checks? → Do NOT use results
│                            → Run failure_diagnoser.py
│         └── All passed? → Results are valid

検証しきい値の選び方

メトリクス	保守的	標準	緩和
質量許容誤差	1e-6	1e-3	1e-2
残差の増加	2x	10x	100x
dt の縮小	10x	100x	1000x

スクリプトの出力（JSON フィールド）

スクリプト	出力フィールド
scripts/preflight_checker.py	report.status、report.blockers、report.warnings
scripts/runtime_monitor.py	alerts、residual_stats、dt_stats（アラートには NaN/Inf/オーバーフローの検出、残差の増加、dt の崩壊が含まれます）
scripts/result_validator.py	checks、confidence_score、failed_checks、status（PASS / FAIL / INSUFFICIENT_DATA）；チェックが実行されなかった場合、confidence_score は null です
scripts/failure_diagnoser.py	probable_causes、recommended_fixes

3段階検証プロトコル

ステージ1：実行前（シミュレーション開始前）

1. scripts/preflight_checker.py --config simulation.json を実行します
2. BLOCK ステータス：ただちに停止し、すべてのブロッカーの問題を修正します
3. WARN ステータス：警告を確認し、受け入れるリスクを記録します
4. PASS ステータス：シミュレーションに進みます

注：preflight_checker.py は必須キー、数値範囲、出力ディレクトリへのアクセス、ディスク容量を検証します。数値安定性（CFL / 拡散フーリエ数）は評価しません。陽解法の安定性を判定するには、skills/core-numerical/numerical-stability/scripts/cfl_checker.py を使用してください。

python3 scripts/preflight_checker.py \
    --config simulation.json \
    --required dt,dx,kappa \
    --ranges "dt:1e-6:1e-2,dx:1e-4:1e-1" \
    --min-free-gb 1.0 \
    --json

ステージ2：実行時（シミュレーション中）

1. scripts/runtime_monitor.py --log simulation.log を定期的に実行します
2. 問題の種類に応じてアラートのしきい値を設定します
3. 重大なアラートが発生した場合はシミュレーションを停止します

python3 scripts/runtime_monitor.py \
    --log simulation.log \
    --residual-growth 10.0 \
    --dt-drop 100.0 \
    --json

ステージ3：実行後（シミュレーション終了後）

1. scripts/result_validator.py --metrics results.json を実行します
2. すべてのチェックが PASS：結果は解析に使用できます
3. いずれかのチェックが FAIL：結果を使用せず、失敗の原因を診断します

python3 scripts/result_validator.py \
    --metrics results.json \
    --bound-min 0.0 \
    --bound-max 1.0 \
    --mass-tol 1e-3 \
    --json

変分モデル／勾配流モデル（Allen-Cahn、Cahn-Hilliard）では、--variational を追加すると、エネルギーが単調非増加であることを厳密にチェックします。

失敗の診断

検証に失敗した場合：

python3 scripts/failure_diagnoser.py --log simulation.log --json

会話形式のワークフロー例

ユーザー：フェーズフィールドシミュレーションが1000ステップ後にクラッシュしました。原因を一緒に調べてもらえますか？

エージェントのワークフロー：

1. まず、明らかなエラーがないかログを確認します。

   python3 scripts/failure_diagnoser.py --log simulation.log --json
   

2. 診断で数値的な発散が示された場合は、実行時の統計を確認します。

   python3 scripts/runtime_monitor.py --log simulation.log --json
   

3. 調査結果に基づいて修正を提案します。
   • 残差が急増した場合 → 時間刻みを小さくします
   • dt が崩壊した場合 → 安定性条件を確認します
   • NaN が検出された場合 → 初期条件を確認します

エラー処理

エラー	原因	解決方法
Config not found	ファイルパスが無効です	設定ファイルのパスが存在することを確認します
Non-numeric value	パラメーターが数値ではありません	設定ファイルの形式を修正します
out of range	パラメーターが範囲外です	パラメーターまたは範囲を調整します
Output directory not writable	権限の問題です	ディレクトリの権限を確認します
Insufficient disk space at <path>	出力ボリュームの空き容量がほとんどありません	空き容量を確保するか、出力を減らします
Invalid parameter name	--required の名前に使用できない文字が含まれています	英字、数字、_、.、- のみを使用します
range max ... must be greater than min	--ranges または境界値が逆転しているか、同じ値です	max > min となるようにします
must be a finite positive number	nan／inf／負のしきい値が指定されています	有限の正の値を指定します
Log file too large	ログが解析上限の 500 MB を超えています	ログを切り詰めるか、事前にフィルタリングします

解釈のガイドライン

ステータスの意味

ステータス	意味	対応
PASS	すべてのチェックに合格しました	確信を持って続行します
WARN	重大ではない問題が見つかりました	内容を確認し、記録します
BLOCK	重大な問題が見つかりました	続行する前に必ず修正します

信頼度スコアの解釈

スコア	意味
1.0	すべての検証チェックに合格しました → 確信を持って続行します
0.75+	ほとんどのチェックに合格しましたが、軽微な問題があります
0.5-0.75	重大な問題があります。慎重に確認してください
< 0.5	大きな問題があります。結果を信頼しないでください
null（ステータス INSUFFICIENT_DATA）	認識可能なメトリクスフィールドがありません。チェックは実行されていません — 合格ではありません。メトリクスファイルを確認してください。

メトリクスに対応する field_min／field_max がない場合、指定された境界値（--bound-min／--bound-max）は、成功扱いになることなく、失敗した bounds_unverifiable チェックとして報告されます。 変分法／勾配流の実行では、厳密な単調非増加エネルギーチェック（energy_monotone）を適用するために、--variational を渡すか、メトリクスで "energy_variational": true を設定してください。そうしない場合は、実行途中の急増を検出しない、より緩やかな energy_net_decrease チェックが使用されます。

よくある失敗パターン

ログ内のパターン	考えられる原因	推奨される対処
NaN、Inf、オーバーフロー	数値的不安定性	dt を減らし、減衰を増やします
最大反復回数に達した、収束しなかった	ソルバーの失敗	前処理器や許容誤差を調整します
メモリ不足	メモリの枯渇	メッシュを小さくするか、アウトオブコアを有効にします
dt が減少した	適応ステップ幅制御が作動しました	制御されていれば問題ない場合があります

検証チェックリスト

該当する以下の各項目が、明示された具体的な成果物によって満たされるまでは、検証結果を信頼しないでください。 これらの内容をユーザー向けの概要に記録してください。

• result_validator.py --json を実行し、results.status が PASS（INSUFFICIENT_DATA ではない）で、かつ results.confidence_score == 1.0 であることを確認しました。スコアが null、または INSUFFICIENT_DATA の場合はチェックが実行されていません。合格ではなく、未検証として扱ってください。
• results.checks を列挙し、要求されたすべてのチェックが実際に含まれていること（例：mass_conserved、bounds_satisfied、no_nan、および energy_monotone／energy_net_decrease）を確認しました。また、results.failed_checks が空で、bounds_unverifiable の項目が含まれていないことも確認しました。これは、要求された境界条件と比較するための field_min／field_max がなかったことを意味します。
• 変分モデル／勾配流モデル（Allen-Cahn、Cahn-Hilliard）では、--variational を渡す（または "energy_variational": true を設定する）ことで、energy_monotone が適用されるようにしました。途中のエネルギー急増は検出できないため、より緩い energy_net_decrease に依存していないことを記録しました。
• 使用した質量ドリフト許容誤差（--mass-tol、デフォルトは 1e-3）を記録し、実行に適した Conservative／Standard／Relaxed の列と一致することを確認しました。厳密な質量保存が必要な問題で、デフォルトを無条件に受け入れていません。
• runtime_monitor.py --json を実行し、residual_stats（最小値／最大値／最終値）と dt_stats を記録しました。NaN／Inf／オーバーフロー、--residual-growth を超える残差の増大、または --dt-drop を下回る dt の崩壊に関する alerts がないことを確認しました。
• 数値安定性を、core-numerical/numerical-stability/scripts/cfl_checker.py（CFL／フーリエ限界）によって別途判定しました。preflight_checker.py は CFL／フーリエを評価しません。preflight が PASS でも、時間方向／空間方向の安定性が確認されたことにはなりません。
• FAIL またはアラートがあった場合は、failure_diagnoser.py --json を実行し、結果を再利用せずに probable_causes／recommended_fixes を記録しました。

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

安易な近道	間違っている理由／対処方法
「Preflight が合格したので、実行は数値的に安定しています。」	preflight_checker.py がチェックするのは、必須キー、範囲、出力ディレクトリへの書き込み可否、ディスク容量のみです。CFL／フーリエは計算しません。安定性は cfl_checker.py で別途判定してください。
「result_validator が信頼度スコアを出力したので、結果は良好です。」	空、または認識されないメトリクスファイルでは、confidence_score: null とステータス INSUFFICIENT_DATA が返されます。これは「チェックが実行されていない」という意味であり、合格ではありません。認識されるフィールドが存在し、status == PASS であることを確認してください。
「エネルギーが開始時より低くなったので、散逸実行は問題ありません。」	デフォルトの energy_net_decrease は最初と最後だけを比較し、途中の急増を見逃します。勾配流モデルでは --variational を使用し、厳密な単調性を確認する energy_monotone チェックを適用してください。
「境界条件を要求したのに bounds_satisfied: false が出なかったので、境界条件は満たされています。」	field_min／field_max が存在しない場合、バリデーターは bounds_unverifiable（FAILED チェック）を出力します。根拠なく合格になることはありません。メトリクスファイルに実際のフィールド極値が含まれていることを確認してください。
「シミュレーションがクラッシュせずに完了したので、結果は信頼できます。」	実行の完了は正しさを保証しません。結果を使用する前に、質量保存、エネルギーの挙動、物理的な境界条件、および runtime_monitor のアラート一覧に問題がないことを確認してください。
「実行中に dt が小さくなったので、ソルバーは失敗しています。」	runtime_monitor の dt 崩壊チェックは、方向を考慮して（実行中の最大値と現在値を比較し）、--dt-drop を超えた場合にのみアラートを出します。制御された適応ランプは想定内です。実際の dt_stats とアラートが発生したかを確認してください。
「デフォルトのしきい値をそのまま使えばよいでしょう。」	デフォルト（--mass-tol 1e-3、--residual-growth 10、--dt-drop 100）は Standard 列の値です。質量保存が重要な問題には Conservative の許容誤差が必要です。物理現象に合わせてしきい値を選び、記録してください。

セキュリティ

入力の検証

• 設定ファイルのパスは解析前に存在確認され、存在しないパスの場合は明確なエラーが出力されます（終了コード 2）
• --required のパラメーター名は、安全な文字の許可リスト（^[A-Za-z0-9_.-]+$）に照らして検証されます。シェルのメタ文字を含む名前は拒否されます
• --ranges のエントリーは name:min:max として解析され、有限の数値範囲が適用されます。また、max > min が必須です
• --min-free-gb は有限の正の数値として検証されます（負の値、ゼロ、nan、inf は拒否されます）
• --residual-growth と --dt-drop のしきい値は、有限の正の数値として検証されます
• --bound-min と --bound-max は有限の数値として検証され（nan／inf は拒否されます）、--bound-max > --bound-min が適用されます。--mass-tol は有限の正の数値として検証されます
• 無効な入力の場合は、説明メッセージとともに終了コード 2 で終了します

ファイルアクセス

• preflight_checker.py は、ユーザーが指定した単一の設定ファイル（JSON/YAML）を読み込み、解決済みの出力ディレクトリを含むボリュームのディスク容量を確認します
• runtime_monitor.py は、--log で指定された単一のログファイルを読み込みます。ログファイルのサイズには上限（最大 500 MB）があり、上限を超える場合は解析前に拒否されます
• result_validator.py は、--metrics で指定された単一のメトリクスファイル（JSON）を読み込みます
• failure_diagnoser.py は、--log で指定された単一のログファイルを読み込みます。ログファイルは解析前にサイズ制限（最大 500 MB）のチェックを受けます
• スクリプトはファイルシステムに書き込みません。すべての出力は標準出力に送られます

ツールの制限

• Read：スクリプトのソース、参照資料、設定ファイル、シミュレーションログの確認に使用します
• Bash：4 つの Python 検証スクリプト（preflight_checker.py、runtime_monitor.py、result_validator.py、failure_diagnoser.py）を、引数リストを明示して実行するために使用します
• Write：検証レポートの保存に使用します。書き込み先はユーザーの作業ディレクトリ内に限定されます
• Grep/Glob：ログファイルや設定ファイルの検索、および参照情報の検索に使用します

安全対策

• eval()、exec()、動的コード生成は使用しません
• すべてのサブプロセス呼び出しでは、引数リストを明示して使用します（shell=True は使用しません）
• failure_diagnoser.py は、ハードコードされた事前コンパイル済みの診断用正規表現パターンを使用します。runtime_monitor.py は、任意の --residual-pattern／--dt-pattern による上書きを受け付けます。これらは re.compile でコンパイルされ（eval は使用しません）、ユーザー自身のログにのみ適用されます
• 出力される診断文字列は、スキルに用意された固定の原因／対処法テーブルから取得され、生のログ内容から挿入されることはありません

制限事項

• リアルタイムモニターではありません：スクリプトはログを事後に解析します
• 正規表現ベースです：ログ解析はパターンマッチングに依存するため、一般的でない形式を見落とす可能性があります
• 自動修正は行いません：スクリプトは診断を行いますが、シミュレーションは変更しません

参照資料

• references/validation_protocol.md - 詳細なチェックリストと基準
• references/log_patterns.md - 一般的な障害の特徴と正規表現パターン

バージョン履歴

• v1.2.2（2026-06-24）：検証チェックリスト（4 つのスクリプトの JSON 出力に基づく、エビデンスベースのチェックリスト）と、エージェントによる検証判定の解釈を強化する「よくある落とし穴と正当化」の表を追加しました。
• v1.2.0（2026-06-23）：診断用正規表現を修正（正常なログで誤って収束／発散と判定されないように修正）、方向を考慮した dt 崩壊の検出、ランタイムモニターでの NaN/Inf スキャン、厳密な変分エネルギーチェック、空振りにならない境界値／信頼度チェック、設定ファイルを基準とする出力ディレクトリと正しいボリュームのディスクチェックを追加し、文書化されていた入力検証／ファイルサイズの安全対策を実装しました
• v1.1.0（2024-12-24）：ドキュメント、判断の指針、Windows との互換性を強化しました
• v1.0.0：4 つの検証スクリプトを含む初回リリース