Index of every page on this site: llms.txt
All skills
google-deepmind avatar

/python

@eb1ff5e
by Google DeepMindgoogle-deepmind/mujoco18k stars
2,221
Run it yourself

MuJoCo Python (`import mujoco`) simulation lifecycle (MjSpec, MjModel, MjData), stepping (mj_step, mj_step1, mj_step2, mj_forward), named access (data.body, model.geom), bind(), multi-threaded CPU batch simulation (mujoco.batch.Batch, mujoco.rollout), optimization and system ID (mujoco.minimize, mujoco.sysid, mjd_transitionFD), contact/touch sensors, sensordata, keyframe resets, integrators, mju_ spatial math (quaternions, poses), and energy diagnostics. Use only for MuJoCo Python physics simulation, MjModel/MjData state access, MuJoCo CPU batching, stepping loops, and MuJoCo sensors/sysid. Don't use for custom non-MuJoCo Python/NumPy/C++ ODE or rigid-body simulators, custom finite-difference sysid, or general spatial math without `mujoco`, nor for spec editing (mujoco-spec-editing), deformable flex/cloth/cable modeling (mujoco-deformables), rendering (mujoco-rendering), GPU/TPU (mujoco-accelerated), parity (mujoco-parity), or GUI/viewers (mujoco-gui, mujoco-studio).

  • 1 file
  • 22.9 KB
  • Updated 3 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/google-deepmind/mujoco/python

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈247 tokens for metadata: the name and description. ≈5.6k when used: this file.

Description uses 12.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈997 characters, or 12.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

MuJoCo Python: Simulation, Sensors & Math

[!TIP]

