DualSPHysics MCP

DualSPHysics MCP

言語： 英語 | 中国語

AI エージェントから DualSPHysics シミュレーションを設計、実行、検証できます — ただ眺めるだけではありません。

10 個のModel Context Protocolツールが、ローカルのDualSPHysics SPH ツールチェーンをエンドツーエンドで操作します。構造化されたパラメーターでケースを設計し（XML を手書きする必要も、反復のたびにソルバーを実行する必要もありません）、進捗、スループット、ソルバー自身の推定残り時間を確認しながら CPU ジョブをバックグラウンドで実行し、ParaView 対応の VTK と CSV 時系列に後処理し、Koshizuka & Oka（1996）の実験と 2D ダムブレークを照合して、時刻ごとの誤差と MAE／RMSE／最大誤差を検証できます。

サーバーは DualSPHysics のコマンドラインツールをサブプロセスとして起動するだけです。DualSPHysics 自体はここでは配布していません。無償の LGPL-2.1-or-later ソフトウェアであり、このパッケージはそのコードやバイナリーをリンクも再配布もしないため、MIT ライセンスに追加の義務は生じません。DualSPHysics を使用した成果を公開する場合は、Dominguez et al. (2022), Computational Particle Mechanics 9:867–895, doi:10.1007/s40571-021-00404-2. を引用してください。

ツール

ツール	機能
check_environment	このマシン上の 4 つの DualSPHysics ツールを検出します。解決されたパス、検出元（環境変数、PATH、スキャン）、バージョン、ソルバーの機能フラグを表示し、見つからないツールがある場合はインストール方法を案内します。
create_case	2D ダムブレーク実験を平易なパラメーターで記述し、GenCase の *_Def.xml を取得します。XML を手書きする必要はなく、ソルバーも不要です。自己チェック用に粒子数の推定値を返します。
edit_case	既存のケースのパラメーターを変更し（その場で、または save_path に保存）、統合した結果を再検証します。
describe_case	ケースファイルを読み取り、dp、領域、柱／水槽／障害物、時間設定、ゲージ、粒子数の推定値を要約して返します。
gencase	ケースを離散化して Case.xml と Case.bi4（およびプレビュー用 VTK）を生成し、実際の粒子数を報告します。
run_case	CPU ソルバーをバックグラウンドで起動し（jobs/ ディレクトリ、Run.out、Part_*.bi4）、すぐに job_id を返します。
job_status	ジョブの状態、t／tmax、進捗率、ソルバーの Time/Sec スループットと予測終了時刻、Run.out の末尾を確認します。
partvtk	Part_*.bi4 の出力を ParaView 用の VTK 粒子ファイルに変換します。フィルターと変数はそのまま渡されます。
measure_tool	点の位置で解をサンプリングし、CSV 時系列を取得します（決定的な解析のため、区切り文字にはカンマを強制します）。
validate_dambreak	CSV からダム先端の遡上前線を再構成し、埋め込み済みの Koshizuka & Oka（1996）のデータ系列と照合します。時刻ごとの誤差に加え、MAE／RMSE／最大誤差を返します。

処理の流れ：check_environment → create_case → describe_case → gencase → run_case → job_status をポーリング → partvtk + measure_tool → validate_dambreak。用語、3 つのガード、粒子数推定の計算方法については、docs/case-generation.md を参照してください。

ドメイン契約

ラップされたツールの動作のうち、-h の出力ではわからないもの：

• ドメインボックスの外側にあるジオメトリは、GenCase によって警告なく暗黙にクリップされます（終了コード 0、警告なし）— create_case はすべてのドメインの包含をチェックします。
• DualSPHysics の CSV は、既定で区切り文字にセミコロンを使用します。measure_tool は、呼び出し元が独自の -csvsep を渡さない限り、カンマを強制します。
• MeasureTool の points ファイルでは、先頭の # コメント行は使用できません。MeasureTool のエラーは stderr ではなくstdoutに出力されます。
• Run.out の Time/Sec は、シミュレーション時間 1 秒あたりの実時間（秒）です。steps/second ではありません。行末はソルバーの予測終了時刻です。
• Run.out の行形式はソルバー v5.0/v5.2 と v5.4 で異なります。パーサーは両方に対応しています。

（形式、終了コードを含む）14 項目すべての契約：docs/domain-contracts.md。

インストール

Python 3.10 以降。バイナリは DSPH_* 環境変数、PATH、または標準的なインストール先（/opt、/usr/local、~/softwares、~、cwd → <root>/DualSPHysics*/bin/linux）から検出されます。

uv sync                 # or: python -m venv .venv && .venv/bin/pip install -e .

ソルバーの入手方法（GitHub リポジトリには GenCase / PartVTK / MeasureTool のビルド済みバイナリが含まれますが、ソルバーは含まれていません）：

1. https://dual.sphysics.org/downloads/ から完全パッケージを入手する、または
2. git clone https://github.com/DualSPHysics/DualSPHysics を実行して make -f Makefile_cpu で CPU ソルバーをビルドし（g++ のみで、CUDA は不要）、bin/linux/ のビルド済みツールをコピーします。

環境変数で設定します（.env の解析は行いません。.env.example を参照してください。同じパスは examples/mcp_config.example.json にも記載されています）。

