# m871-akram/black_hole_assembly architecture

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

- Interactive diagram: https://gitdiagram.com/m871-akram/black_hole_assembly
- Repository: https://github.com/m871-akram/black_hole_assembly

## Overview

##### Project Type and Purpose
- This is a C++/OpenGL real-time physics simulation suite (not a web app or service), consisting of four simulations:
- BlackHole_space (3D ray tracer with gravitational lensing)
- Gravity_Grid (N-body particle simulation)
- BlackHole_curv (2D lensing)
- PhysicsASM_Demo (standalone x86-64 assembly physics routines)
- All simulations integrate:
- Hand-written x86-64 assembly (physics_asm.s + physics_asm.hpp) for vector ops, distances, forces
- OpenGL compute/vertex/fragment shaders for GPU acceleration
- External libraries: GLFW (window/input), GLEW (extensions), GLM (math)

##### File-Structure Analysis
- Top level:
- CMakeLists.txt & build_and_run.sh: build system entry points
- .cpp files (one per simulation) + common.hpp: C++ host code
- physics_asm.s / physics_asm.hpp: low-level physics library
- Shader files: geodesic.comp (compute shader), grid.vert / grid.frag
- Docs (.md): ARCHITECTURE.md, PHYSICS.md, ASSEMBLY.md outline internals
- Patterns:
- Modular simulation executables sharing a common physics interface
- Shared external dependencies managed by CMake
- Clear separation: host code (C++), compute shaders (GPU), assembly routines (CPU)

##### Key Insights from README
- The assembly module is a core “physics engine” used by all simulations for performance
- Each simulation has a distinct rendering pipeline stage (compute for ray tracing, grid rendering shaders for particles or 2D)
- Interactive controls layer sits in host C++ and maps user input to camera and simulation parameters

##### Main Components & Interactions
A. Build System
– CMake + build_and_run.sh → Produces executables (BlackHole_space, Gravity_Grid, BlackHole_curv, PhysicsASM_Demo)
B. Host Application (per simulation)
– User Input (keyboard/mouse via GLFW)
– Simulation Manager (C++ code in .cpp files)
– Shader Dispatcher (loads geodesic.comp or grid.vert/frag via GLEW+OpenGL API)
– Assembly Physics Interface (calls vector_distance_squared, gravitational_force, etc., via physics_asm.hpp → physics_asm.s)
C. GPU Compute Pipeline
– Compute Shader (geodesic.comp) for ray tracing or force accumulation
– Vertex/Fragment Shaders (grid.vert, grid.frag) for particle or 2D grid rendering
D. External Libraries
– GLFW (window & input)
– GLEW (OpenGL function loading)
– GLM (math types & utilities)
E. Hardware/OS
– GPU (OpenGL 3.3+) executes shaders
– CPU executes C++ host and assembly physics routines
– OS & drivers provide context (X11 forwarding, etc.)

- User Input → Host Application
- Host Application → Assembly Physics Interface → CPU execution
- Host Application → Shader Dispatcher → GPU execution
- GPU → Framebuffer → Display
- CMake → Builds Host + Assembly + Shaders → Executables

