How raymondyfei/apic2d works
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