mesh-generation

メッシュ生成

目標

PDE シミュレーションでメッシュ解像度を選択し、メッシュ品質を確認するための、一貫したワークフローを提供します。

要件

• Python 3.10+
• 外部依存関係なし（標準ライブラリを使用）

収集する入力

入力	説明	例
領域サイズ	物理的な寸法	1.0 × 1.0 m
特徴サイズ	解像する最小の特徴	0.01 m
特徴あたりの点数	解像度の要件	10 points
アスペクト比の上限	dx/dy の最大比	5:1
品質しきい値	スキューネスの上限	< 0.8

判断の指針

解像度の選択

What is the smallest feature size?
├── Interface width → dx ≤ width / 5
├── Boundary layer → dx ≤ layer_thickness / 10
├── Wave length → dx ≤ lambda / 20
└── Diffusion length → dx ≤ sqrt(D × dt) / 2

メッシュタイプの選択

問題	推奨メッシュ
単純な形状、均一	構造化デカルトメッシュ
複雑な形状	非構造三角形／四面体メッシュ
境界層	ハイブリッド（壁面付近は構造化）
適応的細分化	クアッドツリー／オクトツリーまたは AMR

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

すべてのスクリプトは、inputs（CLI 値をそのまま格納）と results（以下の計算フィールド）を持つトップレベルオブジェクトを出力します。次のようにインデックスを指定します：result["results"]["..."]。

スクリプト	results フィールド
scripts/grid_sizing.py	dx、counts（次元ごとのセル数のリスト。長さは dims と同じ）、notes
scripts/mesh_quality.py	aspect_ratio、skewness、size_anisotropy、quality_flags、dims、notes

mesh_quality.py は、エッジ間隔のみで定義される軸平行（直交デカルト）セルを扱います。このようなセルでは、すべての内角が 90° であるため、真の角度スキューネスは常に 0.0 となり、high_skewness が設定されることはありません。セルの伸長は、別途 aspect_ratio と、冗長な利便フィールド size_anisotropy（= 1 - 1/aspect_ratio）で報告されます。

ワークフロー

1. 解像度を推定する - 物理スケールに基づきます
2. グリッドサイズを計算する - scripts/grid_sizing.py を実行します
3. 品質指標を確認する - scripts/mesh_quality.py を実行します
4. 必要に応じて調整する - アスペクト比を修正し、スキューネスを低減します
5. 検証する - メッシュ収束試験を行います

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

ユーザー: 界面幅 10 μm のフェーズフィールドシミュレーション用に、1mm × 1mm の領域をメッシュ化したいです。

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

1. グリッドサイズを計算します：

   python3 scripts/grid_sizing.py --length 0.001 --resolution 200 --json
   

2. 界面が解像されていることを確認します：dx = 5 μm、界面幅 = 10 μm → 界面幅あたり 2 点です。
3. 推奨：界面を横切る 5 点を確保するため、500 点（dx = 2 μm）に増やします。

メッシュ生成前のチェックリスト

• 特徴／界面ごとの目標解像度を定義する
• dx が安定性の制約を満たすことを確認する（numerical-stability を参照）
• アスペクト比が上限未満であることを確認する（通常は 5:1）
• スキューネスがしきい値未満であることを確認する（通常は 0.8）
• 細分化試験でメッシュ収束を検証する

CLI の例

# Compute grid sizing for 1D domain
python3 scripts/grid_sizing.py --length 1.0 --resolution 200 --json

# Check mesh quality (3D cell)
python3 scripts/mesh_quality.py --dx 1.0 --dy 0.5 --dz 0.5 --json

# High aspect ratio check (2D cell; --dz omitted is treated as 2D)
python3 scripts/mesh_quality.py --dx 1.0 --dy 0.1 --json

エラー処理

すべての検証エラーは stderr に書き込まれ、スクリプトはコード 2 で終了します。

エラーメッセージ	原因	解決方法
length must be positive, got ...	領域サイズが正でない	正の値を使用します
resolution must be positive, got ...	解像度が正でない（resolution=1 は有効な単一セルメッシュです）	正の整数を使用します
dims must be one of (1, 2, 3), got ...	未対応の次元数	1、2、または 3 を使用します
<name> must be a finite positive number, got ...	dx／dy／dz が有限でない、または正でない	有限の正の値を使用します
<name> exceeds maximum (...), got ...	入力がリソース枯渇の上限を超えている	より小さな値を使用します

