# flamegpu/flamegpu2 architecture

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

- Interactive diagram: https://gitdiagram.com/flamegpu/flamegpu2
- Repository: https://github.com/flamegpu/flamegpu2

## Overview

##### Main Components

a) Core Library Components:
- Model Definition Layer
- AgentDescription
- ModelDescription
- EnvironmentDescription
- MessageDescription
- FunctionDescription
- Runtime Layer
- CUDA Execution Engine
- Agent Management System
- Message Communication System
- Environment Management
- Simulation Control
- CUDASimulation
- CUDAEnsemble
- MPI Distribution System

b) Interface Components:
- C++/CUDA API
- Python Bindings (via SWIG)
- Visualization System
- I/O Systems (JSON/XML)

##### Component Relationships

- User Code → Model Definition Layer (model configuration)
- Model Definition Layer → Runtime Layer (compilation/preparation)
- Runtime Layer → CUDA Execution Engine (execution)
- Runtime Layer ↔ Agent Management System (data flow)
- Runtime Layer ↔ Message Communication System (agent communication)
- Runtime Layer ↔ Environment Management (global state)

##### Architectural Patterns

Key patterns:
- Layer separation between model definition and execution
- Agent-based modeling patterns
- CUDA-based parallel execution patterns
- Message-passing communication patterns

##### Detailed Component Breakdown

Model Definition Layer:
**ModelDescription**
- AgentDescription(s)
- Variables
- Functions
- States
- MessageDescription(s)
- Variables
- Communication Patterns
- EnvironmentDescription
- Global Properties

Runtime Layer:
**CUDASimulation**
- Agent Management
- State Lists
- Variable Arrays
- Message Systems
- Spatial
- Discrete
- Brute Force
- Environment
- Properties

##### Performance Components

Optimization elements:
- CUDA memory management
- Message sorting and spatial partitioning
- Agent state management
- Parallel execution patterns

##### Hardware Interface Layer

This architecture emphasizes FLAME GPU 2's core strength as a high-performance agent-based modeling system while showing its flexibility in supporting multiple programming interfaces and execution modes.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style definitions
    classDef interface fill:#90EE90,stroke:#333,stroke-width:2px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:2px
    classDef runtime fill:#FFE4B5,stroke:#333,stroke-width:2px
    classDef execution fill:#FFA07A,stroke:#333,stroke-width:2px
    classDef hardware fill:#D3D3D3,stroke:#333,stroke-width:2px

    %% Interface Layer
    subgraph InterfaceLayer
        CAPI["C++/CUDA API"]:::interface
        PythonAPI["Python Bindings"]:::interface
        VIS["Visualization System"]:::interface
        IO["I/O Systems"]:::interface
    end

    %% Model Definition Layer
    subgraph ModelDefinition
        MD["Model Description"]:::core
        AD["Agent Description"]:::core
        ED["Environment Description"]:::core
        FD["Function Description"]:::core
        MsgD["Message Description"]:::core
    end

    %% Runtime Layer
    subgraph RuntimeLayer
        CudaExec["CUDA Execution Engine"]:::runtime
        AgentMgmt["Agent Management System"]:::runtime
        MsgComm["Message Communication System"]:::runtime
        EnvMgmt["Environment Management"]:::runtime
    end

    %% Message Systems
    subgraph MessageSystems
        BruteForce["Brute Force"]:::runtime
        Spatial2D["Spatial 2D"]:::runtime
        Spatial3D["Spatial 3D"]:::runtime
        Array["Message Array"]:::runtime
    end

    %% Simulation Control
    subgraph SimControl
        CUDASim["CUDA Simulation"]:::execution
        CUDAEns["CUDA Ensemble"]:::execution
        MPI["MPI Distribution"]:::execution
    end

    %% Hardware Layer
    subgraph HardwareLayer
        GPU["GPU Hardware"]:::hardware
    end

    %% Relationships
    CAPI & PythonAPI & VIS & IO --> ModelDefinition
    ModelDefinition --> RuntimeLayer
    RuntimeLayer --> SimControl
    SimControl --> GPU
    MsgComm --> MessageSystems
    MessageSystems --> GPU
    
    %% Click events
    click CAPI "https://github.com/FLAMEGPU/FLAMEGPU2/blob/master/include/flamegpu/runtime/HostAPI.h"
    click PythonAPI "https://github.com/FLAMEGPU/FLAMEGPU2/tree/master/swig/python/"
    click VIS "https://github.com/FLAMEGPU/FLAMEGPU2/tree/master/include/flamegpu/visualiser/"
    click IO "https://github.com/FLAMEGPU/FLAMEGPU2/tree/master/include/flamegpu/io/"
    click AD "https://github.com/FLAMEGPU/FLAMEGPU2/blob/master/include/flamegpu/model/AgentDescription.h"
    click MD "https://github.com/FLAMEGPU/FLAMEGPU2/blob/master/include/flamegpu/model/ModelDescription.h"
    click ED "https://github.com/FLAMEGPU/FLAMEGPU2/blob/master/include/flamegpu/model/EnvironmentDescription.h"
    click FD "https://github.com/FLAMEGPU/FLAMEGPU2/blob/master/include/flamegpu/model/AgentFunctionDescription.h"
    click CudaExec "https://github.com/FLAMEGPU/FLAMEGPU2/blob/master/include/flamegpu/runtime/DeviceAPI.cuh"
    click AgentMgmt "https://github.com/FLAMEGPU/FLAMEGPU2/tree/master/include/flamegpu/runtime/agent/"
    click MsgComm "https://github.com/FLAMEGPU/FLAMEGPU2/tree/master/include/flamegpu/runtime/messaging/"
    click EnvMgmt "https://github.com/FLAMEGPU/FLAMEGPU2/tree/master/include/flamegpu/runtime/environment/"
    click BruteForce "https://github.com/FLAMEGPU/FLAMEGPU2/tree/master/include/flamegpu/runtime/messaging/MessageBruteForce/"
    click Spatial2D "https://github.com/FLAMEGPU/FLAMEGPU2/tree/master/include/flamegpu/runtime/messaging/MessageSpatial2D/"
    click Spatial3D "https://github.com/FLAMEGPU/FLAMEGPU2/tree/master/include/flamegpu/runtime/messaging/MessageSpatial3D/"
    click Array "https://github.com/FLAMEGPU/FLAMEGPU2/tree/master/include/flamegpu/runtime/messaging/MessageArray/"
    click CUDASim "https://github.com/FLAMEGPU/FLAMEGPU2/blob/master/include/flamegpu/simulation/CUDASimulation.h"
    click CUDAEns "https://github.com/FLAMEGPU/FLAMEGPU2/blob/master/include/flamegpu/simulation/CUDAEnsemble.h"

    %% Legend
    subgraph Legend
        L1["Interface Components"]:::interface
        L2["Core Components"]:::core
        L3["Runtime Components"]:::runtime
        L4["Execution Components"]:::execution
        L5["Hardware Components"]:::hardware
    end
```
