DualSPHysics MCP

Servidor MCP DualSPHysics

Idioma: Inglês | 中文

Projete, execute e verifique simulações DualSPHysics a partir de um agente de IA — não apenas observe-as.

Dez ferramentas do Model Context Protocol envolvem um fluxo de trabalho SPH local do DualSPHysics de ponta a ponta: projete casos como parâmetros estruturados (sem XML escrito à mão, sem necessidade de solver para iterar), execute-os como trabalhos de CPU em segundo plano com progresso, vazão e o próprio ETA do solver disponíveis, pós-processe em VTK pronto para ParaView e séries temporais em CSV, e verifique um rompimento de barragem 2D contra o experimento de Koshizuka & Oka (1996) com erros por tempo e MAE / RMSE / máximo.

O servidor apenas lança as ferramentas de linha de comando do DualSPHysics como subprocessos; o próprio DualSPHysics não é distribuído aqui — é um software livre LGPL-2.1-ou-superior, este pacote não vincula nem redistribui seu código ou binários, portanto a licença MIT não impõe obrigações adicionais. Se você publicar trabalhos usando DualSPHysics, cite Dominguez et al. (2022), Computational Particle Mechanics 9:867–895, doi:10.1007/s40571-021-00404-2.

Ferramentas

Ferramenta	O que faz
check_environment	Encontra as quatro ferramentas DualSPHysics nesta máquina: caminho resolvido, proveniência (variável de ambiente, PATH, varredura), versão, flags de recursos do solver; dicas de instalação quando uma estiver ausente.
create_case	Descreve um experimento de rompimento de barragem 2D em parâmetros simples e obtém um *_Def.xml do GenCase de volta — sem XML à mão, sem necessidade de solver. Retorna uma estimativa de contagem de partículas para autoverificação.
edit_case	Altera parâmetros de um caso existente (no local ou para um save_path), revalidando o resultado mesclado.
describe_case	Lê um arquivo de caso de volta como um resumo: dp, domínio, coluna/tanque/obstáculo, temporização, medidores, estimativa de partículas.
gencase	Discretiza o caso em Case.xml + Case.bi4 (mais VTK de pré-visualização) e relata as contagens reais de partículas.
run_case	Inicia o solver de CPU em segundo plano (diretório jobs/, Run.out, Part_*.bi4) e retorna um job_id imediatamente.
job_status	Consulta um trabalho: estado, t/tmax, percentual, a vazão Time/Sec do solver e término projetado, cauda do Run.out.
partvtk	Converte a saída do Part_*.bi4 em arquivos de partículas VTK para ParaView; filtros e variáveis passam adiante.
measure_tool	Sonda a solução em pontos e obtém séries temporais CSV de volta (separador de vírgula imposto para análise determinística).
validate_dambreak	Reconstrói a frente de onda da ponta da barragem a partir do CSV e a avalia contra a série incorporada de Koshizuka & Oka (1996): erros por tempo + MAE/RMSE/máximo.

Cadeia de trabalho: check_environment → create_case → describe_case → gencase → run_case → consultar job_status → partvtk + measure_tool → validate_dambreak. Vocabulário, três proteções e aritmética de estimativa de partículas: docs/case-generation.md.

Contratos de domínio

Comportamentos das ferramentas envolvidas que sua saída -h não informa:

• Geometria fora da caixa do domínio é silenciosamente recortada pelo GenCase (saída 0, sem aviso) — create_case verifica a contenção de cada domínio.
• CSVs do DualSPHysics usam por padrão separadores de ponto e vírgula; measure_tool força vírgulas a menos que o chamador passe seu próprio -csvsep.
• Arquivos de pontos do MeasureTool rejeitam linhas de comentário # iniciais; erros do MeasureTool são impressos em stdout, não em stderr.
• Time/Sec em Run.out é tempo de relógio em segundos por segundo simulado — não passos/segundo; a cauda da linha é o término projetado do solver.
• Formatos de linha do Run.out diferem entre solver v5.0/v5.2 e v5.4; o analisador lida com ambos.

