# projectphysx/fluidx3d architecture

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

- Interactive diagram: https://gitdiagram.com/projectphysx/fluidx3d
- Repository: https://github.com/projectphysx/fluidx3d

## Overview

Based on your project’s file structure and the extensive README, FluidX3D is a high‐performance computational fluid dynamics (CFD) simulator that uses the lattice Boltzmann method (LBM) optimized for both multi‐GPU and CPU devices. It is written in C++ with OpenCL for compute kernels and includes dedicated modules for rendering (using X11 on Linux and Win32 on Windows), file I/O (for exporting images and volumetric data), and even a separate OpenCL “subsystem” for graphics (raytracing and rasterization). In short, the project is a parallel, multi-GPU full-application that packs simulation, hardware communication (with domain decomposition), and real-time visualization components.

##### Main Components
- Simulation Core (LBM Engine):
– Contains core files such as lbm.cpp/lbm.hpp, kernel.cpp/hpp, and physics-related code (collision and streaming steps, force/torque computations, DDF-shifting, and multi-GPU domain decomposition).
– Relies on simulation parameters defined in files like defines.hpp and uses utilities (utilities.hpp) for common functions.

- OpenCL Compute Subsystem:
– The “src/OpenCL” folder holds OpenCL headers, libraries, and kernels that implement the heavy computations.
– This component abstracts the hardware compute layer; it manages kernel compilation, device/context management, memory buffers, and in-place streaming (Esoteric-Pull) for efficiency.

- Graphics and Visualization Module:
– Contains graphics.cpp/hpp and references to X11 in “src/X11” for Linux interactive graphics.
– Also integrates raytracing and rasterization kernels (both implemented in OpenCL) as described in the README.
– The “skybox” directory (with images like skybox8k.png) and lodepng files in “src” help in texture mapping and exporting images.

- Multi-GPU & Domain Decomposition Manager:
– Although not in a separate directory, the domain decomposition handling (swapping buffers and inter-device communication) is a key architectural element and is detailed in the README.

- File I/O & Export Utilities:
– Modules such as info.cpp/hpp, resource.rc, and parts of setup.cpp, along with lodepng, handle exporting data (images in PNG, VTK exports, etc.) and provide status, logging, or simulation setup information.

- Build and Configuration Infrastructure:
– Top-level files like FluidX3D.sln, FluidX3D.vcxproj, makefile, and make.sh indicate multiple build paths (Visual Studio solution for Windows and make-based builds for Linux/macos).

##### Relationships and Data Flow
- At startup, main.cpp and setup.cpp initialize the application.
- The Simulation Core then configures the simulation parameters, creates and manages OpenCL contexts (both for compute and for rendering) by calling into the OpenCL Compute Subsystem.
- The Compute Subsystem loads simulation kernels from the “src/OpenCL” directory and allocates device buffers for DDFs, density, velocity, etc.
- The Multi-GPU Manager divides the global simulation grid into domains, creates corresponding transfer buffers (using mechanisms described in the README) and handles inter-device data synchronization.
- For visualization, the Graphics Module fetches data from the GPU device buffers, runs interactive OpenCL-based rasterization and raytracing kernels, and then produces output frames.
- Meanwhile, File I/O modules export data (such as in .vtk and image formats) and log simulation status.
- The Build Infrastructure sits outside this flow but targets all of these modules and ensures cross-platform compatibility.

##### Architectural Patterns & Principles
- Clearly separate simulation (compute) logic from the presentation (graphics) layer.
- Use abstraction layers: the OpenCL Engine abstracts hardware details, and the Multi-GPU Manager encapsulates domain decomposition and PCIe communication.
- In-place streaming and memory efficiency optimizations (for instance, the “Esoteric-Pull” algorithm) in the simulation core.
- Data flows occur from main initialization to compute kernels (via simulation core), then outward to visualization and export—coupled with synchronization points for multi-GPU communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application Initialization"
        A["Main Application Initialization (main.cpp/setup.cpp)"]:::init
    end

    subgraph "Simulation & Compute Layer"
        B["Simulation Core (LBM Engine)"]:::simulation
        C["OpenCL Compute Engine"]:::opencl
        D["Multi-GPU Manager/Domain Decomposition"]:::multiGPU
    end

    subgraph "Visualization & Export Layer"
        E["Graphics & Visualization Module"]:::graphics
        F["File I/O & Export Module"]:::fileio
    end

    subgraph "Build/Configuration Infrastructure"
        G["Build & Config Infrastructure"]:::build
    end

    A -->|"initializes"| B
    B -->|"launches_kernel_via"| C
    C -->|"manages_GPU_buffers"| D
    B -->|"provides_data_to"| E
    D -->|"synchronizes_with"| E
    E -->|"renders_and_exports"| F
    A ---|"built_with"| G

    classDef init fill:#f9d29d,stroke:#333,stroke-width:2px;
    classDef simulation fill:#a1c4fd,stroke:#333,stroke-width:2px;
    classDef opencl fill:#c3f584,stroke:#333,stroke-width:2px;
    classDef multiGPU fill:#f7c6c7,stroke:#333,stroke-width:2px;
    classDef graphics fill:#fcd1a1,stroke:#333,stroke-width:2px;
    classDef fileio fill:#d1f7c4,stroke:#333,stroke-width:2px;
    classDef build fill:#a1f0f7,stroke:#333,stroke-width:2px;

    click B "https://github.com/projectphysx/fluidx3d/blob/master/src/lbm.cpp"
    click B "https://github.com/projectphysx/fluidx3d/blob/master/src/lbm.hpp"
    click B "https://github.com/projectphysx/fluidx3d/blob/master/src/kernel.cpp"
    click B "https://github.com/projectphysx/fluidx3d/blob/master/src/kernel.hpp"
    click B "https://github.com/projectphysx/fluidx3d/blob/master/src/defines.hpp"
    click B "https://github.com/projectphysx/fluidx3d/blob/master/src/utilities.hpp"

    click C "https://github.com/projectphysx/fluidx3d/tree/master/src/OpenCL"
    click C "https://github.com/projectphysx/fluidx3d/blob/master/src/OpenCL/include/CL/opencl.hpp"

    click E "https://github.com/projectphysx/fluidx3d/blob/master/src/graphics.cpp"
    click E "https://github.com/projectphysx/fluidx3d/blob/master/src/graphics.hpp"
    click E "https://github.com/projectphysx/fluidx3d/tree/master/src/X11"
    click E "https://github.com/projectphysx/fluidx3d/tree/master/skybox"

    click F "https://github.com/projectphysx/fluidx3d/blob/master/src/info.cpp"
    click F "https://github.com/projectphysx/fluidx3d/blob/master/src/info.hpp"
    click F "https://github.com/projectphysx/fluidx3d/blob/master/src/resource.rc"
    click F "https://github.com/projectphysx/fluidx3d/blob/master/src/setup.cpp"
    click F "https://github.com/projectphysx/fluidx3d/blob/master/src/setup.hpp"
    click F "https://github.com/projectphysx/fluidx3d/blob/master/src/lodepng.cpp"
    click F "https://github.com/projectphysx/fluidx3d/blob/master/src/lodepng.hpp"

    click G "https://github.com/projectphysx/fluidx3d/blob/master/FluidX3D.sln"
    click G "https://github.com/projectphysx/fluidx3d/blob/master/FluidX3D.vcxproj"
    click G "https://github.com/projectphysx/fluidx3d/blob/master/make.sh"
    click G "https://github.com/projectphysx/fluidx3d/tree/master/makefile"
```
