# raymondyfei/apic2d architecture

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

- Interactive diagram: https://gitdiagram.com/raymondyfei/apic2d
- Repository: https://github.com/raymondyfei/apic2d

## Overview

##### Project type and purpose
- APIC2D is a C++‐based, cross‐platform educational tool illustrating the affine‐particle‐in‐cell algorithm for 2D fluid (water) simulation. It compiles via CMake for desktop (Windows/Mac/Linux), WebAssembly (via Emscripten), and uses Eigen for linear algebra, TBB (optional) for parallelism, and GLUT/FreeGLUT for OpenGL‐based visualization.

##### File structure
- Top‐level:
- CMakeLists.txt, .gitignore, LICENSE, README.md
- cmake/ – custom Find modules (FindFreeGLUT, FindTBB)
- /eigen – bundled Eigen matrix library (headers + tests)
- apic2d/ – core source tree
- apic2d subdirectories and files:
- main.cpp – entry point & loop
- fluidsim.cpp/.h – high‐level simulation controller
- kernel.cpp/.h – kernel weight computations (PIC, APIC, …)
- sorter.cpp/.h – particle‐to‐grid remapping order
- sparse_matrix.h – grid linear system abstractions
- pcg_solver.h – conjugate‐gradient solver
- blas_wrapper.h – BLAS interface via Eigen/TBB
- gluvi.cpp/.h & openglutils.cpp/.h – window creation, input, rendering utilities
- util.h – miscellaneous helpers (timers, logging)
- Build & deployment:
- CMake orchestrates dependency lookup (Eigen included, FindTBB, FindFreeGLUT), generates Visual Studio/Xcode/Unix makefiles, supports emcmake for WASM.

##### README for additional insights
- Describes multiple integration schemes (PIC, FLIP, RPIC, APIC, AFLIP, ASFLIP) toggled via an `integration_scheme` enum.
- Supports different ODE integrators for velocity (Euler, Ralston’s 2nd order, RK3, RK4).
- UI: interactive painting of velocity, camera pan/zoom with shift + mouse.

##### Components
a. Main components
1. Build & Deployment Layer
– CMake + cmake/Find*.cmake
– Emscripten toolchain (for WebAssembly)
2. Core Simulation Engine
– fluidsim module (simulation loop, time stepping)
– kernel module (weight interpolation)
– sorter module (particle‐grid indexing)
– solver module (PCG solver, sparse_matrix abstraction)
– integrator module (Euler, RK2, RK3, RK4 schemes)
3. Data Structures
– Particle data container (position, velocity, affine moment)
– Grid data (node velocities, pressures, mass)
4. Math & Parallelism
– Eigen (linear algebra, vector/matrix operations)
– Optional TBB (parallel_for for grid operations)
5. Visualization & UI
– gluvi (window/input abstraction)
– openglutils (shader setup, buffers, drawing)
6. External Dependencies
– GLUT/FreeGLUT (context creation, event loop)
– Emscripten runtime (when compiling to WASM)

b. Relationships and interactions
– Main.cpp initializes Build/Dependencies → constructs Simulation Engine + UI
– Per‐frame loop:
User Input → fluidsim/controller →
Particle‐to‐Grid (sorter + kernel) →
Grid operations (apply forces, boundary conditions, PCG solver) →
Grid‐to‐Particle update (kernel, affine moment) →
Integrator advances particle states →
UI/Rendering draws particles & grid
– Math calls (Eigen) wrap inside simulation & solver modules. Optional TBB parallelism invoked within heavy loops.

c. Architectural patterns / design principles
– Modular separation:
- Simulation logic vs. data storage vs. rendering vs. math
– Dependency injection via CMake find scripts for optional parallel backend (TBB) and visualization (GLUT)
– Single‐threaded or multi‐threaded compute paths selected at compile time
– Pluggable integration and interpolation schemes via enums and strategy‐like switches

d. Relevant technologies / frameworks
– CMake (build system + cross‐platform generators)
– Eigen (header‐only linear algebra)
– TBB (threading building blocks)
– FreeGLUT/GLUT (OpenGL context & input)
– Emscripten (WASM target)
– OpenGL (real‐time rendering)

