Skip to content

csml-rpi/Foam-Agent

BranchesTags

Repository files navigation

Foam-Agent Paper

Foam-Agent System Architecture

An End-to-End Composable Multi-Agent Framework for Automating CFD Simulation in OpenFOAM

Foam-Agent automates the entire OpenFOAM-based CFD simulation workflow from a single natural language prompt. It manages meshing, case setup, execution, error correction, and post-processing — dramatically lowering the expertise barrier for Computational Fluid Dynamics. Evaluated on FoamBench with 110 simulation tasks, our framework achieves an 100% success rate with Claude Opus 4.6.

Visit deepwiki.com/csml-rpi/Foam-Agent for a comprehensive introduction and to ask questions interactively.

Key Features

  • End-to-End Automation: From meshing (including external Gmsh .msh files) to HPC job submission to ParaView/PyVista visualization — one prompt does it all.
  • Multi-Agent Workflow: Architect, Input Writer, Runner, and Reviewer agents collaborate through a LangGraph pipeline with automatic error correction (up to 25 iterations).
  • RAG-Enhanced Generation: Hierarchical FAISS indices built from OpenFOAM tutorials provide context-specific retrieval for accurate configuration file generation.
  • Composable Service Architecture: Core functions are exposed as MCP tools, enabling integration with Claude Code, Cursor, and other agentic systems.

Quick Start

1. Pull and run the Docker image

docker run -it \
  -e OPENAI_API_KEY=your-key-here \
  -p 7860:7860 \
  --name foamagent \
  leoyue123/foamagent

The container comes with OpenFOAM v10, Conda, and all dependencies pre-installed.

For a specific release: docker pull leoyue123/foamagent:v2.0.0

2. Write your prompt

Edit user_requirement.txt inside the container:

do a Reynolds-Averaged Simulation (RAS) pitzdaily simulation. Use PIMPLE algorithm.
The domain is a 2D millimeter-scale channel geometry. Boundary conditions specify a
fixed velocity of 10m/s at the inlet (left), zero gradient pressure at the outlet
(right), and no-slip conditions for walls. Use timestep of 0.0001 and output every
0.01. Finaltime is 0.3. use nu value of 1e-5.

3. Run

python foambench_main.py --output ./output --prompt_path ./user_requirement.txt

That's it. Foam-Agent will plan the case, generate all OpenFOAM files, run the simulation, and fix errors automatically.

Configuration

All settings live in src/config.py with sensible defaults. Every setting can be overridden via environment variables — no need to edit files, especially useful for Docker and CI.

LLM Provider and Model

Environment Variable Purpose Allowed Values
FOAMAGENT_MODEL_PROVIDER LLM backend openai, openai-codex, anthropic, bedrock, ollama
FOAMAGENT_MODEL_VERSION Model identifier e.g., gpt-5-mini, gpt-5.3-codex, claude-opus-4-6

Example:

docker run -it \
  -e FOAMAGENT_MODEL_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY=your-key-here \
  -e FOAMAGENT_MODEL_VERSION=claude-opus-4-6 \
  -p 7860:7860 \
  leoyue123/foamagent

Embedding Provider and Model

Environment Variable Purpose Allowed Values
FOAMAGENT_EMBEDDING_PROVIDER Embedding backend openai, huggingface, ollama
FOAMAGENT_EMBEDDING_MODEL Embedding model e.g., Qwen/Qwen3-Embedding-0.6B, text-embedding-3-small

Defaults to huggingface with Qwen/Qwen3-Embedding-0.6B (runs locally, no API key needed).

API Keys

Variable When needed
OPENAI_API_KEY Using openai provider
ANTHROPIC_API_KEY Using anthropic provider
AWS credentials Using bedrock provider

Input Writer Generation Mode

Set in src/config.py via input_writer_generation_mode:

Mode Behavior Best for
sequential_dependency Files generated in order with cross-file context Expensive runs (HPC, long simulations)
parallel_no_context Files generated in parallel, no cross-file context Fast local runs where retry is cheap

