DualSPHysics MCP

DualSPHysics MCP

Language: English | 中文

[Listed on mcpservers.org] [vegetableno1/DualSPHysics-mcp MCP server] [CI]

Design, run, and verify DualSPHysics simulations from an AI agent — not just stare at them.

Ten Model Context Protocol tools wrap a local DualSPHysics SPH toolchain end to end: design cases as structured parameters (no hand-written XML, no solver needed to iterate), run them as background CPU jobs with progress, throughput and the solver's own ETA on tap, post-process into ParaView-ready VTK and CSV time series, and verify a 2D dam-break against the Koshizuka & Oka (1996) experiment with per-time errors and MAE / RMSE / max.

The server only launches the DualSPHysics command-line tools as subprocesses; DualSPHysics itself is not distributed here — it is free LGPL-2.1-or-later software, this package neither links nor redistributes its code or binaries, so the MIT licence carries no extra obligations. If you publish work using DualSPHysics, cite Dominguez et al. (2022), Computational Particle Mechanics 9:867–895, doi:10.1007/s40571-021-00404-2.

Tools

Working chain: check_environment → create_case → describe_case → gencase → run_case → poll job_status → partvtk + measure_tool → validate_dambreak. Vocabulary, three guards and particle-estimate arithmetic: docs/case-generation.md.

Domain contracts

Behaviours of the wrapped tools that their -h output does not tell you:

• Geometry outside the domain box is silently clipped by GenCase (exit 0, no warning) — create_case containment-checks every domain.
• DualSPHysics CSVs default to semicolon separators; measure_tool forces commas unless the caller passes their own -csvsep.
• MeasureTool points files reject leading # comment lines; MeasureTool errors print on stdout, not stderr.
• Time/Sec in Run.out is wall-clock seconds per simulated second — not steps/second; the row tail is the solver's projected finish.
• Run.out row formats differ between solver v5.0/v5.2 and v5.4; the parser handles both.

All fourteen contracts (formats, exit codes): docs/domain-contracts.md.

Install

Python 3.10+. The binaries are discovered from DSPH_* environment variables, PATH, or conventional install roots (/opt, /usr/local, ~/softwares, ~, cwd → <root>/DualSPHysics*/bin/linux).

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

Getting the solver (the GitHub repository ships GenCase / PartVTK / MeasureTool prebuilt but not the solver):

1. Full package from https://dual.sphysics.org/downloads/, or
2. git clone https://github.com/DualSPHysics/DualSPHysics and build the CPU solver with make -f Makefile_cpu (g++ only, no CUDA needed), then copy the prebuilt tools from bin/linux/.

Configure through environment variables (no .env parsing; see .env.example — the same paths appear in examples/mcp_config.example.json):

DSPH_GENCASE=/home/<user>/softwares/DualSPHysics/bin/linux/GenCase_linux64DSPH_SOLVER=/home/<user>/softwares/DualSPHysics/bin/linux/DualSPHysics5.4CPU_linux64DSPH_PARTVTK=/home/<user>/softwares/DualSPHysics/bin/linux/PartVTK_linux64DSPH_MEASURETOOL=/home/<user>/softwares/DualSPHysics/bin/linux/MeasureTool_linux64DSPH_JOBS_DIR=/abs/path/to/jobs     # optional, default ./jobsDSPH_OMP_THREADS=8                  # optional, default all cores

Run

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

Client registration templates: 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

Example: 2D dam-break validation (Koshizuka & Oka 1996)

examples/dambreak_val2d/ holds the showcase: the official validation layout (dp = 0.01 m; 1 m × 2 m water column in a 4 m × 3 m tank; TimeMax = 2 s, TimeOut = 0.01 s; Verlet / Wendland / artificial viscosity 0.02 / Fourtakas DDT 0.1), regenerated by gen_dambreak_val2d.py (MIT), a surge-front MeasureTool points file (401 points along z = 0.03 m), and the digitised experiment.

Measured on this case (GenCase v5.4.354 / solver v5.4.355, 8 CPU threads, i5-10210U):

[Simulated surge front vs the 1996 experiment]

The residual is SPH physics, not a measurement artefact: the front extraction tracks the solver's own SWL gauge (mean deviation 8 mm < 10 mm point spacing), and the experiment ends at X/a ≈ 4.13 — beyond the 4 m tank — so the comparison saturates after wall impact (validate_dambreak notes impact_time_s).

Agent transcript:

check_environment()                                  # all four tools foundgencase("examples/dambreak_val2d/CaseDambreakVal2D_Def.xml")  -> particle_counts: total=21001 fluid=20000 bound=1001run_case("<out>/CaseDambreakVal2D")                  # returns job_idjob_status(job_id)                                   # poll until percent=100partvtk(job_id=job_id)                               # 201 fluid VTK filesmeasure_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 reports per-time errors plus MAE / RMSE / max in metres and as % of the 1 m column. The figure comes from examples/make_validation_figure.py; examples/render_dambreak.py turns the same run's Part_*.vtk into an MP4 animation (dev dependencies).

Tests

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

The suite is green without any solver installed (discovery, command construction, log-fixture parsing, validation math, case generation, stdio end-to-end). Tests marked solver exercise a real local toolchain and auto-skip otherwise.

Contents

• src/dualsphysics_mcp/ — MCP server, tool discovery and config, error codes, the ten tools in tools/.
• examples/ — validation case, create_case_demo.py, figure + animation scripts, client template.
• tests/ — pytest suite (solver tests auto-skip).

Repository rules

• Committed: source, tests, examples, documentation, templates.
• Not committed: DualSPHysics binaries or sources (LGPL work stays out), virtual environments, .env, job outputs and generated results.
• Experiment values in examples/dambreak_val2d/ are digitised facts cited to Koshizuka & Oka (1996) as shipped with the DualSPHysics examples; the generated case XML and all code here are original MIT content — details in CONTRIBUTING.md.