How m871-akram/black_hole_assembly works
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