Recommended Models

Framework Model Basic Advanced
FoamAgent 2.0.0 (10 loops) Opus 4.6 85.45% 100%
FoamAgent 2.0.0 (25 loops) Opus 4.6 100% 100%
FoamAgent 2.0.0 (25 loops) Sonnet 4.6 87.88% 75.00%
FoamAgent 2.0.0 (25 loops) Haiku 4.6 54.55% 37.50%
FoamAgent 2.0.0 (25 loops) gpt-5.4 45.45% 75.00%
FoamAgent 2.0.0 (25 loops) gpt-5.3-codex 54.55% 62.50%

We recommend Anthropic Claude Opus 4.6 for best results.

Advanced Usage

Custom Mesh Files

Foam-Agent supports external Gmsh .msh files (ASCII 2.2 format). Describe boundary conditions in your prompt and pass the mesh:

python foambench_main.py \
  --output ./output \
  --prompt_path ./user_req_tandem_wing.txt \
  --custom_mesh_path ./tandem_wing.msh

To mount a mesh file from the host into Docker:

docker run -it \
  -e OPENAI_API_KEY=your-key-here \
  -v /path/to/my_mesh.msh:/home/openfoam/Foam-Agent/my_mesh.msh \
  -p 7860:7860 \
  leoyue123/foamagent

Skill / MCP Integration (Claude Code, Cursor, Windsurf, etc.)

Foam-Agent exposes its full CFD workflow as an MCP server — the universal protocol supported by Claude Code, Cursor, Windsurf, and other AI-powered tools. It also ships with a Claude Code skill (/foam) for one-command simulation runs.

Quick Setup (Local Install)

# 1. Install (adds the foamagent-mcp command)
pip install -e .

# 2. Register with your AI tool
claude mcp add foamagent -- foamagent-mcp                # Claude Code

For Cursor: open Settings > Features > MCP > Edit MCP Settings, and add:

{
  "mcpServers": {
    "foamagent": {
      "command": "foamagent-mcp"
    }
  }
}

For Windsurf / other MCP-compatible tools, use the same JSON config above.

Quick Setup (Docker)

If running in Docker, start the HTTP server and point your MCP client at it:

docker run -it \
  -e OPENAI_API_KEY=your-key-here \
  -p 7860:7860 \
  leoyue123/foamagent \
  foamagent-mcp --transport http --host 0.0.0.0 --port 7860

Then configure your MCP client:

{
  "mcpServers": {
    "foamagent": {
      "url": "http://localhost:7860/mcp"
    }
  }
}

If running Docker on a remote server, ensure port 7860 is reachable (e.g., via SSH port forwarding or -p 7860:7860).

Available MCP Tools

All tools generate output following Foundation OpenFOAM v10 conventions.

Tool Description
plan Analyze requirements and plan simulation structure using Foundation v10 conventions
input_writer Generate all OpenFOAM configuration files (system/, constant/, 0/) targeting Foundation v10
run Execute Allrun script locally with error collection (requires Foundation OpenFOAM v10)
review Analyze simulation errors and suggest fixes via LLM
apply_fixes Rewrite OpenFOAM files based on review analysis
visualization Generate PyVista visualization of simulation results

Claude Code Skill

For Claude Code users who clone this repo, a /foam skill is included in .claude/skills/foam.md. It orchestrates the MCP tools into a complete workflow:

/foam Simulate lid-driven cavity flow at Re=1000

This triggers the full pipeline: plan -> generate files -> run -> review/fix loop -> visualize.

Codex OAuth Sign-in (No API Key)

If you have a ChatGPT/Codex subscription, you can authenticate via OAuth instead of an API key:

  1. Install the Codex CLI on your host machine.
  2. Run codex login and choose "Sign in with ChatGPT".
  3. Verify the token cache exists: ls ~/.codex/auth.json
  4. Mount it into the container:
