benchmark-and-mms-planner

ベンチマークとMMSプランナー

目標

シミュレーション結果を信頼する前に、検証と妥当性確認の計画を設計します。このスキルは、エージェントが製造解、ベンチマークケース、細分化プロトコル、不確実性チェック、合否基準を選択するのに役立ちます。

要件

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

収集する入力

入力	説明	例
PDE またはモデルクラス	支配方程式の系統	diffusion、elasticity、phase-field
注目する量	検証する指標	interface velocity、L2 temperature error
次元	1、2、または3	2
期待次数	形式上の離散化次数	2
参照解の有無	解析解、ベンチマーク、またはなし	analytic
リスクレベル	誤った結果によるコストや影響	high

判断の指針

• コードの正しさに確信がなく、解析解を組み込める場合は、MMSを使用します。
• コード検証よりも物理モデルの妥当性確認が重要な場合は、標準ベンチマークを使用します。
• 結果を主張、設計上の判断、比較に使用する場合は、必ず格子／時間細分化を行います。
• 入力値が較正済み、ノイズを含む、または実験で測定されたものである場合は、不確実性伝播を行います。

スクリプトの出力

scripts/benchmark_mms_planner.py は、次の項目を含む inputs と results を出力します。

• verification_strategy
• effective_model — 実際に使用される、解決済みのモデル系統。不明な系統は general にフォールバックします。
• mms_plan
• benchmark_cases
• refinement_protocol（dimension、levels、spacing_ratio、expected_order、accept_observed_order_min、include_time_refinement）
• uncertainty_plan（propagate_inputs、report_error_bars、separate_discretization_and_model_error）— リスクレベルと参照タイプに応じた、伝播とエラーバーに関する指針です。
• acceptance_criteria
• warnings

accept_observed_order_min は認証された上限ではなく、工学的なスクリーニング用のヒューリスティックです。形式上の expected_order から一定割合の許容差（高リスクでは10％、それ以外では20％）を差し引き、1次収束（1.0）を下限とします。この相対許容幅により、形式次数にかかわらず厳格さが一貫します。references/vv_patterns.mdを参照してください。

ワークフロー

1. 支配モデル、注目する量、リスクレベルを収集します。
2. benchmark_mms_planner.py --json を実行します。
3. 高リスクの主張については、警告を阻害要因として扱います。
4. 返されたプロトコルをテスト、シミュレーション実行、またはレビュー用チェックリスト項目に変換します。

python3 skills/verification-validation/benchmark-and-mms-planner/scripts/benchmark_mms_planner.py \
  --model diffusion \
  --quantity "L2 error in temperature" \
  --dimension 2 \
  --expected-order 2 \
  --reference analytic \
  --risk high \
  --json

エラー処理

• 次元または期待次数が無効な場合は、作業を中断してモデルの説明を修正します。
• 参照解がない場合は、保存則と収束性を確認しますが、結果を妥当性確認済みとは呼びません。

制限事項

このスキルは検証作業を計画するものであり、ソルバーを実行したり、物理モデルが実験に適切であると証明したりするものではありません。

検証チェックリスト

このプランナーを使用した結果を信頼する前に、各項目について具体的な証拠を記録してください。

• benchmark_mms_planner.py --json を実行して inputs ブロックを保存し、エコーされた dimension、expected_order、reference、risk が実際の実行内容と一致することを確認しました（effective_model: general へのフォールバックは意図したものであり、--model のタイプミスではありません）。
• refinement_protocol を実行しました。報告された levels（3、高リスクの場合は4）の、spacing_ratio が2の系統的に細分化されたグリッドを使用し、それらの実行で観測された精度の次数を記録しました。
• 観測された次数が accept_observed_order_min 以上であることを確認しました。下回る場合は、合格と見なすのではなく、調査内容（メッシュがまだ漸近領域に達していない、境界／ソース誤差、リミッターの作動）を記録しました。
• include_time_refinement が true の場合、別途時間刻みの細分化試験を実行し、空間の次数だけでなく、時間方向の観測次数も記録しました。
• mms_plan.manufacture_solution が true の場合、ソース項／強制項を記号的に導出し、対応する境界項を適用して、製造解に対する L2 および Linf 誤差ノルムを記録しました。
• すべての acceptance_criteria 項目を数値で確認しました。保存則／収支が文書化された許容誤差内で閉じていること、細分化に伴って関心量がプラトーに達すること、本番利用前に benchmark_cases とのベンチマークの不一致が説明されていることを確認しました。
• warnings のすべての項目を高リスクの主張に対するブロッカーとして扱い、それぞれをどのように解決したかを記録しました（たとえば、reference が none または experimental の場合、独立した解析的／公開済みの参照を追加しました）。

よくある落とし穴と自己正当化

