Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
267 changes: 112 additions & 155 deletions src/Neuro_Mujoco/README.md
Original file line number Diff line number Diff line change
@@ -1,169 +1,126 @@
# 基于 MuJoCo 的神经网络代理实现
实现基于 MuJoCo 物理引擎的机器人、机械结构等智能体的感知、规划与控制,结合神经网络实现动态环境中的自主决策与行为生成。新增**强化学习策略推理**与**ROS 1 实时通信**功能,支持端到端的智能控制流程。

# 环境配置
平台:Windows 10/11,Ubuntu 20.04/22.04(ROS推荐),macOS(Intel/Apple Silicon)
软件:Python 3.7-3.12(需支持 3.7 及以上版本)、PyTorch(策略网络依赖)
核心依赖:MuJoCo 物理引擎、mujoco-python 绑定

# 基础依赖安装
安装 Python 3.11(推荐版本)
安装核心依赖:
```shell
# 安装MuJoCo Python绑定
# 基于 MuJoCo 的智能体控制工具
整合 MuJoCo 物理引擎的模型加载、格式转换、速度测试、可视化功能,新增强化学习策略推理与ROS 1 实时通信能力,支持机器人端到端智能控制流程。
## 环境配置
1. 支持平台
Windows 10/11、Ubuntu 20.04/22.04(ROS 推荐)、macOS(Intel/Apple Silicon)
2. 软件要求
Python 3.7-3.12(推荐 3.11)、MuJoCo 物理引擎、PyTorch(策略网络依赖,可选)、ROS 1 Noetic(ROS 功能依赖,可选)
3. 核心依赖安装
shell
## 安装 MuJoCo Python 绑定
pip install mujoco -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com

# 安装PyTorch(策略网络必需,根据系统配置选择)
pip3 install torch torchvision torchaudio -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com

# 安装文档生成工具
pip install mkdocs -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com
pip install -r requirements.txt
```

(可选)验证安装:
```shell
python -c "import mujoco; print('MuJoCo version:', mujoco.__version__)"
python -c "import torch; print('PyTorch version:', torch.__version__)" # 验证策略依赖
mkdocs --version
```

# 核心功能使用
## 1. 模型可视化与控制
支持直接加载模型文件或目录,集成策略控制与ROS通信:
```shell
## PyTorch(策略网络推理必需)
pip install torch torchvision torchaudio -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

## ROS 1 依赖(仅 Ubuntu,需先安装 ROS Noetic)
sudo apt install ros-noetic-rospy ros-noetic-geometry-msgs ros-noetic-sensor-msgs
## 验证安装
shell
### 验证 MuJoCo
python -c "import mujoco; print(f'MuJoCo 版本: {mujoco.__version__}')"

# 验证 PyTorch(策略功能)
python -c "import torch; print(f'PyTorch 版本: {torch.__version__}')"

### 验证 ROS(ROS 功能)
# python -c "import rospy; print('ROS 1 导入成功')"
## 快速开始
### 模型可视化(核心功能)
支持加载单个模型文件或目录(自动识别目录内 .xml/.mjb 文件),控制优先级:ROS 指令 > 策略推理 > 无控制。
1.1 运行命令
shell
# 基础可视化(无控制)
python mujoco_utils.py visualize /path/to/model.xml
python mujoco_utils.py visualize /path/to/your/model.xml

# 启用ROS 1模式(发布关节状态/基座姿态,接收控制指令)
python mujoco_utils.py visualize /path/to/model.xml --ros
# 启用 ROS 1 模式(发布关节状态/接收控制指令)
python mujoco_utils.py visualize /path/to/your/model.xml --ros

# 加载预训练策略模型(自动生成控制指令)
python mujoco_utils.py visualize /path/to/model.xml --policy /path/to/policy.pth

# 联合模式(ROS + 策略控制)
python mujoco_utils.py visualize /path/to/model.xml --ros --policy /path/to/policy.pth
```
- 交互说明:可视化窗口支持鼠标拖拽旋转、滚轮缩放,按ESC键退出
- 控制优先级:ROS指令 > 策略推理 > 无控制