docker run -it \
  -e FOAMAGENT_MODEL_PROVIDER=openai-codex \
  -e FOAMAGENT_MODEL_VERSION=gpt-5.3-codex \
  -v ~/.codex/auth.json:/root/.codex/auth.json:ro \
  -p 7860:7860 \
  leoyue123/foamagent

Foam-Agent searches for OAuth tokens at (first match wins):

  • $CODEX_HOME/auth.json
  • ~/.codex/auth.json
  • ~/.clawdbot/agents/main/agent/auth-profiles.json

Security note: auth.json contains access tokens. Treat it like a password.

Manual Installation (Without Docker)

git clone https://github.com/csml-rpi/Foam-Agent.git
cd Foam-Agent
conda env create -n FoamAgent -f environment.yml
conda activate FoamAgent

You also need Foundation OpenFOAM v10 (openfoam.org) installed and sourced. ESI OpenFOAM (openfoam.com) is not compatible. Follow the official installation guide and verify with:

echo $WM_PROJECT_DIR   # should print e.g. /opt/openfoam10

Then run:

python foambench_main.py --output ./output --prompt_path ./user_requirement.txt

Building the Docker Image from Source

git clone https://github.com/csml-rpi/Foam-Agent.git
cd Foam-Agent
docker build -f docker/Dockerfile -t foamagent:latest .
docker run -it \
  -e OPENAI_API_KEY=your-key-here \
  -p 7860:7860 \
  foamagent:latest

Troubleshooting

Problem Solution
OpenFOAM environment not found Ensure Foundation OpenFOAM v10 (openfoam.org) bashrc is sourced, or use the Docker image. ESI OpenFOAM (openfoam.com) is not compatible
Database files missing Ensure the full repo is cloned including database/. Docker image has these pre-built
Missing dependencies conda env update -n FoamAgent -f environment.yml --prune
API key errors Ensure the appropriate key is set (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
MCP connection errors Verify the container is running and port 7860 is accessible

OpenFOAM version: Foam-Agent targets Foundation OpenFOAM v10 (openfoam.org) exclusively. All generated case files, dictionary names, and solver binaries follow Foundation v10 conventions. ESI OpenFOAM (openfoam.com, e.g., v2312, v2406, v2512) is not supported — generated files will not work without manual adaptation. The Docker image includes Foundation OpenFOAM v10 pre-installed.

Community

Join the WeChat community

Chinese-speaking users can join the Foam-Agent WeChat community by adding the volunteer's WeChat account: ZDSJTUCFD. The volunteer will invite you to the group.

Citation

If you use Foam-Agent in your research, please cite our paper:

@article{yue2025foam,
  title={Foam-Agent: Towards Automated Intelligent CFD Workflows},
  author={Yue, Ling and Somasekharan, Nithin and Zhang, Tingwen and Cao, Yadi and Chen, Zhangze and Di, Shimin and Pan, Shaowu},
  journal={arXiv preprint arXiv:2505.04997},
  year={2025}
}

@article{somasekharan2026cfdllmbench,
    title={CFDLLMBench: A Benchmark Suite for Evaluating Large Language Models in Computational Fluid Dynamics},
    author={Somasekharan, Nithin and Yue, Ling and Cao, Yadi and Li, Weichao and Emami, Patrick and Bhargav, Pochinapeddi Sai and Acharya, Anurag and Xie, Xingyu and Pan, Shaowu},
    journal={Journal of Data-centric Machine Learning Research},
    year={2026},
    url={https://openreview.net/forum?id=kTcH1MnkjY},
    note={}
}

Star History

Star History Chart

About

Foam-Agent: An end-to-end, composable multi-agent framework for automating CFD simulations in OpenFOAM. NeurIPS 2025 Machine Learning and the Physical Sciences Workshop.

arxiv.org/abs/2505.04997

Topics

agent simulation physics cfd openfoam computational-fluid-dynamics multi-agent-systems foam-agent

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

188 stars

Watchers

7 watching

Forks

45 forks
Report repository

Releases 4

v2.1.0 Latest
Apr 1, 2026
+ 3 releases

Packages

 
 
 

Contributors

Languages