PaperlayerView exact revision on arXiv

Source-linked AI summary

Foam-Agent: A Large Language Model-Based Multi-Agent Framework for Automating Computational Fluid Dynamics Workflows

Ling Yue, Nithin Somasekharan, Tingwen Zhang, Yadi Cao, Zhangze Chen, Shimin Di, Shaowu Pan

arXiv:2505.04997v3cs.AIcs.MA

TL;DR

Existing LLM-based CFD agents focus on isolated solver configuration and leave workflow stages, file dependencies, and runtime correction inadequately addressed. Foam-Agent combines specialist agents with stage-aware retrieval, dependency-aware file generation, and trajectory-conditioned repair. Across three cases, it was 2.1–14.5× faster than a senior OpenFOAM user under the reported comparison protocol.

  • Problem

    Earlier OpenFOAM agents focus on isolated solver configuration, omit pre- and post-processing, generate files independently, and cannot diagnose or correct runtime failures.

    Source: §1 · p. 2

  • Method

    Foam-Agent uses specialist agents with multi-index retrieval, dependency-aware file generation, and a trajectory-conditioned reviewer loop for OpenFOAM workflows.

    Source: §1 · p. 2

  • Results

    2.1–14.5× faster than a senior OpenFOAM user across three cases, under the reported setup and timing protocol.

    Source: §3.7 · p. 14

  • Takeaways & Limitations

    Foam-Agent makes OpenFOAM case structure explicit enough to retrieve, execute, inspect, and repair workflow configurations.

    Source: §4 · p. 15

    For complex geometries, meshing remains an open problem, and Foam-Agent integrates existing tools and inherits their limits.

    Source: §2.1.2 · p. 4

Abstract

from arXiv · show

Computational fluid dynamics (CFD) has been the main workhorse of computational physics, yet its steep learning curve and fragmented, multi-stage workflow create significant barriers to entry. We present Foam-Agent, a multi-agent framework that leverages large language models (LLMs) to automate the end-to-end CFD workflow in OpenFOAM from a single natural-language prompt. Foam-Agent rests on three methodological contributions. First, a multi-index retrieval scheme organizes domain knowledge along four complementary structural dimensions and selects indices by workflow stage, sharpening retrieval precision over conventional single-index retrieval-augmented generation. Second, dependency-aware file generation is formulated as a topological traversal of the OpenFOAM case dependency graph, so that each configuration file is synthesized in the context of its already-generated predecessors, enforcing cross-file consistency. Third, a trajectory-conditioned reviewer loop iteratively repairs failed runs by conditioning each correction on the accumulated error-and-diagnosis trajectory of its own previous attempts, applying a minimal configuration edit that targets a reduced solver-error set. Around these contributions, six specialist agents span planning, meshing, file writing, execution, review, and visualization; Foam-Agent additionally exposes its capabilities through the Model Context Protocol as a deployment surface for external orchestrators. On FoamBench, Foam-Agent achieves an 88.2% execution success rate on the 110 Basic-tier tasks and 62.5% on the out-of-distribution Advanced tier, all without expert intervention. These results show how strategic harnessing of specialized multi-agent systems can reduce expertise barriers while preserving the rigor of solver-based simulation workflows.

1. Introduction

CFD workflows in OpenFOAM span multiple stages and require substantial domain expertise, while earlier LLM agents chiefly automate isolated solver configuration. Foam-Agent organizes the workflow around specialist agents and three methods for retrieval, file generation, and runtime correction.

