# johnbuffer/pendulum-neat architecture

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

- Interactive diagram: https://gitdiagram.com/johnbuffer/pendulum-neat
- Repository: https://github.com/johnbuffer/pendulum-neat

## Overview

Based on an analysis of the complete file tree and the brief README, it is clear that “Pendulum NEAT” is a C++ simulation project that integrates a custom game or simulation engine with a NEAT (NeuroEvolution of Augmenting Topologies) module. In essence, the project is structured into two main layers: the underlying engine framework (handling low-level tasks like entity management, rendering, windowing, and resource management) and the user-level modules (which implement the pendulum simulation, physics, and training via a NEAT algorithm).

##### Main Components
a. Engine Framework (located in src/engine):
- Core Systems: This includes the entity management system (files like entity.cpp, entity.hpp, entity_manager.hpp, and system.hpp), timing (timer.cpp/hpp), and overall engine control (engine.cpp/hpp). This subsystem is responsible for running the simulation loop, managing entities, and ensuring component interactions.
- Common Utilities: Encompassing math utilities, the thread pool (under common/thread_pool), and general helper components (e.g., common/utils, math, and binary I/O). These utilities provide foundational support across the engine.
- Rendering and Windowing: The rendering module (src/engine/render) and window handling (src/engine/window) handle drawing the simulation and managing the application’s graphical context and viewport.
- Resource Management: Found in src/engine/resources, this component loads and manages simulation assets needed by the engine.

b. User-Level Modules (located in src/user):
- NEAT Algorithm Module: Under src/user/common/neat, all components (such as activation functions, genome, network, mutator, network generator) encapsulate the evolutionary algorithm that evolves neural networks to control the pendulum.
- Physics Simulation: The physics-related files (under src/user/common/physic) define how the pendulum and other objects behave; these include definitions for constraints, objects, matrices, and anchors.
- Rendering and Visualization for Simulation: In src/user/common/render and parts of src/user/training/render, code related to displaying charts (bar graphs, line charts), agent rendering, network visualization, and other UI elements are provided to monitor simulation state.
- Training and Simulation Control: Located in src/user/training, these files (such as evolver.hpp, scene.hpp, training_state.hpp, and training/render components) set up the simulation experiments, control the training iterations, and manage state transitions in the simulation environment.

c. External Libraries:
- GLM (located in the lib folder): This math library is extensively used for vector, matrix, and geometric operations across the engine and physics modules. It supports the mathematical computations needed for both physics simulation and rendering.

##### Out Relationships and Data Flow
- At the heart, the Engine Framework manages the simulation loop. It initializes the core systems and resource managers.
- The User-Level “Training” module sets up simulation scenes (e.g., pendulum environment), configuring physics properties and linking them to NEAT’s evolving neural networks.
- The NEAT module uses its evolutionary routines (genome, network, mutator functions) to generate candidate controllers for the pendulum.
- The Physics Simulation sub-system computes dynamics (collisions, constraints, and motion) and provides updated state information.
- The Rendering module, using data from both the engine’s state and the training feedback, visualizes the pendulum’s motion, training statistics (charts, graphs), and potentially the network structure.
- Communication occurs in a layered approach: the Training module interacts with both the NEAT module for evolutionary decision-making and with the engine’s core for physics updates and rendering.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The clear division between the engine framework (handling “how” things are executed) and user-level simulation/training (specifying “what” the simulation does) is a principal design guideline.
- Modularity: Components are organized in directories such as “core”, “render”, “resources”, and “common” for utilities, promoting modular design and reusability.
- Entity-Component-System (ECS) Paradigm: The engine’s core (from files like entity_manager.hpp and system.hpp) suggests an ECS-style architecture that efficiently handles dynamic simulation objects.
- Use of External Libraries: The GLM library’s integration emphasizes a reliance on proven third-party math utilities for reliable mathematical computations.

##### Essential Elements
- Clear Labels: Each major subsystem or module (Engine Core, Rendering, Resource Management, NEAT Module, Physics Simulation, Training Controller, Visualization) should be clearly labeled.
- Notations: Optionally, add notes to indicate where design patterns (like ECS) are used for clarity.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Engine Framework"
        subgraph "Core Components"
            EUtil("Engine Common Utilities"):::engine
            ECore("Engine Core Systems"):::engine
        end
        ERes("Engine Resource Management"):::engine
        subgraph "Rendering & Windowing"
            ERender("Engine Rendering"):::engine
            EWindow("Engine Windowing"):::engine
        end
    end

    subgraph "User-Level Modules"
        NEAT("NEAT Algorithm Module"):::user
        Phys("Physics Simulation"):::user
        subgraph "Simulation Rendering and Visualization"
            VisCommon("Common Render"):::user
            VisTrain("Training Render"):::user
        end
        Train("Training and Simulation Control"):::user
    end

    External("External GLM Library"):::external

    %% Engine Framework internal interactions
    EUtil -->|"provides"| ECore
    ECore -->|"initializes"| ERes
    ECore -->|"invokes"| ERender
    ECore -->|"initiates"| EWindow
    ECore -->|"runs_loop"| Train

    %% Interactions between Engine and User Modules
    ERender -->|"renders"| VisCommon
    EWindow -->|"displays"| VisTrain

    %% User-Level Module interactions
    NEAT -->|"controls"| Phys
    Train -->|"manages"| NEAT
    Train -->|"updates"| Phys
    Phys -->|"state_update"| VisCommon
    Phys -->|"state_update"| VisTrain
    Train -->|"triggers"| VisCommon

    %% External Library Integration
    External -.->|"math_functions"| EUtil
    External -.->|"physics_math"| Phys

    %% Click Events
    click ECore "https://github.com/johnbuffer/pendulum-neat/tree/main/src/engine/core"
    click EUtil "https://github.com/johnbuffer/pendulum-neat/tree/main/src/engine/common"
    click ERes "https://github.com/johnbuffer/pendulum-neat/tree/main/src/engine/resources"
    click ERender "https://github.com/johnbuffer/pendulum-neat/tree/main/src/engine/render"
    click EWindow "https://github.com/johnbuffer/pendulum-neat/tree/main/src/engine/window"
    click NEAT "https://github.com/johnbuffer/pendulum-neat/tree/main/src/user/common/neat"
    click Phys "https://github.com/johnbuffer/pendulum-neat/tree/main/src/user/common/physic"
    click VisCommon "https://github.com/johnbuffer/pendulum-neat/tree/main/src/user/common/render"
    click VisTrain "https://github.com/johnbuffer/pendulum-neat/tree/main/src/user/training/render"
    click Train "https://github.com/johnbuffer/pendulum-neat/tree/main/src/user/training"
    click External "https://github.com/johnbuffer/pendulum-neat/tree/main/lib/glm"

    %% Styles
    classDef engine fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef user fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#000,stroke-width:2px;
```
