# nvlabs/curobo architecture

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

- Interactive diagram: https://gitdiagram.com/nvlabs/curobo
- Repository: https://github.com/nvlabs/curobo

## Overview

##### Project Overview and Main Components
- cuRobo is a robotics library that leverages CUDA for accelerating key robotics algorithms. It provides capabilities such as forward/inverse kinematics, collision checking, numerical optimization (e.g., gradient descent, L‑BFGS, MPPI), geometric planning, and trajectory optimization.
- The project is organized into several main modules (as seen under the src/curobo directory) and additional directories for benchmarks, examples, Docker integrations, and tests. The library also provides wrappers (in the wrap subfolder) to expose its functionalities to higher-level applications or robotics simulators (e.g., Isaac Sim).

##### Analyzing the Directory Structure
- Core Libraries and Modules:
- The src/curobo folder is composed of multiple submodules:
▸ cuda_robot_model – Contains CUDA kernels, GPU-based kinematics parsing, and robot model generation.
▸ curobolib – Implements core algorithms related to collision checking, kinematics evaluation, optimization routines (e.g., L-BFGS, MPPI), and cost computations.
▸ geom (including geom/sdf) – Provides geometric constructs, signed distance functions (SDF), collision checking utilities (using meshes, voxel representations), and transformations.
▸ graph – Manages graph-based representations (e.g., sampling-based planning such as PRMs) that are useful in planning.
▸ opt (with subdirectories newton and particle) – Contains different optimization strategies to improve trajectories with smoothness and minimum-jerk costs.
▸ rollout – Implements the motion generation and trajectory evaluation logic that synthesizes outputs from kinematics, collision checks, and optimization.
▸ types – Contains data structures and definitions for robot models, states, cameras, tensors, etc.
▸ util – Provides helper functions, logging, error/metric calculations, and file utilities.
▸ wrap – Builds Python-friendly wrappers that expose the low-level, high-performance functions to higher-level APIs or external applications.
- Supporting Items:
- The assets in src/curobo/content contain robot descriptions (URDFs, meshes), configuration YAML files for robots and environments, and scene definitions.
- The examples and benchmarks directories show typical use cases—from simple demos (e.g., inverse kinematics examples) to robust performance testing (benchmarking CUDA performance and optimization).
- Docker files assist with setting up reproducible environments (including configurations for Isaac Sim) and deployment.

##### Relationships and Interactions Between Components
▸ Core Computational Layer: Consists of the CUDA-accelerated modules (cuda_robot_model, curobolib) and the geometric processing (geom/sdf). This layer handles the heavy computations like kinematics and collision checking via GPU kernels.
▸ Algorithmic Layer: Includes the optimization routines (opt/newton, opt/particle), trajectory generation (rollout), and motion planning components (graph). Their interconnection is visible in how design decisions for collision-free, minimum-jerk trajectories are optimized.
▸ API & Integration Layer: The wrap module and higher-level Python APIs serve as the interface for user applications, external simulators (e.g., Isaac Sim as seen in examples), and integration with MoveIt (Isaac ROS cuMotion plugin).
▸ Configuration & Asset Layer: Contains robot asset descriptions, configuration files, and scene definitions that feed into the core computational processes.
- Data flows are largely unidirectional: User input (via high-level APIs) passes parameters/configurations to the wrappers, which then invoke core CUDA kernels through the computational modules. Processed results (e.g., planned trajectories or kinematics solutions) flow back up for visualization or control.

##### Architectural Patterns and Design Principles
- Modular Separation: Each submodule has a clear responsibility (e.g., collision versus optimization), allowing for easy extension or debugging.
- Layered Architecture: Distinguishing between computationally intensive GPU modules, algorithmic logic, and API exposure.
- High Parallelism: The use of CUDA indicates a design optimized for parallel computation; hence, components should be marked as “GPU-accelerated” where appropriate.
- Extensibility: The presence of detailed configuration files and assets implies that the library is designed to be extended to support additional robots, environments, or planning algorithms.

