DualSPHysics MCP

Ejecuta y valida simulaciones de fluidos SPH de DualSPHysics desde tu agente: preparación de casos, resoluciones en segundo plano con progreso en vivo, postprocesamiento de VTK/CSV y validación de rotura de presa contra el experimento de 1996.

GitHub

Documentación

Servidor MCP DualSPHysics

Idioma: English | 中文

Diseña, ejecuta y verifica simulaciones DualSPHysics desde un agente de IA — no solo las observes.

Diez herramientas del Model Context Protocol envuelven una cadena de herramientas SPH local de DualSPHysics de principio a fin: diseña casos como parámetros estructurados (sin XML escrito a mano, sin necesidad de solucionador para iterar), ejecútalos como trabajos CPU en segundo plano con progreso, rendimiento y el propio ETA del solucionador a mano, post-procesa en VTK listo para ParaView y series temporales CSV, y verifica una rotura de presa 2D contra el experimento de Koshizuka & Oka (1996) con errores por tiempo y MAE / RMSE / máx.

El servidor solo lanza las herramientas de línea de comandos de DualSPHysics como subprocesos; DualSPHysics en sí no se distribuye aquí — es software libre LGPL-2.1-o-posterior, este paquete no enlaza ni redistribuye su código o binarios, por lo que la licencia MIT no conlleva obligaciones adicionales. Si publicas trabajo que use DualSPHysics, cita Dominguez et al. (2022), Computational Particle Mechanics 9:867–895, doi:10.1007/s40571-021-00404-2.

Herramientas

Herramienta	Qué hace
`check_environment`	Encuentra las cuatro herramientas de DualSPHysics en esta máquina: ruta resuelta, procedencia (variable de entorno, PATH, escaneo), versión, indicadores de características del solucionador; sugerencias de instalación cuando falta alguna.
`create_case`	Describe un experimento de rotura de presa 2D en parámetros simples y obtén un `*_Def.xml` de GenCase de vuelta — sin XML a mano, sin necesidad de solucionador. Devuelve una estimación del conteo de partículas para autoverificación.
`edit_case`	Cambia parámetros de un caso existente (en su lugar o a un `save_path`), revalidando el resultado fusionado.
`describe_case`	Lee un archivo de caso de vuelta como resumen: dp, dominio, columna/tanque/obstáculo, temporización, medidores, estimación de partículas.
`gencase`	Discretiza el caso en `Case.xml` + `Case.bi4` (más VTK de vista previa) e informa los conteos reales de partículas.
`run_case`	Inicia el solucionador CPU en segundo plano (directorio jobs/, `Run.out`, `Part_*.bi4`) y devuelve un `job_id` inmediatamente.
`job_status`	Consulta un trabajo: estado, `t`/`tmax`, porcentaje, el rendimiento `Time/Sec` del solucionador y finalización proyectada, cola de `Run.out`.
`partvtk`	Convierte la salida de `Part_*.bi4` en archivos de partículas VTK para ParaView; filtros y variables pasan a través.
`measure_tool`	Sondea la solución en puntos y obtén series temporales CSV de vuelta (separador de coma forzado para análisis determinista).
`validate_dambreak`	Reconstruye el frente de oleaje de la punta de la presa desde el CSV y evalúalo contra la serie embebida de Koshizuka & Oka (1996): errores por tiempo + MAE/RMSE/máx.

Cadena de trabajo: check_environment → create_case → describe_case → gencase → run_case → consulta job_status → partvtk + measure_tool → validate_dambreak. Vocabulario, tres salvaguardas y aritmética de estimación de partículas: docs/case-generation.md.

Contratos de dominio

Comportamientos de las herramientas envueltas que su salida -h no te dice:

La geometría fuera de la caja del dominio es recortada silenciosamente por GenCase (salida 0, sin advertencia) — create_case verifica la contención de cada dominio.
Los CSV de DualSPHysics usan por defecto separadores de punto y coma; measure_tool fuerza comas a menos que el llamador pase su propio -csvsep.
Los archivos de puntos de MeasureTool rechazan líneas de comentario # al inicio; los errores de MeasureTool se imprimen en stdout, no en stderr.
Time/Sec en Run.out son segundos de reloj de pared por segundo simulado — no pasos/segundo; la cola de la fila es la finalización proyectada del solucionador.
Los formatos de fila de Run.out difieren entre solucionador v5.0/v5.2 y v5.4; el analizador maneja ambos.

