# sumukhashridhar/flug architecture

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

- Interactive diagram: https://gitdiagram.com/sumukhashridhar/flug
- Repository: https://github.com/sumukhashridhar/flug

## Overview

##### Project type and purpose
- Fluidchen is a C++ scientific computing application—a computational‐fluid‐dynamics (CFD) solver framework that evolves from a sequential implementation to a parallel MPI‐enabled solver.
- The code base is structured as a modular, pipeline‐style solver: it reads a “case” file, builds the computational grid and data structures, applies discretization, solves the pressure and velocity fields, and writes results (via VTK) to disk.

##### File‐structure analysis
- Top‐level:
- CMakeLists.txt, .gitlab‐ci.yml, Doxyfile, formatting tools → build, CI, and documentation infrastructure.
- / and src/ → core solver modules (headers and implementations).
- example_cases/ → input data sets (.dat) and reference geometry (.pgm).
- results/ → placeholder for output directories (e.g. VTK files).
- tools/ → formatting scripts.
- Key modules (in include/ and src/):
- Case: parameter parsing and scenario setup
- Domain, Grid, Cell: mesh and geometry representation
- Fields: velocity, pressure data structures
- Discretization: stencil coefficients, time stepping
- PressureSolver: Poisson solver (sequential or parallel)
- Communication: MPI wrappers for halo‐exchange (once parallelized)

##### README insights
- Describes external dependencies: GCC/Clang, CMake, VTK (for I/O), and OpenMPI (for parallel runs).
- Builds a single executable (`fluidchen`) that takes a .dat case file and generates VTK output.

##### Main components and interactions (to capture
a. Fluidchen Executable (CLI)
- Input: .dat case file
- Parses into a Case object
b. Case Module
- Defines physical and numerical parameters
- Selects geometry file if present
c. Domain & Grid Module
- Reads geometry (.pgm)
- Builds mesh cells
d. Fields Module
- Initializes velocity and pressure arrays
e. Discretization Module
- Assembles finite‐volume matrices
- Calls PressureSolver
f. PressureSolver Module
- Solves linear system (sequential or MPI)
- Uses Communication module for ghost exchange in parallel
g. I/O Layer
- VTK library integration → writes .vtk files per time step
h. External Services
- MPI runtime (when enabled)
- VTK library (compile‐time dependency)

##### Architectural patterns and principles
- Pipeline pattern: sequential stages (Setup → Discretize → Solve → Output).
- Modular separation by responsibility (parsing, mesh, solver, I/O).
- Strategy/Factory in `Case` to pick different flow scenarios.
- (Future) Master‐Worker communication for domain decomposition with MPI.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Point
    fluidchen["fluidchen Executable"]:::setup

    %% Setup Layer
    subgraph "Setup Layer"
        Case["Case Module"]:::setup
        Domain["Domain Module"]:::setup
        Grid["Grid Module"]:::setup
        Cell["Cell Module"]:::setup
        Boundary["Boundary Module"]:::setup
        Fields["Fields Module"]:::setup
    end

    %% Compute Layer
    subgraph "Compute Layer"
        Discretization["Discretization Module"]:::compute
        PressureSolver["PressureSolver Module"]:::compute
        Communication["Communication Module"]:::compute
    end

    %% I/O Layer
    subgraph "I/O Layer"
        IO["VTK I/O Integration"]:::io
        InputCases["example_cases/"]:::io
        OutputDir["results/"]:::io
    end

    %% External Services
    subgraph "External Services"
        MPI["MPI Runtime"]:::external
        VTK["VTK Library"]:::external
    end

    %% Data Flow
    fluidchen -->|"reads .dat"| Case
    Case -->|"defines params"| Domain
    Domain -->|"builds mesh"| Grid
    Grid -->|"initializes cells"| Cell
    Cell -->|"apply boundaries"| Boundary
    Boundary -->|"setup fields"| Fields
    Fields -->|"initialize arrays"| Discretization
    Discretization -->|"assemble matrices"| PressureSolver
    PressureSolver -->|"solvePoisson()"| Communication
    Communication -->|"exchange halo"| PressureSolver
    PressureSolver -->|"update fields"| Fields
    Fields -->|"writeVTK()"| IO
    IO -->|"input files"| InputCases
    IO -->|"output files"| OutputDir

    %% External dependencies connections
    PressureSolver -.->|"parallel enabled"| MPI
    IO -.->|compile-time| VTK

    %% Click Events
    click fluidchen "https://github.com/sumukhashridhar/flug/blob/main/src/main.cpp"
    click Case "https://github.com/sumukhashridhar/flug/blob/main/include/Case.hpp"
    click Case "https://github.com/sumukhashridhar/flug/blob/main/src/Case.cpp"
    click Domain "https://github.com/sumukhashridhar/flug/blob/main/include/Domain.hpp"
    click Grid "https://github.com/sumukhashridhar/flug/blob/main/include/Grid.hpp"
    click Grid "https://github.com/sumukhashridhar/flug/blob/main/src/Grid.cpp"
    click Cell "https://github.com/sumukhashridhar/flug/blob/main/include/Cell.hpp"
    click Cell "https://github.com/sumukhashridhar/flug/blob/main/src/Cell.cpp"
    click Boundary "https://github.com/sumukhashridhar/flug/blob/main/include/Boundary.hpp"
    click Boundary "https://github.com/sumukhashridhar/flug/blob/main/src/Boundary.cpp"
    click Fields "https://github.com/sumukhashridhar/flug/blob/main/include/Fields.hpp"
    click Fields "https://github.com/sumukhashridhar/flug/blob/main/src/Fields.cpp"
    click Discretization "https://github.com/sumukhashridhar/flug/blob/main/include/Discretization.hpp"
    click Discretization "https://github.com/sumukhashridhar/flug/blob/main/src/Discretization.cpp"
    click PressureSolver "https://github.com/sumukhashridhar/flug/blob/main/include/PressureSolver.hpp"
    click PressureSolver "https://github.com/sumukhashridhar/flug/blob/main/src/PressureSolver.cpp"
    click Communication "https://github.com/sumukhashridhar/flug/blob/main/include/Communication.hpp"
    click Communication "https://github.com/sumukhashridhar/flug/blob/main/src/Communication.cpp"
    click InputCases "https://github.com/sumukhashridhar/flug/tree/main/example_cases/"
    click OutputDir "https://github.com/sumukhashridhar/flug/tree/main/results/"

    %% Styles
    classDef setup fill:#D6E4FF,stroke:#4287f5;
    classDef compute fill:#DFF7DF,stroke:#28a745;
    classDef io fill:#FFEAC3,stroke:#f5a142;
    classDef external stroke-dasharray: 5 5,fill:none,stroke:#666;
    class fluidchen,Case,Domain,Grid,Cell,Boundary,Fields setup
    class Discretization,PressureSolver,Communication compute
    class IO,InputCases,OutputDir io
    class MPI,VTK external
```
