# nakulbhat/golicuda architecture

> Architecture diagram of the GitHub repository nakulbhat/golicuda, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nakulbhat/golicuda
- Repository: https://github.com/nakulbhat/golicuda

## Overview

#### Purpose and Execution Model
`golicuda` is a native CUDA/C++ Conway’s Game of Life simulator. It runs either as an interactive GPU-rendered application or as a headless benchmark/simulation process. The executable entry point is `src/main.cu`, with shared application declarations in `include/main.h`.

#### Startup, CLI, and Configuration
Startup parses runtime choices for grid dimensions, generation limits, initialization, kernel mode, rendering, and synchronization. Command-line handling is isolated in `src/args.cu` / `include/args.h`; help output is in `src/help.cu` / `include/help.h`. These settings determine the simulation representation and dispatch path before GPU resources are initialized.

#### Simulation State and Initialization
The central state layer owns grid dimensions, active generation buffers, run/pause state, viewport data, and likely mode-specific resources. It is defined by `src/state.cu` and `include/state.h`. Initialization can populate the grid with GPU-generated random cells, explicit CLI cell coordinates, or an RLE pattern. Standard RLE parsing/loading is handled by `src/rle.cu` and `include/rle.h`, with `glider.rle` as a repository pattern input.

#### CUDA Compute Backend
`src/cuda_functions.cu` / `include/cuda_functions.h` contain the GPU-side simulation operations and kernel-dispatch boundary. Runtime selection supports element, row, column, shared-memory tiled, bitpacked, and atomic-bitpacked algorithms. All implement toroidal neighbor lookup and advance the board through ping-pong buffers: one device grid is read for a generation while the alternate grid receives its successor state, then buffer ownership swaps.

#### Representation Boundary
Byte-per-cell and 32-cells-per-word bitpacked modes are materially different data layouts. The state and CUDA layers must consistently select matching allocation, initialization, step kernel, and rendering logic. Bitpacked mode reduces device memory traffic; atomic bitpacked uses per-cell bit writes with CUDA atomics, making synchronization behavior part of the compute contract.

#### Rendering and Interactivity
The graphical path is implemented in `src/render.cu` / `include/render.h`. It integrates CUDA with an OpenGL pixel buffer object (PBO), allowing CUDA to write display pixels into GPU-shared graphics memory rather than copying through host memory. GLFW/GLEW and OpenGL 3.3 provide windowing, input, and presentation. The render loop processes pause, pan, zoom, reset, and VSync controls, then coordinates simulation stepping and frame presentation. Headless mode bypasses this graphics path.

#### Runtime and Build Dependencies
The project requires NVIDIA CUDA (sm_50+; Makefile defaults to sm_86), CUDA `curand` for random initialization, OpenGL 3.3+, GLFW3, and GLEW. `Makefile` is the primary native build entry point. Nix development/build metadata is also present in `flake.nix` and `flake.lock`.

#### Outputs and Measurement
Verbose interactive execution exposes FPS for kernel/render profiling; disabling VSync permits uncapped throughput measurements. Headless finite-generation runs provide a compute-focused execution path. Existing result artifacts, `results/gens_power.csv` and `results/res_scaling.csv`, indicate generation/power and resolution-scaling experiment outputs.