解釈の指針

アスペクト比

アスペクト比	品質	影響
1:1	優秀	精度が最適です
1:1 - 3:1	良好	許容範囲です
3:1 - 5:1	普通	精度に影響する可能性があります
> 5:1	不良	ソルバーの問題が発生する可能性が高いです

スキュー度

スキュー度は、理想的なセル形状からの角度のずれです （四角形／六面体の場合は max(|90° - θ_i|) / 90°。詳細は references/quality_metrics.md を参照してください）。 mesh_quality.py は軸に沿ったエッジ間隔を使用します。これは、内角がすべて厳密に90°の直交デカルトセルを表すため、 これらのセルでは常に skewness = 0.0 と報告します。以下のしきい値は、 dx/dy/dz の間隔からではなく、実際のセル頂点の形状（例：非構造メッシュ）から 真のスキュー度を取得した場合に適用されます。

スキュー度	品質	影響
0 - 0.25	優秀	最適
0.25 - 0.50	良好	許容範囲
0.50 - 0.80	普通	精度に影響する可能性があります
> 0.80	低い	問題が発生する可能性が高いです

注：セルの伸長はスキュー度ではありません。異方的でも直交しているセル （例：壁面に沿った境界層セル）は、高い aspect_ratio / size_anisotropy を持ちますが、スキュー度はゼロであり、多くの場合まったく問題ありません。

解像度のガイドライン

用途	特徴あたりの点数
フェーズフィールド界面	5-10
境界層	10-20
衝撃波	3-5（捕捉手法を使用）
波動伝播	波長あたり10-20
滑らかな勾配	5-10

検証チェックリスト

• grid_sizing.py --json の dx と counts を記録し、最小の物理的特徴を十分な点数で表現できることを確認しました（上記の解像度選定に従い、界面は ≥5×dx、境界層は ≥10×dx、波長は ≥20×dx）。
• 異方的な領域では、エッジ長が異なるごとに grid_sizing.py を実行する（または軸ごとに --dx を適用する）ようにしました。長さの異なるエッジに、単一の --length から算出した点数を適用していません。
• notes フィールドで "Grid does not fully cover length" を確認し、counts を信頼する前に、部分的なカバレッジに関する警告を解消しました。
• mesh_quality.py --json の aspect_ratio と quality_flags を記録しました。high_aspect_ratio がないこと、または伸長が意図的で物理に即していること（例：壁に沿った AR≤100 の境界層セル）を確認しました。
• 報告された skewness = 0.0 が、直交デカルト格子で想定される結果であり、品質検査に合格したという測定結果ではないことを確認しました。非構造セル／非直交セルについては、セル頂点の形状から角度ベースの実際のスキュー度を取得し、しきい値 <0.8 と照合しました。
• 解像度を確定する前に、dx がソルバーの安定性制約も満たすことを検証しました（数値安定性の情報と照合）。
• メッシュ収束性試験（段階的に細分化した格子を3つ以上）を実施し、メッシュが十分であると判断する前に、対象とする物理量が単調または漸近的に変化することを確認しました。

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