##### Essential elements
- Clear component names (e.g., “FluidSim Controller”, “Kernel Interpolator”, “PCG Solver”)
- Build system node showing CMake → FindTBB / FindFreeGLUT → target
- Data flows for particle‐to‐grid and grid‐to‐particle transfers
- Render & input loop branching from the main simulation loop

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment Layer
    subgraph "Build & Deployment Layer"
        CMakeRoot["CMakeLists.txt"]:::build
        CMakeApic["apic2d/CMakeLists.txt"]:::build
        FindTBB["FindTBB.cmake"]:::build
        FindGLUT["FindFreeGLUT.cmake"]:::build
        emcmake["Emscripten Toolchain"]:::external
    end

    %% Core Simulation Engine
    subgraph "Core Simulation Engine"
        SimCtrl["FluidSim Controller"]:::core
        Kernel["Kernel Interpolator"]:::core
        Sorter["Sorter (Particle-to-Grid)"]:::core
        Solver["PCG Solver & SparseMatrix"]:::core
        Blas["BLAS/Eigen Wrapper"]:::core
        Integrator["Integrator Strategies"]:::core
    end

    %% Data Structures
    subgraph "Data Structures"
        PartArr["Particle Array"]:::data
        GridArr["Grid Array"]:::data
        Enums["MathDefs & Enums"]:::data
        Utils["Utilities (timers, logging)"]:::data
    end

    %% Visualization & UI
    subgraph "Visualization & UI"
        MainCPP["Main & Loop"]:::ui
        Gluvi["Gluvi (window & input)"]:::ui
        GLUtils["OpenGL Utils"]:::ui
    end

    %% Math & Parallelism
    subgraph "Math & Parallelism"
        Eigen["Eigen Library"]:::external
        TBB["TBB (optional)"]:::external
    end

    %% External Dependencies
    subgraph "External Dependencies"
        FreeGLUT["FreeGLUT/GLUT"]:::external
        Emscripten["Emscripten Runtime"]:::external
    end

    %% Connections
    MainCPP -->|initializes| SimCtrl
    MainCPP -->|renders via| GLUtils
    MainCPP -->|handles input via| Gluvi
    Gluvi -->|user input| SimCtrl

    SimCtrl -->|invoke| Sorter
    Sorter -->|particle-to-grid| PartArr
    Sorter -->|particle-to-grid| GridArr

    Sorter -->|uses| Kernel
    Kernel -->|weight interpolation| PartArr
    Kernel -->|weight interpolation| GridArr

    Kernel -->|setup linear system| Solver
    Solver -->|solve pressure| GridArr
    Solver -->|uses| Blas

    Solver -->|updates| GridArr
    SimCtrl -->|grid-to-particle| Kernel
    Kernel -->|interpolate| PartArr

    SimCtrl -->|advance states| Integrator
    Integrator -->|reads/writes| PartArr

    SimCtrl -->|render| GLUtils

    SimCtrl -->|math ops| Eigen
    Solver -->|parallel loops| TBB

    CMakeRoot -->|includes| FindTBB
    CMakeRoot -->|includes| FindGLUT
    CMakeApic -->|module config| cmake/FindTBB.cmake
    CMakeApic -->|module config| cmake/FindFreeGLUT.cmake

    CMakeRoot -->|emcmake| emcmake
    emcmake -->|produces| Emscripten

    FreeGLUT -->|provides| Gluvi

    %% Click Events
    click CMakeRoot "https://github.com/raymondyfei/apic2d/blob/master/CMakeLists.txt"
    click CMakeApic "https://github.com/raymondyfei/apic2d/blob/master/apic2d/CMakeLists.txt"
    click FindTBB "https://github.com/raymondyfei/apic2d/blob/master/cmake/FindTBB.cmake"
    click FindGLUT "https://github.com/raymondyfei/apic2d/blob/master/cmake/FindFreeGLUT.cmake"
    click SimCtrl "https://github.com/raymondyfei/apic2d/blob/master/apic2d/fluidsim.cpp"
    click Kernel "https://github.com/raymondyfei/apic2d/blob/master/apic2d/kernel.cpp"
    click Sorter "https://github.com/raymondyfei/apic2d/blob/master/apic2d/sorter.cpp"
    click Solver "https://github.com/raymondyfei/apic2d/blob/master/apic2d/pcg_solver.h"
    click Solver "https://github.com/raymondyfei/apic2d/blob/master/apic2d/sparse_matrix.h"
    click Blas "https://github.com/raymondyfei/apic2d/blob/master/apic2d/blas_wrapper.h"
    click PartArr "https://github.com/raymondyfei/apic2d/blob/master/apic2d/array1.h"
    click PartArr "https://github.com/raymondyfei/apic2d/blob/master/apic2d/array2.h"
    click PartArr "https://github.com/raymondyfei/apic2d/blob/master/apic2d/array2_utils.h"
    click Enums "https://github.com/raymondyfei/apic2d/blob/master/apic2d/math_defs.h"
    click Utils "https://github.com/raymondyfei/apic2d/blob/master/apic2d/util.h"
    click Gluvi "https://github.com/raymondyfei/apic2d/blob/master/apic2d/gluvi.cpp"
    click GLUtils "https://github.com/raymondyfei/apic2d/blob/master/apic2d/openglutils.cpp"
    click MainCPP "https://github.com/raymondyfei/apic2d/blob/master/apic2d/main.cpp"
    click Eigen "https://github.com/raymondyfei/apic2d/tree/master/include/eigen/"
    click TBB "https://github.com/raymondyfei/apic2d/blob/master/cmake/FindTBB.cmake"
    click FreeGLUT "https://github.com/raymondyfei/apic2d/blob/master/cmake/FindFreeGLUT.cmake"

    %% Styles
    classDef build fill:#9c27b0,stroke:#333,stroke-width:1px,color:#fff
    classDef core fill:#ffeb3b,stroke:#333,stroke-width:1px
    classDef data fill:#8bc34a,stroke:#333,stroke-width:1px
    classDef ui fill:#ff9800,stroke:#333,stroke-width:1px
    classDef external fill:#03a9f4,stroke:#333,stroke-width:1px,color:#fff
```
