DualSPHysics MCP

DualSPHysics MCP

语言： 英语 | 中文

通过 AI Agent 设计、运行并验证 DualSPHysics 仿真——而不只是看着仿真运行。

十个 模型上下文协议 工具端到端封装本地 DualSPHysics SPH 工具链：使用结构化参数设计案例（无需手写 XML，无需求解器即可迭代），将其作为后台 CPU 任务运行，并随时查看进度、吞吐量和求解器自身的预计完成时间；后处理生成可供 ParaView 使用的 VTK 和 CSV 时间序列；并使用逐时误差及 MAE / RMSE / 最大值，将 2D 溃坝与 Koshizuka & Oka（1996）实验进行验证。

该服务仅将 DualSPHysics 命令行工具作为子进程启动；此处不分发 DualSPHysics 本身——它是免费的 LGPL-2.1-or-later 软件。本软件包既不链接也不重新分发其代码或二进制文件，因此 MIT 许可证不附带任何额外义务。如果你发布了使用 DualSPHysics 的作品，请引用 Dominguez 等人（2022），Computational Particle Mechanics 9:867–895，doi:10.1007/s40571-021-00404-2。

工具

工具	功能
check_environment	查找此计算机上的四个 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。术语、三项保护措施和粒子数量估算算法：docs/case-generation.md。

领域约定

封装工具的一些行为，其 -h 输出不会告知你：

• GenCase 会静默裁剪超出计算域边界框的几何体（退出码为 0，不会发出警告）——create_case 会检查每个计算域是否包含相应几何体。
• DualSPHysics CSV 文件默认使用分号分隔符；measure_tool 会强制使用逗号，除非调用方传入自己的 -csvsep。
• MeasureTool 的点文件不接受以 # 开头的注释行；MeasureTool 的错误会输出到标准输出，而非标准错误。
• Run.out 中的 Time/Sec 表示每模拟秒所耗费的实际秒数，并非每秒步数；行末是求解器预计的完成时间。
• Run.out 的行格式在求解器 v5.0/v5.2 和 v5.4 之间有所不同；解析器兼容这两种格式。

全部十四项约定（格式、退出码）：docs/domain-contracts.md。

安装

Python 3.10+。程序会从 DSPH_* 环境变量、PATH 或常见安装根目录（/opt、/usr/local、~/softwares、~、当前工作目录 → <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

示例：二维溃坝验证（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 / artificial viscosity 0.02 / Fourtakas DDT 0.1），由 gen_dambreak_val2d.py（MIT）重新生成；还包含一个涌浪前沿 MeasureTool 点文件（沿 z = 0.03 m 设置 401 个点）以及数字化实验数据。

此案例的测量结果（GenCase v5.4.354 / solver v5.4.355，8 个 CPU 线程，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）。

Agent 对话记录：

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/ 中的十个工具。
• examples/ — 验证案例、create_case_demo.py、图表和动画脚本、客户端模板。
• tests/ — pytest 测试套件（求解器测试会自动跳过）。

仓库规则

• 纳入版本控制：源代码、测试、示例、文档、模板。
• 不纳入版本控制：DualSPHysics 二进制文件或源代码（LGPL 相关内容不纳入）， 虚拟环境、.env、作业输出和生成的结果。
• examples/dambreak_val2d/ 中的实验值是数字化事实，引用自随 DualSPHysics 示例一同提供的 Koshizuka & Oka（1996）；生成的案例 XML 和此处的所有代码均为原创 MIT 内容——详情见 CONTRIBUTING.md。