DSPH_GENCASE=/home/<user>/softwares/DualSPHysics/bin/linux/GenCase_linux64
DSPH_SOLVER=/home/<user>/softwares/DualSPHysics/bin/linux/DualSPHysics5.4CPU_linux64
DSPH_PARTVTK=/home/<user>/softwares/DualSPHysics/bin/linux/PartVTK_linux64
DSPH_MEASURETOOL=/home/<user>/softwares/DualSPHysics/bin/linux/MeasureTool_linux64
DSPH_JOBS_DIR=/abs/path/to/jobs     # optional, default ./jobs
DSPH_OMP_THREADS=8                  # optional, default all cores

実行

.venv/bin/python mcp_server.py    # hub-style entry point (stdio)
.venv/bin/dualsphysics-mcp        # console script
uvx dualsphysics-mcp              # published on PyPI

クライアント登録テンプレート：examples/mcp_config.example.json：

{ "mcpServers": { "dualsphysics-mcp": { "command": "uvx", "args": ["dualsphysics-mcp"] } } }

claude mcp add dualsphysics-mcp -- /abs/repo/path/.venv/bin/python /abs/repo/path/mcp_server.py

例：2D ダムブレーク検証（Koshizuka & Oka 1996）

examples/dambreak_val2d/ にサンプル一式があります。公式の検証レイアウト（dp = 0.01 m、4 m × 3 m の水槽内に 1 m × 2 m の水柱、TimeMax = 2 s、TimeOut = 0.01 s、Verlet / Wendland / 人工粘性 0.02 / Fourtakas DDT 0.1）、gen_dambreak_val2d.py（MIT）で再生成したケース、サージ先端の MeasureTool points ファイル（z = 0.03 m に沿った 401 点）、デジタイズした実験データが含まれています。

このケースの測定値（GenCase v5.4.354 / solver v5.4.355、CPU 8 スレッド、i5-10210U）：

量	値
粒子の合計数	21,001（流体 20,000 + 境界 1,001）
Part ファイル数	201（Part_0000 … Part_0200）
ソルバーの実時間（TimeMax = 2 s）	約 14 分
実験値に対するダム先端の MAE（0.09–0.75 s）	0.220 m（水柱の 22.0 %）、RMSE 0.240 m
初期崩壊時のダム先端誤差（t ≤ 0.2 s）	±0.01–0.16 m の範囲内
壁面への衝突	t ≈ 0.67 s に前面が 3.98 m で停止

残差は測定上のアーティファクトではなく、SPH の物理特性によるものです。先端抽出はソルバー独自の SWL ゲージを追跡しており（平均偏差 8 mm、点間隔 10 mm 未満）、実験データは X/a ≈ 4.13（4 m の水槽の外側）で終わるため、壁面への衝突後は比較値が飽和します（validate_dambreak は impact_time_s を記録します）。

エージェントのトランスクリプト：

check_environment()                                  # all four tools found
gencase("examples/dambreak_val2d/CaseDambreakVal2D_Def.xml")
  -> particle_counts: total=21001 fluid=20000 bound=1001
run_case("<out>/CaseDambreakVal2D")                  # returns job_id
job_status(job_id)                                   # poll until percent=100
partvtk(job_id=job_id)                               # 201 fluid VTK files
measure_tool(job_id=job_id, points_file="examples/dambreak_val2d/points_damtip.txt")
validate_dambreak(csv_path="<measure csv>", points_file="examples/dambreak_val2d/points_damtip.txt")

validate_dambreak は、時刻ごとの誤差に加え、1 m の水柱に対する割合とメートル単位で MAE / RMSE / 最大誤差を報告します。図は examples/make_validation_figure.py で生成します。examples/render_dambreak.py は同じ実行の Part_*.vtk を MP4 アニメーションに変換します（開発用依存関係が必要です）。

テスト

uv run pytest -q          # or: .venv/bin/python -m pytest
uv run ruff check .

ソルバーをインストールしていなくても、テストスイートはすべて成功します（検出、コマンド構築、ログフィクスチャの解析、検証計算、ケース生成、stdio のエンドツーエンドテスト）。solver マーク付きテストは、実際のローカルツールチェーンを使用し、利用できない場合は自動的にスキップされます。

内容

• src/dualsphysics_mcp/ — MCP サーバー、ツールの検出と設定、エラーコード、tools/ 内の 10 個のツール。
• examples/ — 検証ケース、create_case_demo.py、図とアニメーションのスクリプト、クライアントテンプレート。
• tests/ — pytest テストスイート（ソルバーのテストは自動的にスキップされます）。

リポジトリのルール

• コミットするもの：ソースコード、テスト、サンプル、ドキュメント、テンプレート。
• コミットしないもの：DualSPHysics のバイナリまたはソースコード（LGPL の成果物は含めません）、仮想環境、.env、ジョブの出力、生成された結果。
• examples/dambreak_val2d/ の実験値は、DualSPHysics のサンプルに同梱された Koshizuka & Oka（1996）の出典に基づき、デジタル化した値です。生成されるケース XML とここにあるすべてのコードは、オリジナルの MIT コンテンツです。詳細は CONTRIBUTING.md をご覧ください。