## 2. 模型格式转换
支持XML与MJB(二进制)格式互转(MJB加载速度更快):
```shell
# XML转MJB
python mujoco_utils.py visualize /path/to/your/model.xml --policy /path/to/your/policy.pth

# 混合模式(ROS + 策略控制)
python mujoco_utils.py visualize /path/to/your/model.xml --ros --policy /path/to/your/policy.pth

# 目录自动加载(选目录内第一个模型文件)
python mujoco_utils.py visualize /home/lan/桌面/nn/mujoco_menagerie/anybotics_anymal_b
1.2 交互说明
窗口操作:鼠标拖拽旋转、滚轮缩放,按 ESC 键退出;
关节状态:仅发布非自由关节(排除 mjJNT_FREE 类型)的位置 / 速度;
策略映射:输出 [-1,1] 自动线性缩放至执行器 ctrlrange 范围,并强制裁剪至物理极限。
### 模型格式转换
2.1 运行命令
shell
# XML 转 MJB(提升加载速度)
python mujoco_utils.py convert input.xml output.mjb

# MJB转XML
# MJB 转 XML(便于编辑)
python mujoco_utils.py convert input.mjb output.xml
```

## 3. 模拟速度测试
多线程测试模型仿真性能,评估实时性:
```shell
# 默认参数(1线程,10000步)
python mujoco_utils.py testspeed /path/to/model.xml

# 自定义配置(4线程,50000步,控制噪声0.02)
python mujoco_utils.py testspeed /path/to/model.xml --nthread 4 --nstep 50000 --ctrlnoise 0.02
```
输出指标包括:每秒步数、实时因子(仿真时间/真实时间)、线程耗时统计

# ROS 集成配置(Ubuntu 专属)
### 1. ROS 版本要求
- Ubuntu 20.04 → ROS Noetic
- Ubuntu 22.04 → ROS Humble(需适配 Python 3.10+)

### 2. 安装 ROS 依赖
```shell
# ROS Noetic 依赖(Ubuntu 20.04)
sudo apt install ros-noetic-rospy ros-noetic-catkin ros-noetic-geometry-msgs ros-noetic-sensor-msgs
sudo apt install python3-catkin-tools python3-rosdep
```

### 3. Catkin 工作空间配置
```shell
# 创建/进入 Catkin 工作空间(示例路径:~/桌面/nn/catkin_ws)
mkdir -p ~/桌面/nn/catkin_ws/src && cd ~/桌面/nn/catkin_ws/src

# 将 mujoco_ros 功能包软链接到 Catkin 工作空间
ln -s ~/桌面/nn/src/Neuro_Mujoco/mujoco_ros ./mujoco_ros

# 初始化 rosdep(首次使用)
sudo rosdep init && rosdep update
rosdep install --from-paths ./ --ignore-src -r -y
```

### 4. 编译 Catkin 工作空间
```shell
cd ~/桌面/nn/catkin_ws
# 清理旧编译缓存
rm -rf build devel
# 编译(支持虚拟环境 Python)
catkin_make -DPYTHON_EXECUTABLE=$(which python3)
```


# 策略网络说明
## 网络结构
轻量级多层感知器(MLP),适用于机器人关节控制:
```python
### 仿真速度测试
多线程测试模型仿真性能,优化点:线程内动态生成控制噪声,降低内存占用。
3.1 运行命令
shell
# 默认参数(1线程,10000步,噪声0.01)
python mujoco_utils.py testspeed /path/to/your/model.xml

# 自定义配置(4线程,50000步,噪声0.02)
python mujoco_utils.py testspeed /path/to/your/model.xml --nthread 4 --nstep 50000 --ctrlnoise 0.02
3.2 输出指标
总步数 / 总耗时 / 每秒步数;
实时因子(仿真时间 / 真实时间);
线程耗时统计(平均值 ± 标准差)。
## ROS 1 集成(Ubuntu 专属)
1. ROS 话题说明
类型 话题名 消息类型 说明
发布 /mujoco/joint_states sensor_msgs/JointState 非自由关节位置 / 速度
发布 /mujoco/pose geometry_msgs/PoseStamped 基座位置 / 姿态(world 帧)
订阅 /mujoco/ctrl_cmd std_msgs/Float32MultiArray 控制指令(长度 = 模型 nu)
2. 运行步骤
shell
# 1. 启动 ROS 核心(新开终端)
roscore

# 2. 启动 MuJoCo ROS 节点
python mujoco_utils.py visualize /path/to/your/model.xml --ros

# 3. (可选)发布测试控制指令(100Hz)
rostopic pub /mujoco/ctrl_cmd std_msgs/Float32MultiArray "data: [0.1, 0.2, 0.3]" -r 100
## 策略网络说明
1. 网络结构
轻量级 MLP,适配机器人关节控制场景:
python
运行
class PolicyNetwork(nn.Module):
def __init__(self, obs_dim: int, action_dim: int, hidden_dim: int = 64):
super().__init__()
self.net = nn.Sequential(
nn.Linear(obs_dim, hidden_dim), # 观测维度=关节位置数+速度数
nn.Tanh(),
nn.Linear(hidden_dim, hidden_dim),
nn.Tanh(),
nn.Linear(hidden_dim, action_dim), # 输出维度=控制维度(nu)
nn.Tanh() # 输出范围[-1,1],自动映射到实际控制范围
nn.Linear(obs_dim, hidden_dim), nn.Tanh(),
nn.Linear(hidden_dim, hidden_dim), nn.Tanh(),
nn.Linear(hidden_dim, action_dim), nn.Tanh() # 输出 [-1,1]
)
```

