Class MjData
A simulation's state and everything computed from it, what mujoco.MjData is to Gymnasium's MuJoCo envs,
with the engine that advances it: a from-scratch physics core for the eleven envs (the 21 ids that run on MuJoCo 3
and 4), written to step exactly as MuJoCo 4.0.0's mj_step does on win-x64. The same quantities are computed
in the same floating-point order, so every array it publishes (state, contacts, constraint rows, solver output)
equals MuJoCo's bit for bit. It followed MuJoCo 3.15.0 until the pin moved to 4.0.0 (DR-64), whose RK4,
quaternion kernels, capsule pairs, PGS scale and convex collider round differently.
public sealed class MjData : IDisposable
- Inheritance
-
MjData
- Implements
- Inherited Members
- Extension Methods
Remarks
Its public members are what Gymnasium's envs, utils and tests read of mujoco.MjData, under .NET names,
each [PyName]d to Python's (DR-68), and Mujoco's functions run its engine; the internal
fields keep MuJoCo's names and layouts so they can be compared with a recorded mjData.
It is not a translation of MuJoCo's sources: it computes only what such models need (hinge and slide joints
under an optional free root in each kinematic tree, a ground plane with spheres, capsules and cylinders, a box's
plane test (point.xml's arrow, which never reaches the floor; a box that would touch is refused), the
native convex collider's GJK, EPA and multi-contact pass for a capsule against a cylinder (the capsule's edge
clipped against the cylinder's disk), joint limits, pyramidal and frictionless contacts, motors, constraint
islands with the dense Newton solve per island or PGS on one tree, Euler with implicit joint damping or RK4
with its free-joint velocity correction, fixed tendons' lengths, sites, the inertia-box fluid forces, the
external contact forces of mj_rnePostConstraint) and drops MuJoCo's generality (sparse paths, sleeping,
flex, active tendons, sensors, callbacks, meshes, box contacts, the convex collider's face-face and discrete-geom
paths). Load(byte[]) refuses models outside that scope.
Not thread-safe: one instance owns its arrays, and Gym.MuJoCo.MjData.Step() reuses scratch storage, so give each thread (each vector sub-env) its own MjData; several may share one MjModel, which the engine only reads.
Verified by the trace checker (tools/parity/mujoco/halfcheetah_poc, which compiles these files)
against oracle.py's traces (docs/plans/MUJOCO_ASSESSMENT.md §11, §13 and §14), and searched for the branches
random actions reach (§13.4, §14.3). Branches no trace has executed are written
from MuJoCo's source but unproven. Some no model here can reach: geom priorities, direct (negative) or
mixed-sign solref, an impedance of power 1, a body of zero subtree mass, the undamped Euler step, a tilted or
lifted cylinder (Pusher's object only slides), a body welded to the world in the fluid, and union-find chains
of three trees. Others none of about 90 million searched physics steps reached: the auto-reset of a bad
state or bad controls, coincident sphere centers, two parallel capsules touching at both ends, a contact in the
gap zone, PGS's cost-rise revert, Newton's
fallbacks (a zero step, an exhausted or stuck line search, a lost rank in the factor update), the convex
collider's degenerate exits (EPA from a segment, a degenerate simplex, EPA's failure exits), and the kernels'
degenerate cases (tiny pivots, zero-length vectors and quaternions, a zero rotation angle).
Reference: MuJoCo 4.0.0's engine_forward.c, engine_core_smooth.c, engine_core_util.c, engine_collision_driver.c, engine_collision_primitive.c, engine_collision_convex.c, engine_core_constraint.c, engine_island.c, engine_solver.c, engine_passive.c and engine_support.c (Apache-2.0); each member names the MuJoCo function whose arithmetic it reproduces. GJK and EPA are in Gym.MuJoCo.Ccd.
Constructors
MjData(MjModel)
Allocates the core's arrays for a model; the state starts at the reference configuration, at rest.
public MjData(MjModel model)
Parameters
modelMjModelThe model, as returned by Load(byte[]).
Exceptions
- ArgumentNullException
modelis null.
Properties
Act
The actuator activations (act), shape (na,): always empty, since no bundled model has a stateful
actuator (Gymnasium's set_state clears it anyway).
[PyName("act")]
public NDArray Act { get; }
Property Value
CfrcExt
The external contact forces on each body (cfrc_ext), shape (nbody, 6), float64, torque then force
in the body's center-of-mass frame. Footgun: only MjRnePostConstraint(MjModel, MjData) computes it (Gymnasium's
envs call it after each step's physics), so after a reset it holds zeros.
[PyName("cfrc_ext")]
public NDArray CfrcExt { get; }
Property Value
Cinert
The bodies' inertias in their center-of-mass frames (cinert), shape (nbody, 10), as MuJoCo packs them.
[PyName("cinert")]
public NDArray Cinert { get; }
Property Value
Ctrl
The controls (ctrl), shape (nu,), float64: what the actuators apply at the next step, clamped to
their control ranges by the engine (not by the write). A writable view, as Qpos.
[PyName("ctrl")]
public NDArray Ctrl { get; }
Property Value
Cvel
The bodies' velocities in their center-of-mass frames (cvel), shape (nbody, 6), angular then linear.
[PyName("cvel")]
public NDArray Cvel { get; }
Property Value
GeomXpos
The geoms' positions in the world (geom_xpos), shape (ngeom, 3); the free camera looks at their median.
[PyName("geom_xpos")]
public NDArray GeomXpos { get; }
Property Value
QfrcActuator
The actuator forces in joint space (qfrc_actuator), shape (nv,).
[PyName("qfrc_actuator")]
public NDArray QfrcActuator { get; }
Property Value
QfrcConstraint
The constraint forces in joint space (qfrc_constraint), shape (nv,).
[PyName("qfrc_constraint")]
public NDArray QfrcConstraint { get; }
Property Value
Qpos
The joint positions (qpos), shape (nq,), float64: a free joint's 3 coordinates and unit
quaternion, then one value per hinge or slide. A writable view of the simulation's own array, as Python's is:
Data.Qpos[2] = 1.0 moves the model at the next MjForward(MjModel, MjData). The caller owns the view
and should dispose it; disposing it never affects the simulation.
[PyName("qpos")]
public NDArray Qpos { get; }
Property Value
Qvel
The joint velocities (qvel), shape (nv,), float64; a writable view, as Qpos.
[PyName("qvel")]
public NDArray Qvel { get; }
Property Value
SiteXpos
The sites' positions in the world (site_xpos), shape (nsite, 3): InvertedDoublePendulum's tip.
[PyName("site_xpos")]
public NDArray SiteXpos { get; }
Property Value
SolverNiter
The solver's iterations per constraint island at the last step (solver_niter), shape (20,), int32:
MuJoCo's mjNISLAND entries, all 0 when there were no constraints.
[PyName("solver_niter")]
public NDArray SolverNiter { get; }
Property Value
TenLength
The tendon lengths (ten_length), shape (ntendon,): Humanoid's two, empty elsewhere.
[PyName("ten_length")]
public NDArray TenLength { get; }
Property Value
TenVelocity
The tendon velocities (ten_velocity), shape (ntendon,).
[PyName("ten_velocity")]
public NDArray TenVelocity { get; }
Property Value
Time
The simulation time in seconds (time), advanced by each step's time step; writable, as in Python.
[PyName("time")]
public double Time { get; set; }
Property Value
Xipos
The bodies' centers of mass in the world (xipos), shape (nbody, 3), as Humanoid's mass_center weighs them.
[PyName("xipos")]
public NDArray Xipos { get; }
Property Value
Methods
Body(int)
The body with index id's quantities (data.body(id)).
[PyName("body")]
public MjDataBody Body(int id)
Parameters
idintThe body's index, 0 (the world) to
nbody - 1.
Returns
- MjDataBody
A view of the body.
Exceptions
- IndexError
The index is out of range, with MuJoCo's message.
Body(string)
The body named name's quantities (data.body(name)): its Xpos,
which MujocoEnv.get_body_com returns.
[PyName("body")]
public MjDataBody Body(string name)
Parameters
namestringThe body's name in the model.
Returns
- MjDataBody
A view of the body.
Exceptions
- ArgumentNullException
nameis null.- KeyError
No body has that name, with MuJoCo's message listing the valid names in sorted order.
Dispose()
Releases the views' roots, which pin the data's arrays; views a caller still holds keep working until disposed. Gym.NET's MuJoCo envs dispose their data when closed.
public void Dispose()