# 基础框架

MotrixLab 是一个机器人强化学习平台，这一节我们会介绍 MotrixLab 的框架设计以及各个组成部分之间的关系。如果您已经熟悉强化学习的内容，可以直接跳转至下一节，了解如何开发自己的训练环境。

## MotrixLab 的框架设计

MotrixLab 采用分层架构设计，将训练环境与训练逻辑进行了清晰拆分：

```
MotrixLab/
├── motrix_envs/               # 环境层：物理仿真和任务定义
│   ├── basic/                  # 基础环境（cartpole、walker等）
│   ├── locomotion/             # 运动环境（GO1机器人等）
│   ├── np/                     # NumPy仿真后端框架
│   ├── base.py                 # 环境基类
│   └── registry.py             # 环境注册系统
├── motrix_rl/                # 训练层：RL算法和配置
│   ├── skrl/                   # SKRL框架集成（JAX/PyTorch）
│   ├── rslrl/                  # RSLRL框架集成（PyTorch）
│   ├── base.py                 # RL配置基类
│   └── registry.py             # RL配置注册系统
└── scripts
    ├── train.py                # 训练入口脚本
    ├── play.py                 # 测试入口脚本
    └── view.py                 # 可视化脚本
```

## 核心组件架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        用户接口层                                │
│                    train.py │ play.py │ view.py                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    训练算法层 (SKRL / RSLRL)                    │
│                    PPO训练器 │ 网络架构 │ 优化器                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      环境实现层                                  │
│  环境配置(EnvCfg) │ 环境实现(Env) │ 奖励函数(Reward)            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    物理仿真层 (MotrixSim)                       │
│                    MJCF模型 │ 物理引擎 │ 碰撞检测                │
└─────────────────────────────────────────────────────────────────┘
```

## 核心组件详解

### 1. 训练环境 (Training Environment)

**位置**：环境实现层

训练环境是 MotrixLab 的核心组件，包含三个关键部分：

-   **环境配置 (EnvCfg)**：定义物理仿真参数（模型文件、时间步长、episode 长度等）和任务特定参数
-   **环境实现 (Env)**：继承基础环境类，实现具体的任务逻辑、物理仿真交互和终止条件检查
-   **奖励函数 (Reward)**：在环境的 step 方法中实现，根据当前状态和动作计算奖励值

环境通过装饰器注册到系统中。

### 2. 奖励函数 (Reward Function)

**位置**：配置管理层 + 环境实现层

奖励函数在 MotrixLab 中采用双重结构设计：

-   **配置层面**：在配置类中定义奖励权重、奖励组件类型和缩放参数
-   **实现层面**：在环境的 `_compute_reward` 方法中根据配置参数计算具体奖励值

这种设计使得奖励函数既可以通过配置文件灵活调整，又能在代码中实现复杂的计算逻辑。

### 3. 配置参数 (Configuration Parameters)

**位置**：配置管理层

配置参数采用分层管理结构：

-   **环境配置 (EnvCfg)**：控制物理仿真和任务行为，包括仿真参数、重置噪声、时间限制等
-   **训练配置 (RLCfg)**：控制强化学习算法，包括网络结构、学习率、批次大小、训练步数等

配置类支持继承、参数验证和运行时覆盖，确保参数的合理性和灵活性。

### 4. 注册系统 (Registry System)

**位置**：连接各组件的枢纽

注册系统通过装饰器模式实现组件的自动注册：

-   环境配置类通过 `@registry.envcfg()` 注册
-   环境实现类通过 `@registry.env()` 注册，支持多后端
-   RL 配置类通过 `@rlcfg()` 注册

注册系统实现了组件的解耦，使得新增环境或修改配置变得简单快捷。

## 数据流和工作流程

### 训练流程概览

```
用户命令 → 配置解析 → 环境创建 → 训练循环 → 模型保存
   ↓
train.py --env cartpole
   ↓
查找配置类 → 创建环境 → 启动PPO训练 → 保存模型
```

### 核心工作流程

1. **环境定义**：在 `/motrix_envs/` 中创建环境配置类和实现类
2. **自动注册**：通过装饰器将组件注册到系统中
3. **配置加载**：命令行启动时，系统自动查找并加载对应的配置
4. **环境创建**：工厂模式创建环境实例，支持参数覆盖
5. **训练执行**：PPO 算法与环境交互，收集数据并更新策略
6. **结果保存**：定期保存检查点和最终模型

### 配置参数的作用

配置参数在整个流程中起到关键的连接作用：

-   **环境配置**决定物理仿真行为（时间步长、模型文件、噪声等）
-   **奖励配置**影响学习信号（奖励权重、计算方式等）
-   **训练配置**控制算法行为（网络结构、学习率、批次大小等）

## 多框架支持

MotrixLab 的分层设计天然支持多种 RL 框架：

-   **仿真后端**：MotrixSim（CPU）
-   **训练框架**：
    -   **SKRL**：支持 JAX 和 PyTorch 后端，支持 GPU 加速
    -   **RSLRL**：支持 PyTorch 后端，支持 GPU 加速
-   **框架选择**：使用 `--rllib` 参数在 `skrl`（默认）和 `rslrl` 之间选择

## 设计优势

这种架构设计带来了以下核心优势：

1. **模块解耦**：环境开发与训练逻辑完全分离
2. **配置灵活**：支持分层配置和运行时参数覆盖
3. **扩展性强**：通过注册系统轻松添加新组件
4. **多后端兼容**：同一环境可使用不同仿真和训练后端
5. **实验友好**：配置可保存、比较，确保实验可重现

通过这个框架设计，MotrixLab 为机器人强化学习提供了一个清晰、灵活且易用的开发平台。