##### Architectural Patterns & Principles
- Modular executables sharing common physics library (assembly)
- Clear separation of concerns:
- User interface & control (GLFW)
- Physics computation (assembly & compute shaders)
- Rendering pipeline (OpenGL shaders)
- High-performance focus: SIMD in assembly, GPU offloading

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build System
    subgraph "Build System"
        CMake["CMakeLists.txt"]:::build
        BuildSh["build_and_run.sh"]:::build
    end
    CMake -->|"builds"| ExecGroup
    BuildSh -->|"builds"| ExecGroup

    %% Simulation Executables
    subgraph "Simulation Executables"
        ExecGroup((" ")):::empty
        BHs["BlackHole_space"]:::host
        GG["Gravity_Grid"]:::host
        BHc["BlackHole_curv"]:::host
        Demo["PhysicsASM_Demo"]:::host
    end
    ExecGroup --> BHs
    ExecGroup --> GG
    ExecGroup --> BHc
    ExecGroup --> Demo

    %% Source Files for Executables
    BHs --> BHsCode["black_hole_space.cpp"]:::host
    BHs --> BHsCommon["common.hpp"]:::host
    GG --> GGCode["gravity_grid.cpp"]:::host
    GG --> GGCommon["common.hpp"]:::host
    BHc --> BHcCode["black_hole_curv.cpp"]:::host
    BHc --> BHcCommon["common.hpp"]:::host
    Demo --> DemoCode["physics_asm_demo.cpp"]:::host
    Demo --> ASM_H["physics_asm.hpp"]:::assembly

    %% Host Application Components
    subgraph "Host Application" 
        UI["User Input\n(GLFW)"]:::host
        SM["Simulation Manager\n(.cpp)"]:::host
        SD["Shader Dispatcher\n(OpenGL)"]:::host
        API["Assembly Physics Interface"]:::assembly
        UI --> SM
        SM --> API
        SM --> SD
    end
    BHs --> UI
    GG --> UI
    BHc --> UI
    Demo --> UI

    %% GPU Pipeline
    subgraph "GPU Compute & Rendering Pipeline"
        CS["Compute Shader\n(geodesic.comp)"]:::shader
        VS["Vertex Shader\n(grid.vert)"]:::shader
        FS["Fragment Shader\n(grid.frag)"]:::shader
        CS --> Framebuffer["Framebuffer"]:::hw
        VS --> Framebuffer
        FS --> Framebuffer
        Framebuffer --> Display["Display"]:::hw
    end
    SD --> CS
    SD --> VS
    SD --> FS

    %% Assembly Module
    subgraph "Assembly Module"
        ASM["physics_asm.s\n(x86-64 SIMD)"]:::assembly
    end
    API --> ASM

    %% External Libraries
    subgraph "External Libraries"
        LibGLFW["GLFW"]:::external
        LibGLEW["GLEW"]:::external
        LibGLM["GLM"]:::external
    end
    UI --> LibGLFW
    SD --> LibGLEW
    SM --> LibGLM

    %% Hardware & OS
    subgraph "Hardware & OS"
        CPU["CPU"]:::hw
        GPU["GPU\n(OpenGL 3.3+)"]:::hw
        OS["OS & Drivers"]:::hw
    end
    ASM --> CPU
    CS --> GPU
    VS --> GPU
    FS --> GPU
    OS --> CPU
    OS --> GPU

    %% Click Events
    click CMake "https://github.com/m871-akram/black_hole_assembly/blob/master/CMakeLists.txt"
    click BuildSh "https://github.com/m871-akram/black_hole_assembly/blob/master/build_and_run.sh"
    click ASM "https://github.com/m871-akram/black_hole_assembly/blob/master/physics_asm.s"
    click ASM_H "https://github.com/m871-akram/black_hole_assembly/blob/master/physics_asm.hpp"
    click BHsCode "https://github.com/m871-akram/black_hole_assembly/blob/master/black_hole_space.cpp"
    click BHsCommon "https://github.com/m871-akram/black_hole_assembly/blob/master/common.hpp"
    click GGCode "https://github.com/m871-akram/black_hole_assembly/blob/master/gravity_grid.cpp"
    click GGCommon "https://github.com/m871-akram/black_hole_assembly/blob/master/common.hpp"
    click BHcCode "https://github.com/m871-akram/black_hole_assembly/blob/master/black_hole_curv.cpp"
    click BHcCommon "https://github.com/m871-akram/black_hole_assembly/blob/master/common.hpp"
    click DemoCode "https://github.com/m871-akram/black_hole_assembly/blob/master/physics_asm_demo.cpp"
    click CS "https://github.com/m871-akram/black_hole_assembly/blob/master/geodesic.comp"
    click VS "https://github.com/m871-akram/black_hole_assembly/blob/master/grid.vert"
    click FS "https://github.com/m871-akram/black_hole_assembly/blob/master/grid.frag"

    %% Styles
    classDef build fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef host fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef assembly fill:#FFA500,stroke:#333,stroke-width:1px
    classDef shader fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef hw fill:#000000,stroke:#FFF,stroke-width:1px,color:#FFF
    classDef empty fill:none,stroke:none;color:none
```
