A C++/Vulkan port of GustGrid, a tool for real-time PC airflow and thermal simulation
Report Bug
·
Request Feature
Table of Contents
GustGrid-Vulkan is a high-performance simulation engine built in C++ and Vulkan, leveraging Vulkan compute shaders to deliver real-time visualization of PC airflow and thermal dynamics. By harnessing GPU-accelerated fluid dynamics, it accurately models heat dissipation, fan performance, and airflow patterns within complex computer chassis geometries. Its intuitive graphical interface allows users to interactively adjust component layouts and cooling configurations, enabling rapid design iterations and optimized thermal management for any PC build.
This project is a C++ and Vulkan port of GustGrid, which was made in C++, OpenGL, and CUDA.
gustgrid-vulkan-clip.mp4
Features:
- Voxel-based Fluid & Thermal Simulation: Simulates a 64×256×128 voxel grid (volume pixels), with one GPU thread per voxel for maximum parallelism.
- All-in-one Physics: Handles semi-Lagrangian advection, fan thrust, buoyancy, wall interactions, pressure projection, dissipation, convection, and conduction all on the GPU.
- GPU-powered Pressure Solve: Computes divergence, performs Jacobi iterations in shared memory, subtracts pressure gradients, and enforces boundary conditions to ensure incompressibility.
- Advanced Heat Transfer: Models convective (wind-chill style) and conductive (solid/fluid-specific diffusivity) heat exchange, alongside explicit heat sources and neighbor dissipation.
- Interactive Vulkan Renderer: Real-time ray marching volume heatmaps, PBR shading for chassis components, and custom controls for dynamic scene adjustments.
See the open issues for a full list of proposed features (and known issues).
- Update Fan Visibility:
- Ray march from each fan’s world position to the voxel center. If any solid voxel blocks the ray, fan influence is disabled for that fan.
- Velocity Update (advectKernel):
- Advection: Backward-trace voxel positions along velocity, trilinearly sample previous velocity field.
- Wall Proximity: Scale advection strength by local solid proximity to simulate drag near chassis.
- Fan Thrust: Add axial and radial forces for voxels within a fan’s beam, attenuated by distance and alignment.
- Buoyancy: Apply upward acceleration for hot voxels using α·ΔT·g, capped for stability.
- Thermal Swirl & Back-pressure: Inject swirl in high ΔT regions and push fluid away from solid neighbors for hot pockets.
- Pressure Projection
- Divergence: Compute ∇·u using central differences, treating solids as zero-velocity.
- Jacobi Solver: Iterate: load local tile in shared memory, average neighbor pressures, subtract divergence·scale, blend with previous pressure (β-relaxation).
- Velocity Correction: Subtract ∇p from velocity, incorporate thermal-pressure tweaks at boundaries, and reflect velocities into solids.
- Temperature Advection & Dissipation
- Forward-trace Advection: Advect temperature using updated velocity, accumulate into tempSum/weightSum for weighted average.
- Dissipation: Compute per-voxel dissipation based on ΔT and velocity magnitude, then scatter dissipated energy into neighbors via tempSumDiss.
- Normalize & Combine: Compute advected temperature = tempSum/weightSum (or fallback), apply keepFraction, then add neighbor-dissipated heat.
- Convective & Conductive Heat Exchange
- Convective Heat: For |ΔT|>threshold, loop over neighbors, compute heat transfer coefficients based on relative velocity and flow alignment, clamp and apply ∂T.
- Conductive Diffusion: Apply finite-difference diffusion with solid vs fluid diffusivity multipliers, add explicit heat sources, and clamp T to [ambient−10, ambient+200].
For any platform, you need to first run after cloning the repository:
git submodule update --init --recursiveor, just clone the repository with the submodules:
git clone --recurse-submodules https://github.com/josephHelfenbein/gustgrid-vulkan.gitTo compile the project on MacOS, you'll need:
- Homebrew - Install Homebrew at https://brew.sh/
- Xcode Command Line Tools - Install Xcode Command Line Tools by running
xcode-select --installin the terminal. - Packages - In the terminal, install prerequisite packages by running in VSCode:
brew install molten-vk glfw glm ninja cmake libomp
export LDFLAGS="-L/opt/homebrew/opt/libomp/lib"
export CPPFLAGS="-I/opt/homebrew/opt/libomp/include"
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
export DYLD_LIBRARY_PATH="/usr/local/lib:/opt/homebrew/lib:$DYLD_LIBRARY_PATH"- Download and install Vulkan SDK from https://vulkan.lunarg.com/sdk/home
- Run the
MacOS Releaseconfiguration in VSCode.
To compile the project on Linux, use your distro’s packages (glslc is provided by shaderc). The project requires: C++ toolchain, CMake, Ninja, Git, pkg-config, Vulkan headers/loader/tools, GLFW, FreeType, and OpenMP (via GCC/libgomp). GLM is vendored and not required from the system (installing it is fine but optional).
-
Install packages
- Debian:
sudo apt update sudo apt install -y \ build-essential cmake ninja-build git pkg-config \ libvulkan-dev vulkan-tools \ glslc \ libglfw3-dev libfreetype6-dev # Optional: libglm-dev (GLM is vendored, not required)- Ubuntu:
sudo apt update sudo apt install -y \ build-essential cmake ninja-build git pkg-config \ libvulkan-dev vulkan-tools \ shaderc \ libglfw3-dev libfreetype6-dev \ vulkan-validationlayers # Optional: libglm-dev- Arch Linux:
sudo pacman -Syu --needed \ base-devel cmake ninja git pkgconf \ vulkan-headers vulkan-tools vulkan-icd-loader vulkan-validation-layers \ shaderc glfw freetype2 # Optional: glm- Fedora:
sudo dnf install -y \ gcc-c++ cmake ninja-build git pkgconf-pkg-config \ vulkan-headers vulkan-loader-devel vulkan-tools vulkan-validation-layers \ glslc glfw-devel freetype-devel # Optional: glm-devel- openSUSE:
sudo zypper install -y \ gcc-c++ cmake ninja git pkg-config \ vulkan-headers libvulkan1 Vulkan-Tools vulkan-validationlayers \ shaderc libglfw-devel freetype2-devel # Optional: glm-devel- RHEL:
sudo dnf install -y epel-release sudo dnf install -y \ gcc-c++ cmake ninja-build git pkgconf-pkg-config \ vulkan-headers vulkan-loader-devel vulkan-tools \ glslc glfw-devel freetype-devel # Optional: vulkan-validation-layers (if available in your enabled repos) # Optional: glm-devel
Notes:
- glslc should be available at /usr/bin/glslc after installing shaderc.
- GCC provides OpenMP (libgomp) by default; if you switch to clang, also install libomp-devel (name varies by distro).
-
Run the
Linux Releaseconfiguration in VSCode.
To compile the project on Windows, you'll need:
- Vulkan SDK - Download and install Vulkan SDK from https://vulkan.lunarg.com/sdk/home
- Visual Studio 2022 - Install Visual Studio 2022 at https://visualstudio.microsoft.com/downloads/ installing the
Desktop development with C++workload, and the componentsWindows 10/11 SDKandMSVC v143. - CMake - Install CMake at https://cmake.org/download/.
- vcpkg (for FreeType)
- Clone vcpkg (once):
- PowerShell:
git clone https://github.com/microsoft/vcpkg.git "$env:USERPROFILE\vcpkg"then& "$env:USERPROFILE\vcpkg\bootstrap-vcpkg.bat"
- PowerShell:
- Install FreeType for x64-MSVC:
& "$env:USERPROFILE\vcpkg\vcpkg.exe" install freetype:x64-windows
- Clone vcpkg (once):
- Run the
Windows Releaseconfiguration in VSCode.
Distributed under the MIT License. See LICENSE.txt for more information.
- Best README Template
- Vulkan Tutorial
- "(FREE) Gaming Pc" (https://skfb.ly/oGSTB) by Moonway 3D is licensed under Creative Commons Attribution (http://creativecommons.org/licenses/by/4.0/).
- "AM4 Cpu [ Free ]" (https://skfb.ly/pqx6R) by Igor.Jop is licensed under Creative Commons Attribution (http://creativecommons.org/licenses/by/4.0/).
- "Cooler Master CPU Cooler" (https://skfb.ly/oQV6T) by BlenderFace is licensed under Creative Commons Attribution (http://creativecommons.org/licenses/by/4.0/).
- "GeForce RTX 2060 Super Founders Edition" (https://skfb.ly/6Y7ww) by exéla is licensed under Creative Commons Attribution-NonCommercial (http://creativecommons.org/licenses/by-nc/4.0/).