1. Introduction

  • CFD workflows combine pre-processing, context-dependent solver configuration, and post-processing, creating a steep learning curve and substantial expertise demands.CFD is used across science and engineering applications, including aircraft, wind-turbine design, and blood-flow simulation.Source: §1 · pp. 1–2
  • Earlier OpenFOAM agents focus largely on isolated solver configuration, generate files independently, and cannot diagnose or correct runtime failures.Their narrow coverage omits critical pre- and post-processing stages and overlooks rigid cross-file dependencies.Source: §1 · p. 2
  • Foam-Agent assigns six specialist agents to canonical OpenFOAM stages, so they specialize in a stable workflow rather than rediscovering its steps.Its contributions are designed as domain-level harness engineering and sit at the workflow layer, not within the solver's numerical methods, discretization, or mesh technology.Source: §1 · p. 2
  • Multi-index retrieval organizes knowledge across case metadata, directory structure, file contents, and execution scripts, selecting an index by workflow stage.The paper reports improved retrieval precision over a flat single-index design.Source: §1 · p. 2
  • Dependency-aware generation traverses the OpenFOAM case dependency graph, generating each file in the context of its already-emitted predecessors to support cross-file consistency.This approach is intended to suppress hallucinated undefined symbols.Source: §1 · p. 2
  • The trajectory-conditioned reviewer diagnoses solver errors using prior attempts and applies a minimal configuration edit targeting a reduced error set on the next run.The correction is execution-grounded and conditioned on the accumulated error-and-diagnosis trajectory.Source: §1 · p. 2

2. Methods

Foam-Agent decomposes OpenFOAM automation into specialist stages, from planning and mesh generation through file writing, execution, repair, and visualization. Its methods emphasize stage-matched retrieval, dependency-aware file generation, and trajectory-conditioned correction, with MCP serving as an integration interface for external orchestrators.

2.1.1. Architect Agent

  • The Architect classifies the natural-language request, retrieves a tutorial, decomposes it into file tasks, orders them by OpenFOAM dependencies, and supplies a structured plan for generation.The classification includes four fields, with solver-family and solver values restricted to those found in the tutorial corpus.Source: §2.1.1 · pp. 3–4

2.1.2. Meshing Agent

  • The Meshing Agent selects among blockMesh, snappyHexMesh, Gmsh-generated meshes, and user-supplied Gmsh .msh files; it integrates existing tools and inherits their limits rather than introducing a new meshing algorithm.snappyHexMesh requires a watertight STL surface, and support for additional external mesh formats would require conversion-specific boundary-patch validation.Source: §2.1.2 · p. 4

2.1.3. Input Writer Agent

  • The Input Writer emits files in dependency order, supplying each generation call with the task, retrieved tutorial, and verbatim contents of already-emitted predecessor files to maintain cross-file parameter continuity.OpenFOAM’s fixed directory hierarchy sets the order system, constant, 0, then Allrun; a second LLM call generates the execution script.Source: §2.1.3 · pp. 4–5

2.1.4. Runner Agent

  • The Runner prepares and executes the Allrun script locally or on HPC, then extracts canonical ERROR: fragments from solver logs for the Reviewer to classify.This extractor misses runner-script failures before solver invocation and bare floating-point exceptions without an ERROR: line.Source: §2.1.4 · pp. 5–6

2.1.5. Reviewer Agent

  • The Reviewer diagnoses solver errors against prior logs and diagnoses, then makes minimal configuration edits targeting fewer errors; re-execution checks the target, which is not guaranteed to decrease monotonically.The loop repeats until the error set is empty or the iteration cap is reached; masked errors can emerge after an edit.Source: §2.1.5 · pp. 6–7

2.1.6. Visualization Agent

  • After a successful run, the Visualization Agent can identify requested fields, generate and execute a PyVista or ParaView Python script, and repair visualization errors up to a configurable retry limit.Saved visualizations are PNG files in the run directory.Source: §2.1.6 · p. 7

2.2. Multi-Index Retrieval

  • Multi-index retrieval selects among four OpenFOAM knowledge dimensions by workflow stage, with deterministic reranking; the knowledge base indexes Foundation v10 tutorials across case metadata, directory structure, file contents, and execution scripts.A fixed similarity cutoff was replaced because per-solver tuning over-filtered rare families and under-filtered common ones; recall depth defaults to k=3, while a k-sweep remains future work.Source: §2.2 · pp. 7–8, §2.2.1 · p. 8