魅力的な近道	誤りの理由／対処方法
「プランナーが実行されて計画が出力されたので、結果は検証済みです。」	このスクリプトは V&V を計画するだけで、ソルバーは実行しません。検証には、計画を生成するのではなく、refinement_protocol、MMS、acceptance_criteria を実行する必要があります。
「2つのグリッドで収束したので、観測次数は問題ありません。」	refinement_protocol.levels が3（高リスクの場合は4）なのには理由があります。観測次数を推定し、それを提示する前に解が漸近領域にあることを確認するには、系統的に細分化されたグリッドが3つ以上必要です。
「観測次数が accept_observed_order_min を上回っているので、認定済みです。」	このしきい値は、正式な次数から相対許容差10%／20%を差し引き、1.0を下限とする、工学的なスクリーニング用の経験則であり、認定された境界ではありません。厳密に次数を検証するには、Richardson／GCI 試験を実行してください。
「モデルは定常状態に見えるので、include_time_refinement は省略できます。」	プランナーが include_time_refinement: true を設定した場合（時間依存のファミリーまたは general へのフォールバック）、空間方向の細分化だけでは時間誤差が隠れてしまいます。時間刻みの試験も実行してください。
「ベンチマークと一致したので、コードは妥当性確認済みです。」	benchmark_cases と一致したり収束したりすることは、コードが何らかの解に近づいていることを示しますが、物理モデルが正しいことの証明にはなりません。妥当性確認には独立した参照とモデル誤差の分離が必要であり、収束だけでは不十分です。
「reference none でも問題ありません。実行結果は物理的に妥当に見えます。」	reference: none の場合、戦略は検証のみを対象とします。その旨は warnings に記載されています。収束や保存則については報告できますが、結果を妥当性確認済みと呼んではいけません。
「モデル名が不明なので、general へのフォールバックは無視します。」	認識されない --model は、通知なしに effective_model: general として解決されます。このフォールバックによって benchmark_cases と時間細分化の判断の両方が変わるため、意図したものであることを確認してください。

セキュリティ

入力検証

すべての入力はコマンドライン引数であり、argparse で解析されます。検証は plan_vv（および一部はパーサー）で行われます。拒否された入力があると、スクリプトはエラーを標準エラー出力に出力し、終了コード 2 で終了します。

• dimension は 1、2、または 3 のいずれかでなければなりません。それ以外の整数は拒否されます。
• expected_order は正の有限数でなければなりません（NaN、無限大、ゼロ、負の値は拒否されます）。
• risk は許可リスト low、medium、high のいずれかでなければなりません（argparse の選択肢として制限され、plan_vv でも再検証されます）。
• reference は許可リスト analytic、benchmark、experimental、none のいずれかでなければなりません（argparse の選択肢として制限され、plan_vv でも再検証されます）。
• model と quantity はそれぞれ最大256文字（MAX_FIELD_LEN）です。これを超える文字列は拒否されます。
• model と quantity の文字列の内容には、これ以外の許可リストやサニタイズ処理はありません。quantity は出力にそのまま反映され、認識されない model ファミリーは拒否されず、暗黙に general として解決されます。

ファイルアクセス

• スクリプトはファイルを読み書きしません。すべての入出力は、コマンドライン引数から標準出力の JSON（または短いプレーンテキストの要約）への出力であり、エラーは標準エラー出力に出力されます。
• ファイルシステムのパスを受け取ったり構築したりしないため、パストラバーサルの攻撃対象領域はなく、パスのサンドボックス化も不要です。
• DoS に関係するサイズ制限は、model と quantity の256文字制限のみです。数値出力は検証済みの入力によって上限が設けられています。

ツールの制限

フロントマターでは allowed-tools: Read, Bash, Write, Grep, Glob が宣言されています。

• Bash は、同梱の scripts/benchmark_mms_planner.py を実行する場合にのみ使用されます（例：ワークフロー内の python3 ... --json の呼び出し）。
• Read、Grep、Glob は、計画時にスキル自身のファイルや参照（例：references/vv_patterns.md）を調べるために使用されます。
• Write は、返されたプロトコルをテスト用スタブやチェックリストファイルにするために使用されます。プランナースクリプト自体は書き込みを行いません。

安全対策

• eval、exec、動的コード実行はありません。プランナーは辞書を計算する純粋な Python コードです。
• スクリプトはサブプロセスを起動せず、外部ソルバーも呼び出さないため、エスケープが必要なサブプロセス引数リストはありません。
• pickle やその他の信頼できないデータのデシリアライズは行われません。出力は json.dumps でシリアライズされます。
• 256文字のフィールド制限は、異常に長い入力文字列に対する明示的な DoS 対策です。

参考資料

• MMS、ベンチマーク、不確実性の計画に関するメモについては、references/vv_patterns.md を参照してください。

バージョン履歴

• 1.1.3：プランナーの refinement_protocol、mms_plan、acceptance_criteria、warnings に関連付けた証拠ベースの項目からなる「検証チェックリスト」と、 ドメイン固有の V&V の近道（計画 != 検証、観測次数には3つ以上のグリッドが必要、スクリーニング帯は認証済みの境界ではない、 時間細分化、収束 != 妥当性確認、reference none、general フォールバック）を明確にした「よくある落とし穴と正当化」の表を追加。
• 1.1.1：各3つのケースについて、プランナー固有の出力（解決済みの verification_strategy、相対的な accept_observed_order_min の帯、細分化の levels、 include_time_refinement、uncertainty_plan のフラグ、モデル固有のベンチマークケース、正確な警告文字列）を固定する決定論的な script_checks を追加し、評価スイートの識別能力を高める。
• 1.1.0：未知のモデルファミリーを一度だけ general に解決することで、ベンチマークの選択と時間細分化の判断が一致するように修正（一覧にない非定常 PDE でも時間細分化がスキップされなくなりました）。解決済みファミリーを effective_model として反映。固定の絶対観測次数オフセットを、一次精度を下限とする相対許容誤差に置き換え。uncertainty_plan、effective_model、受け入れヒューリスティックを文書化。文字列入力に256文字の上限を追加。
• 1.0.0：ベンチマークおよび MMS 計画スキルの初版。