つい選びがちな近道	それが間違っている理由／すべきこと
「skewness が 0.0 だったので、メッシュ品質に問題はありません。」	mesh_quality.py は、軸に沿った間隔に対して常に skewness = 0.0 を返します。これは直交セルの定義上の性質であり、測定値ではありません。実際のスキュー度を求めるには、非構造メッシュのセル頂点の角度が必要です。0.0 を品質チェックの合格と解釈しないでください。
「2つのグリッドでほぼ同じ結果が出たので、メッシュは収束しています。」	2つのグリッドだけでは、観測次数や漸近領域を確定できません。連続して細分化したグリッドを3つ以上使用し、結果をメッシュ非依存として示す前に、関心のある量が収束していることを確認してください。
「aspect_ratio が高いと警告されたので、このセルは不適切です。」	縦長であることはスキュー度とは異なります。流れ／場に沿って配置された壁面境界層セルは、AR が約100まででも許容されます。high_aspect_ratio フラグだけで判断せず、size_anisotropy と物理現象を確認してください。
「--length を1つ設定して、すべての軸で counts を使い回します。」	grid_sizing.py は呼び出しごとに等方的に処理し、算出した単一のカウントをすべての次元に適用します。辺の長さが異なる場合、軸によって解像度が過剰または不足します。辺の長さごとに実行するか、軸ごとに --dx を指定してください。
「dx = length/resolution なら、resolution が大きいので特徴を解像できます。」	領域あたりの点数は、特徴あたりの点数ではありません。全体の dx が細かくても、薄い界面／層を横切るセル数が少なすぎる場合があります。feature_size / dx を解像度ガイドライン（界面では5～10、境界層では10～20）と照らして確認してください。
「メッシュは十分細かいので、時間ステップは無視できます。」	メッシュ解像度と時間安定性は連動しています。dx を小さくすると、陽解法の CFL／拡散制約が厳しくなります。細分化したメッシュがソルバーの安定性制約に違反すると発散するため、細分化後は dt を数値安定性に照らして再確認してください。

セキュリティ

入力の検証

• すべての入力（length、resolution、dx、dy、dz）は、リソース枯渇を防ぐため、上限を設けたうえで有限の正数として検証されます
• dims は {1, 2, 3} に制限されています
• argparse の型パラメーターにより、処理が始まる前に CLI の境界で数値以外の入力が拒否されます

ファイルアクセス

• スクリプトは外部ファイルを読み込みません。すべての入力は CLI 引数で指定します
• スクリプトは標準出力（JSON 出力）にのみ書き込みます。エージェントが明示的に Write ツールを使用しない限り、ファイルは作成されません

ツールの制限

• Read：スクリプトのソース、参照資料、ユーザーの設定ファイルの確認に使用します
• Write：グリッドのサイジング結果やメッシュ品質レポートの保存に使用します。書き込み先はユーザーの作業ディレクトリ内に限定されます
• Grep/Glob：関連ファイルの特定や参照先の検索に使用します
• このスキルの allowed-tools では、ユーザー提供の入力を処理する際にエージェントが任意のコマンドを実行するのを防ぐため、Bash を除外しています

安全対策

• eval()、exec()、動的コード生成は使用しません
• すべてのサブプロセス呼び出しでは、明示的な引数リストを使用します（shell=True は使用しません）
• ツールの範囲が縮小されている（Bash を使用しない）ため、ユーザーのテキストからシェルコマンドを組み立てるのではなく、Read と Write を使って入力を準備し、出力を取得してください
• すべての出力は決定論的な JSON であり、シェルで解釈される内容は含まれません

制限事項

• 2D／3D のみ：非構造メッシュの生成には対応していません
• 品質指標：アスペクト比とサイズ異方性は、軸に沿った間隔のみから算出されます。これらの直交セルではスキュー度は 0 として報告されます（実際の角度によるスキュー度には、実際のセル頂点形状が必要です）
• メッシュ生成なし：サイジングの推奨のみです
• 呼び出しごとに等方的：grid_sizing.py は単一の --length を受け取り、算出されたカウントをすべての次元に適用します。異方性のある領域（例：10 cm × 5 cm）では、長さの異なる辺ごとに1回実行するか、物理条件から dx を計算して軸ごとに適用してください（例：--length 0.10 --dx 5e-5、次に --length 0.05 --dx 5e-5）。

参考資料

• references/mesh_types.md - 構造格子と非構造格子
• references/quality_metrics.md - アスペクト比／スキューネスのしきい値

バージョン履歴

• v1.2.0 (2026-06-23): スキューネスの計算を修正（直交セルのスキューネスを 0 として報告）、size_anisotropy を追加、mesh_quality.py --dz を任意に変更（2D セル）、解像度からカウントを求める場合の grid_sizing の off-by-one を修正、dx オーバーライドに関する注記を明記、出力／エラー処理のドキュメントを修正
• v1.1.0 (2024-12-24): ドキュメント、判断の指針、例を拡充
• v1.0.0: 2 つのメッシュ品質スクリプトを含む初回リリース