cfd-knowledge-graph

An OWL2 ontology of the CFD simulation domain, with SPARQL query functions and a LangGraph agent for ontology-grounded recommendations.

Why This Exists

Vector similarity search retrieves documents that mention similar concepts. A SPARQL query on a typed ontology returns only nodes that satisfy an explicit logical constraint. For engineering domains where wrong recommendations have real consequences, the precision difference matters.

This repository tests that idea on a small CFD ontology: solvers, physical phenomena, numerical schemes, errors, fixes, case examples, and porous-media parameters.

Class Hierarchy

owl:Thing
+-- cfd:CFDSimulation
|   +-- cfd:OpenFOAMCase    [DamBreakCase]
|   +-- cfd:FluentCase      [LimestoneContactorCase]
+-- cfd:Solver
|   +-- cfd:SteadySolver    [simpleFoam]
|   +-- cfd:TransientSolver [pimpleFoam]
|   |   +-- cfd:MultiphaseSolver [interFoam]
|   +-- cfd:CompressibleSolver [rhoPimpleFoam]
+-- cfd:PhysicalPhenomenon
|   +-- cfd:Turbulence          [RANS_turbulence]
|   +-- cfd:MultiphaseFlow      [VOF_multiphase]
|   +-- cfd:SpeciesTransport
|   +-- cfd:PorousMedia         [DarcyForchheimer]
|   +-- cfd:ChemicalReaction    [CO2_dissolution]
+-- cfd:NumericalScheme
|   +-- cfd:ConvectionScheme    [vanLeer, linearUpwind, upwind]
|   +-- cfd:TemporalScheme      [Euler_ddt, backward_ddt]
|   +-- cfd:GradientScheme      [GaussLinear, GaussLimitedLinear]
+-- cfd:Error
|   +-- cfd:DivergenceError
|   +-- cfd:OscillationError
|   +-- cfd:ConvergencePlateau
+-- cfd:Fix
+-- cfd:Parameter

Object Properties

Property	Domain	Range	Meaning
cfd:recommended_for	Solver	PhysicalPhenomenon	Solver-to-physics recommendation.
cfd:may_cause_error	Solver	Error	Known failure mode for a solver.
cfd:is_fixed_by	Error	Fix	Corrective action for an error.
cfd:appropriate_for	NumericalScheme	PhysicalPhenomenon	Scheme suitability for a physics class.
cfd:models_phenomenon	CFDSimulation	PhysicalPhenomenon	Physics represented by a case.
cfd:uses_solver	CFDSimulation	Solver	Solver used by a case.
cfd:requires_parameter	PhysicalPhenomenon	Parameter	Required parameter for a physics model.

Figures

Full knowledge graph: solvers, phenomena, errors, fixes, cases.

Multi-hop SPARQL query: error to fix chain for interFoam, and porous-media parameters.

The useful result is not the image itself; it is the typed path behind it. A query can require the solver to be linked to an error, and the error to be linked to a fix. That constraint is stronger than retrieving a paragraph where the same words happen to appear.

SPARQL Queries

Function	What it returns
find_solver_for_phenomenon(phenomenon)	Solvers linked by cfd:recommended_for.
find_common_errors_for_solver(solver)	Errors linked by cfd:may_cause_error.
get_fix_for_error(error_type)	Fixes linked by cfd:is_fixed_by.
recommend_schemes_for_case(phenomenon)	Numerical schemes linked by cfd:appropriate_for.
get_parameters_for_porous_media()	Darcy-Forchheimer parameters and typical values.
get_error_fix_chain_for_solver(solver)	Multi-hop solver to error to fix chain.
list_all_solvers()	Solver individuals grouped by ontology class.

Quick Start

git clone https://github.com/abdou-elaoudi/cfd-knowledge-graph.git
cd cfd-knowledge-graph

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Run a SPARQL query without an API key:

python -c "
from knowledge_graph.sparql_queries import find_solver_for_phenomenon
for row in find_solver_for_phenomenon('VOF_multiphase'):
    print(row['solver'], row['label'])
"

Generate graph outputs:

python -m knowledge_graph.populate_graph
python -m knowledge_graph.graph_visualizer --output-dir reports/

Run the agent after configuring an LLM key:

cp .env.example .env
python -m agent.kg_agent

Real Use Cases

Dam-break case

The ontology encodes an OpenFOAM dam-break example using cfd:interFoam for cfd:VOF_multiphase. It also links interFoam to cfd:HighCourantNumber and cfd:FPE_divergence, with fixes such as cfd:ReduceMaxCo and cfd:ReduceTimeStep.

cfd:DamBreakCase  cfd:uses_solver        cfd:interFoam
cfd:interFoam     cfd:recommended_for    cfd:VOF_multiphase
cfd:interFoam     cfd:may_cause_error    cfd:HighCourantNumber
cfd:HighCourantNumber cfd:is_fixed_by    cfd:ReduceMaxCo

Limestone contactor case

The Fluent example represents species transport through porous media with CO2 dissolution and CaCO3 interaction. The graph links cfd:SpeciesPlateau to fixes such as lower species under-relaxation and improved source-term coupling.

cfd:LimestoneContactorCase cfd:models_phenomenon cfd:SpeciesTransport
cfd:LimestoneContactorCase cfd:models_phenomenon cfd:DarcyForchheimer
cfd:SpeciesPlateau         cfd:is_fixed_by       cfd:ReduceURF
cfd:DarcyForchheimer       cfd:requires_parameter cfd:param_porosity

Agent Example

$ python -m agent.kg_agent -q "My interFoam case diverged with NaN at t=0.67. What should I do?"

Agent: [queries sparql_error_fix_chain("interFoam")]

According to the knowledge graph, interFoam may cause FPE_divergence when the
Courant number is too high. The graph links that error to ReduceMaxCo and
ReduceTimeStep. Start by setting maxCo <= 0.5, enabling adaptive time stepping,
and checking the mesh before rerunning the case.

Tests

pytest tests/ -v

The tests cover ontology parsing, expected classes and individuals, SPARQL query functions, tool wrappers, and a mocked agent path. They do not require OpenFOAM, Fluent, or an API key.

Scope

Educational prototype. The ontology is intentionally small and should not be treated as a complete CFD knowledge base. Recommendations must be checked against the solver documentation, the case setup, and engineering judgement.

The ontology is also hand-built. That keeps the relationships inspectable, but it means coverage is limited to the concepts encoded in ontology/cfd_ontology.ttl.

Technical Context

At Forvis Mazars, I work with ontologies, LangGraph agents, and SPARQL over structured financial data. This repository applies the same pattern to CFD simulation concepts to compare typed graph queries with document retrieval in an engineering setting.

License

MIT. See LICENSE.