# mouadhaikal/cuda-barnes-hut architecture

> Architecture diagram of the GitHub repository mouadhaikal/cuda-barnes-hut, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mouadhaikal/cuda-barnes-hut
- Repository: https://github.com/mouadhaikal/cuda-barnes-hut

## Overview

##### Project Type and Purpose
- This is a high-performance, standalone N-body gravitational simulation application implementing the Barnes-Hut algorithm fully on the GPU (CUDA) with real-time visualization via Vulkan.  It also contains a CPU baseline for comparison and an ImGui interface for interactive control.

##### File Structure Analysis
- Top-level files:
- CMakeLists.txt & build.sh: build orchestration
- README.md, LICENSE, .gitignore
- assets/ (fonts), shaders/ (GLSL and SPIR-V binaries, compile script)
- src/: core source divided into:
- main.cpp, app.cpp/hpp: application entry, initialization, window & device setup
- common.* & log.hpp: shared utilities, logging
- simulation.*: generic simulation interface
- cpu/: cpuSimulation.* — brute-force CPU kernel for correctness/benchmark
- gpu/:
– barnesHutSystem.cu/.cuh: octree build & force compute kernels
– gpuSimulation.*: orchestrates kernel launches and data buffers
– kernels.cu/.cuh: supporting device functions
– renderer.*: Vulkan swapchain, pipeline, shader modules
– camera.*, inputManager.*: user interaction, view transforms
– gui.*: ImGui setup & frame rendering
- vendor/: third-party dependencies (e.g., ImGui)

##### README Insights
- Technologies: CUDA Toolkit, Vulkan SDK, GLFW3, ImGui, C++17
- Emphasizes CUDA-Vulkan interoperability (data stays on GPU) and optimized parallel algorithms

a. Main Components:
1. Application Layer
– App / main.cpp: initializes windowing (GLFW), Vulkan context, CUDA context, ImGui
2. Simulation Layer
– CPU Module: cpuSimulation (brute force)
– GPU Module:
- Morton code generation & parallel radix sort
- Octree builder (Karras algorithm)
- Force computation & integration (Barnes-Hut kernels)
3. Rendering Layer
– Vulkan Renderer: swapchain, pipelines, shader modules (compiled SPV)
– GUI: ImGui integration
4. Utility Layer
– Input Manager, Camera controller, Logging, Common utilities
5. Assets & Shaders
– fonts, shader source (.vert/.frag), compiled SPV binaries
6. Build & Deployment
– CMake, build.sh, external libs (vendor)

b. Relationships & Data Flow:
- At startup: App → initializes Vulkan & CUDA → loads shaders & assets
- Per frame:
1. InputManager captures user events → updates Camera & simulation parameters via GUI
2. GPU Simulation orchestrator
- All data resides in GPU buffers (CUdevicePointers / Vulkan buffer objects)
4. GUI draws over frame via ImGui (Vulkan backend)
5. Present swapchain
- Optionally, CPU Module can be invoked for baseline runs; its results may be compared or visualized

c. Architectural Patterns & Principles
- Pipeline processing: each simulation step is a stage with clear input/output buffers
- Shared GPU memory between CUDA and Vulkan (zero-copy interop)
- Modular separation: simulation core vs rendering vs UI vs utilities
- Explicit synchronization points between kernels and graphics queue (e.g., CUDA → Vulkan pipeline barriers)