Todos os quatorze contratos (formatos, códigos de saída): docs/domain-contracts.md.

Instalação

Python 3.10+. Os binários são descobertos a partir de variáveis de ambiente DSPH_*, PATH ou raízes de instalação convencionais (/opt, /usr/local, ~/softwares, ~, cwd → <root>/DualSPHysics*/bin/linux).

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

Obtendo o solver (o repositório GitHub envia GenCase / PartVTK / MeasureTool pré-compilados, mas não o solver):

1. Pacote completo de https://dual.sphysics.org/downloads/, ou
2. git clone https://github.com/DualSPHysics/DualSPHysics e compile o solver de CPU com make -f Makefile_cpu (apenas g++, sem necessidade de CUDA), depois copie as ferramentas pré-compiladas de bin/linux/.

Configure por meio de variáveis de ambiente (sem análise de .env; veja .env.example — os mesmos caminhos aparecem em 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

Execução

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

Modelos 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

Exemplo: validação de rompimento de barragem 2D (Koshizuka & Oka 1996)

examples/dambreak_val2d/ contém o caso de demonstração: o layout oficial de validação (dp = 0,01 m; coluna de água de 1 m × 2 m em um tanque de 4 m × 3 m; TimeMax = 2 s, TimeOut = 0,01 s; Verlet / Wendland / viscosidade artificial 0,02 / Fourtakas DDT 0,1), regenerado por gen_dambreak_val2d.py (MIT), um arquivo de pontos MeasureTool da frente de onda (401 pontos ao longo de z = 0,03 m) e o experimento digitalizado.

Medido neste caso (GenCase v5.4.354 / solver v5.4.355, 8 threads de CPU, i5-10210U):

Quantidade	Valor
Partículas totais	21.001 (fluido 20.000 + limite 1.001)
Arquivos de partes	201 (Part_0000 … Part_0200)
Tempo de relógio do solver (TimeMax = 2 s)	≈ 14 min
MAE da ponta da barragem vs experimento (0,09–0,75 s)	0,220 m (22,0 % da coluna); RMSE 0,240 m
Erro da ponta da barragem, colapso inicial (t ≤ 0,2 s)	dentro de ±0,01–0,16 m
Impacto na parede	frente fixada em 3,98 m em t ≈ 0,67 s

O resíduo é física SPH, não um artefato de medição: a extração da frente rastreia o medidor SWL do próprio solver (desvio médio de 8 mm < espaçamento de pontos de 10 mm), e o experimento termina em X/a ≈ 4,13 — além do tanque de 4 m — portanto a comparação satura após o impacto na parede (validate_dambreak observa impact_time_s).

Transcrição do 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 relata erros por tempo mais MAE / RMSE / máximo em metros e como % da coluna de 1 m. A figura vem de examples/make_validation_figure.py; examples/render_dambreak.py transforma o Part_*.vtk da mesma execução em uma animação MP4 (dependências de desenvolvimento).

Testes

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

A suíte está verde sem qualquer solver instalado (descoberta, construção de comandos, análise de fixtures de log, matemática de validação, geração de casos, stdio de ponta a ponta). Testes marcados como solver exercitam um fluxo de trabalho local real e são pulados automaticamente caso contrário.

Conteúdo

• src/dualsphysics_mcp/ — servidor MCP, descoberta e configuração de ferramentas, códigos de erro, as dez ferramentas em tools/.
• examples/ — caso de validação, create_case_demo.py, scripts de figura + animação, modelo de cliente.
• tests/ — suíte pytest (testes de solver pulam automaticamente).

Regras do repositório

• Comprometidos: fonte, testes, exemplos, documentação, modelos.
• Não comprometidos: binários ou fontes do DualSPHysics (trabalho LGPL permanece fora), ambientes virtuais, .env, saídas de trabalhos e resultados gerados.
• Valores experimentais em examples/dambreak_val2d/ são fatos digitalizados citados a Koshizuka & Oka (1996) conforme enviados com os exemplos do DualSPHysics; o XML de caso gerado e todo o código aqui são conteúdo MIT original — detalhes em CONTRIBUTING.md.