How terry-cyx/metaopenfoam works
Project Type and Purpose
• MetaOpenFOAM is an LLM-based multi-agent orchestration framework for automating CFD simulation and post-processing with OpenFOAM.
• It provides a one-click installer, a YAML-driven input configuration, and a chain-of-thought agent pipeline (Architect, TaskDivider, InputWriter, Runner, Reviewer) built on MetaGPT and active_subspaces.
File Structure Analysis
• Top-level:
• install_metaopenfoam.sh, Makefile, environment.yml, requirements.txt – install & build scripts
• active_subspaces/ – dependency library for dimension-reduction methods
• inputs/ – YAML case definitions for different CFD scenarios
• database/ – placeholder for simulation metadata (initialized by the pipeline)
• run/ – placeholder for run artifacts
• src/ – core MetaOpenFOAM code
• src/ hierarchy:
• actions/ – implementations of agent behaviors (ArchitectAction, TaskDivideAction, etc.)
• roles/ – agent role definitions (Architect, TaskDivide, InputWriter, Runner, Reviewer)
• utility scripts (OptMetaOpenfoam.py, Statistics.py, file_sta.py, etc.) for orchestration, QA, post-processing
• Configuration: config_path.py, postprocessing_list.py, qa_module.py
• Tutorials & tests exist but are peripheral to core architecture.
Key Insights from README
• One-click installer sets up Conda env, installs dependencies (MetaGPT, active_subspaces), and compiles MetaOpenFOAM.
• Users configure a YAML (inputs/*.yaml), set Case_input in Makefile, then run make and make run_main.
• The pipeline bootstraps a database, spins up agents that coordinate the CFD workflow via LLM calls to Deepseek or OpenAI, and drives OpenFOAM commands.
a. Main Components
1. Installer & Environment Setup
2. CLI / Makefile Interface
3. Orchestrator (OptMetaOpenfoam.py)
4. Agent Manager (MetaGPT-based multi-agent runtime)
5. Agent Roles & Actions
– Architect: plans simulation chain
– TaskDivider: decomposes tasks
– InputWriter: generates OpenFOAM case files from YAML
– Runner: executes OpenFOAM solvers
– Reviewer: evaluates results, triggers post-processing
6. Data Stores
– inputs/*.yaml
– database (SQLite or JSON) for metadata
– run/ directory for logs & outputs
7. External Systems
– OpenFOAM (CFD solver invoked via shell)
– LLM service (Deepseek or OpenAI API)
– active_subspaces library for sensitivity analysis
b. Relationships & Interactions
• User → CLI/Makefile → Orchestrator
• Orchestrator → Agent Manager → spawns Agents in sequence
• Each Agent uses Actions to read/write data:
• InputWriter reads YAML → writes case directory
• Runner calls OpenFOAM shell commands → captures logs/results
• Reviewer reads logs → stores metrics in database → may loop back
• Agent Manager issues LLM API calls (for chain-of-thought reasoning) and invokes active_subspaces functions as needed.
c. Architectural Patterns & Principles
• Multi-agent pipeline (chain-of-thought)
• Plugin-style Actions/Role separation for easy extension
• Configuration-as-code (YAML + Makefile)
• Clear separation between orchestration logic and domain logic (CFD, data analysis)
d. Key Technologies & Libraries
• Python 3.x, MetaGPT (LLM orchestration)
• active_subspaces (sensitivity analysis)
• OpenFOAM-10 (CFD executable)
• Conda environment management
• Deepseek/OpenAI APIs for embeddings & chat