# terry-cyx/metaopenfoam architecture

> Architecture diagram of the GitHub repository terry-cyx/metaopenfoam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/terry-cyx/metaopenfoam
- Repository: https://github.com/terry-cyx/metaopenfoam

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Installer & Setup"
        EnvScript["install_metaopenfoam.sh"]:::core
        EnvYml["environment.yml"]:::core
        Req["requirements.txt"]:::core
        MakefileSetup["Makefile"]:::core
    end

    subgraph "CLI & Orchestrator"
        CLI["Makefile (run_main)"]:::core
        Orchestrator["OptMetaOpenfoam.py"]:::core
    end

    subgraph "Agent Pipeline"
        AgentMgr["Agent Manager\n(metaOpenfoam_v2.py)"]:::core

        subgraph "Agent Roles"
            Architect["Architect"]:::plugin
            TaskDivide["TaskDivider"]:::plugin
            InputWriterRole["InputWriter"]:::plugin
            RunnerRole["Runner"]:::plugin
            ReviewerRole["Reviewer"]:::plugin
        end

        subgraph "Agent Actions"
            ArchitectAct["ArchitectAction"]:::plugin
            TaskDivideAct["TaskDivideAction"]:::plugin
            InputWriterAct["InputWriterAction"]:::plugin
            RunnerAct["RunnerAction"]:::plugin
            ReviewerAct["ReviewerAction"]:::plugin
        end
    end

    subgraph "Configuration & Utilities"
        ConfigPath["config_path.py"]:::core
        PostList["postprocessing_list.py"]:::core
        QAModule["qa_module.py"]:::core
        FileSta["file_sta.py"]:::core
        Stats["Statistics.py"]:::core
        Tut["Tutorial_postprocess.py"]:::core
    end

    subgraph "Data Stores"
        Inputs["inputs/*.yaml"]:::datastore
        Database["database/"]:::datastore
        RunOut["run/"]:::datastore
    end

    subgraph "External Services"
        OpenFOAM["OpenFOAM"]:::external
        LLM["LLM API"]:::external
        ASpace["active_subspaces"]:::external
    end

    %% Connections
    User[/"User"/]:::external -->|uses| CLI
    CLI -->|invokes| Orchestrator
    Orchestrator -->|bootstraps| AgentMgr
    Orchestrator --> ConfigPath
    Orchestrator --> PostList
    Orchestrator --> QAModule
    Orchestrator --> FileSta
    Orchestrator --> Stats
    Orchestrator --> Tut

    AgentMgr --> ArchitectAct
    ArchitectAct -->|plans| TaskDivideAct
    TaskDivideAct -->|divides tasks| InputWriterAct
    InputWriterAct -->|writes case files| Inputs
    InputWriterAct --> RunOut
    TaskDivideAct --> LLM
    ArchitectAct --> LLM
    InputWriterAct --> ASpace
    InputWriterAct -->|calls| ASpace

    InputWriterAct --> RunnerAct
    RunnerAct -->|executes| OpenFOAM
    RunnerAct --> RunOut

    RunnerAct --> ReviewerAct
    ReviewerAct -->|evaluates| RunOut
    ReviewerAct --> Database
    ReviewerAct -->|may loop back| AgentMgr

    %% Click Events
    click EnvScript "https://github.com/terry-cyx/metaopenfoam/blob/main/install_metaopenfoam.sh"
    click EnvYml "https://github.com/terry-cyx/metaopenfoam/blob/main/environment.yml"
    click Req "https://github.com/terry-cyx/metaopenfoam/blob/main/requirements.txt"
    click MakefileSetup "https://github.com/terry-cyx/metaopenfoam/tree/main/Makefile"
    click CLI "https://github.com/terry-cyx/metaopenfoam/tree/main/Makefile"
    click Orchestrator "https://github.com/terry-cyx/metaopenfoam/blob/main/src/OptMetaOpenfoam.py"
    click AgentMgr "https://github.com/terry-cyx/metaopenfoam/blob/main/src/metaOpenfoam_v2.py"
    click Architect "https://github.com/terry-cyx/metaopenfoam/blob/main/src/roles/Architect.py"
    click TaskDivide "https://github.com/terry-cyx/metaopenfoam/blob/main/src/roles/TaskDivide.py"
    click InputWriterRole "https://github.com/terry-cyx/metaopenfoam/blob/main/src/roles/InputWriter.py"
    click RunnerRole "https://github.com/terry-cyx/metaopenfoam/blob/main/src/roles/Runner.py"
    click ReviewerRole "https://github.com/terry-cyx/metaopenfoam/blob/main/src/roles/Reviewer.py"
    click ArchitectAct "https://github.com/terry-cyx/metaopenfoam/blob/main/src/actions/ArchitectAction.py"
    click TaskDivideAct "https://github.com/terry-cyx/metaopenfoam/blob/main/src/actions/TaskDivideAction.py"
    click InputWriterAct "https://github.com/terry-cyx/metaopenfoam/blob/main/src/actions/InputWriterAction.py"
    click RunnerAct "https://github.com/terry-cyx/metaopenfoam/blob/main/src/actions/RunnerAction.py"
    click ReviewerAct "https://github.com/terry-cyx/metaopenfoam/blob/main/src/actions/ReviewerAction.py"
    click ConfigPath "https://github.com/terry-cyx/metaopenfoam/blob/main/src/config_path.py"
    click PostList "https://github.com/terry-cyx/metaopenfoam/blob/main/src/postprocessing_list.py"
    click QAModule "https://github.com/terry-cyx/metaopenfoam/blob/main/src/qa_module.py"
    click FileSta "https://github.com/terry-cyx/metaopenfoam/blob/main/src/file_sta.py"
    click Stats "https://github.com/terry-cyx/metaopenfoam/blob/main/src/Statistics.py"
    click Tut "https://github.com/terry-cyx/metaopenfoam/blob/main/src/Tutorial_postprocess.py"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5;
    classDef external fill:#c8e6c9,stroke:#388e3c;
    classDef datastore fill:#fff9c4,stroke:#f9a825;
    classDef plugin stroke-dasharray: 5 5,fill:#fff;
    classDef pluginLabel fill:#fff,stroke:#000;
    class User external
```
