Natural-language-driven CAE pipeline for DeepSeek Harness: the agent takes a plain-language simulation request and drives a complete CAD → mesh → solve → post-process chain over build123d, Gmsh, CalculiX, OpenFOAM, and PyVista.
Five tools cover the chain end to end — geometry (scripted construction or external STEP import with validation/healing), solid and fluid meshing behind one mode switch, linear static solving plus steady or transient incompressible CFD behind another, result extraction/plotting, and automated mesh-independence verification — with receipts (paths, volumes, mesh quality, field extremes) fed back to the model after every stage.
Install
Recommended (Docker): install Docker, add the plugin, and point python at the prebuilt image — no conda, no apt CalculiX, no OpenFOAM install. The image is pulled automatically on first use (~3–4 GB):
python: docker://ghcr.io/daiyuhangsustc/dsh-cae:latest
Local interpreter (no Docker): the routes below.
Python stack first: pip install build123d gmsh pyvista ccx2paraview, plus a CalculiX solver — sudo apt install calculix-ccx on Debian/Ubuntu or conda install -c conda-forge calculix elsewhere (the ccx binary must be on PATH).
For the CFD modes, OpenFOAM (Foundation v11–13 or ESI) must be installed; its etc/bashrc is auto-detected ($FOAM_BASHRC, /opt/openfoam*, /usr/lib/openfoam*) or set via openfoamBashrc.
Then load the plugin into a profile — run dsh from a DeepSeek Harness checkout:
- Local checkout (plugin development):
dsh plugin --profile web add /path/to/dsh-cae — installs as a link: dependency; after changing the plugin, pnpm build and restart the surface to pick it up.
- Direct git checkout:
dsh plugin --profile web add https://github.com/DaiYuhangSustc/dsh-cae-plugin.git (git installs run the prepare build script; pnpm users may need to allow it via allowBuilds).
- npm registry (once published):
dsh plugin --profile web add dsh-cae.
Each profile holds its own plugin list — repeat the add for every profile you use (e.g. headless).
Launch and use
- Browser:
dsh web boots the web UI on http://127.0.0.1:3080 (--port to change; it opens the default browser automatically) — paste a plain-language request and watch the tool calls and receipts stream.
- Terminal:
dsh --profile headless "20×20 mm square duct, 1 m long, water at 0.02 m/s inlet — steady laminar solve and a pressure contour" runs one task headlessly and prints the transcript.
A surface started before the plugin was added cannot see it — restart the surface after add (or after a rebuild, for link: installs).
Try it
See examples/cantilever.md: a single Chinese sentence produces a fixed-end cantilever under tip load via cae_geometry → cae_mesh → cae_solve → cae_post, with a von Mises contour and a cae_verify mesh-independence check.
And examples/duct-flow.md: one Chinese sentence produces a laminar duct-flow solution (cae_mesh fluid mode → cae_solve steady mode → cae_post) validated against the Shah–London friction constant.
The five tools
| Tool | Modes | Input | Output |
|---|
cae_geometry | mode: 'build' | 'import' | build: build123d script (defines part, optional NAMED_FACES) + name; import: external .step path (+ optional repair, nameFaces face naming) | build: .step path, volume, bounding box, named faces with areas/centroids; import: validated/healed .step path, face table (areas/centroids/normals) for BC anchors, optional faces.json sidecar |
cae_mesh | mode: 'solid' | 'fluid' | solid: .step path, elementSizeMm, elementType (tet4/tet10); fluid: duct lengthMm/widthMm/heightMm/cellSizeMm (+ wallGrading, full blockMeshDict text, name) | solid: .msh path, node/element counts, named groups, minimum scaled Jacobian; fluid: caseDir (SI bounds, cell count, checkMesh quality, checksPassed) |
cae_solve | mode: 'static' | 'steady' | 'transient' | static: .msh path, material (youngMPa, poisson), constraints/loads on named groups; steady/transient: caseDir, inletVelocityMS, kinematicViscosityM2S, densityKgM3, dict overrides (+ transient time controls endTimeS/writeIntervalS/maxCourant/deltaTS) | static: .frd/.vtu paths, exitCode, log tail; steady: converged + final residuals, VTK path; transient: time-step history, max Courant seen, VTK path |
cae_post | — | .vtu/.vtk/.frd path, maxima/probes/ queries (+ for CFD pressure) |
cae_solve mode='steady' vs mode='transient': steady is the default recommendation for internal-flow requests; the transient branch (Euler/PIMPLE, Courant-limited adaptive step) is for genuinely time-dependent physics — the steady-vs-transient trade-off is spelled out in the tool description for the agent to recommend and the user to decide.
Migrating from v0.4
v0.5.0 is a breaking release: the nine v0.4 tool names are gone, and so are the v0.4 verify tool's flat boundary-condition shapes (a list of constrained group names; force vectors keyed by group). Boundary conditions are canonical everywhere — constraints: [{groupName, kind: 'fixed'}] and loads: [{groupName, vectorN: [fx, fy, fz]}] — used by cae_solve (mode='static') and cae_verify (chain='structural').
Every v0.4 tool maps onto one of the five v0.5 tools plus a mode/chain switch: the two geometry tools became cae_geometry (mode='build' scripted construction, mode='import' external STEP import); the solid mesher and the duct mesher became cae_mesh (mode='solid' / mode='fluid'); the structural solver and the two CFD solvers became cae_solve (mode='static' / 'steady' / 'transient'); the post-processor became cae_post; and the mesh-independence study became cae_verify (chain='structural' / 'cfd'). The v0.4 names and schemas remain available in the git history (the pre-refactor tree at commit 01fad90, where origin/master also sits).
Six-stage workflow mapping
The plugin covers the classic CFD/CAE six-stage workflow; stages 1–5 are automated, stage 6 is deliberately human.
| Fluent stage | dsh-cae coverage |
|---|
| 1 Pre-processing | cae_geometry (build script geometry · import external STEP: validate/heal/name faces) · cae_mesh (solid Gmsh tetrahedra · fluid blockMesh duct) |
| 2 Solver setup | parameters of cae_solve (materials, BCs, ν); steady vs transient is a recommendation the agent makes, the user decides |
| 3 Solution | cae_solve — static (CalculiX) · steady / transient (foamRun) |
| 4 Post-processing | cae_post (PyVista) |
| 5 Verification | cae_verify (mesh independence, Richardson + GCI); convergence receipts on every solve |
| 6 Validation | deliberately human — the plugin provides the numbers and plots, the engineer compares against reality |
Architecture
Five tools map onto five Python packages: src/tools/{geometry,mesh,solve,post,verify}.ts ↔ python/dsh_cae/{geometry,mesh,solve,post,verify} (+ python/dsh_cae/shared for receipt emission, the dependency self-check, and OpenFOAM case assembly). The TS layer owns orchestration only; each tool call is a one-shot python -m dsh_cae.<stage> subprocess coupled through argv plus the stdout receipt line after the <<<DSH_CAE_JSON>>> marker — nothing else crosses the boundary. Two contracts are deliberately mirrored on both sides: the override whitelist exists as the file enum of overrides in src/tools/solve.ts (OVERRIDES_PARAM) and as CASE_DICT_FILES in python/dsh_cae/shared/cfd_case.py — change both in one commit — and cae_verify's per-level loop (mesh + solve + post per size) runs in-process inside the single python -m dsh_cae.verify process, which is why its stage timeout is scaled by 3×levels.
Trust boundary
The script parameter is model-generated Python (and batch text) executed locally with trust level equal to the harness's own bash tool; treat it accordingly and use a profile permission layer (tools/pre-execute) for governance.
Units
Millimeters, newtons, megapascals everywhere: geometry in mm, forces in N, stresses in MPa, so deflections come out in mm and Young's modulus is entered as MPa (steel ≈ 210000).
The CFD branch takes geometry in mm at cae_mesh (mode='fluid', converted to m once) and is SI afterwards: m, m/s, Pa, Pa·s; cae_post converts kinematic pressure to Pa when given densityKgM3.
Configuration
| Field | Default | Meaning |
|---|
python | auto | 'auto' probes a conda env named dsh-cae ($CONDA_PREFIX, $CONDA_ENVS_PATH, ~/.conda, ~/miniconda3, ~/anaconda3, ~/mambaforge, /opt/conda), falling back to python3; or set an explicit interpreter path; or docker://<image-ref> to run every stage in a container — recommended image ghcr.io/daiyuhangsustc/dsh-cae (auto-pulled on first use) |
workdir | ./cae | Artifact directory (relative to agent cwd) for STEP/MSH/INP/FRD/VTU/PNG files |
stageTimeoutMs | 600000 | Per-stage wall-clock budget in ms; exceeded kills the stage process group |
openfoamBashrc | auto-detect | OpenFOAM etc/bashrc path; auto-detection checks $FOAM_BASHRC, /opt/openfoam*/etc/bashrc, /usr/lib/openfoam*/etc/bashrc |
Troubleshooting
If import build123d dies with pyexpat ... undefined symbol: XML_SetAllocTrackerActivationThreshold, an inherited LD_LIBRARY_PATH (e.g. OpenFOAM's bashrc listing /usr/lib dirs) is shadowing the interpreter's own newer libexpat. For a conda-style interpreter — python: auto or an explicit env path — the runner already prepends the env's lib to LD_LIBRARY_PATH and its bin to PATH at spawn time; for other layouts force the newer one first yourself: LD_PRELOAD=$CONDA_PREFIX/lib/libexpat.so.1.
Linux servers without a display need EGL or OSMesa for PyVista rendering — conda-forge's vtk ships X-only window classes (no EGL/OSMesa build), so use the pip wheel (pip install 'vtk==9.6.2', which bundles vtkEGLRenderWindow; install libegl1 for the EGL runtime it dlopens) and set PYVISTA_OFF_SCREEN=true with VTK_DEFAULT_OPENGL_WINDOW=vtkEGLRenderWindow; the Docker image does exactly this.
OpenFOAM 11+ (Foundation) replaced standalone solvers: this plugin runs foamRun (solver incompressibleFluid), the simpleFoam successor; ESI releases keep simpleFoam but the invoked names here are Foundation's. foamToVTK writes legacy .vtk, which cae_post reads directly.
Docker route errors are explicit: "Docker is not installed" → install Docker; "daemon is not running" → sudo systemctl start docker (using a rootless/remote daemon via DOCKER_HOST/DOCKER_CONTEXT? Export those in the shell that launches the harness — the runner passes a minimal environment to the docker CLI); "failed to pull" → run the printed docker pull by hand. A stale image behaves like stale dependencies — docker pull ghcr.io/daiyuhangsustc/dsh-cae:latest to refresh. On SELinux-enforcing hosts (Fedora/RHEL) the stage bind mounts may be denied — look at container-selinux if stage logs show permission errors. With python: docker://… leave openfoamBashrc unset: host paths don't exist inside the container, and the image's own OpenFOAM is used automatically.
Limitations
Structural: linear static analysis only, tetrahedral meshes only; CFD: incompressible laminar internal flow only (steady or transient), block-hex meshes only; POSIX only; single-machine.
Roadmap
CAE skill for prompt guidance, background jobs via ctx.jobs, modal/thermal analysis, turbulence (kOmegaSST + y+ treatment), snappyHexMesh/STL geometry, pluggable solver providers.
Contributing
PRs and issues are welcome — a natural-language CAE stack covers a lot of ground, and it needs many hands: more physics, more solvers, better examples and docs.
Development setup (TS side): pnpm install.
Note: @deepseek-ai/dsh-tools is at rc.1 and its runtime import chain pulls dsh-llm/dsh-scope/dsh-session/dsh-timeout; when installed out-of-tree into a profile, resolution normally comes from the in-profile dsh-base.
For a standalone dev checkout, pnpm install needs autoInstallPeers: false (already in pnpm-workspace.yaml) plus the declared extra devDeps — if peers still fail to resolve, install within a dsh profile rather than standalone.
Kernel environment, no sudo required (the route CI-equivalent validation uses locally):
conda create -n dsh-cae -c conda-forge python=3.11 calculix -y
conda run -n dsh-cae python -m ensurepip --upgrade
conda run -n dsh-cae pip install build123d gmsh pyvista ccx2paraview pytest
The env name matters: the default python: auto probes for a conda env named exactly dsh-cae, so this env needs no further configuration.
Run the suite that matches your change:
| Layer | Command | Notes |
|---|
| TS tools / runner | pnpm build && pnpm vitest run | keyless, runs everywhere |
| Python stages | pytest pytest -v | inside the kernel env; the pytest/ directory shadows the pytest package, so the console script is required — never python -m pytest from the repo root |
| Loader composition | DSH_COMPOSITION=1 pnpm vitest run tests/composition.e2e.ts | needs a dsh harness checkout; opt-in, CI does not gate it |
Contracts every change must keep:
- The TS layer owns orchestration only (tool schemas, subprocesses, timeouts, receipts); all domain knowledge lives in
python/dsh_cae/. The layers couple through argv and the stdout receipt line <<<DSH_CAE_JSON>>> — nothing else.
- Solver outcomes are data: a non-zero ccx exit is a normal receipt carrying
exitCode and logTail for the model to diagnose; only infrastructure failures (missing binary, timeout, unparseable output) raise.
- Units are mm/N/MPa everywhere, with no conversion anywhere.
- Some solver realities are encoded deliberately, with comments: Gmsh tet10 mid-edge nodes 9/10 are swapped against Abaqus C3D10 in
solve.py; ccx exits 0 even on a singular (unconstrained) system, so the domain-failure test drives ccx with a *CLOAD on a nonexistent node.
PR expectations: the tests covering your layer are green; kernel tests self-skip without kernels — say so in the PR and let CI run them for real; update README.md and README.zh.md together (the two files mirror each other); conventional commit subjects (feat:, fix:, docs:, test:).
Good first targets are the Roadmap items above: a new analysis type (*FREQUENCY, *HEAT TRANSFER), turbulence and snappyHexMesh extensions on top of the CFD branch, a cae skill teaching the model build123d/INP idioms, and more runnable examples in the style of examples/cantilever.md.
License
MIT