2.3. The Model Context Protocol Deployment Surface

  • MCP exposes Foam-Agent functions through one server for MCP-capable orchestrators; it is a deployment surface, not a methodological contribution, and does not change the underlying solver trajectory or metrics.When used as a component, workflow planning and iterative correction move to the orchestrator, whose iteration policy can affect whether repair continues to completion.Source: §2.3 · pp. 8–9

3. Results

Foam-Agent outperforms the evaluated baselines on FoamBench, while execution success exceeds strict field-level complete success. Ablations and case studies show how retrieval, iterative repair, and workflow support contribute to that performance.

3. Results

  • FoamBench evaluates 110 Basic cases and 16 hand-crafted Advanced cases using execution and bucketed field-fidelity metrics, with comparisons matched on the LLM backbone.Mexec requires a clean solver completion; MNMSE scores normalized field error, and complete success requires both execution success and MNMSE=1.Source: §3 · p. 9, §3.1 · p. 9

3.2. Overall Performance Comparison

  • 88.2% Mexec on FoamBench-Basic exceeds MetaOpenFOAM’s 55.5%, while Foam-Agent’s MNMSE is 0.477 versus 0.173; strict complete success is 41.8%.On GPT-4o, Foam-Agent’s Mexec is 59.1% versus 17.3%; 38 cases ran to completion but had NMSE above 0.3.Source: §3.2 · pp. 10–11, Table 1 · p. 10

3.3. Ablation Studies

  • Across configurations, the Reviewer raises execution success from roughly 50% to over 80%; without it, dependency-aware generation improves success from 48.2% to 56.4% at T=0.0 and 45.4% to 57.3% at T=0.6.On FoamBench-Basic (n=110, T=0.6), multi-index retrieval increases Mexec from 44.5% to 57.3% without the Reviewer and from 84.5% to 88.2% with it.Source: §3.3 · p. 11, Table 2 · p. 11

3.3.1. Retrieval Case Studies

  • Retrieval and repair complement each other: multi-index retrieval fixes BenardCells patch typing on the first call, while the Reviewer recovers all ten damBreakWithObstacle paraphrases after missing-file errors.Reviewer iterations are front-loaded, but some cases oscillate and still converge; aggregate recovery is 80.9%, while solver/model mismatch is the hardest residual failure class.Source: §3.3.1 · p. 12, §3.3.2 · p. 12, §3.3.3 · p. 12

3.4. External Mesh

  • Foam-Agent accepts externally supplied meshes and produces results close to expert simulations; Gmsh-based meshing captures obstacle geometries that native OpenFOAM meshing utilities could not.For externally supplied meshes, the workflow converts to polyMesh and checks boundary-patch consistency; the Gmsh route converts its generated .msh file for OpenFOAM use.Source: §3.4 · pp. 12–13, §3.5 · p. 13

3.7. Computational Cost

  • Foam-Agent was 2.1–14.5× faster than a senior user across three standard cases; Reviewer passes dominate attributed wall-clock, and Basic-tier median cost was $0.29 per case.Agent call time is independent of mesh resolution by construction, while solver wall-clock grows with problem size; a full stratified HPC scaling grid remains future work.Source: §3.7 · pp. 14–15

3.8. Multi-Physics Case Study: A Multi-Region Burner

  • The multi-region burner case ran end-to-end without manual changes and achieved NMSE 0.0398 against an expert reference, placing it in the top fidelity bucket.The case combines reactive flow, conjugate heat transfer, radiation, and compressible thermodynamics.Source: §3.8 · p. 15

3.9. Interoperability demonstration

  • The MCP demonstration let an external orchestrator sequence mesh generation, file writing, HPC scripting, execution, and visualization for a NACA 0012 airfoil simulation.Source: §3.9 · p. 15

4. Conclusion

Foam-Agent makes OpenFOAM workflow structure explicit through retrieval, dependency-aware generation, and execution-grounded repair. It reports higher execution-success rates than MetaOpenFOAM on both FoamBench tiers, while identifying limits in geometry scope, repair, and dependency ordering.

