# code-saturne/code_saturne architecture

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

- Interactive diagram: https://gitdiagram.com/code-saturne/code_saturne
- Repository: https://github.com/code-saturne/code_saturne

## Overview

##### Project Type and Purpose
- Code_Saturne is a large‐scale, open‐source Computational Fluid Dynamics (CFD) application designed for HPC.
- It provides both CLI and GUI front‐ends, Python scripting, a study‐manager module, and a modular C++/Fortran core engine with parallel MPI support.
- Dedicated physics modules (turbulence, combustion, radiative transfer, multiphase, atmospheric chemistry, groundwater, etc.) plug into the core finite‐volume (FVM) solver.

##### File Structure Analysis
Top‐level:
- bin/             → launcher scripts (bash, Python)
- python/          → Python API, GUI (Qt-based) and study‐manager
- src/             → core engine subdivided into folders (base services, FVM, algebraic solvers, physics submodules: atmo, cdo, turb, etc.)
- external/        → third‐party physics libraries (e.g., atmospheric chemistry)
- extras/          → coupling support (FMI, batch scripts, templates)
- data/            → default configuration, thermodynamic data, user scripts
- tests/           → unit and regression tests
- docs/            → user and developer guides, Doxygen, manpages
- sbin/, libple/…  → auxiliary installation, mesh‐location library

##### Key README Insights
- Emphasizes portability, MPI parallelism, variety of mesh and output formats (CGNS, MED, EnSight).
- In‐situ post‐processing via ParaView Catalyst and Melissa.
- Coupling with external EDF tools (SYRTHES, code_aster).

a. Main Components
1. User Interfaces
- CLI tools (bin/code_saturne.py, code_saturne.sh)
- Python GUI (python/code_saturne/gui) – Qt‐based (MVC pattern)
- Study‐manager (python/code_saturne/studymanager)
2. Python API Layer
- Case management, XML reader/writer, scripting glue
3. Core Engine
- C++/Fortran solver executable (src/apps/cs_solver, cs_io_dump)
- Layered modules:
- Base services (src/base): I/O, parallelism, logging, mesh handling
- FVM framework (src/fvm): grid data structures, discretization kernels
- Algebraic solvers (src/alge): matrix assembly, iterative solvers, CUDA/HIP accelerations
- Physics submodules (src/atmo, cdo, turb, comb, rayt, gwf, lagr, etc.)
- User extension hooks (src/user) and examples
4. Data & Case Configuration
- XML engine (python and C++ modules)
- Configuration files (data/setup.xml, extras templates)
5. External Services & Libraries
- MPI communication
- Mesh import/export (CGNS, MED, GMSH via MEDcoupling, HDF5)
- Linear algebra (PETSc, Hypre, MUMPS, AMGX)
- In‐situ post (Catalyst, Melissa)
- Coupling frameworks (FMI, SYRTHES, code_aster)
6. Post-Processing & Visualization
- File output modules (EnSight, CGNS, MED writers)
- In‐situ adapters

b. Relationships & Interactions
- UI ↔ Python API: user commands → case definition → XML and control files
- Python API → Core Engine: invokes solver binary with MPI, passing configuration
- Core Engine → Modules: orchestrates mesh import, discretization, solve loops, physics modules
- Core Engine ↔ External libs: calls MPI, solver libraries, I/O libraries, Catalyst/Melissa
- Core Engine → Output modules → Post‐processing data
- Python study‐manager → post‐processing scripts, plotting

c. Architectural Patterns & Principles
- Layered architecture: UI → API → Core → Modules → Libraries
- Plugin/modular physics modules loaded at runtime via XML configuration
- MVC pattern in Qt GUI
- Separation of concerns: mesh handling, numerical kernels, physics, I/O distinctly organized
- Parallel distributed-memory design via MPI and domain decomposition

