Table of Contents

Class MjData

Namespace
Gym.MuJoCo
Assembly
Gym.Environments.dll

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

model MjModel

The model, as returned by Load(byte[]).

Exceptions

ArgumentNullException

model is 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

NDArray

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

NDArray

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

NDArray

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

NDArray

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

NDArray

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

NDArray

QfrcActuator

The actuator forces in joint space (qfrc_actuator), shape (nv,).

[PyName("qfrc_actuator")]
public NDArray QfrcActuator { get; }

Property Value

NDArray

QfrcConstraint

The constraint forces in joint space (qfrc_constraint), shape (nv,).

[PyName("qfrc_constraint")]
public NDArray QfrcConstraint { get; }

Property Value

NDArray

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

NDArray

Qvel

The joint velocities (qvel), shape (nv,), float64; a writable view, as Qpos.

[PyName("qvel")]
public NDArray Qvel { get; }

Property Value

NDArray

SiteXpos

The sites' positions in the world (site_xpos), shape (nsite, 3): InvertedDoublePendulum's tip.

[PyName("site_xpos")]
public NDArray SiteXpos { get; }

Property Value

NDArray

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

NDArray

TenLength

The tendon lengths (ten_length), shape (ntendon,): Humanoid's two, empty elsewhere.

[PyName("ten_length")]
public NDArray TenLength { get; }

Property Value

NDArray

TenVelocity

The tendon velocities (ten_velocity), shape (ntendon,).

[PyName("ten_velocity")]
public NDArray TenVelocity { get; }

Property Value

NDArray

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

double

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

NDArray

Methods

Body(int)

The body with index id's quantities (data.body(id)).

[PyName("body")]
public MjDataBody Body(int id)

Parameters

id int

The 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

name string

The body's name in the model.

Returns

MjDataBody

A view of the body.

Exceptions

ArgumentNullException

name is 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()