Running the multi-solver stack¶

📦 v0.1.0 — OpenFOAM (required), XLB (recommended, GPU-only), DoMINO (recommended, needs NGC auth).

This walkthrough brings up the Arxyne stack - the single MCP Gateway plus the OpenFOAM, DoMINO, and XLB solver images - and dispatches an aero workflow against any solver via --solver.

You'll end up able to run, on the same product, in the same session:

arxyne --product drivaer-notchback --aero --solver openfoam   # CPU RANS
arxyne --product drivaer-notchback --aero --solver xlb        # GPU LBM
arxyne --product drivaer-notchback --aero --solver auto       # per-solver flywheel dispatch

Each routes through the same gateway, the same input + output + failure contract trilogy, and writes results to the same USD twin with full provenance.

Prerequisites¶

Python venv with the platform installed: pip install -e ".[dev]" (dev) or pip install arxyne (release).
Docker + NVIDIA Container Toolkit (for the XLB GPU solver). Verify with docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi.
Solver images built locally (see step 2).

1. Pre-flight¶

Run the doctor - it checks Python, USD, Docker, GPU, and which solver images are built:

arxyne --doctor

Anything marked "not built" comes with the exact build command to fix it.

2. Build the solver images¶

Solvers ship as Docker images built from the in-tree solvers/<name>/ directories. Build them once:

arxyne --pull openfoam      # CPU RANS image
arxyne --pull xlb           # GPU LBM image (~8 GB; pulls NVIDIA JAX base)
arxyne --pull all           # pull all solver images

DoMINO is not built locally - it's NVIDIA's NIM, which you pull yourself from NGC (arxyne --doctor prints the instructions).

3. Start the gateway¶

All solver dispatch goes through one gateway on one port (8100):

arxyne --start-solver gateway

You normally don't even need this step - if the gateway isn't running when you dispatch a solver, the CLI auto-starts it and tells you. Starting it manually is useful when you want it warm ahead of a batch, or want to watch its log:

tail -f ~/.arxyne/logs/gateway.log

One gateway, not per-solver servers

There are no per-solver MCP servers and no ARXYNE_MCP_<NAME>_URL env vars. The gateway launches each solver container per-call and manages Docker internally.

4. Verify the stack¶

arxyne --solvers

This lists the registered solvers per domain and shows whether the gateway is reachable. OpenFOAM, XLB, and DoMINO all live under the aero domain - none "owns" it; the dispatch resolver picks one per call based on the requested solver, the registry, and the current conditions. Single-solver domains (dynamics, with just Chrono) render as a flat row.

5. Dispatch a workflow¶

Either via the dedicated aero command:

arxyne --product drivaer-notchback --aero --solver openfoam   # CPU RANS
arxyne --product drivaer-notchback --aero --solver xlb        # GPU LBM

...or via the domain-driven workflow path:

arxyne --product drivaer-notchback --run-workflow --solver xlb

--solver resolution:

openfoam - explicit OpenFOAM. Filters surrogates to those registered against OpenFOAM (none today); falls through to live OpenFOAM.
xlb - explicit XLB. Filters surrogates to those registered against XLB (none today); falls through to live XLB GPU LBM.
auto - registry-routed. Flywheel surrogates (trained on Arxyne-captured runs) beat third-party pretrained (DoMINO); falls through to OpenFOAM as the domain default.
domino - explicit DoMINO surrogate (NVIDIA's pretrained NIM).

6. Read back what the run produced¶

A completed run writes:

Cd, Cl, CmPitch to the product USD (visible via arxyne --results --product <name>). cm_pitch is computed by OpenFOAM; XLB does not compute moments.
Provenance — solver name, version, timestamp, mesh stats.
Gate status — PASS / FAIL / INCONCLUSIVE per target.

7. Remote solver dispatch¶

The gateway can run on a different machine from the platform - e.g. a remote GPU host. Point the platform at it with a single env var:

# Local (default - you don't need to set anything)
export ARXYNE_GATEWAY_URL=http://127.0.0.1:8100/mcp/

# Remote GPU host (on-prem, Tailscale peer, or cloud instance)
export ARXYNE_GATEWAY_URL=http://<remote-host>:8100/mcp/

On the remote host: install the platform (for the gateway), build the solver images, and start the gateway there:

pip install arxyne
arxyne --pull xlb
arxyne --start-solver gateway

Cloud instances: check the firewall

Cloud providers often block inbound ports by default. Open port 8100 in the instance's security group / firewall, or use an SSH tunnel: ssh -L 8100:localhost:8100 user@remote and point ARXYNE_GATEWAY_URL at http://localhost:8100/mcp/.

Trailing /mcp/ is required

The gateway mounts its endpoint at /mcp/. A bare URL without the path will 404 the initialize request.

Local for iteration, remote for resolution. Same product, same command, same contract - different compute.

8. Troubleshoot¶

Symptom	Cause	Fix
Dispatch hangs with no solver output	Gateway not running and not auto-started	`arxyne --start-solver gateway`, then check `~/.arxyne/logs/gateway.log`
`--solvers` shows the gateway offline	Gateway not started / wrong `ARXYNE_GATEWAY_URL`	Start it, or fix the URL (note the trailing `/mcp/`)
Solver image "not built"	First-time setup	`arxyne --pull <solver>`
XLB run hangs at "compiling"	First-call JAX/Warp JIT compile	Wait ~10 s; subsequent calls reuse the cache
`gpu_oom` failure record	Voxel grid too fine for the GPU	Coarsen via `--body-res`, or lower `--steps`
OpenFOAM container not found	First run pulls/builds the image	`arxyne --pull openfoam`

9. Architectural rules respected by this stack¶

If anything below isn't true at any point, that's a bug - not a feature.

One gateway, pure solver containers. The platform talks MCP to one gateway; the gateway launches pure Docker solver containers per-call. No per-solver MCP servers.
Solver owns its geometry. STLs are bundled in the solver image; the platform sends case.yaml only.
Typed failure contract. Every error path returns a typed record with class ∈ {configuration, runtime, convergence, data}. No silent skips.