tomyud1/agentic-cfd

Agentic CFD ワークフロー

あなたは問題文を信頼できるシミュレーションレポートに変換します。読者はエンジニアで、主に概要を読み、すべての主張を確認できなければなりません。4 つのルールがあります。

1. コードがすべての数値を計算します。 あなたはコードを書き、結果、参照値、数式の出力を手動でレポートに入力してはいけません。理論はシンボリックに解かれ（SymPy）、自己チェックされます。
2. すべての選択が文書化されます。 各 OpenFOAM 設定は、理由、影響、代替案を含む判断に属します。チェッカーはそれ以外のレポートのレンダリングを拒否します。
3. 記憶に頼りません。 参照データ、相関式、定数は、問題の reference/ ファイルまたは引用されたソースから取得します。近似値を使用する必要がある場合は、レポートにその旨を記載します。
4. 洞察は、実験ノートのようにリアルタイムで記録します。 あなたの仕事の一部は、後続のエージェントのためにこのワークフローを改善することです。何かが失敗した、驚かされた、再試行が必要になった、またはこれらのガイドラインが不明瞭になった瞬間に、修正を始める前に洞察を記録します： insights.log(case, stage, problem); 診断、修正、教訓、ガイドラインを insights.resolve(...) で入力します。最後にまとめて記録しないでください。長時間のセッションの記憶は失われ歪みます。5～15 件のエントリを記録することを想定してください。1 件も記録がない実行は、注意深く見られていなかったことを意味します。

フォルダ構成

cfdlib/                       共有ツール (変更しないでください。必要な変更は洞察として記録し、stage は "tooling" にします)
  foam.py         render_case, run (タイムアウト、PID ファイル), stop, running; フィールドと postProcessing .dat ファイルの読み取り
  monitor.py      parse_log, assess (ヘルスチェック), preflight (短いテスト実行 + 実行時間の予測)
  verification.py 誤差ノルム、観測次数、Richardson 補外、GCI、level_sequence (任意のレベルの系列の収束。参照自身のものを含む)
  signals.py      周期信号: サイクル、精細化されたピーク、周期性チェック、FFT 周波数
  plots.py        図のスタイルとサイズ (figure, wide, sketch); to_svg はテキストの重なりをチェック
  report.py       m(), tex_num(), tex_fix() (テーブル列の固定小数点), tex_pct(), LETTERS, load_yaml, environment_info(), render()
  perf.py         実行ごとのパフォーマンス数値 (summarize, machine) パフォーマンス付録用
  contract.py     レポート契約チェッカー (--decisions モードも)
  insights.py     ライブ洞察ログ (ログ記録時にタイプセットをチェック; 埋められたエントリの上書きを拒否)
  foamdict.py     OpenFOAM 辞書パーサー (チェッカーが使用)
cases/<name>/                 問題ごとのフォルダ
  problem.yaml   ユーザーから与えられる: description (簡単な概要), setup (事実のリスト: 形状、境界条件、定義), given data, requested outputs [+ reference/]。物理を変更しないでください。description と setup はそのままレポートに渡します。
  reference/     ユーザー提供の参照データ (出典付き)
  numerics.yaml  あなたの数値計画 (メッシュ、実行長さ、許容誤差)
  decisions.yaml すべての選択。ケースをセットアップするときに記述します
  insights.yaml  ライブログ (cfdlib.insights)
  template/      OpenFOAM ケース (0/, constant/, system/) に {{ placeholders }} を含む
  theory.py / analytical.py, sketch.py, run.py, analyze.py
results/<name>/  生データ、results.json、report.html

実例 (開始前にすべてのファイルを読み、構造をコピーします。数値設定はコピーしないでください):

