How johnbuffer/pendulum-neat works
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.