4. Conclusion

  • Foam-Agent achieves 88.2% execution success on 110 Basic-tier cases and 62.5% on the out-of-distribution Advanced tier, 1.6× and 5× MetaOpenFOAM’s rates, respectively.Both systems used Claude 3.5 Sonnet.Source: §4 · p. 16
  • Its three methodological components are multi-index retrieval, topological dependency-aware file generation, and a trajectory-conditioned Reviewer loop for execution-grounded correction.Specialist agents organize the workflow, which is also exposed through an MCP deployment surface for external orchestrators.Source: §4 · p. 16
  • Many LLM-driven CFD failures are structural, including inconsistent file dependencies, incompatible solver and boundary choices, constrained meshing, and local repairs that damage global case structure.Foam-Agent aligns specialist agents in an explicitly serial dependency structure.Source: §4 · p. 16
  • The system is most reliable for simple-to-moderate geometries using blockMesh, snappyHexMesh, or Gmsh; repair does not modify CAD or pre-meshing geometry definitions, and file dependencies use a fixed topological order.External expert meshes can be ingested when needed.Source: §4 · p. 16
  • Broader validation is needed on non-tutorial benchmarks, especially industrial geometries and cases stratified by mesh-generation pathway.The paper also identifies multi-physics workflows and advanced geometric tasks as incompletely represented in the current harness.Source: §4 · p. 16

CRediT authorship contribution statement

The contribution statement distributes research, implementation, validation, and writing responsibilities across seven contributors.

CRediT authorship contribution statement

  • Ling Yue contributed across conceptualization, data curation, formal analysis, investigation, methodology, software, validation, and both stages of writing.Yue also contributed to project administration, supervision, and funding acquisition.Source: CRediT authorship contribution statement · pp. 16–17
  • Nithin Somasekharan contributed to conceptualization, data curation, formal analysis, investigation, methodology, validation, and review and editing.Source: CRediT authorship contribution statement · pp. 16–17
  • Tingwen Zhang contributed data curation, methodology, software, validation, and review and editing; Zhangze Chen contributed validation, visualization, and review and editing.Source: CRediT authorship contribution statement · p. 17
  • Yadi Cao, Shimin Di, and Shaowu Pan contributed to conceptualization and supervision, with Cao and Pan also contributing project administration and Pan funding acquisition and resources.Cao and Di also contributed to review and editing; Pan contributed to review and editing as well.Source: CRediT authorship contribution statement · p. 17

Data statement

The paper identifies public locations for the study data and evaluation materials.

Data statement

  • Datasets generated and analyzed during the study are available in the Foam-Agent database repository.Source: Data statement · p. 17
  • Evaluation datasets and associated scripts are based on the publicly available CFDLLMBench framework.Source: Data statement · p. 17
  • The paper states that source data are provided with the study.Source: Data statement · p. 17

Code availability

The complete Foam-Agent code base and associated materials are publicly available under the MIT license.

Code availability

A. System and User Prompts

The appendix supplies prompts for Foam-Agent’s specialist agents, covering case planning, file and command generation, error repair, and an example simulation request.

A. System and User Prompts

  • The appendix organizes system and user prompts by agent role and function in Foam-Agent’s multi-agent architecture.The Architect Agent turns requirements into a structured simulation plan and manageable subtasks.Source: A. System and User Prompts · p. 19, §A.1 · p. 19

A.1. Architect Agent Prompts

  • The Architect Agent converts a user requirement into a case description and JSON subtasks specifying OpenFOAM filenames and folders.The prompts also use a similar-case directory structure and directory counts as references.Source: §A.1.1 · p. 19, §A.1.2 · pp. 19–20

A.2. Input Writer Agent Prompts

  • The Input Writer Agent generates configuration files and checks that their fields, boundary conditions, mesh settings, units, and solver settings remain consistent.Its prompts direct the agent to use similar-case file content as a template while matching user requirements and already-generated files.Source: §A.2 · p. 20, §A.2.1 · pp. 20–21