• cases/plane_poiseuille/: 線形、定常、厳密解 (検証)。レポート: results/plane_poiseuille/report.html。
• cases/lid_driven_cavity_re100/: 非線形、定常、厳密解なし、公開ベンチマーク (ベンチマーク比較、Richardson 補外、残差停止 SIMPLEC、事前テストと本番コマンドを分離)。レポート: results/lid_driven_cavity_re100/report.html。その insights.yaml には、それを構築したエージェントからの 15 の教訓が含まれています。
• cases/stokes_first_problem/: 線形、非定常、厳密解 (メッシュとタイムステップの複合および個別スタディ、時間ステップごとの運動量バランス、同時実行)。レポート: results/stokes_first_problem/report.html。
• cases/dfg_cylinder_re100/: 非線形、非定常かつ周期的 (渦放出)、複数の参照レベルを持つベンチマーク、Python で生成された曲線ボディ O グリッドメッシュ、MPI 実行とパフォーマンス付録。レポート: results/dfg_cylinder_re100/report.html。その insights.yaml には 16 の教訓が含まれています (最も重要なもの: PISO は時間に関して 1 次だった)。

ステージ

0. 受け入れ

• problem.yaml と reference/ ファイルを読みます。要求された出力をリストアップします (それらには a, b, c... の文字が割り当てられます)。
• 支配的な無次元数 (Re, Ma, ...) をコードで計算します。適用される物理を決定します。
• データが不足しているか矛盾している場合は、文書化された仮定を選択し、レポートの制限事項にフラグを立てます。入力を黙ってでっち上げてはいけません。
• 参考文献が不確かさを与えていない場合は、不確かさを推定し (その格子、印刷された桁、2 番目のソース)、その方法を記録します。ステージ 5 で必要になります。

1. 理論: シミュレーションなしでわかること

• 厳密解が利用可能な場合: SymPy で導出し、自己チェックし (方程式と境界条件を満たす)、要求された量を評価します。cases/plane_poiseuille/analytical.py を参照。
• 厳密解がない場合 (通常のケース): theory.intro でその旨を述べ、理論が何を言えるかを示します: 極限ケース、スケーリング、保存則、対称性、量の符号、期待される流れ構造。cases/lid_driven_cavity_re100/theory.py を参照。
• 導出されたすべての量について: なぜ重要か、この問題における各記号の意味と値、および数値を代入した式 (手計算で確認できるように)。

2. セットアップと判断

• 最も近い OpenFOAM チュートリアル ($FOAM_TUTORIALS) を見つけ、そこから開始します。変更は最小限にします。
• references/openfoam-primer.md を読み、各ファイルが制御するものと既知の落とし穴を確認します。
• テンプレートには Jinja ループを含めることができます: Python から blockMeshDict 全体を生成することは問題なく、曲線ボディをメッシュ化する方法です (例: cases/dfg_cylinder_re100/run.py の mesh_spec())。
• LaTeX を含むファイルは、Bash のヒアドキュメントやインライン Python ではなく、編集/書き込みツールのみで編集します。Bash ツールはバックスラッシュを削除します (\times が TAB になります)。ケース 3 と 4 は両方ともこれで時間をロスしました。
• decisions.yaml を進めながら書きます: 選択ごとに 1 エントリとし、kind (physics / accuracy / solver / output) と、ケースファイル内のすべての設定をカバーする settings パターンを含めます。1 つのケースがレンダリングされたらすぐにカバレッジを確認します: python -m cfdlib.contract --decisions cases/<name>/decisions.yaml <case dir>。
• メッシュスタディを計画します: 少なくとも 3 つのメッシュ、 refinement ratio 2 (観測次数と GCI に必要)。非定常問題にはタイムステップスタディも必要です (または、時間誤差が無視できることを数値で示す主張)。
• 問題に対する物理的な収束/定常性チェック (バランス、保存量、変化が止まらなければならない監視値) とその許容誤差を、結果を見る前に定義します。正規化された残差だけでは十分ではありません。非定常問題: 時間ステップごとのバランス (保存量の変化 = 境界フラックス) は強力なチェックです。ソルバー自身の時間スキームを使用する必要があります。
• 合格/不合格の許容誤差は判別可能でなければなりません: 粗い事前テストの誤差と期待される次数 (最も細かいメッシュが到達すべきもの) からサイズ設定し、丸い数値からではありません。達成されたものより 100 倍緩い許容誤差は何も証明しません (ケース 3)。観測された精度次数を独立したルールにします。

3. 事前テスト (必須、長時間実行の前)

• cfdlib.monitor.preflight() を最も粗いメッシュと最も細かいメッシュの両方で、短い実行 (全長の数%) で実行します。これは別の <case>_preflight コピーで動作します。事前テストと本番ケースも別々のディレクトリにレンダリングし、一方を再実行しても他方が削除されないようにします。
• クラッシュ、NaN、Courant 数、残差/Courant/連続性の傾向を報告し、実行時間を予測します。非定常実行: 予測は信頼性があります。定常実行: residual_targets を渡します。結果は下限です (SIMPLE は後で、より細かいメッシュで遅くなります)。
• 事前テストが書き込んだすべての postProcessing ファイルのヘッダーと最初の行を出力し、それぞれが非自明であることを確認します (ケース 4: 圧力積分がすべてのステップで 0 を書き込み、黙って続行)。
• 非定常非線形問題: 短いタイムステップスタディ (3 つのタイムステップ、比 2、粗いメッシュ) は、メッシュスタディの前に事前テストに属します。時間における観測次数を示します: PISO (1 外部修正子) はケース 4 で 1 次であることが判明し、完全な再実行のコストがかかりました。
• 静止状態から開始する事前テストは、発達した非定常流れのコストを過小評価します (ケース 4: 2 倍)。発達したフィールドから開始するか (粗い実行からの mapFields)、予測の 2 倍の予算を見積もります。
• 失敗または警告が出た場合、セットアップを修正し、洞察を記録します。失敗する事前テストでは本番実行を行いません。予測時間が過剰な場合 (ここでは実行あたり約 15 分以上)、計画を粗くし、その旨を述べます。

4. 本番実行

• メッシュを粗いものから細かいものへと実行します。定常実行の場合、最も細かいメッシュの反復回数をより粗いメッシュから外挿してから (多くの場合、refinement ごとに 3～4 倍増加します) 起動します。
• 停止は物理的でなければなりません: ステージ 2 の物理チェックを停止ルールにします (例: プローブ値に対する runTimeControl 関数オブジェクト。プライマーを参照)、またはメッシュごとに残差ターゲットが実際にそれを満たすかどうかを、最初に粗いメッシュで確認します。
• 独立した実行 (異なるメッシュ) は同時に実行できます (最大 6 つ、8 コア)。これは実行ごとのウォールタイムを増加させるため、再現性ノートにその旨を記載します。
• 長時間実行はバックグラウンドで行います。 python -m cfdlib.foam ps はソルバープロセスをリストし、 python -m cfdlib.foam stop <case dir> は 1 つを強制終了します (Python ラッパーだけを停止すると孤立したソルバーが残ります)。実行ごとに記録: ヘルス (monitor.assess)、物理チェック、ウォールタイム。
• 一連の長時間実行を、完了マーカーと実行ごとのレコードを書き込む 1 つのバックグラウンドスクリプトとして実行します。中断後 (API ポーズも)、何かを再実行する前にそれらのファイルを読みます。
• すべてのハードウェアスレッドがソルバーを実行している間、あなた自身の作業は遅くなります: 1～2 スレッドを空けておくか、予測の 1.5 倍の予算を見積もります。

5. 解析

