# nvlabs/cutamp architecture

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

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

## Overview

##### Project type and purpose
- cuTAMP is an open-source Python library and CLI tool for Differentiable GPU-Parallelized Task and Motion Planning in robotics research.
- It integrates with NVIDIA’s cuRobo (for collision checking, robot kinematics, meshes) and PyTorch (for GPU-accelerated optimization).
- The primary use cases are: defining environments (Tetris, stick button, bookshelf), instantiating robot models (Franka, UR5, Robotiq grippers), sampling initial particles, optimizing a cost-based plan skeleton, and (optionally) running a motion planner and visualizing the result.

##### File structure
Top-level layout:
- cutamp/ – core Python package
– algorithm.py, optimize_plan.py, motion_solver.py, particle_initialization.py, samplers.py, rollout.py
– constraint_checker.py, cost_function.py, cost_reduction.py, costs.py
– config.py, experiment_logger.py
– envs/ – domain definitions + YAML asset files
– robots/ – robot models, URDF/XACRO descriptions, mesh assets, ROS2 launch snippets
– task_planning/ – symbolic structs, search, constraints, costs
– scripts/ – CLI entrypoint run_cutamp.py + script utilities
- docs/ – static assets, examples
- pyproject.toml, README.md, LICENSE

Architectural hints:
– Clear separation between “domain” (envs, tamp_domain/world), “solver” (algorithm, optimize_plan), “physical models” (robots), and “infrastructure” (config, logger, utils, scripts).
– Uses GPU via PyTorch for parallel cost evaluation and gradient-based optimization.
– Integrates external services: cuRobo (C++ extension for collision & kinematics), Rerun (visualization), ROS2 descriptors for robot assets.

##### Additional insights from README
- The CLI (`cutamp-demo` → run_cutamp.py) orchestrates end-to-end demos (Tetris, blocks, stick button).
- Emphasizes GPU memory management (num_particles), soft cost tuning, Rerun visualization with port forwarding.
- Cites core dependencies: Python 3.10+, PyTorch 2.0+, CUDA >= Volta, cuRobo.
- Demonstrates three phases: sampling initial plan skeletons, gradient-based optimization of soft/hard costs, optional downstream motion planning.

a. Main components:
– User Interface: CLI entrypoint (`cutamp-demo` / run_cutamp.py)
– Configuration & Params: config.py, command-line flags, experiment_logger
– Domain Definitions: cutamp/envs (surfaces, obstacles, YAML asset files), cutamp/tamp_domain & tamp_world
– Robot Definitions: cutamp/robots (URDF/XACRO, meshes), cuRobo integration
– Planning Engine:
- Task Planning submodule (plan skeleton generation, search)
- Particle Initialization (samplers, constraint_checker)
- Optimization Core (cost_function, cost_reduction, algorithm, optimize_plan using PyTorch on GPU)
- Motion Solver (optional trajectory refinement)
– Visualization & Logging: experiment_logger + Rerun SDK
– External Dependencies: cuRobo (collision/KD-tree), PyTorch (GPU), Rerun (visualization), ROS2 launch assets

b. Relationships & data flow:
1. CLI → reads config → Instantiates Domain + Robot Models
2. Task Planning → generates symbolic plan skeletons
3. Particle Initialization → samples state particles under hard constraints via constraint_checker
4. Optimization Core → repeatedly evaluates cost_function & cost_reduction on particles (GPU) → updates parameters
5. (Optional) Motion Solver → refines a continuous trajectory via cuRobo motion planning
6. experiment_logger streams data to Rerun visualizer → user inspects timelines
7. Final plan & metrics output to console/files

c. Architectural patterns & principles:
– Modular layering: separation of “symbolic” vs “geometric” planning
– GPU-parallel pipeline: batched tensor operations in PyTorch
– Plug-in extensibility: new envs, robots, cost terms can be added under respective directories
– Clear interface boundaries: constraint_checker & cost_function have well-defined inputs/outputs

d. Key technologies/frameworks:
– Python 3.10+, PyTorch 2.0+ (CUDA)
– cuRobo C++/Python extension (collision, kinematics, meshes)
– Rerun SDK for visualization
– ROS2 URDF/XACRO & launch files for robot asset descriptions
– Conda/pip installation with git-lfs for large assets

##### Diagramming recommendations
- Blue: core solver modules (algorithm, optimize_plan)
- Green: domain & robot definitions (envs/, robots/)
- Orange: external dependencies (cuRobo, PyTorch, Rerun)
- Grey: configuration & CLI

