CH-11 MuJoCo 仿真
在仿真中检查机器人动作之前,先试着让一个刚体在重力下运动。屏幕上的物体为什么没有掉落?是没有运动自由度,还是计算后的状态尚未显示出来?第 10 章明确了模型、状态和时序,本章用固定的盒子与球体开始,再增加一个关节,逐步检查加载、前向计算、积分和渲染。这样就能把第 04 章的连续动力学接成可记录的仿真循环,为后续策略闭环准备运行环境。
本章使用 MuJoCo,它的名称是 Multi-Joint dynamics with Contact 的缩写。这个通用物理引擎用广义坐标表示多关节机构,将接触动力学纳入同一套计算框架,可用于机器人、生物力学、图形与动画,以及其他需要快速、准确仿真的领域。Python bindings 直接访问底层库;Python API 与 C API 保持一致,可以共用 API 文档。参数顺序等写法有时不同于常见的 Python 习惯,读代码时需要对照底层引擎结构。
1. 安装与 MJCF 模型
先加载两个几何体,确认模型与派生量,再增加转动关节。暂时不接控制器,可以逐项定位物体不动的原因:它是否具有自由度,派生量是否刷新,窗口是否读到了当前状态。每增加一个环节,都能用前一步已经确认的结果检查它。
物理引擎从当前状态、力和约束计算下一状态,显示程序随后读取结果;预先给定的位姿序列无法代替这个计算过程。Todorov、Erez 与 Tassa 的 MuJoCo 论文将多关节动力学与接触作为模型控制的计算基础,后面的学习环境也会反复调用同一类物理步。
1.1 运行环境
通过 PyPI 安装 mujoco 时,包内已经包含 MuJoCo 动态库,不需要另行下载物理引擎。本章固定使用 3.3.7。
1 | python -m venv .venv |
下载本章的完整示例脚本后,可以直接运行无窗口仿真:
1 | python mujoco_intro.py --seconds 2 |
1.2 MJCF 几何体
下面的模型由一个红色盒子和一个绿色球体组成。worldbody 表示世界刚体;它没有父节点,也不会运动。几何体没有指定 type 时,默认类型为球体。
1 | import mujoco |
盒子的 size 指定三个半边长,球体的 size 指定半径,rgba 则给出颜色与透明度。两个几何体都直接附着在世界刚体上,模型尚未定义能够运动的关节。
按这些尺寸解释,盒子的实际边长是 $0.4\,\mathrm m$,球体半径是 $0.1\,\mathrm m$。两者的 pos 都在 worldbody 坐标系中给出,所以绿色球中心为 $(0.2,0.2,0.2)$,无需再加上盒子的位置偏移。不同 geom 类型对 size 的解释不同,核对尺寸时应检查编译后的模型。
当前两个 geom 可以参与场景表示与碰撞关系,却没有独立的运动状态。重力不会使固定在世界上的物体变成自由刚体;它能够怎样运动,仍由第 03 章介绍的关节约束决定。
2. 模型与状态
同一机器人可以从不同构型开始仿真。几何与惯性参数通常保持不变,位置、速度和时间则随实验变化。分别保存这两类数据,才能明确重置、前向计算和物理步各自改变了什么。
2.1 MjModel
mjModel 包含模型描述,例如物体数量、几何形状、关节类型、惯性参数,以及编译模型时确定的各种数组大小。Python bindings 使用 MjModel 类暴露这一结构。
1 | print(model.ngeom) |
通过名称访问对象,可以减少手工维护数字索引的工作。命名属性是同一底层数组的切片,例如 model.geom('green_sphere').rgba 指向 model.geom_rgba 中球体对应的行,两种访问方式的修改会相互反映。
修改参数时,要区分显示与物理计算。颜色只影响外观,质量、惯量和关节参数会改变实验中的系统,也可能影响其他预计算量。这里的教学实验宜通过修改 XML、重新编译和记录模型版本来管理变化,再比较相同输入下的轨迹。
模型中的计数也各有含义。ngeom 统计几何体,nq、nv 统计状态坐标;一个刚体附着十个 geom,可以仍然只有一个 hinge,世界上的两个 geom 则可以完全没有运动坐标。
2.2 MjData
mjData 包含动态状态和随状态变化的计算量,例如时间、广义位置、广义速度、控制输入,以及几何体在世界坐标系中的位置。它由模型创建,但不会改变模型的拓扑结构。
1 | print(data.time) |
刚创建的 MjData 中,部分派生量尚未按当前状态计算。模型给出了几何体的相对位置,世界位置 geom_xpos 还需要通过运动学得到。
这些量之间存在计算依赖:qpos、qvel 和执行器状态是输入,世界位姿、Jacobian、惯性与加速度是结果。手工修改 qpos 后,需要重新执行相应算法;否则读出的 geom_xpos 即使是有限数值,也可能来自上一构型。第 12 章的 Pinocchio Data 也采用这种工作方式。控制循环应先读入状态,调用算法,再读取该次计算的结果。
1 | mujoco.mj_kinematics(model, data) |
mj_kinematics 执行运动学计算。另一种常用方式是调用 mj_forward:它运行前向计算流程,根据当前状态更新动力学和其他派生量,但不推进仿真时间。
1 | mujoco.mj_forward(model, data) |
选择调用时,可以从需要的结果出发:mj_kinematics 更新运动学位置,mj_forward 完成不积分的前向计算,mj_step 再通过积分推进状态与时间。检查候选构型的末端位置时,额外的物理步会在重力和控制作用下改变该构型;此时应刷新派生量,而非推进状态。
研究自由摆动则需要积分,仅重复 mj_forward 不会产生运动轨迹。MuJoCo 3.3.7 的函数文档区分了这些计算阶段;读取派生量之前,应确认其依赖的阶段已经完成。
3. 场景与渲染
3.1 Renderer 场景
创建 Renderer 并不自动把模型状态放入可视化场景。渲染之前,需要先完成前向计算,再更新 scene。
1 | with mujoco.Renderer(model, height=360, width=640) as renderer: |
返回的 pixels 是 RGB 图像数组,光源、材质和相机参数都会影响它的内容。物理计算先更新状态,可视化场景随后更新,画面才会反映新的位置。
沿着图像生成过程看,物理状态先给出世界几何位置,update_scene 将它们组织成场景,render 再生成像素。记录相机图像时,因而应同时保存所用物理状态的时间和图像输出时间。慢速渲染可以使墙钟运行变慢,每个物理步仍可保持原来的仿真时长。
图像驱动的策略还要面对不同采样频率:若图像每隔若干物理步更新一次,多次策略调用可能读到同一帧。这是采样保持的结果,策略调用频率与相机测量频率应分别记录。

