Foam-Agent: Automating CFD Simulations with AI Agents

Foam-Agent is a framework that automates the entire workflow of running CFD (Computational Fluid Dynamics) simulations using the open-source software OpenFOAM. It takes a simple description of what you want to simulate (in plain English) or an existing simulation case, and then handles everything: creating the mesh, setting up the simulation files, running the simulation, fixing errors automatically, and even visualizing the results.

What Does It Do?

• End-to-End Automation: From a natural language prompt (e.g., "simulate flow in a channel with these conditions") or an existing case folder, Foam-Agent plans the simulation, generates all necessary OpenFOAM configuration files, runs the simulation locally or on a high-performance computing (HPC) cluster, and optionally creates visualizations.
• Multi-Agent System: It uses several AI agents (Architect, Input Writer, Runner, Reviewer) that work together through a pipeline. The Reviewer detects errors and the Input Writer fixes them, with up to 25 automatic correction attempts.
• RAG-Enhanced Generation: It uses a retrieval system (FAISS) built from OpenFOAM tutorials to find relevant examples and generate accurate configuration files.
• Composable Service: The core functions are exposed as MCP (Model Context Protocol) tools, allowing integration with AI assistants like Claude Code, Cursor, and Windsurf.

How Does It Work?

1. Input: You provide either a text prompt describing the simulation or an existing OpenFOAM case directory/ZIP file.
2. Planning: The Architect agent analyzes the requirements and decides what steps are needed (meshing, file generation, etc.).
3. Generation: The Input Writer creates the OpenFOAM files, using RAG to pull relevant examples from a database of tutorials.
4. Execution: The Runner runs the simulation (locally or via Slurm on HPC).
5. Review & Fix: The Reviewer checks for errors. If any are found, the Input Writer rewrites the necessary files and the simulation is re-run. This loop continues until success or the retry limit is reached.
6. Visualization (optional): If requested, PyVista generates visual outputs.

Quick Start

Using Docker (Recommended)

Pull the pre-built Docker image (includes OpenFOAM v10 and all dependencies):

docker run -it \
  -e FOAMAGENT_MODEL_PROVIDER=openai \
  -e FOAMAGENT_MODEL_VERSION=gpt-5-mini \
  -e OPENAI_API_KEY=your-key-here \
  -p 7860:7860 \
  --name foamagent \
  leoyue123/foamagent

Then write your simulation description in a file called user_requirement.txt inside the container, and run:

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

Running an Existing Case

You can also give Foam-Agent an existing OpenFOAM case directory or ZIP file. It will preserve the original, create a working copy, and run it (or modify it according to a prompt). Example:

python foambench_main.py --output ./output/imported-dam-break --case_path /path/to/damBreak

Configuration

Foam-Agent is highly configurable via environment variables. Key settings include:

• LLM Provider: Choose between OpenAI, Anthropic, Bedrock, Ollama, DeepSeek, etc. (default: openai-codex).
• Model: Specify which model to use (e.g., gpt-5-mini, claude-sonnet-4-6).
• Embedding Provider/Model: For RAG, defaults to HuggingFace with Qwen/Qwen3-Embedding-0.6B (runs locally, no API key needed).
• OpenFOAM Target: Choose between Foundation v10 (default) and ESI/OpenCFD v2006.

Reported Benchmark Results

The project reports results on the FoamBench benchmark (110 simulation tasks). With Claude Opus 4.6 and 25 repair loops, it achieved a 100% success rate on both basic and advanced tasks. However, these are benchmark results, not guarantees for arbitrary cases. Other models scored lower (see the README table).

Advanced Features

• Custom Meshes: Supports external Gmsh .msh files.
• MCP Integration: Exposes tools like plan, input_writer, run, review, apply_fixes, run_case, and visualization for use with AI assistants.
• Claude Code Skill: A /foam skill that orchestrates the full pipeline with a single command.
• HPC Execution: Can submit jobs to Slurm clusters, though monitoring has limitations (it treats an empty squeue as completed).
• Docker Build: You can build the image from source.

Important Caveats

• The README explicitly states that the 100% success rate is a benchmark result, not a guarantee.
• Error correction is limited to 25 iterations; if no progress is made, the workflow fails and leaves the last attempt's files.
• If visualization fails after a successful simulation, the workflow reports partial_success.
• Importing existing cases has specific rules (e.g., no symbolic links, no command whitelist).

For a more detailed introduction, visit deepwiki.com/csml-rpi/Foam-Agent.

---

This explainer is based solely on the project's README.