• すべての比較はコード内で行います。厳密解がある場合: メッシュごとの誤差と観測次数。ない場合: 3 つのメッシュからの観測次数と Richardson 補外、最も細かいメッシュの GCI (verification.py)、次に補外値を参考文献と比較します。
• ベンチマークもシミュレーションです: 一致は (あなたの GCI バンド + 参考文献自身の不確かさ) に対して判断し、ゼロに対してではありません。差が refinement で縮まない場合、それは離散化誤差ではありません。どちらかの側を非難する前に、ロバスト性をテストし (別のスキーム、より厳しい反復)、2 番目の独立した参考文献を推奨します。
• 参考文献が複数のメッシュレベルを与える場合、それはまだ収束しています。その観測次数と Richardson 値を計算し (verification.level_sequence)、あなたの結果をその最も細かいレベルと補外値の両方と比較します。確認する前に合格ルールを決定します (ケース 4 は最も細かいレベルのルールを保持し、補外をコンテキストとして報告しました)。
• 周期的な出力 (放出、振動): cfdlib.signals を使用します (上向き交差間のサイクル、放物線精細化ピーク、周期性チェック、FFT クロスチェック)。独自に書かないでください。
• 粗いメッシュでの一致は幸運である可能性があります (誤差の相殺)。差異を正直に、どこでなぜかを報告します。
• 説明は主張です: 書く前にデータ (符号、サイズ、スケーリング) に対してチェックします。ケース 3 では、誤差の最初の説明が間違った符号と 3 分の 1 のサイズでした。

6. レポート

• analyze.py で results.json を構築し、report.render(results, svgs, out, case_dir=<最も細かいケース>) を呼び出します。契約は references/report-contract.md にあります。render はそれを破るレポートの書き込みを拒否します。
• 数式: すべての式、記号、科学数値はテキスト内で \( \) 内の LaTeX として記述します (m(), tex_num()): \(0.009\,U\) と書き、0.009 U、6.3e-06、u*H/nu とは書きません。チェッカーは e-表記法と ASCII 数式を拒否し、プレーンテキスト内の数値×記号を警告します。
• キャプションと発見も結果です: データから生成します (「縮小する」と言うキャプションは計算されなければなりません)。図は {fig:<key>} として参照します。 render() が番号を挿入します。
• 図 (cfdlib.plots): 1 つのパネルには plots.figure()、2～3 つのパネルには plots.wide(n)、問題のスケッチには plots.sketch() (必須)。 to_svg() は、テキストがテキスト、線、矢印、または図形と重なっている場合、または凡例がデータを覆っている場合、または列より広い場合、図を拒否します。レイアウトを修正します (ラベルを線から離す、リーダー線付きの annotate、凡例は外側)。 allow= は本当に意図された重なりの場合のみ使用し、必要であれば洞察を記録します。
• 評決: あなたが定義したすべてのチェックに合格した場合のみ PASS。結果が注意点とともに使用可能な場合は WARN。それ以外は FAIL。チェックに失敗したものを決して和らげてはいけません。

7. ビジュアルレビュー (必須)

契約は構造をチェックします。見ることだけが読者が見るものを捉えます。ローカルサーバーを通じてビルトインブラウザでレポートを開きます (file:// は機能しません): http://localhost:8765/<name>/report.html (読み込まれない場合は、プレビューツールを使用して .claude/launch.json から reports サーバーを起動します)。再レンダリング後は ?v=<n> を追加してキャッシュを回避します。

• すべてのセクションを上から下までスクリーンショットします。確認: 図が読みやすいこと (テキストが小さすぎない、重なりがない、リーダー線が曲線を横切っていない)、テーブルが切り取られていない、数式がレンダリングされている (生の \( がない)、テーブルの列が揃っている、概要が各要求に回答していること。
• ページ内で実行します (MathJax を待ち、すべての ⓘ パネルを開き、コンテンツが切り取られているすべての要素をリストします。空であるべきです。MathJax が終了する前に、読み込み直後に実行すると、タイプセットされていない TeX がオーバーフローとして報告されます): await MathJax.startup.promise; document.querySelectorAll('details').forEach(d => d.open = true); [...document.querySelectorAll('section *')].filter(x => !x.tagName.startsWith('MJX') && x.scrollWidth > …