Official MuJoCo documentation (doc/*.rst): Read short chapters like ../../programming/simulation.rst (.. _Simulation:) and ../../overview.rst directly when in a MuJoCo checkout; for large reference files like ../../python.rst (.. _PyStructs:, .. _PyNamed:, .. _PyBatch:, .. _PySysid:), ../../modeling.rst (.. _CTuning:), ../../computation/index.rst (.. _Pipeline:, .. _geIntegrators:, .. _geChoosingTimestepIntegrator:), ../../XMLreference.rst, and ../../APIreference/functions.rst, grep the literal .. _Label: anchor. Outside a checkout, the same doc/*.rst tree ships offline in pip install mujoco at pathlib.Path(mujoco.__file__).parent / 'doc'; otherwise fetch https://mujoco.readthedocs.io/en/latest/<path>.html (or /en/stable/ for released pages; functions.rst renders inside APIreference/APIfunctions.html, and Sphinx anchors lowercase the label, e.g. .. _PyBatch: → #pybatch) and browse repo paths (../../../, python/*.ipynb) under https://github.com/google-deepmind/mujoco/tree/main/.

Related skills:

  • mujoco-spec-editing — Procedural model editing and composing scenes with MjSpec.
  • mujoco-deformables — Deformable <flexcomp>, <flex>, and <skin> modeling (rods, cloth, and 3D FEM soft bodies).
  • mujoco-rendering — Offscreen image rendering, cameras, depth, and segmentation.
  • mujoco-accelerated — GPU/TPU physics simulation with MJX (JAX) and MJWarp (CUDA).
  • mujoco-parity — Cross-engine physics parity comparison against MJWarp and MJX.
  • mujoco-studio — Interactive viewers, Studio viewer apps, and plugin architecture.

[!CAUTION]

  • NEVER use mj_name2id, model.name2id, or raw integer indexing (e.g., data.qpos[0], data.xpos[body_id]) to look up elements by name. Always use named access (data.body('name').xpos) or bind() instead.
  • Do not use dm_control / PyMJCF lookup patterns. model.find('body', 'name'), .find_body(), and physics.named do not exist in MuJoCo 3.x. Use direct accessors: .body('name'), .geom('name') etc. on MjSpec, MjModel, and MjData.

1. Compilation Lifecycle: MjSpec → MjModel → MjData

MuJoCo models follow a three-stage lifecycle:

MjSpec  ──spec.compile()──▶  MjModel  ──MjData(model)──▶  MjData
  │                             │                            │
  │  (mutable blueprint)        │  (compiled, mostly frozen) │ (simulation state)
  │                             │                            │
  └── spec.recompile(m, d) ─────┴────────────────────────────┘
  1. MjSpec: Mutable data structure defining the simulation elements and hierarchy.
  2. MjModel: Compiled, optimized physics model containing constant and precomputed parameters. Structural changes require recompilation.
  3. MjData: Dynamic simulation state (positions, velocities, forces, contacts, diagnostic buffers).

Python Lifecycle

import mujoco

# 1. Build or load spec
spec = mujoco.MjSpec()
body = spec.worldbody.add_body(name='pendulum', pos=[0, 0, 1])
body.add_geom(type=mujoco.mjtGeom.mjGEOM_SPHERE, size=[0.1])
body.add_joint(name='hinge', type=mujoco.mjtJoint.mjJNT_HINGE, axis=[0, 1, 0])

# 2. Compile to model and instantiate data
model = spec.compile()
data = mujoco.MjData(model)
mujoco.mj_forward(model, data)

# 3. Dynamic recompilation (preserves existing state)
body2 = spec.worldbody.add_body(name='ball2', pos=[1, 0, 1])
body2.add_geom(size=[0.1])
body2.add_freejoint()
model, data = spec.recompile(model, data)  # Always reassign return values

C++ Lifecycle

#include <mujoco/mujoco.h>

// 1. Create or load spec (or: mj_parseXML(filename, nullptr, error, sizeof(error)))
mjSpec* spec = mj_makeSpec();
mjsBody* world = mjs_findBody(spec, "world");
mjsBody* body = mjs_addBody(world, nullptr);
mjsGeom* geom = mjs_addGeom(body, nullptr);
geom->type = mjGEOM_SPHERE;
geom->size[0] = 0.1;

// 2. Compile to model and create data
mjModel* model = mj_compile(spec, nullptr);
if (!model) {
  printf("%s\n", mjs_getError(spec));
}
mjData* data = mj_makeData(model);

// 3. Step or evaluate
mj_forward(model, data);

// 4. Clean up allocated resources
mj_deleteData(data);
mj_deleteModel(model);
mj_deleteSpec(spec);

Loading and Serializing

# Direct model loading from file or string
model = mujoco.MjModel.from_xml_path('model.xml')
model = mujoco.MjModel.from_xml_string(xml_str)
model = mujoco.MjModel.from_binary_path('model.mjb')  # Precompiled binary format

# Loading mutable spec from file or string
spec = mujoco.MjSpec.from_file('model.xml')
spec = mujoco.MjSpec.from_string(xml_str)

# Serialization
xml_string = spec.to_xml()
spec.encode('model.xml', model)

[!CAUTION]

mujoco.load_model_from_path does not exist in MuJoCo 3.x. Use mujoco.MjModel.from_xml_path(path) or mujoco.MjSpec.from_file(path). For ready-to-run models, check ../../../model/ (humanoid/humanoid.xml, tendon_arm/arm26.xml, car/car.xml), ../../../test/engine/testdata/, and MuJoCo Menagerie (models.rst, .. _Menagerie:).

2. Accessing State: Named Access & bind()

1. Named Access (on MjModel and MjData)

In Python, access elements by calling the element-type accessor with the element name:

# Reading state
torso_pos = data.body('torso').xpos      # NumPy view (3,)
knee_angle = data.joint('knee').qpos     # Shape depends on joint type
ball_size = model.geom('ball').size      # NumPy view (3,)

# Writing controls and state
data.actuator('motor').ctrl = 1.0        # Writable view
data.joint('knee').qpos = 0.5

Supported element accessors: body, geom, joint (alias jnt), site, camera (alias cam), light, mesh, skin, texture (alias tex), material (alias mat), pair, equality (alias eq), tendon (alias ten), actuator, sensor, numeric, text, tuple, keyframe (alias key).

[!WARNING]

Named access returns views, not copies. In a simulation loop, modifying the simulation changes the array in-place. If logging or storing history, always call .copy():

# ❌ WRONG — all history items will point to the same final state
history.append(data.body('torso').xpos)

# ✅ RIGHT — records distinct coordinates
history.append(data.body('torso').xpos.copy())

2. bind() (Bridges MjSpec elements → MjModel / MjData)

When building models programmatically with MjSpec, use bind() to map spec element handles directly to compiled data:

geom = spec.worldbody.add_geom(name='ball', size=[0.1])
joint = spec.worldbody.add_joint(name='hinge', type=mujoco.mjtJoint.mjJNT_HINGE)
model = spec.compile()
data = mujoco.MjData(model)

# Read through bind
radius = model.bind(geom).size[0]
ball_pos = data.bind(geom).xpos

# Write through bind — always use .set()
data.bind(joint).set('qpos', 0.5)

# Bind lists of spec elements in batch
joints = [spec.joint('j1'), spec.joint('j2')]
joint_angles = data.bind(joints).qpos

3. Simulation Stepping & Execution Pipeline

Stepping Pipeline (mj_step vs mj_step1 / mj_step2)

  • mj_step(model, data): Advances the simulation by one timestep (model.opt.timestep). It computes kinematics, forces, collision constraints, accelerations, and numerical integration in one full pass.
  • Split Stepping (mj_step1 + mj_step2): Used when custom controller forces or external computations depend on the current kinematic state:
# 1. Advance position kinematics and sensor computations
mujoco.mj_step1(model, data)

# 2. Apply control torques or external forces based on current kinematics
data.ctrl[:] = compute_feedback_control(data.qpos, data.qvel)
data.qfrc_applied[:] = compute_external_forces(data)

# 3. Complete dynamic acceleration and integration
mujoco.mj_step2(model, data)

Sensor and Kinematic Initialization (mj_forward)

Before reading sensors or positions at time zero, call mj_forward() instead of mj_step(). mj_forward evaluates kinematics and sensor outputs from the current state without advancing simulation time:

# ✅ RIGHT — initialize sensors and kinematics at t=0
mujoco.mj_forward(model, data)
initial_obs = data.sensordata.copy()

# Advance physics
for _ in range(num_steps):
  mujoco.mj_step(model, data)

Keyframe Resets & Restoring State

Use keyframes to reset configurations reliably:

# Python: reset to named keyframe
key_id = model.key('home').id
mujoco.mj_resetDataKeyframe(model, data, key_id)
mujoco.mj_forward(model, data)  # Recompute kinematics and sensors

In C++:

int key_id = mj_name2id(m, mjOBJ_KEY, "home");
if (key_id >= 0) {
  mj_resetDataKeyframe(m, d, key_id);
  mj_forward(m, d);
}

Integrators & Numerical Stability

Configured via model.opt.integrator (full equations and timestep/integrator selection notes in computation/index.rst, .. _geIntegrators: and .. _geChoosingTimestepIntegrator:, modeling.rst, .. _CTuningGlobal:, and XMLreference.rst, .. _option-integrator:):

  • mjINT_IMPLICITFAST (recommended): Velocity-implicit (damping, kv, fluid drag, free-body gyroscopic forces) via symmetric Cholesky at ~Euler cost.
  • mjINT_IMPLICIT: Adds asymmetric Coriolis/centripetal velocity derivatives (LU factorization) for rapidly spinning multi-link chains.
  • mjINT_EULER (legacy default): Semi-implicit Euler; implicit in joint damping only.
  • mjINT_RK4: 4th-order Runge-Kutta (4 evaluations/step) for smooth, energy-conserving systems.
  • mjINT_DISCRETE (candidate replacement in trial): Also implicit in position (stiff springs, position servos kp, <flex> <elasticity>, and their coupling with contacts; implicit/implicitfast are velocity-implicit only — see mujoco-deformables).

4. Contact & Force Sensing: Declarative Sensors

Why data.contact Should NOT Be Used for Observations

data.contact is a variable-length buffer that changes size and ordering every timestep based on active collision pairs:

# ❌ WRONG — variable size and non-deterministic order break ML policies
for c in data.contact:
  if c.geom1 == target_id:
    force = ...

Declarative Contact Sensors

<contact> sensors (see XMLreference.rst, .. _sensor-contact:) declaratively filter contacts, reduce them to a fixed number of slots, and write deterministic vectors directly into data.sensordata:

<sensor>
  <!-- Detect contacts between gripper and object: fixed 3 slots -->
  <contact name="grip_contact"
           body1="gripper" body2="object"
           num="3" data="found force normal"
           reduce="maxforce"/>

  <!-- Net wrench on an entire body -->
  <contact name="object_net"
           body1="object"
           data="force torque"
           reduce="netforce"/>
</sensor>

Reading contact sensors in Python:

contact_data = data.sensor('grip_contact').data  # Always fixed length

Touch Sensors for Scalar Normal Force

For scalar surface contact forces (e.g., fingertips), use touch sensors (XMLreference.rst, .. _sensor-touch:) attached to a site. Make sure the site is large enough to encompass the geom:

site = body.add_site(name='fingertip', pos=[0, 0, 0.05], size=[0.02])
spec.add_sensor(
    name='touch_sensor',
    type=mujoco.mjtSensor.mjSENS_TOUCH,
    objname=site.name,
    objtype=mujoco.mjtObj.mjOBJ_SITE,
)

5. Spatial Mathematics (mju_ Library)

MuJoCo provides an optimized spatial mathematics library under the mju_ namespace in both C++ and Python.

[!IMPORTANT]

MuJoCo quaternions are scalar-first: [w, x, y, z]. SciPy and ROS use scalar-last: [x, y, z, w]. Swizzle components when converting:

# MuJoCo -> SciPy/ROS
scipy_quat = mj_quat[[1, 2, 3, 0]]

# SciPy/ROS -> MuJoCo
mj_quat = scipy_quat[[3, 0, 1, 2]]

Quaternion Operations

res = np.zeros(3)
mujoco.mju_rotVecQuat(res, vec, quat)         # Rotate vector by quaternion

quat = np.zeros(4)
mujoco.mju_mat2Quat(quat, mat9)               # Flat (9,) rotation matrix → quaternion
mujoco.mju_quat2Mat(mat9, quat)               # Quaternion → flat (9,) matrix
mujoco.mju_axisAngle2Quat(quat, axis, angle)  # Axis-angle → quaternion
mujoco.mju_euler2Quat(quat, euler, 'xyz')     # Euler angles → quaternion
mujoco.mju_mulQuat(res_q, q1, q2)             # Compose quaternions (q1 * q2)
mujoco.mju_negQuat(res_q, quat)               # Quaternion conjugate (inverse)
mujoco.mju_quatZ2Vec(quat, vec)               # Quaternion rotating Z-axis to vector

Pose Operations

# Compose poses (pos1/quat1 then pos2/quat2)
mujoco.mju_mulPose(pos_res, quat_res, pos1, quat1, pos2, quat2)

# Invert pose
mujoco.mju_negPose(pos_res, quat_res, pos, quat)

# Transform 3D point by pose
mujoco.mju_trnVecPose(res, pos, quat, vec)

6. Energy & Diagnostics

MuJoCo can continuously compute total mechanical energy to diagnose simulation stability:

# Enable energy monitoring
model.opt.enableflags |= mujoco.mjtEnableBit.mjENBL_ENERGY

mujoco.mj_step(model, data)
potential_energy = data.energy[0]
kinetic_energy = data.energy[1]
total_energy = potential_energy + kinetic_energy

In passive, unforced, undamped systems, total_energy must remain constant. Growing energy indicates numerical integration instability (requiring smaller timesteps, or implicitfast if large damping or other velocity-dependent forces are the cause). Before stiffening contacts to mask instability, inspect the paused model at t = 0 in Studio/simulate for initial penetrations, visual/collision geom mismatches, concave collision meshes replaced by convex hulls (.. _coChecking:), implausible CAD/URDF inertia boxes, and degree/radian mismatches (compiler/angle defaults to "degree"). For priority-ordered speed-fidelity tuning, diagnosing divergence, non-SI unit mistakes (millimeter/gram meshes), island sleeping, speculative CCD, or fluid drag, read modeling.rst (.. _CTuning:, .. _CTuningDefaults:, .. _CTuningGlobal:, .. _CTuningModel:), overview.rst (.. _Clarifications:, .. _Divergence:, .. _Units:, .. _Soft:), computation/index.rst (.. _Solver:, .. _Sleeping:), programming/simulation.rst (.. _siSleep:), computation/speculative.rst, and computation/fluid.rst.

7. CPU Batching (mujoco.batch & mujoco.rollout), Optimization & Backends

Stateful Multi-Threaded CPU Batching (mujoco.batch.Batch)

For vectorized RL stepping, closed-loop controllers, subset resets, and per-simulation domain randomization on CPU across a native C++ thread pool (GIL released, bit-identical to serial MjData stepping, and supporting all CPU solvers/plugins), use mujoco.batch.Batch (python.rst, .. _PyBatch:, wrapping C mjb_* in APIreference/functions.rst, .. _Batchedsimulation:):

from mujoco import batch

# Pass persistent=True if the model uses sleep, IPC, or stateful plugins
b = batch.Batch(model, nsim=1024, nthread=8)
qpos, ctrl, xpos = b.bind('qpos'), b.bind('ctrl'), b.bind('xpos')

# Named views slice (nsim, ...) and expand per-sim model fields
hinge_qpos = b.joint('hinge').qpos           # (1024, 1)
b.body('pendulum').mass = per_sim_masses     # Domain randomization
b.set_const()                                # Recompute derived model constants

for _ in range(1000):
  ctrl[:] = policy(qpos, xpos)
  b.step()                                   # Or b.step(ids=active_ids)

Stateless Trajectory Rollouts, Optimization & System ID

  • Open-loop trajectory rollouts (mujoco.rollout): When rolling out fixed control sequences (nbatch, nstep, ncontrol) from initial_state in one call, use mujoco.rollout.rollout (python.rst, .. _PyRollout:, and python/rollout.ipynb) or b.rollout(...).
  • Finite-difference derivatives & LQR (mjd_transitionFD): Compute linearized $A, B, C, D$ transition matrices with mujoco.mjd_transitionFD (APIreference/functions.rst, .. _Derivatives-api:, and python/LQR.ipynb).
  • Nonlinear least-squares & System ID (mujoco.minimize, mujoco.sysid): Use mujoco.minimize.least_squares (python.rst, .. _PyMinimize:, and python/least_squares.ipynb) for box-constrained QP optimization (mju_boxQP), and mujoco.sysid (pip install mujoco[sysid]; see python.rst, .. _PySysid:, modeling.rst, .. _CTuningSysid:, python/mujoco/sysid/README.md, and python/mujoco/sysid/sysid.ipynb) for fitting inertias, friction/damping, actuator gains, and delays to hardware logs over batched rollouts.

Compute Backend Comparison

Feature C++ Engine (Default) MJX (JAX) MJWarp (CUDA)
Import import mujoco (mujoco.batch, mujoco.rollout) from mujoco import mjx import mujoco_warp as mjw
Primary Use Real-time control, interactive tools, CPU batch RL/MPC, full solver support Differentiable physics, large batch RL High-throughput batch rollouts
Hardware CPU (single or multi-threaded) GPU / TPU NVIDIA GPU
Precision float64 (or float32 with -DmjUSESINGLE / --@mujoco//:single_precision) float32 float32
Solvers Newton, CG, PGS, noslip Newton, CG Newton, CG
Plugins All plugins Not supported SDF only

For GPU and TPU execution patterns (and RL frameworks like mujoco_playground and reaf-sim), refer to mujoco-accelerated; for cross-engine physics comparison, refer to mujoco-parity.

8. Common Gotchas & Best Practices

  1. Computed fields are read-only: Fields like data.xpos, data.xmat, and data.xquat are output buffers. Never assign to them directly; change inputs (data.qpos, data.ctrl) and call mj_forward() or mj_step().
  2. Duplicate names are forbidden: Spec element names must be unique within each element type.
  3. Orientation keywords are mutually exclusive: When adding geoms, bodies, or sites, provide only one of quat, euler, axisangle, xyaxes, or zaxis.
  4. Euler sequences: Lowercase characters denote intrinsic rotations ('xyz'), uppercase denote extrinsic rotations ('XYZ').
  5. Coordinate convention: +Z is up, gravity is [0, 0, -9.81].
  6. Repeating controls with nstep: Calling mj_step(model, data, nstep=N) repeats the current control across N steps. For dynamic feedback control, step one timestep at a time.

9. Key References

Documentation

Notebooks, Models & Ecosystem

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at eb1ff5e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 days ago
metadata
{
  "publisher": "google"
}

README badge

README badge for google-deepmind/mujoco/python