|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +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 primarily integrates with the SKRL library. The framework is designed for robotics simulation and supports various environments including basic cartpole, locomotion tasks, and manipulation tasks. |
| 8 | + |
| 9 | +## Development Setup |
| 10 | + |
| 11 | +This project uses UV for dependency management and Python 3.10. |
| 12 | + |
| 13 | +### Installation |
| 14 | + |
| 15 | +```bash |
| 16 | +uv sync --all-packages --all-extras |
| 17 | +``` |
| 18 | + |
| 19 | +For SKRL framework with specific backend: |
| 20 | + |
| 21 | +```bash |
| 22 | +uv sync --all-packages --extra skrl-jax # JAX backend |
| 23 | +uv sync --all-packages --extra skrl-torch # PyTorch backend |
| 24 | +``` |
| 25 | + |
| 26 | +**Available dependency groups in MotrixLab:** |
| 27 | + |
| 28 | +- `skrl-jax`: SKRL RL framework with JAX backend |
| 29 | +- `skrl-torch`: SKRL RL framework with PyTorch backend |
| 30 | +- `test`: Test dependencies (pytest) |
| 31 | + |
| 32 | +**Note**: This is a workspace project with two main packages: `motrix_envs` (simulation environments) and `motrix_rl` (RL framework integration). |
| 33 | + |
| 34 | +## Common Commands |
| 35 | + |
| 36 | +### Training |
| 37 | + |
| 38 | +```bash |
| 39 | +uv run scripts/train.py --env cartpole |
| 40 | +``` |
| 41 | + |
| 42 | +### Environment Visualization |
| 43 | + |
| 44 | +View environment without training: |
| 45 | + |
| 46 | +```bash |
| 47 | +uv run scripts/view.py --env cartpole |
| 48 | +``` |
| 49 | + |
| 50 | +### Playing/Evaluation |
| 51 | + |
| 52 | +```bash |
| 53 | +uv run scripts/play.py --env cartpole |
| 54 | +``` |
| 55 | + |
| 56 | +Specify policy file: |
| 57 | + |
| 58 | +```bash |
| 59 | +uv run scripts/play.py --env cartpole --policy <path/to/best.[pickle/pt]> |
| 60 | +``` |
| 61 | + |
| 62 | +### Rendering |
| 63 | + |
| 64 | +Add `--render` flag to training for visualization: |
| 65 | + |
| 66 | +```bash |
| 67 | +uv run scripts/train.py --env cartpole --render |
| 68 | +``` |
| 69 | + |
| 70 | +### TensorBoard |
| 71 | + |
| 72 | +```bash |
| 73 | +uv run tensorboard --logdir runs/{env-name} |
| 74 | +``` |
| 75 | + |
| 76 | +### Testing |
| 77 | + |
| 78 | +```bash |
| 79 | +uv run pytest |
| 80 | +``` |
| 81 | + |
| 82 | +## Architecture |
| 83 | + |
| 84 | +### Core Components |
| 85 | + |
| 86 | +1. **Workspace Structure**: |
| 87 | + |
| 88 | + - `motrix_envs/`: Simulation environment definitions using MotrixSim backend |
| 89 | + - `motrix_rl/`: RL framework integration (primarily SKRL) and training utilities |
| 90 | + |
| 91 | +2. **Scripts** (`scripts/`): |
| 92 | + |
| 93 | + - `train.py`: Main training script with configurable environments and backends |
| 94 | + - `view.py`: Environment visualization without training |
| 95 | + - `play.py`: Policy evaluation and testing |
| 96 | + |
| 97 | +3. **Environment Registry**: Environments are registered via `motrix_envs.registry` and accessed using string names like "cartpole" |
| 98 | + |
| 99 | +### Key Architecture Points |
| 100 | + |
| 101 | +- **Workspace Project**: Uses UV workspace with two packages sharing dependencies |
| 102 | +- **MotrixSim Backend**: Built on MotrixSim simulation engine for physics simulation |
| 103 | +- **SKRL Integration**: Primary RL framework supporting both JAX and PyTorch backends |
| 104 | +- **Environment Naming**: Simple string-based environment identification (e.g., "cartpole") |
| 105 | +- **Automatic Backend Selection**: Training script automatically selects JAX or PyTorch based on GPU availability |
| 106 | +- **Multi-Backend Training**: Supports different simulation backends for the same environment |
| 107 | + |
| 108 | +### Environment Usage Pattern |
| 109 | + |
| 110 | +```python |
| 111 | +# Environment creation handled internally by scripts |
| 112 | +# Use string names to specify environments |
| 113 | +uv run scripts/train.py --env cartpole |
| 114 | +``` |
| 115 | + |
| 116 | +## Results Storage |
| 117 | + |
| 118 | +Training results are saved to `runs/{env-name}/` directory structure with checkpoints and tensorboard logs. |
| 119 | + |
| 120 | +## Important Notes |
| 121 | + |
| 122 | +- **Python Version**: Requires exactly Python 3.10.\* |
| 123 | +- **GPU Support**: Includes CUDA support for both JAX and PyTorch backends |
| 124 | +- **Private PyPI**: Uses internal PyPI server for MotrixSim packages |
| 125 | +- **No Manual Tests**: No test files found in the repository structure |
0 commit comments