3.2 关节与刚体运动
即使连续调用 mj_step,上面的盒子和球体也不会掉落。原因在于,它们直接附着在世界刚体上,而且模型中没有关节。MuJoCo 用关节描述刚体相对于父刚体能够产生的运动;没有关节的刚体与父刚体保持固定关系。
如果希望两个几何体作为一个整体运动,可以把它们放进同一个 body,并给这个刚体增加一个 hinge joint。
1 | <mujoco> |
hinge joint 定义转轴方向和轴上的一点。两个几何体固定在同一刚体上,相对位姿保持不变,整个刚体绕该轴转动。body 和 geom 的位置与姿态,通常相对于所属父坐标系给出。
轴向量 $(1,-1,0)$ 指定转轴方向,计算时取其单位方向;pos=(-0.2,-0.2,-0.2) 给出该 body 局部坐标中的轴上一点。body 的初始旋转会将这个轴和点一起变换到世界坐标系。
预测重力下的摆动,需要求刚体质心相对于转轴的位置。若用第 04 章的单摆公式核对,应先计算复合刚体的质心、绕 hinge 的惯量和重力力臂,不能直接用物体到世界原点的距离。若将球和盒拆成两个带相对关节的 body,允许运动的方式就变了,初始画面相同也不再意味着轨迹相同。
4. 广义坐标
4.1 构型与速度维度
model.nq 是广义位置 qpos 的维度,model.nv 是广义速度 qvel 的维度。对于 hinge joint,两者都为 1;对于 slide joint,也都为 1。
球关节的姿态使用四元数,因此需要四个位置参数,但只有三个角速度自由度。free joint 用三维平移与四元数表示位置和姿态,需要七个位置参数,却只有六个速度自由度。因此,不能普遍假定 nq == nv。
第 02 章的几何表示解释了这个维度差异:四个数存储姿态,独立转动自由度只有三个,四元数的位置导数与角速度也需要通过相应关系转换。
以浮动根加两个 hinge 为例,位置维度为 $7+1+1=9$,速度维度为 $6+1+1=8$;再加一个 ball,二者分别变为 $13$ 与 $11$。自由根的四元数需要保持单位长度,因此不能普遍用位置向量的逐项加法代替速度积分。
MuJoCo 的 mj_integratePos 将 nv 维速度作用到 nq 维构型上,mj_differentiatePos 从两组构型计算一致的速度差。状态与双频率复算脚本核对这里的坐标计数及后面的调度算术;这个额外模型只用于维度分析,脚本没有创建或运行它。
4.2 世界位姿
qpos 和 qvel 是状态变量,body、geom 等对象的世界位姿则由这些状态计算得到。修改 qpos 之后,如果要读取新的 Cartesian 位置,需要重新执行前向计算。
Python bindings 暴露的数组通常直接访问底层内存。仿真向前运行时,相同数组中的值会被覆盖。如果希望保存某个时刻的状态,应当复制数组。
1 | history = [] |
如果仅仅写 history.append(data.qpos),保存的是同一内存的引用,而不是每个时刻的独立快照。
快照中需要保存什么,取决于之后要做的分析。绘制被动 hinge 的曲线,只需记录位置和速度;若要从某时刻继续相同实验,还可能需要激活动力学状态、时间、控制序列和其他内部状态,并保留模型版本。
跨库比较也需要相应条件。运动学比较要求使用同一构型并刷新位姿,动力学比较还要统一惯量、重力、外力和约束。第 12 章的 RNEA/ABA 往返检查将检验同一模型上的算子一致性,这里的仿真循环则需要检查时间积分。
5. 仿真循环
5.1 物理步长
mj_step 先根据当前状态计算动力学,再通过数值积分推进状态。仿真时间步长存储在 model.opt.timestep;它与可视化帧率是两个不同的参数。
1 | duration = 2.0 |
推进物理状态时,无需每一步都渲染。录制 60 Hz 视频,可以在达到下一帧的时间后再更新 scene 并渲染,使数值积分和视频输出各自按所需频率运行。
第 04 章的连续动力学可概括为 $M(q)\dot v+h(q,v)=\tau+J^Tf$,还需配合构型的几何更新。引擎在每步求出加速度,用选定积分器近似连续演化。对于欧氏关节坐标,半隐式 Euler 的示意更新为 $v_{k+1}=v_k+\Delta t\,a_k$、$q_{k+1}=q_k+\Delta t\,v_{k+1}$;它用于解释积分过程,具体 MuJoCo 积分器未必采用该式。
接触、刚性伺服和大增益会引入更快的变化,步长需要足够小,才能解析这些时间尺度。
假设采用轨迹脚本中的 $2\,\mathrm{ms}$ 物理步长,控制器每 $20\,\mathrm{ms}$ 产生一个目标,decimation 就是 10:一个目标保持十个物理步。这十步中,目标相同,状态、接触和低层响应仍然逐步更新。两秒运行包含 1000 个物理步和 100 个完整控制区间。
若按 $[0,2)$ 上的 60 Hz 时间网格采样视频,会得到 120 帧。采样间隔约 $16.667\,\mathrm{ms}$,与物理步长没有整数倍关系。每次选择不早于请求时刻的首个物理状态,理想采样误差小于 $2\,\mathrm{ms}$;渲染间隔会随请求时刻变化,不能始终固定为八步或九步。复算脚本用有理数避开浮点阈值影响,核对出的最大偏移为 $1.333\,\mathrm{ms}$。
比较积分离散误差时,应保持控制周期不变。将物理步长减半,同时保留 $20\,\mathrm{ms}$ 的控制周期,需要把 decimation 加倍;保持原 decimation 则会同时提高控制频率,轨迹差异中就混入了控制变化。
简单的无接触弹簧模型 $\ddot q+\omega_n^2q=0$ 能展示步长与动力学频率的关系。对上述半隐式 Euler,无量纲量 $\omega_n\Delta t$ 小于 2 才能保持稳定振荡。真实机器人还包含更复杂的频率与接触求解过程,这个条件帮助解释步长的影响,其适用范围限于上述示意模型。
具体算一次:物理步长从 $2$ 改为 $1\,\mathrm{ms}$ 后,两秒内物理步数从 1000 增至 2000,decimation 从 10 增至 20;控制区间仍有 100 个,视频仍请求 120 帧。脚本输出了这一比较,控制与采样频率都保持原值,变化仅来自积分网格。
接触出现或消失的时刻可能随积分网格略有变化,因此轨迹比较应允许数值误差。不同网格中相同数组索引也可能对应不同物理时刻,需要先对齐时间,再判断差异。
5.2 交互窗口
viewer.launch 采用 managed 模式,控制仿真循环并阻塞用户代码。viewer.launch_passive 不阻塞用户代码,因此,脚本负责推进物理状态、同步窗口,以及控制循环的时间。
1 | import time |
sync() 把状态与可视化窗口同步,也把 GUI 产生的输入传回模型与数据。在 viewer 自己的线程之外修改相机或其他可视化状态时,需要使用 viewer 提供的锁。
睡眠语句在计算有余量时,使墙钟速度接近仿真速度。若一个物理步加渲染的耗时超过 timestep,程序跳过睡眠,仿真时间仍按固定步长增加,画面因而慢于实时。这里没有改变物理步长来追赶墙钟时间。
性能记录应分别保存模拟秒数、物理步数和实际耗时,再检查模型计算、渲染与界面同步各自的开销。关闭窗口只是结束交互循环,任务是否成功还需要由任务指标判断。
本章脚本的交互入口为:
1 | python mujoco_intro.py --seconds 30 --viewer |
macOS 的 passive viewer 要使用随包安装的 mjpython 启动器,以满足主线程进行渲染的平台要求:
1 | mjpython mujoco_intro.py --seconds 30 --viewer |

