Skip to main content
Glama

CFD External Flow Submit

cfd_external_flow_submit
Destructive

Submit external-flow CFD to compute drag and lift for a solid in a virtual wind tunnel or a prepared case using OpenFOAM or SU2, returning a job ID for async polling.

Instructions

External-flow CFD (drag/lift) via OpenFOAM or SU2, asynchronous. Requires an OpenFOAM (apt/conda) or SU2 binary; when none resolves this returns {ok:false, reason, install} rather than raising. The two case-BUILDING modes below need OpenFOAM specifically — they emit OpenFOAM dictionaries; SU2 only ever runs a case_dir you prepared yourself, which is why solve_capabilities does not count it toward the cfd family's any_available (issue #237). Three modes:

  • Put a real solid in the virtual wind tunnel (issue #223): pass a model (or body) handle + velocity_m_s. The solid's faces tessellate into an STL, a farfield box is auto-sized around it by standard practice (5L upstream / 10L downstream / 5L lateral, overridable via upstream_factor/downstream_factor/ lateral_factor; the reported blockage_ratio warns past 5 %), snappyHexMesh carves the body out, and the forces function object integrates pressure + viscous traction over it. Cd/Cl/Cm come back on the MEASURED frontal silhouette along flow_direction (default +x; exact for a convex body — override with frontal_area_mm2 for a re-entrant one) and reference_length_mm (default: the largest bbox dimension). Mesh knobs: base_cell_mm (default L/2 — a coarser cell is REJECTED, since snappy would then mesh an empty tunnel and report ~0 drag), surface_refine [min,max] levels, wake_refine, stl_tolerance_mm, end_time. Trust: the laminar path is gated live against the sphere drag curve at Re=1 and Re=100 (within ~2 %); turbulence='kOmegaSST' runs but has no verified oracle for arbitrary bodies and comes back gated:false. Past Re≈1000 a laminar request is flagged in warnings rather than silently answered.

  • Build the flat-plate validation case (no model): pass velocity_m_s, with optional plate_length_mm (default 100), a fluid name ('air-20c','water-20c',…) or explicit mu_pa_s+rho_kg_m3, and mesh knobs nx_plate/n_y/end_time. THIS MODE SOLVES A FLAT PLATE, never the caller's geometry: a 2-D laminar plate with a clean leading edge (slip→plate→slip, far-field top), whose wall-shear drag is integrated from the converged U field and returned next to the Blasius reference Cf=1.328/√Re_L (blasius_ratio≈1, ~15 %). turbulence='kOmegaSST' upgrades it to RANS (default plate_length 1000 mm so Re_L > transition), gated BANDED against the mixed-transition Cf = 0.074·Re^(−1/5) − A/Re.

  • Run a prepared case_dir (optionally an application); OpenFOAM runs with its environment sourced, an SU2 case (*.cfg + *.su2 mesh) runs as a direct native subprocess — no bash/WSL needed, including on Windows.

Returns the degradation dict, or {job_id, status, cache_hit}; poll job_result. Body mode: {ok, returncode, cd, cl, cm, drag_force_n, drag_pressure_n, drag_viscous_n, lift_force_n, force_total_n, moment_total_nm, force_drift_pct, n_force_samples, reynolds, reference_length_m, frontal_area_m2, frontal_area_source, moment_reference_m (the bbox centre moments are taken about, not the global origin), blockage_ratio, base_cell_m, converged, gated, warnings, case_dir}. Flat plate: {ok, returncode, reynolds_l, cd, cf_solved, cf_blasius, blasius_ratio, drag_force_n, drag_momentum_n, drag_blasius_n, n_cells, case_dir}; RANS plate swaps the gate fields for {cf_solved (momentum), cf_mixed_ref, cf_mixed_ratio, cf_turbulent_ref, cf_wall_corrected, y_plus_estimate, band_pct}. Prepared case: {ok, returncode, solver, application, case_dir, kind, stdout_tail}.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "cfd_external_flow_submit"
  }
}

Input Schema

NameRequiredDescriptionDefault
n_yNo
bodyNo
fluidNoair-20c
modelNo
mu_pa_sNo
case_dirNo
end_timeNo
nx_plateNo
rho_kg_m3No
workspaceNoRun this call in this named workspace
turbulenceNolaminar
applicationNo
wake_refineNo
base_cell_mmNo
velocity_m_sNo
flow_directionNo
lateral_factorNo
surface_refineNo
plate_length_mmNo
upstream_factorNo
frontal_area_mm2No
stl_tolerance_mmNo
downstream_factorNo
reference_length_mmNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover mutation/destructiveness but say nothing operational; the description supplies binary prerequisites, the degradation return ({ok:false, reason, install}) instead of raising, the async job_id → job_result polling contract, the rejection of an over-coarse `base_cell_mm`, and a live gating/trust story (laminar gated against the sphere drag curve, kOmegaSST `gated:false`, laminar flagged past Re≈1000). No contradiction with destructiveHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the one-line purpose, then organized into three labeled mode bullets, so an agent can stop reading once it knows its mode. It is dense but mostly load-bearing; the parenthetical issue numbers (#223, #237) and the exhaustive field-by-field return enumeration are the few passages that don't help an agent decide or call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 24-parameter, destructive, async tool with no output schema, the description still covers prerequisites, failure modes, polling, per-mode result fields (body Cd/Cl/Cm/moment reference, plate Blasius ratios, RANS gate fields, prepared-case stdout_tail), and deprecation/limitation warnings. Nothing an agent needs to call or interpret it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 4%, so the description carries nearly the whole load, and it does: defaults and rationales for `base_cell_mm` (L/2, coarser is rejected), `reference_length_mm` (largest bbox dimension), `flow_direction` (+x), `frontal_area_mm2` (for re-entrant bodies), plus all mesh knobs and `plate_length_mm`/`fluid`/`mu_pa_s`/`rho_kg_m3`. `nx_plate` and `n_y` are named only as 'mesh knobs' with no units or effect, keeping it short of a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names the verb (submit/run), the physics (external-flow drag/lift), the backends (OpenFOAM or SU2), and the execution model (asynchronous). The three-mode breakdown then makes the exact scope of each invocation explicit, and the mention of the cfd family / solve_capabilities separates it from sibling solvers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Mode selection is stated as a decision rule: pass `model`/`body` for a real solid (issue #223), omit it to get the flat-plate validation case, or supply `case_dir` to run a prepared case. It also states that the plate mode 'SOLVES A FLAT PLATE, never the caller's geometry' — an explicit warning against misuse — and that SU2 can only ever run a `case_dir`, so an agent cannot pick the wrong combination.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools