GGitHub 趋势观察站
每日 07:00 更新订阅EN
← 返回今日榜单

精选指南 · 编程与开发

MuJoCo

用 Python 建立一个竖直下落的小球模型,推进仿真时间并检查高度变化。从核心计算开始认识物理模型与运行状态。

访问 GitHub 仓库 ↗
最近上榜 · 2026-11-11#5

当日排名

+453当日新增 Star17,324总 Star
← 全部精选指南

入选理由:官方核心包可在无图形窗口的环境运行最小实验,模型、时间步长与状态都有明确检查项,补充现有指南中的物理仿真主题;同时说明 4.0 包拆分带来的安装边界。

入选:2026-11-09 · 资料核对:2026-11-09。根据官方资料整理,未进行安装与功能实测。

MuJoCo:用一次小球下落认识可编程物理仿真

它解决什么问题

想研究机器人或物体怎样运动,首先需要一个可以定义质量、关节和重力,再读取位置变化的环境。MuJoCo 提供这套物理计算引擎,也有 Python 接口。

这里的“模型”是物体与物理参数的描述。本篇先建立一个只允许竖直运动的小球,推进 0.2 秒仿真时间,再检查高度是否下降。先读懂一次状态变化,之后再扩展为接触、控制或机器人模型。步骤依据官方文档编写,未进行现场安装和仿真实测。

适合谁,哪些情况不适合

适合会运行 Python 脚本、希望理解机器人仿真或物理引擎基本流程的读者。练习只使用核心 CPU 仿真,不需要机器人硬件、GPU 或图形窗口。

如果目标是直接获得机器人控制策略,还需准备任务、控制算法、训练与评估过程。仿真中的成功也需要通过真实系统验证,不能直接当作实机性能结论。只想体验画面的人可以从官方浏览器示例入手;本文重点是可读取和检查的数值状态。

环境与准备

本次核对的是 2026 年 11 月 6 日发布的 MuJoCo 4.0.0。该版本将 Python 包拆分,mujoco-core 提供核心仿真绑定并依赖 NumPy;完整的 mujoco 包还会安装查看器和渲染组件。本篇用新的虚拟环境安装核心包,避免混用旧版本文件。

需要 Python 3.11 或以上,且版本、操作系统和架构有匹配的安装包。本次发布元数据列出了 CPython 3.11—3.15 的 macOS ARM64、Linux x86-64/AArch64、Windows x86-64 等 wheel。Linux 还需满足 wheel 的 manylinux 系统要求;Intel Mac 不在本次核心包的预编译 wheel 列表中,应另查官方构建路线。

以下命令使用 macOS 或 Linux 的终端语法,先运行 python3 --version 核对版本。安装需要联网访问包索引;运行本文自己的模型不依赖在线模型服务。Windows 用户需改用对应的虚拟环境路径与文件创建方法。

安装与第一次使用

1. 新建练习目录和环境。 下面的命令在同一个终端执行。不要把练习文件放进已有项目的环境里。

mujoco_demo_dir=$(mktemp -d) &&
cd "$mujoco_demo_dir" &&
python3 -m venv .venv &&
.venv/bin/python -m pip install 'mujoco-core==4.0.0' &&
.venv/bin/python -c 'import mujoco; print(mujoco.__version__)'

最后应显示 4.0.0。包名是 mujoco-core,Python 导入名仍是 mujoco。

2. 创建模型。 在当前目录创建 fall.xml:

cat > fall.xml <<'XML'
<mujoco model="vertical_fall">
  <option timestep="0.002" gravity="0 0 -9.81"/>
  <worldbody>
    <body name="ball" pos="0 0 1">
      <joint name="vertical" type="slide" axis="0 0 1"/>
      <geom type="sphere" size="0.05" mass="1"/>
    </body>
  </worldbody>
</mujoco>
XML

按本例的米、秒、千克约定,小球初始中心高度为 1 米,半径为 0.05 米,质量为 1 千克。slide 关节只允许沿指定方向平移,重力沿负 Z 方向。模型暂时没有地面,只运行短时间下落;若要研究落地碰撞,需要再建立碰撞几何体。

3. 推进时间并检查高度。 同目录创建 fall.py:

cat > fall.py <<'PYCODE'
import mujoco

