AI for Engineering · OpenFOAM · Scientific Computing

OpenFOAM Case Intelligence Platform

A graph-driven engineering system designed to let an LLM inspect, reason about, inherit, and modify OpenFOAM simulation cases without consuming complete dictionary files as raw context.

OpenFOAMPythonFastAPILLMMCPGraph Representationn8n

Primary Language

Python

Domain

OpenFOAM / CFD

Interface

FastAPI + MCP

Status

Active Development

Motivation

The Problem

OpenFOAM cases are distributed across multiple dictionaries, fields, solver settings, numerical schemes, turbulence models, mesh definitions, and boundary conditions.

Giving an LLM the complete case directly is inefficient and makes precise modification difficult. The system therefore converts the case into a structural graph that an LLM can navigate before requesting any mutation.

This allows the language model to reason about the structure of the simulation first and retrieve detailed information only when it is needed.

System Design

Architecture

The system separates natural-language reasoning from deterministic simulation manipulation. The LLM decides what needs to change, while dedicated engineering layers determine how those changes are safely applied.

User

Natural-language engineering request

Chat Interface

Collects intent and simulation context

LLM Reasoning

Understands the requested case modification

Case Graph

Provides structural navigation of the OpenFOAM case

Delta Engine

Represents the planned case modifications

Mutation Layer

Applies deterministic dictionary changes

OpenFOAM Case

Updated and validated simulation case

Design Philosophy

Why not let the LLM edit files directly?

Problem

Large Context

Complete simulation cases contain large amounts of information that are irrelevant to most individual modifications.

Problem

Non-deterministic Editing

Allowing a language model to freely rewrite engineering configuration files makes correctness and validation difficult.

Solution

Controlled Mutation

The LLM identifies intent and graph paths, while dedicated tools retrieve and modify the exact engineering entries.

Core Components

Core Design

Case Graph

OpenFOAM dictionaries are represented as traversable structural nodes rather than being passed wholesale to the language model.

Abstract LLM Context

The language model initially sees names and relationships only. Detailed values are retrieved only when a specific graph path is selected.

Case Inheritance

A current case can inherit required structures from a compatible tutorial or donor case before any merge or mutation occurs.

Delta Layer

Requested changes are represented independently from the original case, allowing modifications to be reviewed, validated, and applied deterministically.

Execution

Example Workflow

01. User asks to change a simulation characteristic such as the turbulence model or solver family.
02. The system generates or loads the graph of the current case.
03. The LLM determines which structural areas of the graph are affected.
04. Missing structures can be inherited from a compatible tutorial case.
05. A delta describing the required changes is generated.
06. The execution layer applies the changes to the OpenFOAM dictionaries and validates the resulting case.

Implementation

What moves through the system

The system uses structured representations between the language model and the execution layer. This makes the reasoning layer easier to inspect and prevents uncontrolled edits to simulation files.

Case Graph

Structural representation of an OpenFOAM case, exposing dictionaries, sections, and entries as navigable paths.

{
  "case": "pitzDaily",
  "system": {
    "fvSchemes": {
      "divSchemes": {
        "div(phi,U)": "Gauss linearUpwind grad(U)"
      }
    }
  }
}

Mutation Request

The LLM does not rewrite files directly. It selects a target path and produces a structured modification intent.

{
  "path": "system/fvSchemes/divSchemes/div(phi,U)",
  "operation": "replace",
  "value": "Gauss upwind"
}

Delta Representation

Changes are represented separately from the source case so they can be inspected and validated before application.

{
  "case_id": "current-case",
  "changes": [
    {
      "path": "system/fvSchemes/divSchemes/div(phi,U)",
      "old": "Gauss linearUpwind grad(U)",
      "new": "Gauss upwind"
    }
  ]
}

Case Transformation

From engineering intent to a controlled case change

A modification travels through the system as structured intent. The reasoning layer determines the target, while the execution layer performs the actual dictionary mutation.

Before

Existing OpenFOAM Configuration

The current case uses the existing discretisation configuration in the fvSchemes dictionary.

divSchemes
{
    default         none;

    div(phi,U)
        Gauss linearUpwind grad(U);
}

Decision

Structured Modification

The reasoning layer identifies the exact graph path and generates a controlled modification request rather than rewriting the dictionary.

{
  "path": "system/fvSchemes/divSchemes/div(phi,U)",
  "operation": "replace",
  "value": "Gauss upwind"
}

After

Updated Dictionary

The execution layer applies the requested mutation to the target entry while leaving unrelated dictionary contents untouched.

divSchemes
{
    default         none;

    div(phi,U)
        Gauss upwind;
}

Engineering

Engineering Challenges

A major challenge is that OpenFOAM dictionaries do not always map cleanly to a unique path. Duplicate keywords and repeated structures require explicit resolution before deterministic mutation can occur.

Another challenge is context management. The LLM should have enough structural information to reason about a case without repeatedly ingesting large dictionary contents.

The architecture therefore separates reasoning, structural navigation, data retrieval, and file mutation into distinct layers.

Contribution

What I built

The project combines simulation-domain knowledge with software architecture, structured reasoning, and controlled execution. These are the main pieces I designed and implemented.

→

OpenFOAM case graph generation

→

Structural abstraction for LLM consumption

→

Graph-path based case navigation

→

Case inheritance workflow

→

Delta-based modification representation

→

Controlled dictionary mutation layer

→

FastAPI endpoints for case operations

→

MCP / chatbot integration path

Direction

Current Direction

The broader goal is to create an engineering assistant capable of understanding an existing simulation case, selecting compatible tutorial structures when required, planning modifications through a graph representation, and safely executing those changes through controlled tools.