Main entry points: [`src/main.cu`](https://github.com/nakulbhat/golicuda/blob/main/src/main.cu) (Application entry), [`src/state.cu`](https://github.com/nakulbhat/golicuda/blob/main/src/state.cu) (Simulation state), [`src/cuda_functions.cu`](https://github.com/nakulbhat/golicuda/blob/main/src/cuda_functions.cu) (CUDA dispatch), [`src/args.cu`](https://github.com/nakulbhat/golicuda/blob/main/src/args.cu) (CLI parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build"]
  node_makefile["Native build<br/>Makefile"]
  node_nix["Nix environment<br/>Nix metadata<br/>[flake.nix]"]
end

subgraph group_runtime["Startup &amp; State"]
  node_main["Application entry<br/>CUDA executable<br/>[main.cu]"]
  node_args["CLI parser<br/>runtime options<br/>[args.cu]"]
  node_help["CLI help<br/>help output<br/>[help.cu]"]
  node_state["Simulation state<br/>state manager<br/>[state.cu]"]
  node_rle["RLE loader<br/>pattern parser<br/>[rle.cu]"]
end

subgraph group_compute["CUDA Simulation"]
  node_cuda{{"CUDA dispatch<br/>compute backend<br/>[cuda_functions.cu]"}}
  node_kernels{{"Life kernels<br/>CUDA kernels"}}
  node_pingpong[("Device ping-pong grids<br/>GPU state")]
end

subgraph group_graphics["Interactive Rendering"]
  node_render["Render loop<br/>CUDA/OpenGL renderer<br/>[render.cu]"]
  node_pbo[("CUDA/OpenGL PBO<br/>shared graphics buffer")]
  node_gl["GLFW/GLEW/OpenGL<br/>graphics runtime"]
end

subgraph group_outputs["Inputs &amp; Results"]
  node_pattern["Glider pattern<br/>RLE input<br/>[glider.rle]"]
  node_results["Benchmark results<br/>CSV artifacts<br/>[gens_power.csv]"]
end

node_makefile -->|"builds"| node_main
node_nix -.->|"development environment"| node_makefile
node_main -->|"parses options"| node_args
node_args -.->|"requests help"| node_help
node_args -->|"configures"| node_state
node_main -->|"initializes"| node_state
node_pattern -->|"loads"| node_rle
node_rle -->|"populates grid"| node_state
node_state -->|"selects representation and step mode"| node_cuda
node_cuda -->|"dispatches"| node_kernels
node_kernels -->|"reads and writes generations"| node_pingpong
node_cuda -->|"swaps active buffers"| node_state
node_main -->|"interactive mode"| node_render
node_render -->|"coordinates simulation steps"| node_cuda
node_render -->|"maps for CUDA pixels"| node_pbo
node_pbo -->|"presents"| node_gl
node_main -.->|"headless benchmark output"| node_results

click node_makefile "https://github.com/nakulbhat/golicuda/blob/main/Makefile"
click node_nix "https://github.com/nakulbhat/golicuda/blob/main/flake.nix"
click node_main "https://github.com/nakulbhat/golicuda/blob/main/src/main.cu"
click node_args "https://github.com/nakulbhat/golicuda/blob/main/src/args.cu"
click node_help "https://github.com/nakulbhat/golicuda/blob/main/src/help.cu"
click node_state "https://github.com/nakulbhat/golicuda/blob/main/src/state.cu"
click node_rle "https://github.com/nakulbhat/golicuda/blob/main/src/rle.cu"
click node_cuda "https://github.com/nakulbhat/golicuda/blob/main/src/cuda_functions.cu"
click node_render "https://github.com/nakulbhat/golicuda/blob/main/src/render.cu"
click node_pattern "https://github.com/nakulbhat/golicuda/blob/main/glider.rle"
click node_results "https://github.com/nakulbhat/golicuda/blob/main/results/gens_power.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_makefile,node_nix toneBlue
class node_main,node_args,node_help,node_state,node_rle toneAmber
class node_cuda,node_kernels,node_pingpong toneMint
class node_render,node_pbo,node_gl toneRose
class node_pattern,node_results toneIndigo
```

## Components

### Build

- [Native build](https://github.com/nakulbhat/golicuda/blob/main/Makefile): Makefile · Builds the CUDA/C++ executable with the target GPU architecture. · `Makefile`
- [Nix environment](https://github.com/nakulbhat/golicuda/blob/main/flake.nix): Nix metadata · `flake.nix`

### Startup & State

- [Application entry](https://github.com/nakulbhat/golicuda/blob/main/src/main.cu): CUDA executable · Selects interactive or headless execution. · `src/main.cu`
- [CLI parser](https://github.com/nakulbhat/golicuda/blob/main/src/args.cu): runtime options · Parses dimensions, generation limits, initialization, kernel, rendering, and synchronization choices. · `src/args.cu`
- [CLI help](https://github.com/nakulbhat/golicuda/blob/main/src/help.cu): help output · `src/help.cu`
- [Simulation state](https://github.com/nakulbhat/golicuda/blob/main/src/state.cu): state manager · Owns grid buffers, dimensions, run state, and viewport data. · `src/state.cu`
- [RLE loader](https://github.com/nakulbhat/golicuda/blob/main/src/rle.cu): pattern parser · `src/rle.cu`

### CUDA Simulation

- [CUDA dispatch](https://github.com/nakulbhat/golicuda/blob/main/src/cuda_functions.cu): compute backend · Selects and launches matching layout-specific simulation operations. · `src/cuda_functions.cu`
- **Life kernels**: CUDA kernels · Toroidal element, row, column, tiled, bitpacked, and atomic-bitpacked generation steps.
- **Device ping-pong grids**: GPU state · Alternating source and destination generation buffers.

### Interactive Rendering

- [Render loop](https://github.com/nakulbhat/golicuda/blob/main/src/render.cu): CUDA/OpenGL renderer · Handles input, stepping, and presentation for interactive mode. · `src/render.cu`
- **CUDA/OpenGL PBO**: shared graphics buffer · CUDA writes display pixels directly into GPU-shared OpenGL memory.
- **GLFW/GLEW/OpenGL**: graphics runtime · Provides windowing, input, and OpenGL 3.3 presentation.

### Inputs & Results

- [Glider pattern](https://github.com/nakulbhat/golicuda/blob/main/glider.rle): RLE input · `glider.rle`
- [Benchmark results](https://github.com/nakulbhat/golicuda/blob/main/results/gens_power.csv): CSV artifacts · Generation/power and resolution-scaling measurements. · `results/gens_power.csv`

## Connections

- Native build → Application entry: builds
- Nix environment → Native build: development environment
- Application entry → CLI parser: parses options
- CLI parser → CLI help: requests help
- CLI parser → Simulation state: configures
- Application entry → Simulation state: initializes
- Glider pattern → RLE loader: loads
- RLE loader → Simulation state: populates grid
- Simulation state → CUDA dispatch: selects representation and step mode
- CUDA dispatch → Life kernels: dispatches
- Life kernels → Device ping-pong grids: reads and writes generations
- CUDA dispatch → Simulation state: swaps active buffers
- Application entry → Render loop: interactive mode
- Render loop → CUDA dispatch: coordinates simulation steps
- Render loop → CUDA/OpenGL PBO: maps for CUDA pixels
- CUDA/OpenGL PBO → GLFW/GLEW/OpenGL: presents
- Application entry → Benchmark results: headless benchmark output