d. Key Technologies & Frameworks
- CUDA (kernels, streams)
- Vulkan (rendering, SPIR-V shaders)
- GLFW3 (window & context creation)
- ImGui (immediate mode GUI)
- CMake (build configuration)
- GLSL & glslc (shader authoring & compilation)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment
    subgraph "Build & Deployment"
        CMake["CMakeLists.txt"]:::build
        BuildScript["build.sh"]:::build
    end

    %% Application Layer
    subgraph "Application Layer"
        Main["main.cpp"]:::app
        AppCPP["app.cpp"]:::app
        AppHPP["app.hpp"]:::app
    end

    %% Utility Layer
    subgraph "Utility Layer"
        CommonCPP["common.cpp"]:::util
        CommonHPP["common.hpp"]:::util
        LogHPP["log.hpp"]:::util
    end

    %% Simulation Interface
    SimulationIfaceCPP["simulation.cpp"]:::util
    SimulationIfaceHPP["simulation.hpp"]:::util

    %% CPU Simulation Module
    subgraph "CPU Simulation Module"
        CPUSimCPP["cpuSimulation.cpp"]:::compute
        CPUSimHPP["cpuSimulation.hpp"]:::compute
    end

    %% GPU Simulation Orchestrator
    subgraph "GPU Simulation Orchestrator"
        GPUSimCPP["gpuSimulation.cpp"]:::compute
        GPUSimHPP["gpuSimulation.hpp"]:::compute
    end

    %% GPU Compute Kernels
    subgraph "GPU Compute Kernels"
        KernelsCU["kernels.cu"]:::compute
        KernelsCUH["kernels.cuh"]:::compute
    end

    %% Barnes-Hut Octree & Force Kernels
    subgraph "Barnes-Hut System"
        BHCU["barnesHutSystem.cu"]:::compute
        BHCUH["barnesHutSystem.cuh"]:::compute
    end

    %% Rendering Layer
    subgraph "Rendering Layer"
        RendererCPP["renderer.cpp"]:::render
        RendererHPP["renderer.hpp"]:::render
    end

    %% UI & Interaction
    subgraph "UI & Interaction"
        CameraCPP["camera.cpp"]:::ui
        CameraHPP["camera.hpp"]:::ui
        InputCPP["inputManager.cpp"]:::ui
        InputHPP["inputManager.hpp"]:::ui
        GUICPP["gui.cpp"]:::ui
        GUIHPP["gui.hpp"]:::ui
    end

    %% Assets & Shaders
    subgraph "Assets & Shaders"
        Fonts["assets/fonts/"]:::io
        ShaderVert["shaders/shader.vert"]:::io
        ShaderFrag["shaders/shader.frag"]:::io
        SPVVert["shaders/vert.spv"]:::io
        SPVFrag["shaders/frag.spv"]:::io
        ShaderBuild["shaders/compile.sh"]:::build
    end

    %% Vendor
    Vendor["vendor/"]:::io

    %% Shared GPU Memory
    GPUBuffer["Shared GPU Buffer"]:::storage

    %% Simulation Pipeline Steps
    subgraph "GPU Kernel Pipeline" 
        BB["Bounding Box Kernel"]:::computeStage
        MC["Morton Code Generation"]:::computeStage
        RS["Parallel Radix Sort"]:::computeStage
        KF["Key Fusion Stage"]:::computeStage
        OB["Octree Build Kernel"]:::computeStage
        FI["Force & Integrate Kernels"]:::computeStage
    end

    %% Renderer Pipeline
    subgraph "Rendering Pipeline"
        Swapchain["Swapchain & Command Buffers"]:::renderStage
        DrawCalls["Draw Calls (Vulkan)"]:::renderStage
        Present["Present Frame"]:::renderStage
    end

    %% Startup Flow
    CMake --> BuildScript
    BuildScript --> Main
    Main -->|initializes| AppCPP
    AppCPP -->|uses| CommonCPP
    AppCPP -->|uses| LogHPP
    AppCPP -->|includes| SimulationIfaceHPP
    AppCPP -->|initializes Vulkan & CUDA| GPUBuffer

    %% Load Assets & Shaders
    AppCPP -->|loads| Fonts
    AppCPP -->|compiles| ShaderBuild
    ShaderBuild --> ShaderVert
    ShaderBuild --> ShaderFrag
    ShaderBuild --> SPVVert
    ShaderBuild --> SPVFrag

    %% Per-frame Flow
    InputCPP -->|captures events| CameraCPP
    InputCPP -->|sends to| GUICPP
    CameraCPP -->|updates| GPUBuffer
    GUICPP -->|updates parameters| GPUBuffer

    GPUBuffer -->|feeds| GPUSimCPP
    GPUSimCPP --> BB
    BB --> MC
    MC --> RS
    RS --> KF
    KF --> OB
    OB --> FI
    FI --> GPUBuffer

    %% Rendering
    GPUBuffer -->|vertex data| DrawCalls
    DrawCalls --> Swapchain
    Swapchain --> Present
    GUICPP -->|renders UI overlay| DrawCalls

    %% CPU fallback
    SimulationIfaceCPP --> CPUSimCPP
    CPUSimCPP -->|produces| CommonCPP

    %% Dependencies
    AppCPP --> Vendor
    GPUSimCPP --> KernelsCU
    GPUSimCPP --> BHCU
    GPUSimCPP -->|calls| KernelsCUH
    GPUSimCPP -->|calls| BHCUH
    RendererCPP --> SPVVert
    RendererCPP --> SPVFrag

    %% Click Events
    click Main "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/main.cpp"
    click AppCPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/app.cpp"
    click AppHPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/app.hpp"
    click CommonCPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/common.cpp"
    click CommonHPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/common.hpp"
    click LogHPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/log.hpp"
    click SimulationIfaceCPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/simulation.cpp"
    click SimulationIfaceHPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/simulation.hpp"
    click CPUSimCPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/cpu/cpuSimulation.cpp"
    click CPUSimHPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/cpu/cpuSimulation.hpp"
    click GPUSimCPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/gpuSimulation.cpp"
    click GPUSimHPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/gpuSimulation.hpp"
    click KernelsCU "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/kernels.cu"
    click KernelsCUH "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/kernels.cuh"
    click BHCU "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/barnesHutSystem.cu"
    click BHCUH "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/barnesHutSystem.cuh"
    click RendererCPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/renderer.cpp"
    click RendererHPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/renderer.hpp"
    click CameraCPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/camera.cpp"
    click CameraHPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/camera.hpp"
    click InputCPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/inputManager.cpp"
    click InputHPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/inputManager.hpp"
    click GUICPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/gui.cpp"
    click GUIHPP "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/src/gpu/gui.hpp"
    click ShaderVert "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/shaders/shader.vert"
    click ShaderFrag "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/shaders/shader.frag"
    click SPVVert "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/shaders/vert.spv"
    click SPVFrag "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/shaders/frag.spv"
    click ShaderBuild "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/shaders/compile.sh"
    click Fonts "https://github.com/mouadhaikal/cuda-barnes-hut/tree/main/assets/fonts/"
    click CMake "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/CMakeLists.txt"
    click BuildScript "https://github.com/mouadhaikal/cuda-barnes-hut/blob/main/build.sh"
    click Vendor "https://github.com/mouadhaikal/cuda-barnes-hut/tree/main/vendor/"

    %% Styles
    classDef build fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef app fill:#d1e7dd,stroke:#2f7a4f,stroke-width:1px
    classDef util fill:#cff4fc,stroke:#0c5460,stroke-width:1px
    classDef compute fill:#fde2e2,stroke:#a50e0e,stroke-width:1px
    classDef ui fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef io fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef storage fill:#d6d8db,stroke:#1b1e21,stroke-width:1px
    classDef computeStage fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef render fill:#d1cffc,stroke:#3f0071,stroke-width:1px
    classDef renderStage fill:#e2dffc,stroke:#4b0082,stroke-width:1px
```