6. 仿真输出
无关节模型的 nq 与 nv 都应当为 0;hinge 模型的两个维度都应当为 1。调用 mj_forward 后,绿色球体的世界位置应当为 [0.2, 0.2, 0.2]。hinge 模型在重力作用下运动,运行后 qpos 应当与初始值不同,位置和速度应当保持有限数值。
6.1 状态记录
轨迹记录脚本沿用上面的 hinge 模型,将每一步的 time、qpos[0] 和 qvel[0] 保存为 CSV:
1 | python 11-simulation-trace.py --seconds 2 --csv 11-hinge-trace.csv |
在 MuJoCo 3.3.7 的无窗口 CPU 检查中,脚本打印 nq, nv: 1 1、timestep: 0.002、steps: 1000 和 finite states: True,最终仿真时间约为 2.0 s。CSV 有一个初始状态和 1000 个物理步后的状态。

曲线记录了被动关节的运动,可以检查状态变化、数值是否有限,以及位置和速度是否保存为独立快照。这个模型尚未接入学习策略,图中的曲线也没有用于评价控制性能。
数值有限之后,还要检查模型参数和离散误差。可以保持相同初始状态,将步长减半,在共同时间网格上比较轨迹,避免只比较结束时的数组索引。对于无耗散系统,还可以分析机械能量变化;本例需要先核对完整的惯性与动力学配置,平滑曲线本身不足以证明能量守恒。
完成这些检查后,仿真循环中的状态、控制和物理步就有了可追踪的含义。第 12 章将计算规划所需的运动学与动力学,第 13、14 章再把策略接入这个循环。
参考资料
Google DeepMind. MuJoCo Python Tutorial. Version 3.3.7, cells 4–53: mjModel, mjData, rendering, joints, generalized coordinates. © 2021 DeepMind Technologies Limited;将 notebook 串联为本地脚本,增加维度与有限值检查;Apache License 2.0。
Google DeepMind. Python; Overview. MuJoCo 3.3.7 documentation. © 2021 DeepMind Technologies Limited;中文节选重排;文档采用 CC BY 4.0。
Todorov, Emanuel, Tom Erez, and Yuval Tassa. MuJoCo: A Physics Engine for Model-Based Control. IROS, 2012.
Google DeepMind. MuJoCo 3.3.7 API Functions: Main Simulation; mj_differentiatePos and mj_integratePos. Forward computation, integration and configuration tangent dimensions. 固定版本的接口约定;多频率调度和标量积分稳定性为独立解析案例。