A.2.2. Command Generation Prompts

  • Command-generation prompts request only the OpenFOAM commands needed for an Allrun script, using a pre-curated command list that users need not supply.Inputs include the case directory structure, case information, and similar-case scripts.Source: §A.2.2 · p. 21

A.2.3. Allrun Script Generation Prompts

  • Allrun prompts combine available commands and similar-case scripts with the case requirements and structure, while instructing the agent to prioritize requirements and solver knowledge.The referenced scripts may be unsuitable for a different solver or directory structure.Source: §A.2.3 · p. 21

A.3. Reviewer Agent Prompts

  • The Reviewer Agent diagnoses simulation errors, and the correction prompt requests only complete files needing modification while preserving parameters specified by the user.The correction output is constrained to a JSON format containing modified file contents.Source: §A.3 · p. 21, §A.3.2 · pp. 22–23

A.4. History Tracking Format

  • Subsequent error-analysis prompts include prior attempts and ask for a different approach if errors persist; the appendix records each attempt’s logs and diagnosis.The history format pairs error logs with review analysis under an attempt number.Source: §A.4 · p. 23

A.5. Example User Requirements

  • The example requirement specifies a 2D Rayleigh-Bénard convection case with buoyantFoam, a 90-by-10 mesh, thermal boundary conditions, and a 1000-second run.It also specifies air-like properties, a 1-second timestep, output every 50 steps, and a k-epsilon turbulence model.Source: §A.5 · p. 23

A.3.1. Error Analysis Prompts

The error-analysis prompts guide the Reviewer Agent to diagnose OpenFOAM logs against similar cases and user requirements, with subsequent attempts informed by prior history.

A.3.1. Error Analysis Prompts

  • The Reviewer Agent diagnoses underlying issues from error logs, using similar cases ordered by similarity as a reference.For undefined keywords, the prompt instructs it to propose defining the exact keyword shown in the log.Source: §A.3.1 · p. 22
  • The initial error-analysis prompt supplies similar-case references, Foam files, error logs, and the user requirement for review.Suggestions must adhere to, and not contradict, the user requirement.Source: §A.3.1 · p. 22
  • For subsequent errors, the prompt adds attempt history and asks the reviewer to try a different approach if the error persists.The reviewer is instructed not to suggest changing parameters declared in the user requirement or to modify files directly.Source: §A.3.1 · p. 22

B. User Prompts In Case Studies

The case-study prompts specify diverse CFD requests, spanning external meshes, generated meshes, visualization targets, and an HPC run.

B.1. Multi Element Airfoil

  • The multi-element airfoil case uses a supplied mesh, simpleFoam, SpalartAllmaras, and requests velocity-magnitude visualization on the Z plane.The prompt specifies freestream velocity of 9 m/s, no-slip airfoil and wall boundaries, and empty front-and-back faces.Source: §B.1 · p. 24

B.2. Tandem Wing

  • The tandem-wing case specifies a supplied mesh, simpleFoam, SpalartAllmaras, and velocity-magnitude visualization at the final time on the mid-Z section.Unlike the airfoil case, its front-and-back faces are wall boundaries.Source: §B.2 · p. 24

B.3. Flow Over Cylinder

  • The cylinder-flow case requests a Gmsh mesh, pisoFoam, and velocity-magnitude visualization on the x-y plane.Its prompt specifies a cylinder of radius 0.1, a 2D setup, and a 0.001-second timestep through 2 seconds.Source: §B.3 · p. 24

B.4. Flow Over Two Square Obstacles

  • The two-square-obstacle case requests a Gmsh mesh, pisoFoam, and velocity-magnitude visualization on the x-y plane.It specifies a 2D domain with two 0.25-by-0.25 obstacles and a 0.001-second timestep through 10 seconds.Source: §B.4 · pp. 24–25

B.5. 3D cavity HPC Case

  • The 3D lid-driven cavity request specifies icoFoam, a 100-by-100-by-100 mesh, and an HPC parallel run on Perlmutter split into 32 subdomains.The prompt sets a 0.1-unit cube, a moving top wall, and simulation from 0 to 0.015 seconds.Source: §B.5 · p. 25

