# nicolayp/mppi_gpu architecture

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

- Interactive diagram: https://gitdiagram.com/nicolayp/mppi_gpu
- Repository: https://github.com/nicolayp/mppi_gpu

## Overview

##### Main Components
- Controller & Core Algorithms: Represented by files in src (e.g., Env.cpp, controller_base.cpp, point_mass.cu, point_mass_gpu.cu, cost.cu, and mppi_utils.cu) and matching header files in include. This is the heart of the MPPI implementation and contains the control logic, cost computation, and reduction algorithms.
- GPU Computational Layer: Highlight the CUDA-specific components (e.g., cost.cu, point_mass_gpu.cu, mppi_utils.cu, and test.cu) which are responsible for the parallel computations, the use of cuRAND for randomness, and the performance optimizations described in the README.
- Simulation Environments: Indicate the simulation configuration and definition layers. This includes:
- Configuration Files: The config directory contains YAML files that help set parameters for different simulation modes (point_mass in 1D, 2D, 3D, etc.).
- Environment Descriptions: The envs folder contains the corresponding XML files for Mujoco simulations to define the physical and visual properties of the simulated point-mass systems.
- Mujoco Integration: In the include/mujoco directory, you have multiple header files for Mujoco support. This shows that the project integrates the Mujoco simulation engine to render/control simulation states.
- Utility & Support Libraries: The lib directory (and its subdirectories) shows that there is additional code and even a Mujoco key file (mjkey.txt), pointing to external dependencies or contributed libraries.
- Visualization & Analysis: The scripts directory (with plot_csv.py, plot_miss.py, plot_traj.py) indicates a separate post-processing or visualization component to analyze simulation results.

##### Relationships and Interactions
- Control Flow: Show that the main application (starting in main.cpp and main.cu) initializes the environment and then continuously runs the MPPI controller logic. This component interacts with:
- The cost and reduction algorithms (derived from cost.cu and mppi_utils.cu) to compute performance measures.
- The GPU computational layer where data is generated (using cuRAND, as mentioned in the README) and computations are performed for each simulation step.
- Simulation & Rendering: Indicate that once computations are complete, simulation data may be passed to the Mujoco engine (via the include/mujoco files) for visualizing and verifying simulation trajectories.
- Data Analysis: The output or logs from the simulation can be fed into the visualization scripts, closing the loop for performance verification and debugging.

##### Architectural Patterns and Design Principles
- Modular Separation: The codebase is clearly separated between the core controller logic, GPU-based computational routines, simulation definitions, and utility/visualization tools. This encourages an extensible design where each module can be updated independently.
- GPU vs. CPU Execution: The architecture leverages CUDA for heavy computational tasks while the main bootstrapping and coordination might be in C++ (main.cpp), illustrating a hybrid design.
- Config-Driven Behavior: With multiple YAML configurations and corresponding XML environment definitions, emphasize a pattern where behavior is controlled via configuration files, making experimentation easier.
- Integration with External Engines: The inclusion of Mujoco headers and simulation files validates that it’s designed to work closely with an external simulation engine for realistic environment rendering.
- Performance Optimizations: Note the use of a generic reduction algorithm and memory management optimizations (as described in the changes log) that indicate low-level performance tuning is a key architectural concern.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration and Setup
    subgraph "Configuration/Setup"
        CF["Config Files"]:::config
        EF["Environment Files"]:::config
    end

    %% Application Entry Point
    AE["Application Entry Points"]:::core

    %% MPPI Controller Core
    subgraph "MPPI Controller Core"
        CSC["Controller Source Files"]:::core
        CCH["Controller Header Files"]:::core
    end

    %% GPU Computation Engine
    GPU["GPU Computation Engine (CUDA)"]:::gpu

    %% Mujoco Integration
    MJ["Mujoco Integration"]:::sim

    %% Visualization & Analysis
    VIS["Visualization & Analysis"]:::vis

    %% Utility & Support Libraries
    UTIL["Utility & Support Libraries"]:::util

    %% Flow Connections
    CF -->|config_input| AE
    EF -->|env_setup| AE
    AE -->|initialize| CSC
    AE -->|initialize| GPU
    CSC -->|control_logic| GPU
    GPU -->|simulate| MJ
    MJ -->|render_feedback| VIS

    %% Utility supports core and Mujoco
    UTIL --- CSC
    UTIL --- MJ

    %% Click Events
    click CF "https://github.com/nicolayp/mppi_gpu/blob/master/config/point_mass1d.yaml"
    click EF "https://github.com/nicolayp/mppi_gpu/blob/master/envs/point_mass1d.xml"
    click AE "https://github.com/nicolayp/mppi_gpu/blob/master/src/main.cpp"
    click CSC "https://github.com/nicolayp/mppi_gpu/blob/master/src/controller_base.cpp"
    click CCH "https://github.com/nicolayp/mppi_gpu/blob/master/include/controller_base.hpp"
    click GPU "https://github.com/nicolayp/mppi_gpu/blob/master/src/point_mass_gpu.cu"
    click MJ "https://github.com/nicolayp/mppi_gpu/blob/master/include/mujoco/mujoco.h"
    click UTIL "https://github.com/nicolayp/mppi_gpu/tree/master/lib"
    click VIS "https://github.com/nicolayp/mppi_gpu/blob/master/scripts/plot_csv.py"

    %% Styles
    classDef config fill:#F0E68C,stroke:#333,stroke-width:2px;
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef gpu fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef sim fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef vis fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef util fill:#FFA07A,stroke:#333,stroke-width:2px;
```