d. Key Technologies
- C++17, CUDA (optional), Fortran for numerical kernels
- Python 3 with Qt5/4, PyQt or PySide
- XML for case description
- GNU Autotools / CMake build system
- MPI, PETSc, Hypre, MUMPS, AMGX
- CGNS, MED, HDF5, ParaView Catalyst, Melissa

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        CLI["CLI Tools"]:::ui
        GUI["Python GUI (Qt MVC)"]:::ui
        SM["Study-Manager"]:::ui
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        API["Python API Layer"]:::api
    end

    %% Execution Layer
    subgraph "Execution Layer"
        subgraph "Core Solver"
            CSolver["Core Solver Executable"]:::core
        end
        subgraph "Services & Framework"
            Base["Base Services"]:::core
            FVM["FVM Framework"]:::core
            Alge["Algebraic Solvers"]:::core
        end
        subgraph "Physics Modules"
            Atmo["Atmospheric Module"]:::core
            CDO["CDO Module"]:::core
            Turb["Turbulence Module"]:::core
            Comb["Combustion Module"]:::core
            Rayt["Radiative Transfer Module"]:::core
            GWF["Groundwater Module"]:::core
            Lagr["Lagrangian Module"]:::core
        end
        UserExt["User Extensions"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        XML["Default Case Config (XML)"]:::data
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        MPI["MPI & Build Integration"]:::infra
        ExtChem["External Atmo Chemistry"]:::infra
        Coupling["Coupling Frameworks"]:::infra
        Catalyst["Catalyst/Melissa Adapters"]:::infra
    end

    %% Connections
    CLI -->|"define case"| API
    GUI -->|"define case"| API
    SM  -->|"define case"| API
    API -->|"reads/writes"| XML
    API -->|"launch solver"| CSolver
    XML --> CSolver
    CSolver --> Base
    CSolver --> FVM
    CSolver --> Alge
    CSolver --> Atmo
    CSolver --> CDO
    CSolver --> Turb
    CSolver --> Comb
    CSolver --> Rayt
    CSolver --> GWF
    CSolver --> Lagr
    CSolver --> UserExt
    CSolver --> MPI
    Base --> ExtChem
    FVM --> Catalyst
    CSolver --> Coupling
    CSolver --> ExtChem

    %% Click Events
    click CLI "https://github.com/code-saturne/code_saturne/blob/master/bin/code_saturne.py.in"
    click CLI "https://github.com/code-saturne/code_saturne/blob/master/bin/code_saturne.sh.in"
    click GUI "https://github.com/code-saturne/code_saturne/tree/master/python/code_saturne/gui/"
    click SM "https://github.com/code-saturne/code_saturne/blob/master/python/code_saturne/base/cs_studymanager.py"
    click SM "https://github.com/code-saturne/code_saturne/tree/master/python/code_saturne/studymanager/"
    click API "https://github.com/code-saturne/code_saturne/tree/master/python/code_saturne/base/"
    click CSolver "https://github.com/code-saturne/code_saturne/blob/master/src/apps/cs_solver.cpp"
    click CSolver "https://github.com/code-saturne/code_saturne/blob/master/src/apps/cs_io_dump.cpp"
    click Base "https://github.com/code-saturne/code_saturne/tree/master/src/base/"
    click FVM "https://github.com/code-saturne/code_saturne/tree/master/src/fvm/"
    click Alge "https://github.com/code-saturne/code_saturne/tree/master/src/alge/"
    click Atmo "https://github.com/code-saturne/code_saturne/tree/master/src/atmo/"
    click CDO "https://github.com/code-saturne/code_saturne/tree/master/src/cdo/"
    click Turb "https://github.com/code-saturne/code_saturne/tree/master/src/turb/"
    click Comb "https://github.com/code-saturne/code_saturne/tree/master/src/comb/"
    click Rayt "https://github.com/code-saturne/code_saturne/tree/master/src/rayt/"
    click GWF "https://github.com/code-saturne/code_saturne/tree/master/src/gwf/"
    click Lagr "https://github.com/code-saturne/code_saturne/tree/master/src/lagr/"
    click UserExt "https://github.com/code-saturne/code_saturne/tree/master/src/user/"
    click XML "https://github.com/code-saturne/code_saturne/blob/master/data/setup.xml"
    click ExtChem "https://github.com/code-saturne/code_saturne/tree/master/external/atmo/"
    click MPI "https://github.com/code-saturne/code_saturne/blob/master/m4/cs_mpi.m4"
    click Coupling "https://github.com/code-saturne/code_saturne/tree/master/extras/FMI/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#005cbf,color:#004085;
    classDef api fill:#d4edda,stroke:#155724,color:#155724;
    classDef core fill:#fff3cd,stroke:#856404,color:#856404;
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#383d41;
    classDef infra fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