Los catorce contratos (formatos, códigos de salida): docs/domain-contracts.md.

Instalación

Python 3.10+. Los binarios se descubren desde variables de entorno DSPH_*, PATH, o raíces de instalación convencionales (/opt, /usr/local, ~/softwares, ~, cwd → <root>/DualSPHysics*/bin/linux).

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

Obtener el solucionador (el repositorio de GitHub incluye GenCase / PartVTK / MeasureTool precompilados pero no el solucionador):

Paquete completo desde https://dual.sphysics.org/downloads/, o
git clone https://github.com/DualSPHysics/DualSPHysics y compila el solucionador CPU con make -f Makefile_cpu (solo g++, sin necesidad de CUDA), luego copia las herramientas precompiladas desde bin/linux/.

Configura a través de variables de entorno (sin análisis de .env; ver .env.example — las mismas rutas aparecen en 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

Ejecución

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

Plantillas de registro de cliente: 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

Ejemplo: validación de rotura de presa 2D (Koshizuka & Oka 1996)

examples/dambreak_val2d/ contiene la demostración: el diseño oficial de validación (dp = 0.01 m; columna de agua de 1 m × 2 m en un tanque de 4 m × 3 m; TimeMax = 2 s, TimeOut = 0.01 s; Verlet / Wendland / viscosidad artificial 0.02 / Fourtakas DDT 0.1), regenerado por gen_dambreak_val2d.py (MIT), un archivo de puntos de MeasureTool del frente de oleaje (401 puntos a lo largo de z = 0.03 m), y el experimento digitalizado.

Medido en este caso (GenCase v5.4.354 / solucionador v5.4.355, 8 hilos CPU, i5-10210U):

Cantidad	Valor
Partículas totales	21,001 (fluido 20,000 + límite 1,001)
Archivos de partes	201 (`Part_0000` … `Part_0200`)
Tiempo de reloj del solucionador (TimeMax = 2 s)	≈ 14 min
MAE de la punta de la presa vs experimento (0.09–0.75 s)	0.220 m (22.0 % de la columna); RMSE 0.240 m
Error de la punta de la presa, colapso temprano (t ≤ 0.2 s)	dentro de ±0.01–0.16 m
Impacto en la pared	frente fijado en 3.98 m en t ≈ 0.67 s

Simulated surge front vs the 1996 experiment

El residual es física SPH, no un artefacto de medición: la extracción del frente rastrea el medidor de nivel de agua propio del solucionador (desviación media de 8 mm < espaciado de puntos de 10 mm), y el experimento termina en X/a ≈ 4.13 — más allá del tanque de 4 m — por lo que la comparación se satura después del impacto en la pared (validate_dambreak nota impact_time_s).

Transcripción del agente:

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 informa errores por tiempo más MAE / RMSE / máx en metros y como % de la columna de 1 m. La figura proviene de examples/make_validation_figure.py; examples/render_dambreak.py convierte el Part_*.vtk de la misma ejecución en una animación MP4 (dependencias de desarrollo).

Pruebas

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

La suite está en verde sin ningún solucionador instalado (descubrimiento, construcción de comandos, análisis de fixtures de registro, matemática de validación, generación de casos, extremo a extremo stdio). Las pruebas marcadas solver ejercitan una cadena de herramientas local real y se omiten automáticamente en caso contrario.

Contenidos

src/dualsphysics_mcp/ — servidor MCP, descubrimiento y configuración de herramientas, códigos de error, las diez herramientas en tools/.
examples/ — caso de validación, create_case_demo.py, scripts de figura + animación, plantilla de cliente.
tests/ — suite pytest (las pruebas del solucionador se omiten automáticamente).

Reglas del repositorio

Comprometido: fuente, pruebas, ejemplos, documentación, plantillas.
No comprometido: binarios o fuentes de DualSPHysics (el trabajo LGPL queda fuera), entornos virtuales, .env, salidas de trabajos y resultados generados.
Los valores experimentales en examples/dambreak_val2d/ son hechos digitalizados citados a Koshizuka & Oka (1996) tal como se envían con los ejemplos de DualSPHysics; el XML de caso generado y todo el código aquí son contenido MIT original — detalles en CONTRIBUTING.md.