The key function here is mj_loadXML. It invokes the built-in parser and compiler, and either returns a pointer to
a valid mjModel, or NULL - in which case the user should check the error information in the user-provided string.
The model and all files referenced in it can be loaded from disk or from a VFS when provided.
Encode mjSpec or mjModel to a file. The output format is determined by the file extension
(case insensitive) or content_type. Returns the number of bytes written on success, -1 on failure.
For detailed documentation, supported output formats (.xml, .mjb, .txt, .mjz), and custom encoder
plugins, see Model Encoding & Saving.
Compile mjSpec to mjModel. A spec can be edited and compiled multiple times, returning a new
mjModel instance that takes the edits into account.
If compilation fails, mj_compile returns NULL; the error can be read with mjs_getError.
Compilation leaves the spec as it is written, with two exceptions. It completes keyframes: their
vectors are sized for the model, and keyframes are added up to nkey. And the compiler attributes
discardvisual and fusestatic apply
mjs_discardVisual and mjs_fuseStatic to the spec before it is compiled, which changes it: pointers to
the elements which they remove are no longer valid. An operation which fails changes nothing, but one which succeeded
stays applied if a later one, or the compilation, fails; the error then says so.
Copy to an mjSpec the values which were changed in the mjModel that was compiled from it. The changes
can then be read in the spec, are saved with it, and are in the models which are compiled from it afterwards. An
attribute is copied if the model no longer has what compilation gave it, all of its numbers; everything else in the
spec is left as it is, including what was written there since it was compiled. The position and the orientation of a
pose, and the bounds of a range, are separate attributes. Returns 1 on success. Returns 0 if the model was not compiled
from the spec as it is structured now, or if a value was changed which the spec cannot express; nothing is copied
then, and the error can be read with mjs_getError. A model can also be copied back to a copy of the spec made
by mj_copySpec.
The values which are copied are mjModel.opt, mjModel.vis and mjModel.stat, the real-valued parameters of
bodies, joints, geoms, sites, cameras, lights, materials, contact pairs, equalities, tendons, actuators and sensors,
custom numeric and tuple data, keyframes and the elevation data of height fields. Each is written as what compiles to
it:
A pose is written in the frame which the element is in. An orientation which was not changed stays as
it was written, for example as Euler angles, and one which was changed is written as a quaternion. Where
compilation offsets the position by the orientation, for a mesh geom whose mesh is not centered at its origin and a
body which is aligned with its free joint, a new orientation also writes the position.
The reference pose of a body with a free joint is taken from mjModel.qpos0 if that was changed.
The size and pose of a geom or site which were written as fromto, or computed by fitting a geom to a mesh, are
written in its place. A new radius of a capsule or cylinder leaves fromto as it is.
A mass or inertia which was changed gives the body an explicit inertial, which is then no
longer inferred from its geoms; a body which has one keeps it as it was written if only the mass was changed. The
inertia of the other bodies still follows their geoms, including a size or pose which was copied.
A range whose limited attribute is “auto” keeps the limited state which it has in the model: the attribute is
set if the new range would be inferred otherwise.
A stiffness or damping of a joint with springdamper, and a control or activation
range which was inherited with inheritrange, are written in its place.
Elevation data of a height field which was read from a file is written in place of the file.
The relative pose of a weld between bodies which is marked by a nonzero
mjModel.eq_data[11] is written as computed, with a zero quaternion.
The following changes cannot be expressed in the spec and are errors: the mass or inertia of a body when
inertiafromgeom is “true” or settotalmass is set; the
inertial frame of a body which is aligned with its free joint; the pose of the world
body; the anchor or axis of a free joint and the axis of a ball joint; the size of a mesh or height field geom or of a
mesh site, and the frame of a mesh; the field of view of a camera which has a sensor size, and the intrinsics of one
which has none; and different control ranges for the inputs of an actuator which has one. So are changes which the
next compilation would not keep: damping, armature, friction loss or their solver parameters which differ between the
degrees of freedom of a ball or free joint; elevation data of a height field whose lowest and highest values are not
0 and 1; and the anchor of a connect between bodies in its second body, or the relative pose
of a marked weld, other than the one which mj_setConst computes.
Recompile spec to model, preserving the state. Like mj_compile, this function compiles an mjSpec to an
mjModel, with two differences. First, rather than returning an entirely new model, it will
reallocate existing mjModel and mjData instances in-place. Second, it will preserve the
integration state, as given in the provided mjData instance, while accounting for
newly added or removed degrees of freedom. This allows the user to continue simulation with the same model and data
struct pointers while editing the model programmatically.
mj_recompile returns 0 if compilation succeed. In the case of failure, the given mjModel and mjData
instances will be deleted; as in mj_compile, the compilation error can be read with mjs_getError.
Decode texture id to raw bytes, exactly what compilation would store in tex_data, with
tex_nchannel channels; embedded textures are copied from the model. The buffer is allocated with
mju_malloc and freed by the caller; colorspace receives the resolved colorspace (mjtColorSpace).
Copy of m with every by-reference asset loaded into it, as compilation would have stored it.
Return NULL with error on a file that does not resolve. A hermetic MJB file of a model with
by-reference assets is mj_embedAssets, then mj_saveModel, then mj_deleteModel.
Update XML data structures with info from low-level model created with mj_loadXML, save as MJCF.
If error is not NULL, it must have size error_sz.
Note that this function only saves models that have been loaded with mj_loadXML, the legacy loading mechanism.
See the model editing chapter to understand the difference between the old and new model loading and
saving mechanisms.
Save spec to XML string, return 0 on success, -1 on failure. If the length of the output buffer is too small, returns
the required size. See mj_saveXML for what is saved.
Save spec to XML file, return 0 on success, -1 otherwise. The compiler attributes
savecompiled and savecanonical of the spec say whether
the model is saved as it was compiled or as it is written in the spec, and in which notation; see
Model Encoding & Saving. Saving the compiled values requires that the spec first be compiled, and
compiled again after it is structurally edited (elements added, deleted or attached).
These are the main entry points to the simulator. Most users will only need to call mj_step, which computes
everything and advanced the simulation state by one time step. Controls and applied forces must either be set in advance
(in mjData.{ctrl,qfrc_applied,xfrc_applied}), or a control callback mjcb_control must be installed which
will be called just before the controls and applied forces are needed. Alternatively, one can use mj_step1 and
mj_step2 which break down the simulation pipeline into computations that are executed before and after the
controls are needed; in this way one can set controls that depend on the results from mj_step1. Keep in mind
though that the RK4 solver does not work with mj_step1/2. See Simulation pipeline for a more detailed description.
mj_forward performs the same computations as mj_step but without the integration. It is useful after loading or
resetting a model (to put the entire mjData in a valid state), and also for out-of-order computations that involve
sampling or finite-difference approximations.
mj_inverse runs the inverse dynamics, and writes its output in mjData.qfrc_inverse. Note that mjData.qacc
must be set before calling this function. Given the state (qpos, qvel, act), mj_forward maps from force to acceleration,
while mj_inverse maps from acceleration to force. Mathematically these functions are inverse of each other, but
numerically this may not always be the case because the forward dynamics rely on a constraint optimization algorithm
which is usually terminated early. The difference between the results of forward and inverse dynamics can be computed
with the function mj_compareFwdInv, which can be thought of as another solver accuracy check (as well as a
general sanity check).
The skip version of mj_forward and mj_inverse are useful for example when qpos was unchanged but qvel was
changed (usually in the context of finite differencing). Then there is no point repeating the computations that only
depend on qpos. Calling the dynamics with skipstage = mjSTAGE_POS will achieve these savings.
These are support functions that need access to mjModel and mjData, unlike the utility functions which do
not need such access. Support functions are called within the simulator but some of them can also be useful for custom
computations, and are documented in more detail below.
Copy concatenated state components specified by sig from d into state. The bits of the integer
sig correspond to element fields of mjtState. Fails with mju_error if sig is invalid.
Extract into dst the subset of components specified by dstsig from a state src previously obtained via
mj_getState with components specified by srcsig. Fails with mju_error if the bits set in dstsig
is not a subset of the bits set in srcsig.
Copy concatenated state components specified by sig from state into d. The bits of the integer
sig correspond to element fields of mjtState. Fails with mju_error if sig is invalid.
Read the control value for an actuator at a given time, taking delays into account. If no history buffer exists, return
a pointer to the actuator’s slice of mjData.ctrl. If a history buffer exists (nsample > 0),
read from the delay buffer at time-actuator_delay[id]. Note that the subtraction of the delay changes the semantic
of the time argument from “time at which values were pushed into the delay buffer” to “time at which values come out
of the delay buffer”. See Delays for details.
Return value semantics:
If no history buffer exists (nsample = 0), returns a pointer to the actuator’s slice
of mjData.ctrl.
If a history buffer exists (nsample > 0) and the requested time matches a stored
sample (always true for interp=0), returns a pointer to the data in the history buffer.
If interpolation is required (interp=1or2), returns NULL and writes the interpolated result to
result (must be of size actuator_ctrlnum[id]).
Read a sensor value at a given time, taking delays into account. If no history buffer exists, return a pointer to the
sensor’s slice of mjData.sensordata. If a history buffer exists (nsample > 0), read from the
history buffer at time-sensor_delay[id]. Note that the subtraction of the delay changes the semantic of the
time argument from “time at which values were pushed into the delay buffer” to “time at which values come out of the
delay buffer”. See Delays for details.
Return value semantics:
If no history buffer exists (nsample = 0), returns a pointer to the sensor’s slice of
mjData.sensordata.
If a history buffer exists (nsample > 0) and the requested time matches a stored sample
(always true for interp=0), returns a pointer to the data in the history buffer.
If interpolation is required (interp=1or2), returns NULL and writes the interpolated result to
result (must be of size dim).
Constant extrapolation is used outside of buffer bounds.
Usage:
// read sensor 0 of data size `dim` at time tmjtNumresult[dim];constmjtNum*ptr=mj_readSensor(m,d,0,t,result,/* interp = */1);constmjtNum*data=ptr?ptr:result;
Initialize the history buffer for an actuator with custom values. The times array specifies the timestamps for each
sample (must be length nsample), and values specifies the control values (must be of
size nsample*actuator_ctrlnum[id]). If times is NULL, the existing timestamps in the buffer are used, and
only the values are updated.
See Delays for details.
Initialize the history buffer for a sensor with custom values. The times array specifies the timestamps for each
sample (must be length nsample), and values specifies the sensor values (must be of size
nsample*dim). If times is NULL, the existing timestamps in the buffer are used.
The phase argument sets the user slot, which stores the last computation time for interval sensors.
See Delays for details.
This function multiplies the constraint Jacobian mjData.efc_J by a vector. Note that the Jacobian can be either dense or
sparse; the function is aware of this setting. Multiplication by J maps velocities from joint space to constraint space.
This function computes an end-effector kinematic Jacobian, describing the local linear relationship between the
degrees-of-freedom and a given point. Given a body specified by its integer id (body) and a 3D point in the world
frame (point) treated as attached to the body, the Jacobian has both translational (jacp) and rotational
(jacr) components. Passing NULL for either pointer will skip that part of the computation. Each component is a
3-by-nv matrix. Each row of this matrix is the gradient of the corresponding coordinate of the specified point with
respect to the degrees-of-freedom. The frame with respect to which the Jacobian is computed is centered at the body
center-of-mass but aligned with the world frame. The minimal pipeline stages required for Jacobian
computations to be consistent with the current generalized positions mjData.qpos are mj_kinematics followed
by mj_comPos.
This and the remaining variants of the Jacobian function call mj_jac internally, with the center of the body, geom or
site. They are just shortcuts; the same can be achieved by calling mj_jac directly.
This function computes the time-derivative of an end-effector kinematic Jacobian computed by mj_jac.
The minimal pipeline stages required for computation to be
consistent with the current generalized positions and velocities mjData.{qpos,qvel} are
mj_kinematics, mj_comPos, mj_comVel (in that order).
This function computes the 3xnv angular momentum matrix \(H(q)\), providing the linear mapping from
generalized velocities to subtree angular momentum. More precisely if \(h\) is the subtree angular momentum of
body index body in mjData.subtree_angmom (reported by the subtreeangmom sensor)
and \(\dot q\) is the generalized velocity mjData.qvel, then \(h = H \dot q\).
This function can be used to apply a Cartesian force and torque to a point on a body, and add the result to the vector
mjData.qfrc_applied of all applied forces. Note that the function requires a pointer to this vector, because sometimes
we want to add the result to a different vector.
Compute object 6D acceleration (rot:lin) in object-centered frame, world/local orientation. If acceleration or force
sensors are not present in the model, mj_rnePostConstraint must be manually called in order to calculate
mjData.cacc – the total body acceleration, including contributions from the constraint solver.
Returns the smallest signed distance between two geoms and optionally the segment from geom1 to geom2.
Returned distances are bounded from above by distmax. If no collision of distance smaller than distmax is
found, the function will return distmax and fromto, if given, will be set to (0, 0, 0, 0, 0, 0).
This function subtracts two vectors in the format of qpos (and divides the result by dt), while respecting the
properties of quaternions. Recall that unit quaternions represent spatial orientations. They are points on the unit
sphere in 4D. The tangent to that sphere is a 3D plane of rotational velocities. Thus when we subtract two quaternions
in the right way, the result is a 3D vector and not a 4D vector. Thus the output qvel has dimensionality nv while the
inputs have dimensionality nq.
Scan a directory and load all dynamic libraries. Dynamic libraries in the specified directory
are assumed to register one or more plugins. Optionally, if a callback is specified, it is called
for each dynamic library encountered that registers plugins.
These are components of the simulation pipeline, called internally from mj_step, mj_forward and
mj_inverse. It is unlikely that the user will need to call them.
Integrates the simulation state using an implicit-in-velocity integrator (either “implicit” or “implicitfast”, see
Numerical Integration), and advances simulation time. See mjdata.h for fields computed by this function.
Compute the composite rigid body inertia with mj_crb, add terms due
to tendon armature. The joint-space inertia matrix is stored in both mjData.qM and
mjData.M. These arrays represent the same quantity using different layouts (parent-based and compressed sparse row,
respectively).
Sub-tree linear velocity and angular momentum: compute subtree_linvel, subtree_angmom.
This function is triggered automatically if the subtree velocity or
momentum sensors are present in the model.
It is also triggered for user sensors of stage “vel”.
Recursive Newton Euler with final computed forces and accelerations.
Computes three body-level nvx6 arrays, all defined in the subtreecom-based
c-frame and arranged in [rotation(3),translation(3)] order.
cfrc_ext collects the forces that are not transmitted through the joints: applied Cartesian forces
(xfrc_applied), contacts, connect and weld constraints, and spatial tendons (spring, damper, actuator, constraint
and armature forces along the tendon path). cfrc_int is then the wrench transmitted through the joint, and its
projection on the joint axes is the total joint-space force. Forces of actuators with site, slider-crank and body
transmissions, gravity compensation, fluid forces, flex forces and custom passive forces are not yet collected and are
attributed to the joints.
Ray collisions, also known as ray casting, find the distance x of a ray’s intersection with a geom, where a ray is
a line emanating from the 3D point p in the direction v i.e., (p+x*v,x>=0). All functions in this
family return the distance to the nearest geom surface, or -1 if there is no intersection. Note that if p is inside
a geom, the ray will intersect the surface from the inside which still counts as an intersection.
All ray collision functions rely on quantities computed by mj_kinematics (see mjData), so must be called
after mj_kinematics, or functions that call it (e.g. mj_fwdPosition). The top level functions, which
intersect with all geoms types, are mj_ray which casts a single ray, and mj_multiRay which casts multiple
rays from a single point.
Return distance x to nearest surface, or -1 if no intersection.
If geomid is not NULL, write the id of the intersected geom or -1 if not intersection.
If normal is not NULL, write the surface normal at the intersection point. The normal always points out of the
geometry, regardless of the ray’s direction (i.e., including rays hitting the surface from the inside).
Exclude geoms in body with id bodyexclude, use -1 to include all bodies.
geomgroup is an array of length mjNGROUP, where 1 means the group should be included. Pass
NULL to skip geom group exclusion.
If flg_static is 0, static geoms will be excluded.
Virtual file system (VFS) enables the user to load all necessary files in memory, including MJB binary model files, XML
files (MJCF, URDF and included files), STL meshes, PNGs for textures and height fields, and HF files in our custom
height field format. Model and resource files in the VFS can also be constructed programmatically (say using a Python
library that writes to memory). Once all desired files are in the VFS, the user can call mj_loadModel or
mj_loadXML with a pointer to the VFS. When this pointer is not NULL, the loaders will first check the VFS for any
files they are about to load, and only access the disk if the file is not found in the VFS.
Add file to VFS. The directory argument is optional and can be NULL or empty. Returns 0 on success,
2 on name collision, or -1 when an internal error occurs.
The asset cache is a mechanism for caching assets (e.g. textures, meshes, etc.) to avoid repeated slow recompilation.
The following methods provide way to control the capacity of the cache or to disable it altogether.
Resources are the interface between resource providers and MuJoCo model compilation code.
These functions provide the means to query the resource provider and obtain resources.
Save model to binary MJB file or memory buffer; buffer has precedence when given. The model is written as it is: a
model with by-reference textures keeps them as references, and the file loads wherever the
paths resolve. A hermetic file is mj_embedAssets, then mj_saveModel on the result, then
mj_deleteModel.
Copy mjData, skipping large arrays not required for visualization, like the constraint Jacobian. The copy is
meant for visualization, e.g. with mjv_updateScene; the skipped arrays are NULL, so it is not a valid input
to simulation functions.
Main error function. The error message is dispatched to the active log handler (see mju_setLogHandler).
Errors are always fatal: if the handler returns, the process is terminated with exit(EXIT_FAILURE). Handlers
wishing to recover must longjmp or otherwise transfer control before returning.
Clear all user handlers and restore defaults. Resets the legacy error/warning/memory callbacks to NULL, restores
the default log handler, and resets the log configuration to its defaults (console and file output enabled, all info
topics disabled).
Set the active global log handler. Returns the previous handler (which is never NULL), intended for save/restore
or callback chaining. If handler is NULL, the default handler is restored. The handler receives all errors,
warnings and informational messages as a structured mjLogMessage. See Installing a handler for usage examples.
Log an informational message with optional topic filtering. The topic argument is a mjtLogTopic value.
Topic 0 (mjTOPIC_NONE) always passes through. Other topics must be enabled in the default handler configuration
via mju_setLogConfig. Note that topic filtering is implemented in the default handler; custom handlers
receive all info messages regardless.
Dispatch a structured mjLogMessage to the active log handler. This is the primary entry point for emitting
log messages with full control over all fields. The convenience functions mju_error, mju_warning, and
mju_info are thin wrappers that populate an mjLogMessage and call this function.
The subject field is a one-line summary (up to 1024 bytes, inline in the struct). The body field is an
optional constchar* pointer to multi-line detail text, owned by the caller. When body is NULL, only the
subject line is printed.
The default handler formats the output as follows:
LEVEL FUNC (FILE:LINE) TIME: SUBJECT
BODY
where:
LEVEL is ERROR, WARNING, INFO, or DEBUG.
FUNC is present when the func field is set.
(FILE:LINE) is present when the file and line fields are set.
TIME is present when the timestamp field is set or file logging is active.
SUBJECT is the contents of the subject field.
BODY follows on the next line(s), printed raw without indentation or separators, only if non-NULL.
The default handler appends a trailing blank line after ERROR, WARNING, and INFO messages for visual
separation. DEBUG messages are printed compactly without a trailing blank line.
Example usage:
mjLogMessagemsg={.level=mjLOG_INFO,.timestamp=true,.body=" height: 0.001 m\n velocity: 0.000 m/s\n bounces: 47",};snprintf(msg.subject,sizeof(msg.subject),"The ball has come to rest");mju_message(&msg);
This produces:
INFO Mon Jun 9 15:04:05 2026: The ball has come to rest
height: 0.001 m
velocity: 0.000 m/s
bounces: 47
This function is used for mouse selection, relying on ray intersections. aspectratio is the viewport width/height. relx
and rely are the relative coordinates of the 2D point of interest in the viewport (usually mouse cursor). The function
returns the id of the geom under the specified 2D point, or -1 if there is no geom (note that they skybox if present is
not a model geom). The 3D coordinates of the clicked point are returned in selpnt. See simulate for
an illustration.
The functions in this section implement abstract visualization. The results are used by the OpenGL renderer, and can
also be used by users wishing to implement their own renderer, or hook up MuJoCo to advanced rendering tools such as
Unity or Unreal Engine. See simulate for illustration of how to use these functions.
Rendering functions using the Filament rendering engine. These functions are prefixed with mjrf. See
Filament Rendering for an overview of the core types and their uses.
Submits the given requests for rendering. Because rendering happens asynchronously, callers have
to submit both the render and read requests in the same call. Multiple requests and reads can be
submitted in a single call. These requests will be processed in order, so some care must be
taken. Firstly, requests should be grouped by target. Next, the combined area of the viewports
for all requests for a given target must be contained within the dimensions of the target itself.
Callbacks will be invoked from within this function, though there is no guarantee on which
invocation of this function it will be done.
Sets the mesh of the renderable to a built-in mesh based on the geom type. Note: using the same
parameters (nstack, nslice, nquad) will have better performance as the internal mesh data can be
shared across renderables.
[type: mjtGeom]
Sets the size of the renderable. Note that, for most renderables, this is equivalent to setting
the scale. However, for some geom-based renderables, the size scale is not applied uniformly
(e.g. the spherical ends of a capsule are scaled such that they always remain spherical).
This is the helper function used to construct a UI. The second argument points to an array of mjuiDef structs,
each corresponding to one item. The last (unused) item has its type set to -1, to mark termination. The items are added
after the end of the last used section. There is also another version of this function
(mjui_addToSection) which adds items to a specified section instead of adding them at the end
of the UI. Keep in mind that there is a maximum preallocated number of sections and items per section, given by
mjMAXUISECT and mjMAXUIITEM. Exceeding these maxima results in low-level errors.
This is the main UI update function. It needs to be called whenever the user data (pointed to by the item data pointers)
changes, or when the UI state itself changes. It is normally called by a higher-level function implemented by the user
(UiModify in simulate.cc) which also recomputes the layout of all rectangles and associated
auxiliary buffers. The function updates the pixels in the offscreen OpenGL buffer. To perform minimal updates, the user
specifies the section and the item that was modified. A value of -1 means all items and/or sections need to be updated
(which is needed following major changes.)
This function is the low-level event handler. It makes the necessary changes in the UI and returns a pointer to the item
that received the event (or NULL if no valid event was recorded). This is normally called within the event handler
implemented by the user (UiEvent in simulate.cc), and then some action is taken by user code
depending on which UI item was modified and what the state of that item is after the event is handled.
This function is called in the screen refresh loop. It copies the offscreen OpenGL buffer to the window framebuffer. If
there are multiple UIs in the application, it should be called once for each UI. Thus mjui_render is called all the
time, while mjui_update is called only when changes in the UI take place. dsffsdg
The functions below provide useful derivatives of various functions, both analytic and
finite-differenced. The latter have names with the suffix FD. Note that unlike much of the API,
outputs of derivative functions are the trailing rather than leading arguments.
Letting \(x, u\) denote the current state and control
vector in an mjData instance, and letting \(y, s\) denote the next state and sensor
values, the top-level mj_step function computes \((x,u) \rightarrow (y,s)\)mjd_transitionFD computes the four associated Jacobians using finite-differencing.
These matrices and their dimensions are:
matrix
Jacobian
dimension
A
\(\partial y / \partial x\)
2*nv+nax2*nv+na
B
\(\partial y / \partial u\)
2*nv+naxnu
C
\(\partial s / \partial x\)
nsensordatax2*nv+na
D
\(\partial s / \partial u\)
nsensordataxnu
All outputs are optional (can be NULL).
eps is the finite-differencing epsilon.
flg_centered denotes whether to use forward (0) or centered (1) differences.
The Runge-Kutta integrator (mjINT_RK4) is not supported.
Sleeping is not supported. Disable the sleep flag before calling.
If warm-starts are not disabled, the warm-start accelerations
mjData.qacc_warmstart which are present at call-time are loaded at the start of every relevant pipeline call,
to preserve determinism. If solver computations are an expensive part of the simulation, the following trick can
lead to significant speed-ups: First call mj_forward to let the solver converge, then reduce solver
iterations significantly, then call mjd_transitionFD, finally, restore the original
value of iterations. Because we are already near the solution, few iteration are required
to find the new minimum. This is especially true for the Newton solver, where the required
number of iteration for convergence near the minimum can be as low as 1.
tolerance
Accuracy can be improved if solver tolerance is set to 0. This means that all calls to
the solver will perform exactly the same number of iterations, preventing numerical errors due to early
termination. Of course, this means that solver iterations should be small, to not tread
water at the minimum. This method and the one described above can and should be combined.
Letting \(x, a\) denote the current state and acceleration vectors in an mjData instance, and
letting \(f, s\) denote the forces computed by the inverse dynamics (qfrc_inverse), the function
mj_inverse computes \((x,a) \rightarrow (f,s)\). mjd_inverseFD computes seven associated Jacobians
using finite-differencing. These matrices and their dimensions are:
matrix
Jacobian
dimension
DfDq
\(\partial f / \partial q\)
nvxnv
DfDv
\(\partial f / \partial v\)
nvxnv
DfDa
\(\partial f / \partial a\)
nvxnv
DsDq
\(\partial s / \partial q\)
nvxnsensordata
DsDv
\(\partial s / \partial v\)
nvxnsensordata
DsDa
\(\partial s / \partial a\)
nvxnsensordata
DmDq
\(\partial M / \partial q\)
nvxnC
All outputs are optional (can be NULL).
All outputs are transposed relative to Control Theory convention (i.e., column major).
DmDq, which contains a sparse representation of the nvxnvxnv tensor \(\partial M / \partial q\), is
not strictly an inverse dynamics Jacobian but is useful in related applications. It is provided as a convenience to
the user, since the required values are already computed if either of the other two \(\partial / \partial q\)
Jacobians are requested.
eps is the (forward) finite-differencing epsilon.
flg_actuation denotes whether to subtract actuation forces (qfrc_actuator) from the output of the inverse
dynamics. If this flag is positive, actuator forces are not considered as external.
The model option flag invdiscrete should correspond to the representation of mjData.qacc in order to compute
the correct derivative information.
Attention
The Runge-Kutta 4th-order integrator (mjINT_RK4) is not supported.
The noslip solver is not supported.
Sleeping is not supported. Disable the sleep flag before calling.
\({\tt \small mju\_quatIntegrate}(q, v, h)\) performs the in-place rotation \(q \leftarrow q + v h\),
where \(q \in \mathbf{S}^3\) is a unit quaternion, \(v \in \mathbf{R}^3\) is a 3D angular velocity and
\(h \in \mathbf{R^+}\) is a timestep. This is equivalent to \({\tt \small mju\_quatIntegrate}(q, s, 1.0)\),
where \(s\) is the scaled velocity \(s = h v\).
\({\tt \small mjd\_quatIntegrate}(v, h, D_q, D_v, D_h)\) computes the Jacobians of the output \(q\) with respect
to the inputs. Below, \(\bar q\) denotes the pre-modified quaternion:
Globally register a plugin. This function is thread-safe.
If an identical mjpPlugin is already registered, this function does nothing.
If a non-identical mjpPlugin with the same name is already registered, an mju_error is raised.
Two mjpPlugins are considered identical if all member function pointers and numbers are equal,
and the name and attribute strings are all identical, however the char pointers to the strings
need not be the same.
Globally register a provider in a thread-safe manner. The provider must have a prefix
that is not a sub-prefix or super-prefix of any current registered providers.
Return a slot number >= 0 on success, -1 on failure.
Functions for running many simulations of one model on a thread pool, declared in mujoco/mjbatch.h. See
Batched simulation for an overview and an example.
The functions that run simulations take a selection: ids holds nid sorted, unique simulation indices, or is
NULL to select every simulation, in which case nid is ignored. They return the number of simulations in which
MuJoCo raised an error. Those simulations keep the state they had before the call, and the others run to completion.
mjb_status and mjb_error report the outcome of each simulation’s last call.
Invalid arguments, such as unsorted ids or an unknown stage, are a different kind of error: the function raises
it with mju_error on the caller’s thread, before any simulation runs, and it is not counted in the return value.
Errors in simulations are trapped by a thread-local log handler. Therefore, physics callbacks, engine
plugins and functions run by mjb_apply must not raise errors with mju_error or throw exceptions. Other
messages, such as warnings, go to the log handler the thread would use anyway. On the batch’s threads this is the
global handler. On the caller’s thread it can also be a thread-local handler, such as the one
the Python bindings install. Either way, the counters of mjb_warning count every simulation’s warnings.
The arrays that the batch returns, such as the state rows, outputs and expanded fields, are owned by the batch. They
stay at the same address until mjb_deleteBatch frees them.
Timers (mjData.timer, see mjTimerStat) are not part of the state. In a persistent batch, each simulation’s
mjData times that simulation, and mjb_getData copies its timers. Otherwise, each thread’s mjData accumulates the
timing of every simulation the thread runs, until a reset of one of them clears it. These timers profile the batch as a
whole rather than any one simulation.
Allocate a batch of nsim simulations of a copy of m, and return it. config holds the mjBatchConfig
parameters; if it is NULL, the defaults of mjb_defaultConfig apply. If the model cannot be batched, or making
an mjData raises an error, return NULL and write the reason into error, a buffer of error_sz bytes.
The batch runs on config->nthread threads, including the caller’s. If nthread<=0, it uses one thread per
logical CPU. Either way, it uses at most nsim threads. The number of logical CPUs is the machine’s, which can exceed
what the process may use, for example in a container; set nthread explicitly there.
If config->persistent is nonzero, the batch keeps one mjData per simulation instead of one per thread. Models with
sleep or IPC enabled require this. In a batch that is not persistent,
engine plugins that keep state outside plugin_state share that state among the simulations a thread
runs.
Return the state rows, nsimxnstate. Row i is simulation i’s integration state,
in mj_getState order. Writing to a row sets the simulation’s state for its next call, which then overwrites the
row with the new state.
Return the address of state component component (one bit of mjtState) in the first state row, and write its
number of elements into size. Simulation i’s component is mjb_nstate(b)*i elements further on. Raise an
error if component is not one bit of mjSTATE_INTEGRATION.
Advance each selected simulation by nstep calls to mj_step, then compute the stages of mj_forward up
to stage (an mjtStage) at the new state. Return the number of simulations in which MuJoCo raised an error.
As with mj_step, derived fields after the steps describe the state before the last substep. stage brings
them up to date:
mjSTAGE_VEL makes position- and velocity-dependent fields and sensors current, as mj_step1 does.
Acceleration-dependent fields remain those of the last substep, under the controls it applied.
mjSTAGE_ACC runs mj_forward, at nearly the cost of another step. Its acceleration-dependent values use
controls that the next step will replace.
In a persistent batch, a simulation’s next step continues from these stages with mj_step2, so mjSTAGE_VEL
costs nothing extra. The step does not continue if anything the stages depend on changed in between, other than
ctrl, qfrc_applied and xfrc_applied; the results are the same either way. As with mj_step1 and
mj_step2, this assumes that plugins do not make the position and velocity stages depend on those inputs. A loop
of mj_forward and mj_step computes these stages twice at the same state, while a continued step computes
them once; this matters only to plugins whose computations have side effects. Installed physics
callbacks turn the continuation off, but removing one between a call and the next step is not detected. A
continued step counts as one step in mjData.timer, but its mjTIMER_STEP duration excludes the position and
velocity stages, which are timed in the call that computed them.
Compute the stages of mj_forward up to stage (an mjtStage) on each selected simulation.
mjSTAGE_ACC runs mj_forward. Return the number of simulations in which MuJoCo raised an error.
Reset each selected simulation, then compute the stages of mj_forward up to stage (an mjtStage).
Return the number of simulations in which MuJoCo raised an error.
key holds one keyframe per selected simulation, in call order; a keyframe of -1, or a NULLkey, resets to
the model’s defaults. mjSTAGE_ACC runs mj_forward. mjSTAGE_NONE suits a reset that is followed by writes
to the state and mjb_forward. Writes to the state rows made before the call are discarded.
Return the status of each simulation’s last call: nsim values, nonzero where MuJoCo raised an error. Each call
updates the values of the simulations it runs.
Register mjData field name as an output, and return its storage: nsimxsize elements of the field’s
type. Write the number of elements per simulation into size and the element size in bytes into elemsize. After
every call on a simulation except mjb_apply, the batch copies the field from the simulation’s mjData into its
row of the storage. Registering a field again returns the same storage.
name can be an array field, or one of the counts ncon, ne, nf, nl, nefc, nJ, nA,
nisland and nidof. Return NULL for unknown fields, and for fields of the state row, which mjb_state
already holds.
In a persistent batch, the storage starts with each simulation’s current values. Otherwise, it is zero until the next
call on a simulation, and a field that the call does not compute holds another simulation’s value. Examples are
qfrc_inverse after mj_step, quantities computed only for the sensors that need them, and fields of stages
above the call’s stage.
Give mjModel field name per-simulation values, and return their storage: nsimxsize elements of the
field’s type, initialized from the model. Before each call on a simulation, the batch copies the simulation’s row into
its model. size and elemsize are written as by mjb_output. Expanding a field again returns the same
storage.
Array fields are named as in mjModel, and mjOption fields as "opt.<name>". The storage of
bvh_aabb holds only the bodies’ bounding volumes, which come before the meshes’. Return NULL for unknown fields
and for asset fields (meshes, heightfields, textures, skins), which all simulations share.
Writing a field that mj_setConst reads, an input in MJSETCONST_ARRAYS of mjxmacro.h or an
mjOption field, does not update the constants derived from it until mjb_setConst runs.
Expanding a field that mjb_setConst expanded makes it an input of later calls to mjb_setConst, if
mj_setConst reads it before writing it. To read such a field without that effect, use mjb_expanded.
Return the per-simulation storage of mjModel field name if it is expanded, by mjb_expand or by
mjb_setConst. Otherwise, return NULL: every simulation has the model’s value. Unlike mjb_expand, this
expands nothing, and fields that mjb_setConst derives stay derived. Treat the storage as read-only, since
mjb_setConst overwrites derived fields. size and elemsize are written as by mjb_expand, also when
the field is not expanded.
Run mj_setConst on each selected simulation’s model. Return the number of simulations in which MuJoCo raised an
error; those simulations keep their constants.
Every model field that mj_setConst changes becomes per-simulation, as with mjb_expand, so each simulation
gets its own derived constants; only the arrays marked mjSC_OUT in MJSETCONST_ARRAYS and the scalars in
MJSETCONST_SCALARS can change. If a call makes a new field per-simulation, mj_setConst runs again on the
call’s simulations. Simulations outside the call need no update, since the new field starts from the model’s value,
which is theirs.
Only the groups of mj_setConst computations (the columns of MJSETCONST_ARRAYS) that read a per-simulation
field, or what an earlier such group writes, run; the others would give every simulation the model’s values. With no
per-simulation field that mj_setConst reads, for example only friction or actuator gains, the call does nothing.
Per-simulation mjOption fields count as read by every group. Skipping groups assumes that the constants of the
model given to mjb_makeBatch are current, as after compilation or mj_setConst.
On each call, the fields that mj_setConst derives are recomputed from the model’s values. Expanding such a field
with mjb_expand makes its values inputs instead if mj_setConst reads it before writing it, as the anchors
of connect constraints are in eq_data; otherwise they are recomputed all the same. mjb_expanded reads them
without that effect.
Run each simulation i on models[i], a model of the caller’s, instead of the batch’s model. If models is
NULL, return to the batch’s model.
Each model must give mjData the same layout as the batch’s model, that is, the same sizes for everything mjData holds.
Models compiled from one spec with different parameters qualify, and so do models whose meshes have other shapes but the
same numbers of vertices and faces. The batch only reads the models, so one model can serve several simulations. After
editing a model, call mjb_setModels again; otherwise a persistent batch may continue a step from stages computed
before the edit.
Caller models replace per-simulation fields, and the two cannot be combined: raise an error if the batch has fields from
mjb_expand. While caller models are set:
Advance each selected simulation by nstep calls to mj_step, as rollout does, recording
after each substep. Return the number of simulations in which MuJoCo raised an error.
Before each substep, set the state components in control_spec (a subset of the mjtState bits in
mjSTATE_USER) from control. control is nxnstepxmj_stateSize(m,control_spec), for the n selected
simulations in call order; if it is NULL, the inputs are left as they are. After each substep, copy each of the
nrecordmjBatchRecords in record into its buffer. A simulation whose warning counters rise stops
stepping, and its remaining records repeat its last ones.
Run func (an mjfBatchFunc) on each selected simulation’s model and data, on the batch’s threads, passing it
the simulation’s index and arg. If save is nonzero, save the state back afterwards. Return the number of
simulations in which MuJoCo raised an error.
Fields registered with mjb_output are not refreshed; func returns its results through arg. func may
call other batches, as long as they do not call back into this one; a call on its own batch raises an error in the
simulation. An error raised by a MuJoCo function that func calls unwinds to the batch with longjmp, so func
must not hold C++ objects with destructors across MuJoCo calls.
In a persistent batch:
With save zero, func should not change the simulation’s state. The mjData keeps what lies outside the state,
such as the sleep bookkeeping, which would then no longer match the row.
The mjData that func receives may hold the stages that mjb_step computed at the new state. Its contacts
are then those of the new state, but its constraint forces are not yet computed, so do not read contact forces before
the acceleration stage runs.
For example, this computes the finite-differenced transition matrices of every simulation at its current state, into
arrays indexed by simulation. mjd_transitionFD restores the state it perturbs, so save is zero:
// arrays of TransitionFD, nx = 2*nv + nastructTransitionArgs{mjtNum*A;// nsim x nx x nxmjtNum*B;// nsim x nx x nu};// mjb_apply function: transition matrices of simulation simvoidTransitionFD(constmjModel*m,mjData*d,intsim,void*arg){structTransitionArgs*a=arg;intnx=2*m->nv+m->na;mjd_transitionFD(m,d,1e-6,/*flg_centered=*/0,a->A+sim*nx*nx,a->B+sim*nx*m->nu,NULL,NULL);}structTransitionArgsargs={A,B};mjb_apply(b,/*ids=*/NULL,0,TransitionFD,&args,/*save=*/0);
A function can also read one field of one simulation. The mjData it receives holds the simulation’s state, but in a
batch that is not persistent its derived fields belong to another simulation, so the function computes what it reads.
In a persistent batch, it can instead read the fields that the simulation’s last call left in its mjData:
// mjb_apply function: subtree centers of mass, into arg (3*nbody)voidSubtreeCom(constmjModel*m,mjData*d,intsim,void*arg){mj_kinematics(m,d);mj_comPos(m,d);mju_copy(arg,d->subtree_com,3*m->nbody);}intsim=7;mjb_apply(b,&sim,1,SubtreeCom,com,/*save=*/0);
Write simulation sim’s model into m, ready to render or to pass to any function. Normally, this is the batch’s
model with the simulation’s per-simulation fields and the constants mjb_setConst computed for it; m must then
have the batch’s sizes, such as a copy of mjb_model. With caller models from mjb_setModels, it is a copy
of the simulation’s model, and m must have that model’s sizes. Raise an error if sim is out of range or the
sizes differ.
Write simulation sim’s state and warning counters into d, including writes to its row since its last call;
d must have the batch’s sizes. In a persistent batch, first copy the simulation’s mjData, so that d also holds
its derived fields and sleep state. Otherwise, run mj_forward with the model from mjb_getModel to compute
them. Raise an error if sim is out of range or the sizes differ.
Return the batch’s copy of the model, made by mjb_makeBatch. Per-simulation fields and caller models never
change it; mjb_getModel gives a simulation’s own model.
The “functions” in this section are preprocessor macros replaced with the corresponding C standard library math
functions. When MuJoCo is compiled with single precision (which is not currently available to the public, but we
sometimes use it internally) these macros are replaced with the corresponding single-precision functions (not shown
here). So one can think of them as having inputs and outputs of type mjtNum, where mjtNum is defined as double or float
depending on how MuJoCo is compiled. We will not document these functions here; see the C standard library
specification.
Coordinate transform of 6D motion or force vector in rotation:translation format.
rotnew2old is 3-by-3, NULL means no rotation; flg_force specifies force or motion type.
Band-dense Cholesky decomposition.
Add diagadd+diagmul*mat_ii to diagonal before decomposition.
Returns the minimum value of the factorized diagonal or 0 if rank-deficient.
Symmetric band-dense matrices
mju_cholFactorBand and subsequent functions containing the substring “band” operate on matrices which are a
generalization of symmetric band matrices. Symmetric band-dense or
“arrowhead” matrices have non-zeros along proximal diagonal bands and dense blocks on the bottom rows and right
columns. These matrices have the property that Cholesky factorization creates no fill-in and can therefore be
performed efficiently in-place. Matrix structure is defined by three integers:
ntotal: the number of rows (columns) of the symmetric matrix.
nband: the number of bands under (over) the diagonal, inclusive of the diagonal.
ndense: the number of dense rows (columns) at the bottom (right).
The non-zeros are stored in memory as two contiguous row-major blocks, colored green and blue in the illustration
below. The first block has size nbandx(ntotal-ndense) and contains the diagonal and the bands below it. The
second block has size ndensexntotal and contains the dense part. Total required memory is the sum of the block
sizes.
For example, consider an arrowhead matrix with nband=3, ndense=2 and ntotal=8. In this example, the
total memory required is 3*(8-2)+2*8=34 mjtNum’s, laid out as follows:
Minimize \(\tfrac{1}{2} x^T H x + x^T g \quad \text{s.t.} \quad l \le x \le u\), return rank or -1 if failed.
inputs:
n - problem dimension
H - SPD matrix n*n
g - bias vector n
lower - lower bounds n
upper - upper bounds n
res - solution warmstart n
return value:
nfree<=n - rank of unconstrained subspace, -1 if failure
outputs (required):
res - solution n
R - subspace Cholesky factor nfree*nfree, allocated: n*(n+7)
outputs (optional):
index - set of free dimensions nfree, allocated: n
notes:
The initial value of res is used to warmstart the solver.
R must have allocated size n*(n+7), but only nfree*nfree values are used as output.
index (if given) must have allocated size n, but only nfree values are used as output.
The convenience function mju_boxQPmalloc allocates the required data structures.
Only the lower triangles of H and R are read from and written to, respectively.
Remove object corresponding to the given element; return 0 on success. Deleting a body or a frame also deletes
everything inside it, along with all the elements that reference a deleted element. A
plugin instance is deleted along with the last element that references it.
Create a flexcomp in body and return the resulting flex; the arguments correspond to the
flexcomp attributes. If file is the name of an existing mesh asset, the flexcomp uses that mesh as
with the mesh attribute, otherwise file is the name of a mesh file. The flexcomp is
expanded immediately, so later changes to the mesh asset do not affect the created flex.
Generate a built-in procedural mesh of type mjtMeshBuiltin with the given parameters. Returns 0 on success; on
failure, returns a nonzero value and sets the error of the spec. The parameters of the sphere, hemisphere, cone,
supersphere, supertorus, wedge and plate types are those of the corresponding mesh/builtin
attribute. The procedural types below generate the same shapes as the corresponding flexcomp
types; their nodes are stored in double precision in usernode.
mjMESH_BUILTIN_GRID (count[3], spacing[3], [dim]): A regular grid with count[i]>0 points along each axis,
separated by spacing[i]. dim (default 3) creates tetrahedra (3) or triangles (2);
count must be 1 along the axes beyond dim.
mjMESH_BUILTIN_BOX, mjMESH_BUILTIN_CYLINDER, mjMESH_BUILTIN_ELLIPSOID (count[3], spacing[3], [dim]): The
surface of a box grid with count[i]>=2 points along each axis, projected onto the shape. dim (default 3)
creates tetrahedra connecting the surface to the center (3) or surface triangles (2).
mjMESH_BUILTIN_SQUARE, mjMESH_BUILTIN_DISC (count[3], spacing[3]): A triangulated square, or a disc obtained by
radial projection of the square; count[2] must be 1.
Types without volume (square, disc, and
grid, box, cylinder and ellipsoid with dim < 3) change a legacyinertia to
shell.
Fuse the static bodies of the spec with their parents. A body without joints is replaced by a frame in
its parent, which has the pose of the body and holds its geoms, sites, cameras, lights, frames and child bodies, in the
same coordinates as before. The inertia of the body is added to that of the parent. The compiled model has the same
kinematics and dynamics, with fewer bodies. Bodies which cannot be fused without changing the model are kept, see
fusestatic, which applies this function before compiling. Pointers to the bodies which were
fused are no longer valid. Assets are read as in mj_compile. Returns the number of bodies fused, 0 if the spec
is unchanged, or -1 on error, in which case nothing is fused.
Discard the elements of the spec which are only visual: materials and textures, the geoms which do not collide, and
the meshes which are then not used; an element which another refers to by name is kept. If a discarded geom was used for
inferring the inertia of its body, that inertia becomes the explicit inertial of the body, as in
mjs_adoptInertial, so the compiled model has the same dynamics. See
discardvisual, which applies this function before compiling. Pointers to the elements
which were discarded are no longer valid. Assets are read as in mj_compile, and only if inertia is inferred from
a discarded geom. Returns the number of elements discarded, 0 if the spec is unchanged, or -1 on error, in which case
nothing is discarded.
Merge the textures and meshes of the spec which would compile to the same asset: textures with the same resolved file
or buffer and the same parameters, meshes with the same resolved file or arrays and the same parameters, names
excluded. The first asset of each group keeps its name, every reference to the others (materials, lights, geoms, sites,
default classes, sensors, tuples) is rewritten to it, and the others are deleted as by mjs_delete, so pointers
to them are no longer valid. An unnamed asset is left alone, as is a mesh with a plugin. Nothing is read from disk: a
model which attaches the same sub-model several times is merged without its asset files. Returns the number of assets
merged, 0 if the spec is unchanged, or -1 on error, in which case nothing is merged.
Make the inertial which compilation infers for a body part of the spec. The mass, inertia and inertial frame which the
compiler calculates from the geoms of the body, as the spec is now, are written as the explicit inertial of the body,
so that later changes to its geoms no longer affect them. Compiling before and after gives the same model: the values
are those before the scaling of settotalmass. Nothing is done if the inertial of the body
is not inferred. It is an error when inertiafromgeom is “true”, which infers the
inertia of every body whatever its inertial. Assets are read as in mj_compile. Returns 0 on success.
To read an inferred inertial without adopting it, compile and look it up in mjModel with mjs_getId.
Set user payload, overriding the existing value for the specified key if
present. This version differs from mjs_setUserValue in that it takes a
cleanup function that will be called when the user payload is deleted.