## 观测与控制映射
- 输入观测:`[关节位置(qpos) + 关节速度(qvel)]`
- 输出控制:归一化指令`[-1,1]`,通过模型`actuator_ctrlrange`自动映射到实际范围

# 文档查看
在命令行中进入项目根目录,运行:
```shell
mkdocs build
mkdocs serve
```
使用浏览器打开 http://127.0.0.1:8000,查看项目文档是否正常显示。

# 常见问题解决
1. **`ModuleNotFoundError: No module named 'rclpy'`**
→ 错误导入 ROS 2 库,替换为 ROS 1 的 `rospy` 即可。

2. **`unrecognized arguments: __name:=mujoco_core`**
→ 修改参数解析逻辑,忽略ROS自动添加的参数:
```python
args, unknown = parser.parse_known_args() # 替代 parser.parse_args()
```

3. **`模型文件不存在`**
→ 检查模型路径是否正确,可视化命令支持自动搜索目录下的`.xml`/`.mjb`文件。

4. **`策略模型加载失败`**
→ 确认:① 模型文件存在 ② PyTorch已安装 ③ 模型输入/输出维度与环境匹配(obs_dim=qpos+qvel维度,action_dim=nu)

5. **`ROS话题无数据`**
→ 检查:① `roscore`是否启动 ② Catkin环境是否加载(`source devel/setup.bash`)③ 关节名称映射是否正确

# 贡献指南
提交代码前,请阅读 贡献指南。代码优化方向包括:
- 遵循 PEP 8 代码风格 并完善注释
- 扩展策略网络类型(如CNN、RNN,适配视觉观测)
- 优化策略推理效率(如ONNX导出、TensorRT加速)
- 完善ROS功能(如服务调用、参数服务器配置)
- 增加自动化测试(模型加载/转换验证、策略性能基准测试)
- 支持多智能体仿真与分布式控制

# 参考资源
- MuJoCo 官方文档
- MuJoCo Python 绑定教程
- MuJoCo 模型库(Menagerie)
- PyTorch 神经网络教程
- ROS 1 Noetic 官方文档
- 强化学习在MuJoCo中的应用(MJX框架)
2. 输入输出
输入:观测(关节位置 qpos + 关节速度 qvel);
输出:归一化控制指令([-1,1]),自动映射至模型 actuator_ctrlrange 范围:
python
运行
### 核心映射逻辑
action = ctrl_min + (ctrl_max - ctrl_min) * (action + 1) / 2
action = np.clip(action, ctrl_min, ctrl_max) # 强制裁剪至物理极限
## 性能优化点
速度测试:线程内动态生成控制噪声,避免主线程预生成大数组;
策略推理:复用张量对象,避免重复内存分配;
控制指令:强制裁剪至执行器物理极限,防止超限报错;
路径处理:支持目录自动识别模型文件,提升易用性;
关节映射:精准过滤自由关节,仅发布有效关节状态。
## 常见问题
问题现象 解决方案
模型加载失败 检查路径是否正确,确保文件为 .xml/.mjb 格式
策略加载失败 确认 PyTorch 已安装、策略文件路径正确、输入输出维度匹配
ROS 无数据 确保 roscore 已启动、话题名称匹配、控制指令长度 = 模型 nu
仿真实时性差 使用 MJB 格式模型、减少线程数、降低控制噪声强度
控制指令无效果 检查模型 nu(控制维度)是否 > 0,策略输出是否映射至正确范围
## 参考资源
1、MuJoCo 官方文档
2、PyTorch 神经网络教程
3、ROS 1 Noetic 文档
4、MuJoCo 官方模型库
Loading