##### Elements
- User/Application Interface (API/Wrap)
- CUDA Accelerated Computation Layer:
- cuda_robot_model (GPU Kernels, kinematics parsing)
- curobolib (Collision checking, L-BFGS, MPPI optimization)
- Algorithmic Modules:
- Geom/SDF (Collision Meshes, SDF utilities)
- Graph (Sampling-based planning)
- Optimization (Newton & Particle methods)
- Rollout (Trajectory generation)
- Configuration & Asset Repository:
- Robot Models & Asset Files (URDFs, meshes)
- Config Files (YAML configurations for robots and world)
- For instance, use blue rectangles for CUDA/accelerated components, green for optimization, orange for API/wrappers, and gray for configuration/assets.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Layers
    User["User/Application Interface"]:::generic
    Wrap["Wrap/API"]:::api
    ConfigAssets["Robot Models & Assets"]:::config
    ConfigFiles["Configuration Files"]:::config

    subgraph "Core Computational Layer"
        CudaModel["CUDA Robot Model"]:::cuda
        Curobolib["curobolib (Collision/Kinematics)"]:::cuda
        GeomSDF["Geometric Processing (geom/sdf)"]:::cuda
    end

    subgraph "Algorithmic Layer"
        GraphNode["Graph-Based Planning"]:::optimization
        NewtonOpt["Newton Optimization"]:::optimization
        ParticleOpt["Particle-based Optimization"]:::optimization
        Rollout["Trajectory Generation (Rollout)"]:::optimization
    end

    subgraph "Support Layer"
        Types["Data Structures & Types"]:::generic
        Util["Utility Functions & Helpers"]:::generic
    end

    %% Data Flow from User to API
    User -->|"API_call"| Wrap

    %% Configuration & Asset inputs
    ConfigAssets -->|"assets_input"| Wrap
    ConfigFiles -->|"config_input"| Wrap

    %% API calls into Computational Modules
    Wrap -->|"kinematics_query"| CudaModel
    Wrap -->|"collision_query"| Curobolib
    Wrap -->|"geometry_request"| GeomSDF
    Wrap -->|"planning_request"| GraphNode
    Wrap -->|"optimization_request"| NewtonOpt
    Wrap -->|"optimization_request"| ParticleOpt
    Wrap -->|"trajectory_query"| Rollout

    %% Modules returning results to API layer
    CudaModel -->|"kinematics_result"| Wrap
    Curobolib -->|"collision_result"| Wrap
    GeomSDF -->|"geometry_result"| Wrap
    GraphNode -->|"planning_result"| Wrap
    NewtonOpt -->|"optimization_result"| Wrap
    ParticleOpt -->|"optimization_result"| Wrap
    Rollout -->|"trajectory_result"| Wrap

    %% Support Layer interactions (Data Structures)
    CudaModel -->|"uses"| Types
    Curobolib -->|"uses"| Types
    GeomSDF -->|"uses"| Types
    GraphNode -->|"uses"| Types
    NewtonOpt -->|"uses"| Types
    ParticleOpt -->|"uses"| Types
    Rollout -->|"uses"| Types

    %% Support Layer interactions (Utility Functions)
    CudaModel -->|"helpers"| Util
    Curobolib -->|"helpers"| Util
    GeomSDF -->|"helpers"| Util
    GraphNode -->|"helpers"| Util
    NewtonOpt -->|"helpers"| Util
    ParticleOpt -->|"helpers"| Util
    Rollout -->|"helpers"| Util

    %% Click Events
    click CudaModel "https://github.com/nvlabs/curobo/tree/main/src/curobo/cuda_robot_model"
    click Curobolib "https://github.com/nvlabs/curobo/tree/main/src/curobo/curobolib"
    click GeomSDF "https://github.com/nvlabs/curobo/tree/main/src/curobo/geom"
    click GraphNode "https://github.com/nvlabs/curobo/tree/main/src/curobo/graph"
    click NewtonOpt "https://github.com/nvlabs/curobo/tree/main/src/curobo/opt/newton"
    click ParticleOpt "https://github.com/nvlabs/curobo/tree/main/src/curobo/opt/particle"
    click Rollout "https://github.com/nvlabs/curobo/tree/main/src/curobo/rollout"
    click Types "https://github.com/nvlabs/curobo/tree/main/src/curobo/types"
    click Util "https://github.com/nvlabs/curobo/tree/main/src/curobo/util"
    click Wrap "https://github.com/nvlabs/curobo/tree/main/src/curobo/wrap"
    click ConfigAssets "https://github.com/nvlabs/curobo/tree/main/src/curobo/content/assets"
    click ConfigFiles "https://github.com/nvlabs/curobo/tree/main/src/curobo/content/configs"

    %% Styles
    classDef api fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef cuda fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef optimization fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef generic fill:#FFFFFF,stroke:#000,stroke-width:1px;
```