##### Detail
- Sub-components where relevant (e.g., “constraint_checker” under Particle Initializer)
- Asset pipelines (YAML → env objects; URDF/XACRO → robot model)
- Optional paths (with/without motion_solver, with/without visualizer)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration & CLI
    subgraph "Configuration & CLI"
        CLI["CLI: run_cutamp.py"]:::infra
        Config["Config: config.py"]:::infra
        Logger["Experiment Logger: experiment_logger.py"]:::infra
    end

    %% Domain & World
    subgraph "Domain & World" 
        BookShelf["BookShelf Env"]:::domain
        StickButton["Stick Button Env"]:::domain
        Tetris["Tetris Env"]:::domain
        EnvAssets["YAML Assets"]:::domain
        TampDomain["tamp_domain.py"]:::domain
        TampWorld["tamp_world.py"]:::domain
    end

    %% Robot Models
    subgraph "Robot Models"
        Franka["Franka Model"]:::domain
        UR5["UR5 Model"]:::domain
        RobotUtils["Robot Utils"]:::domain
        RobotAssets["URDF/XACRO & Meshes"]:::domain
    end

    %% Task Planning Engine
    subgraph "Task Planning Engine"
        BaseStructs["base_structs.py"]:::core
        Constraints["constraints.py"]:::core
        TP_Costs["costs.py"]:::core
        Search["search.py"]:::core
        TampStructs["tamp_structs.py"]:::core
    end

    %% Particle Initialization
    subgraph "Particle Initialization"
        ParticleInit["particle_initialization.py"]:::core
        Samplers["samplers.py"]:::core
        ConstraintChecker["constraint_checker.py"]:::core
    end

    %% Optimization Core
    subgraph "Optimization Core"
        Algorithm["algorithm.py"]:::core
        OptimizePlan["optimize_plan.py"]:::core
        CostFunction["cost_function.py"]:::core
        CostReduction["cost_reduction.py"]:::core
        OptCosts["costs.py"]:::core
    end

    %% Motion Solver (Optional)
    subgraph "Motion Solver (Optional)"
        MotionSolver["motion_solver.py"]:::core
    end

    %% Visualization & Logging
    subgraph "Visualization & Logging"
        RerunUtils["rerun_utils.py"]:::infra
        Visualizer["visualizer.py"]:::infra
    end

    %% External Dependencies
    subgraph "External Dependencies"
        CuRobo["cuRobo"]:::external
        PyTorch["PyTorch (GPU)"]:::external
        RerunSDK["Rerun SDK"]:::external
        ROS2["ROS2 Assets"]:::external
    end

    %% Data Flow
    CLI -->|reads params| Config
    CLI -->|initializes| BookShelf
    CLI -->|initializes| StickButton
    CLI -->|initializes| Tetris
    Config -->|provides config| Logger

    BookShelf --> TampDomain
    StickButton --> TampDomain
    Tetris --> TampDomain
    TampDomain --> TampWorld

    TampWorld --> BaseStructs
    TampWorld --> Search

    BaseStructs --> ParticleInit
    Search --> ParticleInit

    ParticleInit --> OptimizePlan
    ParticleInit --> CostFunction
    ParticleInit --> ConstraintChecker

    OptimizePlan --> Algorithm
    Algorithm --> CostFunction
    Algorithm --> CostReduction
    CostReduction --> OptCosts

    Algorithm -->|calls| CuRobo
    Algorithm -->|uses| PyTorch

    Algorithm --> MotionSolver
    MotionSolver --> CuRobo

    Algorithm --> Logger
    Logger -->|streams| RerunSDK
    RerunSDK --> Visualizer

    %% Click Events
    click CLI "https://github.com/nvlabs/cutamp/blob/main/cutamp/scripts/run_cutamp.py"
    click Config "https://github.com/nvlabs/cutamp/blob/main/cutamp/config.py"
    click Logger "https://github.com/nvlabs/cutamp/blob/main/cutamp/experiment_logger.py"
    click BookShelf "https://github.com/nvlabs/cutamp/blob/main/cutamp/envs/book_shelf.py"
    click StickButton "https://github.com/nvlabs/cutamp/blob/main/cutamp/envs/stick_button.py"
    click Tetris "https://github.com/nvlabs/cutamp/blob/main/cutamp/envs/tetris.py"
    click EnvAssets "https://github.com/nvlabs/cutamp/tree/main/cutamp/envs/assets/"
    click TampDomain "https://github.com/nvlabs/cutamp/blob/main/cutamp/tamp_domain.py"
    click TampWorld "https://github.com/nvlabs/cutamp/blob/main/cutamp/tamp_world.py"
    click Franka "https://github.com/nvlabs/cutamp/blob/main/cutamp/robots/franka.py"
    click UR5 "https://github.com/nvlabs/cutamp/blob/main/cutamp/robots/ur5.py"
    click RobotUtils "https://github.com/nvlabs/cutamp/blob/main/cutamp/robots/utils.py"
    click RobotAssets "https://github.com/nvlabs/cutamp/tree/main/cutamp/robots/assets/"
    click BaseStructs "https://github.com/nvlabs/cutamp/blob/main/cutamp/task_planning/base_structs.py"
    click Constraints "https://github.com/nvlabs/cutamp/blob/main/cutamp/task_planning/constraints.py"
    click TP_Costs "https://github.com/nvlabs/cutamp/blob/main/cutamp/task_planning/costs.py"
    click Search "https://github.com/nvlabs/cutamp/blob/main/cutamp/task_planning/search.py"
    click TampStructs "https://github.com/nvlabs/cutamp/blob/main/cutamp/task_planning/tamp_structs.py"
    click ParticleInit "https://github.com/nvlabs/cutamp/blob/main/cutamp/particle_initialization.py"
    click Samplers "https://github.com/nvlabs/cutamp/blob/main/cutamp/samplers.py"
    click ConstraintChecker "https://github.com/nvlabs/cutamp/blob/main/cutamp/constraint_checker.py"
    click Algorithm "https://github.com/nvlabs/cutamp/blob/main/cutamp/algorithm.py"
    click OptimizePlan "https://github.com/nvlabs/cutamp/blob/main/cutamp/optimize_plan.py"
    click CostFunction "https://github.com/nvlabs/cutamp/blob/main/cutamp/cost_function.py"
    click CostReduction "https://github.com/nvlabs/cutamp/blob/main/cutamp/cost_reduction.py"
    click OptCosts "https://github.com/nvlabs/cutamp/blob/main/cutamp/costs.py"
    click MotionSolver "https://github.com/nvlabs/cutamp/blob/main/cutamp/motion_solver.py"
    click RerunUtils "https://github.com/nvlabs/cutamp/blob/main/cutamp/utils/rerun_utils.py"
    click Visualizer "https://github.com/nvlabs/cutamp/blob/main/cutamp/utils/visualizer.py"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef domain fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
