Motrixlab/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MotrixLab is a reinforcement learning framework built on top of MotrixSim simulation backend. It provides a unified interface for training RL agents using multiple simulation backends (MotrixSim) and integrates with SKRL and RSLRL libraries. The framework is designed for robotics simulation and supports various environments including basic cartpole, locomotion tasks, and manipulation tasks.

Development Setup

This project uses UV for dependency management and Python 3.10.

Installation

uv sync --all-packages --all-extras

For SKRL framework with specific backend:

uv sync --all-packages --extra skrl-jax  # JAX backend
uv sync --all-packages --extra skrl-torch  # PyTorch backend

For rslrl frame:

uv sync --all-packages --extra rslrl

Available dependency groups in MotrixLab:

see pyproject.toml

Note: This is a workspace project with two main packages: motrix_envs (simulation environments) and motrix_rl (RL framework integration).

Common Commands

Training

Train with SKRL (default):

uv run scripts/train.py --env cartpole

Train with RSLRL:

uv run scripts/train.py --env cartpole --rllib rslrl

Environment Visualization

View environment without training:

uv run scripts/view.py --env cartpole

Playing/Evaluation

uv run scripts/play.py --env cartpole

Specify policy file:

uv run scripts/play.py --env cartpole --policy <path/to/best.[pickle/pt]>

Rendering

Add --render flag to training for visualization:

uv run scripts/train.py --env cartpole --render

TensorBoard

uv run tensorboard --logdir runs/{env-name}

Testing

uv run pytest

Architecture

Core Components

1. Workspace Structure:

   • motrix_envs/: Simulation environment definitions using MotrixSim backend
   • motrix_rl/: RL framework integration (primarily SKRL) and training utilities

2. Scripts (scripts/):

   • train.py: Main training script with configurable environments, frameworks, and backends (use --rllib to select)
   • view.py: Environment visualization without training
   • play.py: Policy evaluation and testing

3. Environment Registry: Environments are registered via motrix_envs.registry and accessed using string names like "cartpole"

Key Architecture Points

• Workspace Project: Uses UV workspace with two packages sharing dependencies
• MotrixSim Backend: Built on MotrixSim simulation engine for physics simulation
• SKRL Integration: RL framework supporting both JAX and PyTorch backends
• RSLRL Integration: RL framework supporting PyTorch backend (use --rllib rslrl)
• Environment Naming: Simple string-based environment identification (e.g., "cartpole")
• Automatic Backend Selection: For SKRL, training script automatically selects JAX or PyTorch based on GPU availability; RSLRL uses PyTorch only
• Multi-Backend Training: Supports different simulation backends for the same environment

Environment Usage Pattern

Results Storage

Training results are saved to runs/{env-name}/ directory structure with checkpoints and tensorboard logs.

Important Notes

• Python Version: Requires exactly Python 3.10.*
• GPU Support: Includes CUDA support for both JAX and PyTorch backends
• Private PyPI: Uses internal PyPI server for MotrixSim packages
• No Manual Tests: No test files found in the repository structure

RSLRL Configuration

• Field Correspondence: When modifying RslrlRunnerCfg in motrix_rl/rslrl/cfg.py, ensure fields match template/rslrl_config.yaml exactly - no extra or missing fields. This is critical for proper configuration serialization and deserialization.
• Reference Template: Use template/rslrl_config.yaml as the source of truth for valid runner configuration fields