OPENFOAM FOUNDATION V13 · OPEN SOURCE SKILL LIBRARY

EasyFoam

Skill-Oriented OpenFOAM Agents
with Evidence-Driven Evolution

Peng Yin^1* Zhiwei Chen^2,1* Tianyi Liu³
Chen Li³ Kai Li^1† Jian Cheng^1†

¹ Institute of Automation, Chinese Academy of Sciences
² Nanjing University ³ State Key Laboratory of Aerodynamics

* Equal contribution † Co-corresponding authors

Externalized CFD expertise, guided by simulation evidence.

EasyFoam externalizes OpenFOAM expertise into modular skills, references, schemas, and deterministic tools. A coding agent uses these resources to plan, construct, run, assess, and repair a CFD workflow.

Beyond a successful solver run

A simulation can finish successfully and still miss numerical or physical requirements. The accompanying paper studies this executability–acceptability gap and asks how CFD expertise can be reused and refined across agent implementations.

Execution completion

Did the prescribed workflow complete?

Numerical soundness

Does the solution meet the required numerical checks?

QoI satisfaction

Do the quantities of interest meet the task criteria?

Task acceptance requires all three dimensions to pass. Missing evidence is not a pass.

An evidence-driven dual-loop framework

Within a task, structured evidence guides construction and targeted repair. Across tasks, experience can inform reusable skill revisions.

Paper framework: Plan, Write, Run and Postprocess are assessed with execution, numerical and QoI evidence; the Root–Stage–Specialist architecture connects to proposal, paired evaluation and penalized selection. — Research framework (Figure 2): evidence-guided workflow construction and repair, hierarchical skills, and cross-task evolution through paired evaluation. Paper ↗

From the framework to the library

Library architecture: the workflow produces structured records; explicit human review governs reusable changes.

In-task workflow

Plan → Write → Run → Postprocess

CaseSpec makes requirements explicit. Stage-scoped repair reopens the earliest affected stage and invalidates dependent completion claims, while retaining prior run records.

Across-task evolution

Experience → Candidate → Validation → Human decision

The paper studies candidate selection through paired evaluation. The released library provides reviewed, reversible updates: applying, retaining, and rolling back changes require explicit human instruction.

Selected results from the paper

The paper evaluates all four systems with the same DeepSeek-V4-Flash backbone and OpenFOAM Foundation v13. Table 1 reports the initial, manually authored EasyFoam skills, before cross-task evolution. Task Acceptance Rate (TAR) requires all three evaluation dimensions to pass jointly.

Evaluation beyond tutorial-level variations

Download ExtFoamBench on Hugging Face ↗: 100 tasks, 7 geometry assets, and task-specific evaluation metrics and acceptance criteria, with offline reference data and evaluation tools as supporting resources.

FoamBench Basic has 110 tasks, Advanced has 16, and ExtFoamBench has 100 tasks across ten physical families and five variation axes. — Benchmark design (Figure 1): ExtFoamBench pairs task prompts with reference cases across ten families, with variations in operating conditions, geometry, physics, numerics, and study workflows. Paper ↗

Selected results from the paper
Evaluation track	System	Execution	TAR
FoamBench · 126	MetaOpenFOAM 2.0	28.6%	4.8%
	Foam-Agent	59.5%	4.0%
	ChatCFD	34.9%	16.7%
	EasyFoam	97.6%	41.3%
ExtFoamBench · 100	MetaOpenFOAM 2.0	8.0%	0.0%
	Foam-Agent	27.0%	0.0%
	ChatCFD	13.0%	0.0%
	EasyFoam	72.0%	6.0%

Source: paper PDF, Table 1 (p. 6). These are results of the experimental systems evaluated in the paper, not performance guarantees for this library. ExtFoamBench contains 100 tasks across ten physical families and five axes of variation. Paper ↗

What is in the library?

Workflow

Plan, author, execute, diagnose, validate, and postprocess a case. Recoverable state and immutable run records preserve the evidence trail.

Evolution

Retain supported experience, propose a frozen patch, validate it, and request a human decision. Changes can be deferred, rejected, or rolled back.

Reference & tools

Read-only OpenFOAM and CFD knowledge, seven artifact schemas, and deterministic Python scripts for parsing, validation, execution, and state management.

Start with the library

Use Python 3.11 or 3.12, OpenFOAM Foundation v13, Git, and a coding agent with file and command execution capabilities. Windows runs OpenFOAM through WSL; Linux and WSL support native execution.

01Clone and install

git clone https://github.com/CAS-CLab/EasyFoam.git
cd EasyFoam
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

git clone https://github.com/CAS-CLab/EasyFoam.git
Set-Location EasyFoam
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

02Check the OpenFOAM environment

export EASYFOAM_OPENFOAM_BASHRC=/opt/openfoam13/etc/bashrc
export EASYFOAM_EXEC_BACKEND=auto
python skills/_shared/scripts/openfoam_env.py discover

$env:EASYFOAM_OPENFOAM_BASHRC = "/opt/openfoam13/etc/bashrc"
$env:EASYFOAM_EXEC_BACKEND = "auto"
python skills/_shared/scripts/openfoam_env.py discover

Set the bashrc path to your actual OpenFOAM installation. On Windows, use the path visible inside WSL.

03Give your agent a task

From this repository root, load skills/SKILL.md and use EasyFoam Skills
to complete the following OpenFOAM v13 task.

CFD task:
<your simulation requirements>

Fixed run directory:
<your run directory>

The root skill routes the request. Missing decisive inputs are clarified before the case is released for authoring.

Read the full setup and usage guide →

The accompanying paper

EasyFoam: Skill-Oriented OpenFOAM Agents with Evidence-Driven Evolution introduces the research framework behind this skill library, including evidence-guided workflow repair and cross-task skill evolution. Read the paper for the benchmark design, evaluation protocol, and full experiments.

Paper ↗