model = mujoco.MjModel.from_xml_path("fall.xml")
data = mujoco.MjData(model)
mujoco.mj_forward(model, data)
initial_z = float(data.body("ball").xpos[2])

for _ in range(100):
    mujoco.mj_step(model, data)
mujoco.mj_forward(model, data)
final_z = float(data.body("ball").xpos[2])

print(f"time={data.time:.3f}s")
print(f"z: {initial_z:.3f} -> {final_z:.3f}")
assert abs(data.time - 0.2) < 1e-8
assert 0 < final_z < initial_z
print("状态检查通过")
PYCODE

.venv/bin/python fall.py

检查三件事:仿真时间为 0.200 秒;起始高度为 1.000;结束高度为正且低于起始值。每步 0.002 秒乘以 100 步得到 0.2 秒,这是仿真时间,脚本不需要实际等待 0.2 秒。最后一行只有在两个断言通过后才会出现。

这些是依据配置和接口语义给出的预期检查项,没有将它们写成实测输出。mj_forward 更新当前状态对应的派生量,mj_step 推进时间;读取小球的世界坐标时,明确更新后再比较。

4. 做一个可解释的改动。 把 XML 中的重力改为 0 0 0,再次运行。在没有其他力和初速度的本例中,高度应保持不变,原来的“高度下降”断言会失败。此时将该断言改为:

assert abs(final_z - initial_z) < 1e-8

这能帮助区分物理条件变化与程序异常。每次启动脚本都会重新创建初始状态,便于重复比较。

主要能力与典型场景

  • 分开管理模型与状态。 MjModel 保存模型描述,MjData 保存运行中的状态和中间结果。同一模型可以建立不同状态,用于比较初始条件或控制方案。
  • 逐步推进控制实验。 在每次 mj_step 前按模型写入控制输入,再记录相应状态,是进一步设计控制循环的起点。本例没有执行器或控制器。
  • 增加接触与机器人结构。 学会几何体、关节和参数后,可以按官方 MJCF 参考增加地面、机械连杆与传感器;已有模型也需核对尺寸、质量和关节约束。
  • 按需添加查看器。 4.0 提供带渲染依赖的核心包选项及完整包。数值仿真与图形环境可以分开准备;要看窗口时再按官方文档安装相应组件。

常见问题与排错

  • 找不到匹配的发行包。 对照 Python 版本、机器架构和 PyPI wheel 列表。过旧 Python、不支持的架构或不兼容的 Linux 系统不能直接沿用本例预编译安装路线。
  • 安装了但无法导入。 用 .venv/bin/python -m pip show mujoco-core 确认包在本例环境里。脚本不要命名为 mujoco.py,否则可能遮蔽真正的包。
  • 找不到 fall.xml。 在终端核对 pwd 和 ls,确保脚本与模型都在当前练习目录;接口中的相对路径按运行目录解析。
  • 高度没有变化。 核对是否保留竖直 slide 关节、负 Z 重力和推进循环。没有关节的物体会固定在其父体上,不能按这个例子自由移动。
  • 想查看图形却缺少模块。 核心包只准备本篇数值流程。查看器需另外安装文档列出的渲染依赖,并具备图形环境;macOS 的被动查看器还要求专用启动方式。
  • 从 3.x 升级后导入异常。 4.0 发行说明明确指出包拆分带来的文件迁移问题。先阅读该版本升级说明;初学练习可重新建立干净环境,避免在已有环境中反复混装。

费用、隐私与限制

MuJoCo 源码采用 Apache 2.0;官方 doc 目录的文档、图片和视频采用 CC BY 4.0。本篇保留实际阅读的官方来源。自有机器上的核心仿真不需要商业仿真许可证或模型 API 账号,机器、包下载和相关网络成本取决于所用环境。

本例只读取自己创建的 XML 并计算状态,不调用云端推理接口。若使用在线笔记本、浏览器服务或第三方模型资源,需要另行核对数据处理方式和资源许可证。

时间步长、质量、约束及求解设置都会影响结果。这个短时下落例子只核对安装、模型加载和时间推进,不验证接触精度或机器人控制质量。大型模型、渲染和并行训练有各自资源需求,不能依据本例推断其速度或硬件门槛。

官方资料