C. Slurm Script Generated by the Agent

The appendix shows a generated Slurm script for launching an OpenFOAM case in parallel, alongside a description of Foam-Agent’s MCP functions.

C. Slurm Script Generated by the Agent

  • The generated Slurm script requests one Perlmutter CPU node, 32 tasks, a two-hour limit, and 128 GB of memory.The script sets account, queue, job-name, and output/error-log directives.Source: C. Slurm Script Generated by the Agent · p. 26
  • The script creates a logs directory, runs Allrun in parallel, and exits successfully or with failure according to the command result.It enables shell error handling with set -e.Source: C. Slurm Script Generated by the Agent · p. 26
  • Table 7 describes decoupled MCP capabilities with strongly typed inputs and outputs for interaction with orchestrating agents.The paper states that the table presents each function’s purpose.Source: Table 7 · p. 27

D. MCP Functions

Foam-Agent exposes its functions to an external MCP orchestrator, with protocol-level latency and failure modes documented at the boundary.

D. MCP Functions

  • Foam-Agent decomposes its functionality into basic functions exposed to an external orchestrator.Table 7 lists each function’s purpose, and Figure 9 shows the overall MCP design.Source: D. MCP Functions · p. 27
  • Protocol round-trip overhead is small compared with OpenFOAM solver wall-clock time per reviewer iteration.Local STDIO adds single-digit milliseconds per call and HTTP adds tens of milliseconds.Source: D. MCP Functions · p. 27
  • Four protocol-boundary errors include malformed-argument schema failures, timeouts, solver-crash propagation, and orchestrator session drops.Each is returned as a structured error payload, preserving Foam-Agent’s standalone error semantics across the MCP boundary.Source: D. MCP Functions · pp. 27–28

E. Supplementary Experiments on Additional Backbones

Supplementary experiments examine prompt phrasing robustness on GPT-5.3-codex, separately from the headline evaluation backbone. Across paraphrases, execution success and fidelity metrics generally agree, with variation concentrated in known-hard cases.

E. Supplementary Experiments on Additional Backbones

  • The prompt-sensitivity study used GPT-5.3-codex, unlike the Claude 3.5 Sonnet backbone used for the headline FoamBench evaluation.The supplementary studies are presented as relative within-study comparisons.Source: E. Supplementary Experiments on… · p. 28

E.1. Prompt Sensitivity

  • Bucketed M_NMSE agreed across all three paraphrases for 18/27 datasets, while M_exec agreed for 22/27.The Advanced-tier bucketed M_NMSE mean showed zero variation, and the Basic-tier mean varied by at most 0.09.Source: §E.1 · p. 28
  • The 5/27 datasets with M_exec disagreement concentrated in known-hard cases, indicating case difficulty rather than phrasing sensitivity.The paraphrases preserved numerics, quoted boundary-condition names, and OpenFOAM solver names; median embedding-space faithfulness was 0.959.Source: §E.1 · p. 28

E.2. Per-Mesh-Type Reliability

On FoamBench-Advanced, the reported mesh-type comparison identifies solver fidelity and parameter setup—not mesh generation—as the limiting factors.

E.2. Per-Mesh-Type Reliability

  • On FoamBench-Advanced, solver fidelity and parameter setup—not mesh generation—are the limiting factors in both mesh pathways.The reported absolute values are intended for within-table mesh-type comparison.Source: §E.2 · p. 28
  • SnappyHexMesh Advanced cases reached M_exec = 0.80 but clustered in fidelity bucket 0.The passage attributes the residual to solver-side physical accuracy, not the generation of a topologically valid hex-dominant mesh.Source: §E.2 · p. 28
  • Advanced blockMesh cases were bimodal, with one complete-success case and the remainder split between divergent and execution-failure outcomes.FoamBench-Basic is uniformly blockMesh, so its reported numbers already represent blockMesh performance.Source: §E.2 · p. 28
Loading 2505.04997v3…