<commit_before>========
Modeling
========

Introduction
------------

MuJoCo can load XML model files in its native **MJCF** format, as well as in the popular but more limited **URDF**
format. This chapter is the MJCF modeling guide. The reference manual is available in the :doc:`XMLreference`
chapter. The URDF documentation can be found elsewhere; here we only describe
MuJoCo-specific :ref:`URDF extensions <CURDF>`.

MJCF models can represent complex dynamical systems with a wide range of features and model elements. Accessing all
these features requires a rich modeling format, which can become cumbersome if it is not designed with usability in
mind. Therefore we have made an effort to design MJCF as a scalable format, allowing users to start small and build
more detailed models later. Particularly helpful in this regard is the extensive :ref:`default setting <CDefault>`
mechanism inspired by the idea of Cascading Style Sheets (CSS) in HTML. It enables users to rapidly create new models
and experiment with them. Experimentation is further aided by numerous :ref:`options <option>` which
can be used to reconfigure the simulation pipeline, and by quick re-loading that makes model editing an interactive
process.

One can think of MJCF as a hybrid between a modeling format and a programming language. There is a built-in compiler,
which is a concept normally associated with programming languages. While MJCF does not have the power of a
general-purpose programming language, a number of sophisticated compile-time computations are invoked automatically
depending on how the model is designed.

.. _Load:

Loading models
~~~~~~~~~~~~~~

As explained in :ref:`Model instances <Instance>` in the Overview chapter, MuJoCo models can be loaded from plain-text
XML files in the MJCF or URDF formats, and then compiled into a low-level mjModel. Alternatively a previously saved
mjModel can be loaded directly from a binary MJB file - whose format is not documented but is essentially a copy of the
mjModel memory buffer. MJCF and URDF files are loaded with :ref:`mj_loadXML` while MJB files are loaded with
:ref:`mj_loadModel`.

When an XML file is loaded, it is first parsed into a document object model (DOM) using the TinyXML parser internally.
This DOM is then processed and converted into a high-level mjCModel object. The conversion depends on the model format
- which is inferred from the top-level element in the XML file, and not from the file extension. Recall that a valid
XML file has a unique top-level element. This element must be :el:`mujoco` for MJCF, and :el:`robot` for URDF.

.. _Compile:

Compiling models
~~~~~~~~~~~~~~~~

Once a high-level mjCModel is created - by loading an MJCF file or a URDF file, or programmatically when such
functionality becomes available - it is compiled into mjModel. Even though loading and compilation are presently
combined in one step, compilation is independent of loading, meaning that the compiler works in the same way
regardless of how mjCModel was created. Both the parser and the compiler perform extensive error checking, and abort
when the first error is encountered. The resulting error messages contain the row and column number in the XML file,
and are self-explanatory so we do not document them here. The parser uses a custom schema to make sure that the file
structure, elements and attributes are valid. The compiler then applies many additional semantic checks. Finally, one
simulation step of the compiled model is performed and any runtime errors are intercepted. The latter is done by
(temporarily) setting :ref:`mju_user_error` to point to a function that throws C++
exceptions; the user can implement similar error-interception functionality at runtime if desired.

The entire process of parsing and compilation is very fast - less than a second if the model does not contain large
meshes or actuator lengthranges that need to be computed via simulation. This makes it possible to design models
interactively, by re-loading often and visualizing the changes. Note that the `simulate.cc`_ code sample has a
keyboard shortcut for re-loading the current model (Ctrl+L).

.. _Save:

Saving models
~~~~~~~~~~~~~

An MJCF model can consist of multiple (included) XML files as well as meshes, height fields and textures referenced
from the XML. After compilation, the contents of all these files are assembled into mjModel, which can be saved into a
binary MJB file with :ref:`mj_saveModel`. The MJB is a stand-alone file and does not
refer to any other files. It also loads faster. So we recommend saving commonly used models as MJB and loading them
when needed for simulation.

It is also possible to save a compiled mjCModel as MJCF with :ref:`mj_saveLastXML`. If any real-valued fields in the
corresponding mjModel were modified after compilation (which is unusual but can happen in system identification
applications for example), the modifications are automatically copied back into mjCModel before saving. Note that
structural changes cannot be made in the compiled model. The XML writer attempts to generate the smallest MJCF file
which is guaranteed to compile into the same model, modulo negligible numeric differences caused by the plain text
representation of real values. The resulting file may not have the same structure as the original because MJCF has many
user convenience features, allowing the same model to be specified in different ways. The XML writer uses a "canonical"
subset of MJCF where all coordinates are local and all body positions, orientations and inertial properties are
explicitly specified. In the Computation chapter we showed an `example <_static/example.xml>`__ MJCF file and the
corresponding `saved example <_static/example_saved.xml>`__.

.. _Mechanisms:

MJCF Mechanisms
---------------

MJCF uses several mechanisms for model creation which span multiple model elements. To avoid repetition we describe them
in detail only once in this section. These mechanisms do not correspond to new simulation concepts beyond those
introduced in the Computation chapter. Their role is to simplify the creation of MJCF models, and to enable the use of
different data formats without need for manual conversion to a canonical format.

.. _CTree:

Kinematic tree
~~~~~~~~~~~~~~

The main part of the MJCF file is an XML tree created by nested :ref:`body <body>` elements. The top-level body is
special and is called :el:`worldbody`. This tree organization is in contrast with URDF where one creates a collection of
links and then connects them with joints that specify a child and a parent link. In MJCF the child body is literally a
child of the parent body, in the sense of XML.

When a :ref:`joint <joint>` is defined inside a body, its function is not to connect the parent and child but rather to
create motion degrees of freedom between them. If no joints are defined within a given body, that body is welded to its
parent. A body in MJCF can contain multiple joints, thus there is no need to introduce dummy bodies for creating
composite joints. Instead simply define all the primitive joints that form the desired composite joint within the same
body. For example, two sliders and one hinge can be used to model a body moving in a plane.

Other MJCF elements can be defined within the tree created by nested body elements, in particular :ref:`joint <joint>`,
:ref:`geom <geom>`, :ref:`site <site>`, :ref:`camera <camera>`, :ref:`light <light>`. When an element is defined within
a body, it is fixed to the local frame of that body and always moves with it. Elements that refer to multiple bodies, or
do not refer to bodies at all, are defined in separate sections outside the kinematic tree.

.. _CDefault:

Default settings
~~~~~~~~~~~~~~~~

MJCF has an elaborate mechanism for setting default attribute values. This allows us to have a large number of elements
and attributes needed to expose the rich functionality of the software, and at the same time write short and readable
model files. This mechanism further enables the user to introduce a change in one place and have it propagate throughout
the model. We start with an example.

.. code-block:: xml

   <mujoco>
       <default class="main">
           <geom rgba="1 0 0 1"/>
           <default class="sub">
               <geom rgba="0 1 0 1"/>
           </default>
       </default>

       <worldbody>
           <geom type="box"/>
           <body childclass="sub">
               <geom type="ellipsoid"/>
               <geom type="sphere" rgba="0 0 1 1"/>
               <geom type="cylinder" class="main"/>
           </body>
       </worldbody>
   </mujoco>

This example will not actually compile because some required information is missing, but here we are only interested
in the setting of geom rgba values. The four geoms created above will end up with the following rgba values as a
result of the default setting mechanism:

========= =========
geom type geom rgba
========= =========
box       1 0 0 1
ellipsoid 0 1 0 1
sphere    0 0 1 1
cylinder  1 0 0 1
========= =========


The box uses the top-level defaults class "main" to set the values of its undefined attributes, because no other class
was specified. The body specifies childclass "sub", causing all children of this body (and all their children etc.) to
use class "sub" unless specified otherwise. So the ellipsoid uses class "sub". The sphere has explicitly defined rgba
which overrides the default settings. The cylinder specifies defaults class "main", and so it uses "main" instead of
"sub", even though the latter was specified in the childclass attribute of the body containing the geom.

Now we describe the general rules. MuJoCo supports unlimited number of defaults classes, created by possibly nested
:ref:`default <default>` elements in the XML. Each class has a unique name - which is a required
attribute except for the top-level class whose name is "main" if left undefined. Each class also has a complete
collection of dummy model elements, with their attributes set as follows. When a defaults class is defined within
another defaults class, the child automatically inherits all attribute values from the parent. It can then override
some or all of them by defining the corresponding attributes. The top-level defaults class does not have a parent, and
so its attributes are initialized to internal defaults which are shown in the reference documentation below.

The dummy elements contained in the defaults classes are not part of the model; they are only used to initialize the
attribute values of the actual model elements. When an actual element if first created, all its attributes are copied
from the corresponding dummy element in the defaults class that is currently active. There is always an active
defaults class, which can be determined in one of three ways. If no class is specified in the present element or any
of its ancestor bodies, the top-level class is used (regardless of whether it is called "main" or something else). If
no class is specified in the present element but one or more of its ancestor bodies specify a childclass, then the
childclass from the nearest ancestor body is used. If the present element specifies a class, that class is used
regardless of any childclass attributes in its ancestor bodies.

Some attributes, such as body position in models defined in global coordinates, can be in a special undefined state.
This instructs the compiler to infer the corresponding value from other information, in this case the positions of the
geoms attached to the body. The undefined state cannot be entered in the XML file. Therefore once an attribute is
defined in a given class, it cannot be undefined in that class or in any of its child classes. So if the goal is to
leave a certain attribute undefined in a given model element, it must be undefined in the active defaults class.

A final twist here is actuators. They are different because some of the actuator-related elements are actually
shortcuts, and shortcuts interact with the defaults setting mechanism in a non-obvious way. This is explained in the
:ref:`Actuator shortcuts <CActuator>` section below.

.. _CFrame:

Coordinate frames
~~~~~~~~~~~~~~~~~

After compilation the positions and orientations of all elements defined in the kinematic tree are expressed in local
coordinates, relative to the parent body for bodies, and relative to the body that owns the element for geoms, joints,
sites, cameras and lights. Consequently, when a compiled model is saved as MJCF, the coordinates are always local.
However when the user writes an MJCF file, the coordinates can be either local or global, as specified by the
:at:`coordinate` attribute of :ref:`compiler <compiler>`. This setting applies to all position and
orientation data in the MJCF file. A related attribute is :at:`angle`. It specifies whether all angles in the MJCF
file are expressed in degrees or radians (after compilation angles are always expressed in radians). Awareness of
these global settings is essential when constructing new models.

Global coordinates can sometimes be more intuitive and have the added benefit that body positions and orientations can
be omitted. In that case the body frame is set to the body inertial frame, which can itself be omitted and inferred
from the geom masses and inertias. When an MJCF model is defined in local coordinates on the other hand, the user must
specify the positions and orientations of the body frames explicitly. This is because if they were omitted, and the
elements inside the body were specified in local coordinates relative to the body frame, there would be no way to
infer the body frame.

Here is an example of an MJCF fragment in global coordinates:

.. code-block:: xml

   <body>
      <geom type="box" pos="1 0 0" size="0.5 0.5 0.5"/>
   </body>

When this model is compiled and saved as MJCF (in local coordinates) the same fragment becomes:

.. code-block:: xml

   <body pos="1 0 0">
      <inertial pos="0 0 0" mass="1000" diaginertia="166.667 166.667 166.667"/>
      <geom type="box" pos="0 0 0" size="0.5 0.5 0.5"/>
   </body>

The body position was set to the geom position (1 0 0), while the geom and inertial positions were set to (0 0 0)
relative to the body.

In principle the user always has a choice between local and global coordinates, but in practice this choice is viable
only when using geometric primitives rather than meshes. For meshes, the 3D vertex positions are expressed in either
local or global coordinates depending on how the mesh was designed - effectively forcing the user to adopt the same
convention for the entire model. The alternative would be to pre-process the mesh data outside MuJoCo so as to change
coordinates, but that effort is rarely justified.

.. _COrientation:

Frame orientations
~~~~~~~~~~~~~~~~~~

Several model elements have right-handed spatial frames associated with them. These are all the elements defined in the
kinematic tree except for joints. A spatial frame is defined by its position and orientation. Specifying 3D positions is
straightforward, but specifying 3D orientations can be challenging. This is why MJCF provides several alternative
mechanisms. No matter which mechanism the user chooses, the frame orientation is always represented as a unit quaternion
after compilation. Recall that a 3D rotation by angle :math:`a` around axis given by the unit vector :math:`(x, y, z)`
corresponds to the quaternion :math:`(\cos(a/2), \: \sin(a/2) \cdot (x, y, z))`. Also recall that every 3D orientation
can be uniquely specified by a single 3D rotation by some angle around some axis.

All MJCF elements that have spatial frames allow the five attributes listed below. The frame orientation is specified
using at most one of these attributes. The :at:`quat` attribute has a default value corresponding to the null
rotation, while the others are initialized in the special undefined state. Thus if none of these attributes are
specified by the user, the frame is not rotated.

:at:`quat`: :at-val:`real(4), "1 0 0 0"`
   If the quaternion is known, this is the preferred was to specify the frame orientation because it does not involve
   conversions. Instead it is normalized to unit length and copied into mjModel during compilation. When a model is
   saved as MJCF, all frame orientations are expressed as quaternions using this attribute.
:at:`axisangle`: :at-val:`real(4), optional`
   These are the quantities :math:`(x, y, z, a)` mentioned above. The last number is the angle of rotation, in degrees
   or radians as specified by the :at:`angle` attribute of :ref:`compiler <compiler>`. The first three numbers determine
   a 3D vector which is the rotation axis. This vector is normalized to unit length during compilation, so the user can
   specify a vector of any non-zero length. Keep in mind that the rotation is right-handed; if the direction of the
   vector :math:`(x, y, z)` is reversed this will result in the opposite rotation. Changing the sign of :math:`a` can
   also be used to specify the opposite rotation.
:at:`euler`: :at-val:`real(3), optional`
   Rotation angles around three coordinate axes. The sequence of axes around which these rotations are applied is
   determined by the :at:`eulerseq` attribute of :ref:`compiler <compiler>` and is the same for the
   entire model.
:at:`xyaxes`: :at-val:`real(6), optional`
   The first 3 numbers are the X axis of the frame. The next 3 numbers are the Y axis of the frame, which is
   automatically made orthogonal to the X axis. The Z axis is then defined as the cross-product of the X and Y axes.
:at:`zaxis`: :at-val:`real(3), optional`
   The Z axis of the frame. The compiler finds the minimal rotation that maps the vector :math:`(0, 0, 1)` into the
   vector specified here. This determines the X and Y axes of the frame implicitly. This is useful for geoms with
   rotational symmetry around the Z axis, as well as lights - which are oriented along the Z axis of their frame.

.. _CSolver:

Solver parameters
~~~~~~~~~~~~~~~~~

The solver :ref:`Parameters <soParameters>` section of the Computation chapter explained the mathematical and
algorithmic meaning of the quantities :math:`d, b, k` which determine the behavior of the constraints in MuJoCo. Here we
explain how to set them. Setting is done indirectly, through the attributes :at:`solref` and :at:`solimp` which are
available in all MJCF elements involving constraints. These parameters can be adjusted per constraint, or per defaults
class, or left undefined - in which case MuJoCo uses the internal defaults shown below. Note also the override mechanism
available in :ref:`option <option>`; it can be used to change all contact-related solver parameters at runtime, so as to
experiment interactively with parameter settings or implement continuation methods for numerical optimization.

Here we focus on a single scalar constraint. Using slightly different notation from the Computation chapter, let
:math:`a_1` denote the acceleration, :math:`v` the velocity, :math:`r` the position or residual (defined as 0 in
friction dimensions), :math:`k` and :math:`b` the stiffness and damping of the virtual spring used to define the
reference acceleration :math:`a_{\rm ref} = -b v - k r`. Let :math:`d` be the constraint impedance, and :math:`a_0` the
acceleration in the absence of constraint force. Our earlier analysis revealed that the dynamics in constraint space are
approximately

.. math::
   a_1 + d \cdot (b v + k r) = (1 - d)\cdot a_0

Again, the parameters that are under the user's control are :math:`d, b, k`. The remaining quantities are functions of the
system state and are computed automatically at each time step.

First we explain the setting of the impedance :math:`d`. Recall that :math:`d` must lie between 0 and 1; internally
MuJoCo clamps it to the range [:ref:`mjMINIMP mjMAXIMP <glNumeric>`] which is currently set to [0.0001 0.9999]. It
causes the solver to interpolate between the unforced acceleration :math:`a_0` and reference acceleration
:math:`a_{\rm ref}`. Small values of :math:`d` correspond to soft/weak constraints while large values of :math:`d`
correspond to strong/hard constraints. The user can set :math:`d` to a constant, or take advantage of its interpolating
property and make it position-dependent, i.e., a function of :math:`r`. Position-dependent impedance can be used to
model soft contact layers around objects, or define equality constraints that become stronger with larger violation (so
as to approximate backlash for example). The shape of the function :math:`d(r)` is determined by the element-specific
parameter vector :at:`solimp`.

**solimp :** real(5), "0.9 0.95 0.001 0.5 2"

   The five numbers are (dmin, dmax, width, midpoint, power). They parameterize the function :math:`d(r)`. Prior to
   MuJoCo 2.0 this attribute had three parameters, plus a global option specifying the shape of the function. In MuJoCo
   2.0 we expanded the family of impedance functions while keeping it backward-compatible as follows. The user is
   allowed to set only the first three parameters, whose defaults are the same as in prior releases. The defaults for
   the last two parameters then generate the same function which was the default in prior releases (a sigmoid). The new
   parameterization further allows the sigmoid to become shifted and skewed, as shown in the plots below for different
   values of the additional parameters. The plots actually show two reflected sigmoids, because the impedance function
   :math:`d(r)` depends on the absolute value of :math:`r`. This flexibility was added to allow better control of remote
   contact forces, and can also be used for other constraints. The power (of the polynomial spline used to generate the
   function) must be 1 or greater. The midpoint (specifying the inflection point) must be between 0 and 1, and is
   expressed in units of width. Note that when the power is 1, the function is linear regardless of the midpoint.
   |image0|

   These plots show the impedance :math:`d(r)` on the vertical axis, as a function of the constraint violation :math:`r`
   on the horizontal axis. The quantity :math:`r` is computed as follows. For equality constraints, :math:`r` equals the
   constraint violation which can be either positive or negative. For friction loss or friction dimensions of elliptic
   cones, :math:`r` is always 0. For limits, normal directions of elliptic cones and all directions of pyramidal cones,
   :math:`r` is the (limit or contact) distance minus the margin at which the constraint becomes active; for contacts
   this margin is actually margin-gap. Therefore limit and contact constraints are active when the corresponding
   :math:`r` is negative.

Next we explain the setting of the stiffness :math:`k` and damping :math:`b`. The idea here is to re-parameterize the
model in terms of the time constant and damping ratio of the above mass-spring-damper system. By "time constant" we mean
the inverse of the natural frequency times the damping ratio. Constraints whose residual is identically 0 have first-
order dynamics and the mass-spring-damper analysis does not apply. In that case the time constant is the rate of
exponential decay of the constraint velocity, and the damping ratio is ignored. In addition to this format, MuJoCo 2.0
allows a second format where stiffness and damping are specified more directly.

**solref :** real(2), "0.02 1"
   There are two formats for this attribute, determined by the sign of the numbers. If both numbers are positive the
   specification is considered to be in the :math:`(\text{timeconst}, \text{dampratio})` format which has been available
   in MuJoCo all along. Otherwise the specification is considered to be in the new :math:`(-\text{stiffness}, -
   \text{damping})`, format introduced in MuJoCo 2.0. We first describe the original format where the two numbers are
   :math:`(\text{timeconst}, \text{dampratio})`. In this case we use a mass-spring-damper model to compute :math:`k, b`
   after suitable scaling. Note that the effective stiffness :math:`d(r) \cdot k` and damping :math:`d(r) \cdot b` are
   scaled by the impedance :math:`d(r)` which is a function of the distance :math:`r`. Thus we cannot always achieve the
   specified mass-spring-damper properties, unless we completely undo the scaling by :math:`d`. But the latter is
   undesirable because it would ruin the interpolating property, in particular the limit :math:`d=0` would no longer
   disable the constraint. Instead we scale the stiffness and damping so that the damping ratio remains constant, while
   the time constant increases when :math:`d(r)` gets smaller. The scaling formulas are

   .. math::
      \begin{aligned}
      b &= 2 / (d_\text{max}\cdot \text{timeconst}) \\
      k &= d(r) / (d_\text{max}^2 \cdot \text{timeconst}^2 \cdot \text{dampratio}^2) \\
      \end{aligned}

   The timeconst parameter should be at least two times larger than the simulation time step, otherwise the system can
   become too stiff relative to the numerical integrator (especially when Euler integration is used) and the simulation
   can go unstable. This is enforced internally, unless the :at:`refsafe` attribute of :ref:`flag <option-flag>` is set
   to false. The :math:`\text{dampratio}` parameter would normally be set to 1, corresponding to critical damping.
   Smaller values result in under-damped or bouncy constraints, while larger values result in over-damped constraints.
   Next we describe the new format where the two numbers are :math:`(-\text{stiffness}, -\text{damping})`. This allows
   more direct control over restitution in particular. We still apply some scaling so that the same numbers can be used
   with different impedances, but the scaling no longer depends on :math:`r` and the two numbers no longer interact. The
   scaling formulas are

   .. math::
      \begin{aligned}
      b &= \text{damping} / d_\text{max} \\
      k &= \text{stiffness} / d_\text{max}^2 \\
      \end{aligned}

.. _CContact:

Contact parameters
~~~~~~~~~~~~~~~~~~

The parameters of each contact were described in the :ref:`Contact <coContact>` section of the Computation
chapter. Here we explain how these parameters are set. If the geom pair is explicitly defined with the XML element
:ref:`pair <pair>`, it has attributes specifying all contact parameters directly. In that case the
parameters of the individual geoms are ignored. If on the other hand the contact is generated by the dynamic mechanism,
its parameters need to be inferred from the two geoms in the contact pair. If the two geoms have identical parameters
there is nothing to do, but what if their parameters are different? In that case we use the geom attributes
:at:`solmix` and :at:`priority` to decide how to combine them. The combination rules for each contact parameter
are as follows:

condim
   If one of the two geoms has higher priority, its condim is used. If both geoms have the same priority, the maximum of
   the two condims is used. In this way a frictionless geom and a frictional geom form a frictional contact, unless the
   frictionless geom has higher priority. The latter is desirable in particle systems for example, where we may not want
   the particles to stick to any objects.
friction
   Recall that contacts can have up to 5 friction coefficients: two tangential, one torsional, two rolling. Each contact
   in mjData.contact actually has all 5 of them, even if condim is less than 6 and not all coefficients are used. In
   contrast, geoms have only 3 friction coefficients: tangential (same for both axes), torsional, rolling (same for both
   axes). Each of these 3D vectors of friction coefficients is expanded into a 5D vector of friction coefficients by
   replicating the tangetial and rolling components. The contact friction coefficients are then computed according to
   the following rule: if one of the two geoms has higher priority, its friction coefficients are used. Otherwise the
   element-wise maximum of each friction coefficient over the two geoms is used. The rationale is similar to taking the
   maximum over condim: we want the more frictional geom to win.
   The reason for having 5 coefficients per contact and only 3 per geom is as follows. For a contact pair, we want to
   allow the most flexible model our solver can handle. As mentioned earlier, anisotropic friction can be exploited to
   model effects such as skating. This however requires knowing how the two axes of the contact tangent plane are
   oriented. For a predefined contact pair we know the two geom types in advance, and the corresponding collision
   function always generates contact frames oriented in the same way - which we do not describe here but it can be seen
   in the visualizer. For individual geoms however, we do not know which other geoms they might collide with and what
   their geom types might be, so there is no way to know how the contact tangent plane will be oriented when specifying
   an individual geom. This is why MuJoCo does not allow anisotropic friction in the individual geom specifications, but
   only in the explicit contact pair specifications.
margin, gap
   The maximum of the two geom margins (or gaps respectively) is used. The geom priority is ignored here, because the
   margin and gap are distance properties and a one-sided specification makes little sense.
solref, solimp
   If one of the two geoms has higher priority, its solref and solimp parameters are used. If both geoms have the same
   priority, the weighted average is used. The weights are proportional to the solmix attributes, i.e., weight1 =
   solmix1 / (solmix1 + solmix2) and similarly for weight2. There is one important exception to this weighted averaging
   rule. If solref for either geom is non-positive, i.e., it relies on the new direct format introduced in MuJoCo 2.0,
   then the element-wise minimum is used regardless of solmix. This is because averaging solref parameters in different
   formats would be meaningless.

.. _COverride:

Contact override
~~~~~~~~~~~~~~~~

MuJoCo uses an elaborate as well as novel :ref:`Constraint model <Constraint>` described in the
Computation chapter. Gaining an intuition for how this model works requires some experimentation. In order to
facilitate this process, we provide a mechanism to override some of the solver parameters, without making changes to
the actual model. Once the override is disabled, the simulation reverts to the parameters specified in the model. This
mechanism can also be used to implement continuation methods in the context of numerical optimization (such as optimal
control or state estimation). This is done by allowing contacts to act from a distance in the early phases of
optimization - so as to help the optimizer find a gradient and get close to a good solution - and reducing this effect
later to make the final solution physically realistic.

The relevant settings here are the :at:`override` attribute of :ref:`flag <option-flag>` which
enables and disables this mechanism, and the :at:`o_margin`, :at:`o_solref`, :at:`o_solimp` attributes of
:ref:`option <option>` which specify the new solver parameters. Note that the override applies only to
contacts, and not to other types of constraints. In principle there are many real-valued parameters in a MuJoCo model
that could benefit from a similar override mechanism. However we had to draw a line somewhere, and contacts are the
natural choice because they give rise to the richest yet most difficult-to-tune behavior. Furthermore, contact
dynamics often present a challenge in terms of numerical optimization, and experience has shown that continuation over
contact parameters can help avoid local minima.

.. _CUser:

User parameters
~~~~~~~~~~~~~~~

A number of MJCF elements have the optional attribute :at:`user`, which defines a custom element-specific parameter
array. This interacts with the corresponding "nuser_XXX" attribute of the :ref:`size <size>` element. If for example we
set :at:`nuser_geom` to 5, then every geom in mjModel will have a custom array of 5 real-valued parameters. These geom-
specific parameters are either defined in the MJCF file via the :at:`user` attribute of :ref:`geom <geom>`, or set to 0
by the compiler if this attribute is omitted. The default value of all "nuser_XXX" attributes is -1, which instructs the
compiler to automatically set this value to the length of the maximum associated :at:`user` attribute defined in the
model. MuJoCo does not use these parameters in any internal computations; instead they are available for custom
computations. The parser allows arrays of arbitrary length in the XML, and the compiler later resizes them to length
nuser_XXX.

Some element-specific parameters that are normally used in internal computations can also be used in custom
computations. This is done by installing user callbacks which override parts of the simulation pipeline. For example,
the :ref:`general <general>` actuator element has attributes :at:`dyntype` and :at:`dynprm`. If
:at:`dyntype` is set to "user", then MuJoCo will call :ref:`mjcb_act_dyn` to compute
the actuator dynamics instead of calling its internal function. The user function pointed to by
:ref:`mjcb_act_dyn` can interpret the parameters defined in :at:`dynprm` however it
wishes. However the length of this parameter array cannot be changed (unlike the custom arrays described earlier whose
length is defined in the MJCF file). The same applies to other callbacks.

In addition to the element-specific user parameters described above, one can include global data in the model via
:ref:`custom <custom>` elements. For data that change in the course of the simulation, there is also
the array mjData.userdata whose size is determined by the :at:`nuserdata` attribute of the
:ref:`size <size>` element.

.. _CAlgorithms:

Algorithms and related settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The computation of constraint forces and constrained accelerations involves solving an optimization problem
numerically. MuJoCo has three algorithms for solving this optimization problem: CG, Newton, PGS. Each of them can be
applied to a pyramidal or elliptic model of the friction cones, and with dense or sparse constraint Jacobians. In
addition, the user can specify the maximum number of iterations, and tolerance level which controls early termination.
There is also a second Noslip solver, which is a post-processing step enabled by specifying a positive number of
noslip iterations. All these algorithm settings can be specified in the :ref:`option <option>` element.

The default settings work well for most models, but in some cases it is necessary to tune the algorithm. The best way
to do this is to experiment with the relevant settings and use the visual profiler in `simulate.cc`_, which shows the timing of different computations as
well as solver statistics per iteration. We can offer the following general guidelines and observations:

-  The constraint Jacobian should be dense for small models and sparse for large models. The default setting is 'auto';
   it resolves to dense when the number of degrees of freedom is up to 60, and sparse over 60. Note however that the
   threshold is better defined in terms of number of active constraints, which is model and behavior dependent.
-  The choice between pyramidal and elliptic friction cones is a modeling choice rather than an algorithmic choice,
   i.e., it leads to a different optimization problem solved with the same algorithms. Elliptic cones correspond more
   closely to physical reality. However pyramidal cones can improve the performance of the algorithms - but not
   necessarily. While the default is pyramidal, we recommend trying the elliptic cones. When contact slip is a problem,
   the best way to suppress it is to use elliptic cones, large impratio, and the Newton algorithm with very small
   tolerance. If that is not sufficient, enable the Noslip solver.
-  The Newton algorithm is the best choice for most models. It has quadratic convergence near the global minimum and
   gets there in surprisingly few iterations - usually around 5, and rarely more than 20. It should be used with
   aggressive tolerance values, say 1e-10, because it is capable of achieving high accuracy without added delay (due to
   quadratic convergence at the end). The only situation where we have seen it slow down are large models with elliptic
   cones and many slipping contacts. In that regime the Hessian factorization needs a lot of updates. It may also slow
   down in some large models with unfortunate ordering of model elements that results in high fill-in (computing the
   optimal elimination order is NP-hard, so we are relying on a heuristic). Note that the number of non-zeros in the
   factorized Hessian can be monitored in the profiler.
-  The CG algorithm works well in the situation described above where Newton slows down. In general CG shows linear
   convergence with a good rate, but it cannot compete with Newton in terms of number of iterations, especially when
   high accuracy is desired. However its iterations are much faster, and are not affected by fill-in or increased
   complexity due to elliptic cones. If Newton proves to be too slow, try CG next.
-  The PGS solver used to be the default solver until recently, and was substantially improved in MuJoCo 1.50 by making
   it work with sparse models. However we have not yet found a situation where it is the best algorithm, which is not to
   say that such situations do not exist. PGS solves a constrained optimization problem and has sub-linear convergence
   in our experience, however it usually makes rapid progress on the first few iterations. So it is a good choice when
   inaccurate solutions can be tolerated. For systems with large mass ratios or other model properties causing poor
   conditioning, PGS convergence tends to be rather slow. Keep in mind that PGS performs sequential updates, and
   therefore breaks symmetry in systems where the physics should be symmetric. In contrast, CG and Newton perform
   parallel updates and preserve symmetry.
-  The Noslip solver is a modified PGS solver. It is executed as a post-processing step after the main solver (which can
   be Newton, CG or PGS). The main solver updates all unknowns. In contrast, the Noslip solver updates only the
   constraint forces in friction dimensions, and ignores constraint regularization. This has the effect of suppressing
   the drift or slip caused by the soft-constraint model. However, this cascade of optimization steps is no longer
   solving a well-defined optimization problem (or any other problem); instead it is just an adhoc mechanism. While it
   usually does its job, we have seen some instabilities in models with more complex interactions among multiple
   contacts.
-  PGS has a setup cost (in terms of CPU time) for computing the inverse inertia in constraint space. Similarly, Newton
   has a setup cost for the initial factorization of the Hessian, and incurs additional factorization costs depending on
   how many factorization updates are needed later. CG does not have any setup cost. Since the Noslip solver is also a
   PGS solver, the PGS setup cost will be paid whenever Noslip is enabled, even if the main solver is CG or Newton. The
   setup operation for the main PGS and Noslip PGS is the same, thus the setup cost is paid only once when both are
   enabled.

.. _CActuator:

Actuator shortcuts
~~~~~~~~~~~~~~~~~~

As explained in the :ref:`Actuation model <geActuation>` section of the Computation chapter, MuJoCo offers a flexible
actuator model with transmission, activation dynamics and force generation components that can be specified
independently. The full functionality can be accessed via the XML element :ref:`general <general>` which allows the user
to create a variety of custom actuators. In addition, MJCF provides shortcuts for configuring common actuators. This is
done via the XML elements :ref:`motor <motor>`, :ref:`position <position>`, :ref:`velocity <velocity>`,
:ref:`intvelocity <intvelocity>`, :ref:`cylinder<cylinder>`, and :ref:`muscle <muscle>`. These are *not* separate model
elements. Internally MuJoCo supports only one actuator type - which is why when an MJCF model is saved all actuators are
written as :el:`general`. Shortcuts create general actuators implicitly, set their attributes to suitable values, and
expose a subset of attributes with possibly different names. For example, :el:`position` creates a position servo with
attribute :at:`kp` which is the servo gain. However :el:`general` does not have an attribute :at:`kp`. Instead the parser
adjusts the gain and bias parameters of the general actuator in a coordinated way so as to mimic a position servo. The
same effect could have been achieved by using :el:`general` directly, and setting its attributes to certain values as
described below.

Actuator shortcuts also interact with defaults. Recall that the :ref:`default setting <CDefault>` mechanism involves
classes, each of which has a complete collection of dummy elements (one of each element type) used to initialize the
attributes of the actual model elements. In particular, each defaults class has only one general actuator element.
What happens if we specify :el:`position` and later :el:`velocity` in the same defaults class? The XML elements are
processed in order, and the attributes of the single general actuator are set every time an actuator-related element
is encountered. Thus :el:`velocity` has precedence. If however we specify :el:`general` in the defaults class, it will
only set the attributes that are given explicitly, and leave the rest unchanged. A similar complication arises when
creating actual model elements. Suppose the active defaults class specified :el:`position`, and now we create an
actuator using :el:`general` and omit some of its attributes. The missing attributes will be set to whatever values
are used to model a position servo, even though this actuator may not be intended as a position servo.

In light of these potential complications, we recommend a simple approach: use the same actuator shortcut in both the
defaults class and in the creation of actual model elements. If a given model requires different actuators, either
create multiple defaults classes, or avoid using defaults for actuators and instead specify all their attributes
explicitly.

.. _CActRange:

Activation clamping
~~~~~~~~~~~~~~~~~~~

As described in the :ref:`Actuation model <geActuation>` section of the Computation chapter, MuJoCo supports actuators
with internal dynamics whose states are called "activations". One useful application of these stateful actuators is the
"integrated-velocity" actuator. Different from the :ref:`pure velocity<velocity>` actuators, which implement direct
feedback on transmission target's velocity, *integrated-velocity* actuators couple an *integrator* with a *position-
feedback* actuator. In this case the semantics of the activation state are "the target of the position actuator", and
the semantics of the control signal are "the velocity of the target of the position actuator". Note that in real robotic
systems this integrated-velocity actuator is the most common implementation of actuators with velocity semantics, rather
than pure feedback on velocity which is often quite unstable (both in real life and in simulation). This actuator type
is implemented by the :ref:`intvelocity<intvelocity>` shortcut.

In the case of integrated-velocity actuators, it is often desirable to *clamp* the activation state, since otherwise the
position target would keep integrating beyond the joint limits, leading to loss of controllabillity. To see the effect
of activation clamping, load the example model below:

.. code-block:: xml

   <mujoco>
     <default>
       <joint axis="0 0 1" limited="true" range="-90 90" damping="0.3"/>
       <geom size=".1 .1 .1" type="box"/>
     </default>

     <worldbody>
       <body>
         <joint name="joint1"/>
         <geom/>
       </body>
       <body pos=".3 0 0">
         <joint name="joint2"/>
         <geom/>
       </body>
     </worldbody>

     <actuator>
       <general name="unclamped" joint="joint1"/>
       <general name="clamped" joint="joint2" actlimited="true" actrange="-1.57 1.57"/>
       <general name="unclamped" joint="joint1" gainprm="1" biastype="affine"<commit_msg>Fix redundant actuators in modeling doc.<commit_after>========
Modeling
========

Introduction
------------

MuJoCo can load XML model files in its native **MJCF** format, as well as in the popular but more limited **URDF**
format. This chapter is the MJCF modeling guide. The reference manual is available in the :doc:`XMLreference`
chapter. The URDF documentation can be found elsewhere; here we only describe
MuJoCo-specific :ref:`URDF extensions <CURDF>`.

MJCF models can represent complex dynamical systems with a wide range of features and model elements. Accessing all
these features requires a rich modeling format, which can become cumbersome if it is not designed with usability in
mind. Therefore we have made an effort to design MJCF as a scalable format, allowing users to start small and build
more detailed models later. Particularly helpful in this regard is the extensive :ref:`default setting <CDefault>`
mechanism inspired by the idea of Cascading Style Sheets (CSS) in HTML. It enables users to rapidly create new models
and experiment with them. Experimentation is further aided by numerous :ref:`options <option>` which
can be used to reconfigure the simulation pipeline, and by quick re-loading that makes model editing an interactive
process.

One can think of MJCF as a hybrid between a modeling format and a programming language. There is a built-in compiler,
which is a concept normally associated with programming languages. While MJCF does not have the power of a
general-purpose programming language, a number of sophisticated compile-time computations are invoked automatically
depending on how the model is designed.

.. _Load:

Loading models
~~~~~~~~~~~~~~

As explained in :ref:`Model instances <Instance>` in the Overview chapter, MuJoCo models can be loaded from plain-text
XML files in the MJCF or URDF formats, and then compiled into a low-level mjModel. Alternatively a previously saved
mjModel can be loaded directly from a binary MJB file - whose format is not documented but is essentially a copy of the
mjModel memory buffer. MJCF and URDF files are loaded with :ref:`mj_loadXML` while MJB files are loaded with
:ref:`mj_loadModel`.

When an XML file is loaded, it is first parsed into a document object model (DOM) using the TinyXML parser internally.
This DOM is then processed and converted into a high-level mjCModel object. The conversion depends on the model format
- which is inferred from the top-level element in the XML file, and not from the file extension. Recall that a valid
XML file has a unique top-level element. This element must be :el:`mujoco` for MJCF, and :el:`robot` for URDF.

.. _Compile:

Compiling models
~~~~~~~~~~~~~~~~

Once a high-level mjCModel is created - by loading an MJCF file or a URDF file, or programmatically when such
functionality becomes available - it is compiled into mjModel. Even though loading and compilation are presently
combined in one step, compilation is independent of loading, meaning that the compiler works in the same way
regardless of how mjCModel was created. Both the parser and the compiler perform extensive error checking, and abort
when the first error is encountered. The resulting error messages contain the row and column number in the XML file,
and are self-explanatory so we do not document them here. The parser uses a custom schema to make sure that the file
structure, elements and attributes are valid. The compiler then applies many additional semantic checks. Finally, one
simulation step of the compiled model is performed and any runtime errors are intercepted. The latter is done by
(temporarily) setting :ref:`mju_user_error` to point to a function that throws C++
exceptions; the user can implement similar error-interception functionality at runtime if desired.

The entire process of parsing and compilation is very fast - less than a second if the model does not contain large
meshes or actuator lengthranges that need to be computed via simulation. This makes it possible to design models
interactively, by re-loading often and visualizing the changes. Note that the `simulate.cc`_ code sample has a
keyboard shortcut for re-loading the current model (Ctrl+L).

.. _Save:

Saving models
~~~~~~~~~~~~~

An MJCF model can consist of multiple (included) XML files as well as meshes, height fields and textures referenced
from the XML. After compilation, the contents of all these files are assembled into mjModel, which can be saved into a
binary MJB file with :ref:`mj_saveModel`. The MJB is a stand-alone file and does not
refer to any other files. It also loads faster. So we recommend saving commonly used models as MJB and loading them
when needed for simulation.

It is also possible to save a compiled mjCModel as MJCF with :ref:`mj_saveLastXML`. If any real-valued fields in the
corresponding mjModel were modified after compilation (which is unusual but can happen in system identification
applications for example), the modifications are automatically copied back into mjCModel before saving. Note that
structural changes cannot be made in the compiled model. The XML writer attempts to generate the smallest MJCF file
which is guaranteed to compile into the same model, modulo negligible numeric differences caused by the plain text
representation of real values. The resulting file may not have the same structure as the original because MJCF has many
user convenience features, allowing the same model to be specified in different ways. The XML writer uses a "canonical"
subset of MJCF where all coordinates are local and all body positions, orientations and inertial properties are
explicitly specified. In the Computation chapter we showed an `example <_static/example.xml>`__ MJCF file and the
corresponding `saved example <_static/example_saved.xml>`__.

.. _Mechanisms:

MJCF Mechanisms
---------------

MJCF uses several mechanisms for model creation which span multiple model elements. To avoid repetition we describe them
in detail only once in this section. These mechanisms do not correspond to new simulation concepts beyond those
introduced in the Computation chapter. Their role is to simplify the creation of MJCF models, and to enable the use of
different data formats without need for manual conversion to a canonical format.

.. _CTree:

Kinematic tree
~~~~~~~~~~~~~~

The main part of the MJCF file is an XML tree created by nested :ref:`body <body>` elements. The top-level body is
special and is called :el:`worldbody`. This tree organization is in contrast with URDF where one creates a collection of
links and then connects them with joints that specify a child and a parent link. In MJCF the child body is literally a
child of the parent body, in the sense of XML.

When a :ref:`joint <joint>` is defined inside a body, its function is not to connect the parent and child but rather to
create motion degrees of freedom between them. If no joints are defined within a given body, that body is welded to its
parent. A body in MJCF can contain multiple joints, thus there is no need to introduce dummy bodies for creating
composite joints. Instead simply define all the primitive joints that form the desired composite joint within the same
body. For example, two sliders and one hinge can be used to model a body moving in a plane.

Other MJCF elements can be defined within the tree created by nested body elements, in particular :ref:`joint <joint>`,
:ref:`geom <geom>`, :ref:`site <site>`, :ref:`camera <camera>`, :ref:`light <light>`. When an element is defined within
a body, it is fixed to the local frame of that body and always moves with it. Elements that refer to multiple bodies, or
do not refer to bodies at all, are defined in separate sections outside the kinematic tree.

.. _CDefault:

Default settings
~~~~~~~~~~~~~~~~

MJCF has an elaborate mechanism for setting default attribute values. This allows us to have a large number of elements
and attributes needed to expose the rich functionality of the software, and at the same time write short and readable
model files. This mechanism further enables the user to introduce a change in one place and have it propagate throughout
the model. We start with an example.

.. code-block:: xml

   <mujoco>
       <default class="main">
           <geom rgba="1 0 0 1"/>
           <default class="sub">
               <geom rgba="0 1 0 1"/>
           </default>
       </default>

       <worldbody>
           <geom type="box"/>
           <body childclass="sub">
               <geom type="ellipsoid"/>
               <geom type="sphere" rgba="0 0 1 1"/>
               <geom type="cylinder" class="main"/>
           </body>
       </worldbody>
   </mujoco>

This example will not actually compile because some required information is missing, but here we are only interested
in the setting of geom rgba values. The four geoms created above will end up with the following rgba values as a
result of the default setting mechanism:

========= =========
geom type geom rgba
========= =========
box       1 0 0 1
ellipsoid 0 1 0 1
sphere    0 0 1 1
cylinder  1 0 0 1
========= =========


The box uses the top-level defaults class "main" to set the values of its undefined attributes, because no other class
was specified. The body specifies childclass "sub", causing all children of this body (and all their children etc.) to
use class "sub" unless specified otherwise. So the ellipsoid uses class "sub". The sphere has explicitly defined rgba
which overrides the default settings. The cylinder specifies defaults class "main", and so it uses "main" instead of
"sub", even though the latter was specified in the childclass attribute of the body containing the geom.

Now we describe the general rules. MuJoCo supports unlimited number of defaults classes, created by possibly nested
:ref:`default <default>` elements in the XML. Each class has a unique name - which is a required
attribute except for the top-level class whose name is "main" if left undefined. Each class also has a complete
collection of dummy model elements, with their attributes set as follows. When a defaults class is defined within
another defaults class, the child automatically inherits all attribute values from the parent. It can then override
some or all of them by defining the corresponding attributes. The top-level defaults class does not have a parent, and
so its attributes are initialized to internal defaults which are shown in the reference documentation below.

The dummy elements contained in the defaults classes are not part of the model; they are only used to initialize the
attribute values of the actual model elements. When an actual element if first created, all its attributes are copied
from the corresponding dummy element in the defaults class that is currently active. There is always an active
defaults class, which can be determined in one of three ways. If no class is specified in the present element or any
of its ancestor bodies, the top-level class is used (regardless of whether it is called "main" or something else). If
no class is specified in the present element but one or more of its ancestor bodies specify a childclass, then the
childclass from the nearest ancestor body is used. If the present element specifies a class, that class is used
regardless of any childclass attributes in its ancestor bodies.

Some attributes, such as body position in models defined in global coordinates, can be in a special undefined state.
This instructs the compiler to infer the corresponding value from other information, in this case the positions of the
geoms attached to the body. The undefined state cannot be entered in the XML file. Therefore once an attribute is
defined in a given class, it cannot be undefined in that class or in any of its child classes. So if the goal is to
leave a certain attribute undefined in a given model element, it must be undefined in the active defaults class.

A final twist here is actuators. They are different because some of the actuator-related elements are actually
shortcuts, and shortcuts interact with the defaults setting mechanism in a non-obvious way. This is explained in the
:ref:`Actuator shortcuts <CActuator>` section below.

.. _CFrame:

Coordinate frames
~~~~~~~~~~~~~~~~~

After compilation the positions and orientations of all elements defined in the kinematic tree are expressed in local
coordinates, relative to the parent body for bodies, and relative to the body that owns the element for geoms, joints,
sites, cameras and lights. Consequently, when a compiled model is saved as MJCF, the coordinates are always local.
However when the user writes an MJCF file, the coordinates can be either local or global, as specified by the
:at:`coordinate` attribute of :ref:`compiler <compiler>`. This setting applies to all position and
orientation data in the MJCF file. A related attribute is :at:`angle`. It specifies whether all angles in the MJCF
file are expressed in degrees or radians (after compilation angles are always expressed in radians). Awareness of
these global settings is essential when constructing new models.

Global coordinates can sometimes be more intuitive and have the added benefit that body positions and orientations can
be omitted. In that case the body frame is set to the body inertial frame, which can itself be omitted and inferred
from the geom masses and inertias. When an MJCF model is defined in local coordinates on the other hand, the user must
specify the positions and orientations of the body frames explicitly. This is because if they were omitted, and the
elements inside the body were specified in local coordinates relative to the body frame, there would be no way to
infer the body frame.

Here is an example of an MJCF fragment in global coordinates:

.. code-block:: xml

   <body>
      <geom type="box" pos="1 0 0" size="0.5 0.5 0.5"/>
   </body>

When this model is compiled and saved as MJCF (in local coordinates) the same fragment becomes:

.. code-block:: xml

   <body pos="1 0 0">
      <inertial pos="0 0 0" mass="1000" diaginertia="166.667 166.667 166.667"/>
      <geom type="box" pos="0 0 0" size="0.5 0.5 0.5"/>
   </body>

The body position was set to the geom position (1 0 0), while the geom and inertial positions were set to (0 0 0)
relative to the body.

In principle the user always has a choice between local and global coordinates, but in practice this choice is viable
only when using geometric primitives rather than meshes. For meshes, the 3D vertex positions are expressed in either
local or global coordinates depending on how the mesh was designed - effectively forcing the user to adopt the same
convention for the entire model. The alternative would be to pre-process the mesh data outside MuJoCo so as to change
coordinates, but that effort is rarely justified.

.. _COrientation:

Frame orientations
~~~~~~~~~~~~~~~~~~

Several model elements have right-handed spatial frames associated with them. These are all the elements defined in the
kinematic tree except for joints. A spatial frame is defined by its position and orientation. Specifying 3D positions is
straightforward, but specifying 3D orientations can be challenging. This is why MJCF provides several alternative
mechanisms. No matter which mechanism the user chooses, the frame orientation is always represented as a unit quaternion
after compilation. Recall that a 3D rotation by angle :math:`a` around axis given by the unit vector :math:`(x, y, z)`
corresponds to the quaternion :math:`(\cos(a/2), \: \sin(a/2) \cdot (x, y, z))`. Also recall that every 3D orientation
can be uniquely specified by a single 3D rotation by some angle around some axis.

All MJCF elements that have spatial frames allow the five attributes listed below. The frame orientation is specified
using at most one of these attributes. The :at:`quat` attribute has a default value corresponding to the null
rotation, while the others are initialized in the special undefined state. Thus if none of these attributes are
specified by the user, the frame is not rotated.

:at:`quat`: :at-val:`real(4), "1 0 0 0"`
   If the quaternion is known, this is the preferred was to specify the frame orientation because it does not involve
   conversions. Instead it is normalized to unit length and copied into mjModel during compilation. When a model is
   saved as MJCF, all frame orientations are expressed as quaternions using this attribute.
:at:`axisangle`: :at-val:`real(4), optional`
   These are the quantities :math:`(x, y, z, a)` mentioned above. The last number is the angle of rotation, in degrees
   or radians as specified by the :at:`angle` attribute of :ref:`compiler <compiler>`. The first three numbers determine
   a 3D vector which is the rotation axis. This vector is normalized to unit length during compilation, so the user can
   specify a vector of any non-zero length. Keep in mind that the rotation is right-handed; if the direction of the
   vector :math:`(x, y, z)` is reversed this will result in the opposite rotation. Changing the sign of :math:`a` can
   also be used to specify the opposite rotation.
:at:`euler`: :at-val:`real(3), optional`
   Rotation angles around three coordinate axes. The sequence of axes around which these rotations are applied is
   determined by the :at:`eulerseq` attribute of :ref:`compiler <compiler>` and is the same for the
   entire model.
:at:`xyaxes`: :at-val:`real(6), optional`
   The first 3 numbers are the X axis of the frame. The next 3 numbers are the Y axis of the frame, which is
   automatically made orthogonal to the X axis. The Z axis is then defined as the cross-product of the X and Y axes.
:at:`zaxis`: :at-val:`real(3), optional`
   The Z axis of the frame. The compiler finds the minimal rotation that maps the vector :math:`(0, 0, 1)` into the
   vector specified here. This determines the X and Y axes of the frame implicitly. This is useful for geoms with
   rotational symmetry around the Z axis, as well as lights - which are oriented along the Z axis of their frame.

.. _CSolver:

Solver parameters
~~~~~~~~~~~~~~~~~

The solver :ref:`Parameters <soParameters>` section of the Computation chapter explained the mathematical and
algorithmic meaning of the quantities :math:`d, b, k` which determine the behavior of the constraints in MuJoCo. Here we
explain how to set them. Setting is done indirectly, through the attributes :at:`solref` and :at:`solimp` which are
available in all MJCF elements involving constraints. These parameters can be adjusted per constraint, or per defaults
class, or left undefined - in which case MuJoCo uses the internal defaults shown below. Note also the override mechanism
available in :ref:`option <option>`; it can be used to change all contact-related solver parameters at runtime, so as to
experiment interactively with parameter settings or implement continuation methods for numerical optimization.

Here we focus on a single scalar constraint. Using slightly different notation from the Computation chapter, let
:math:`a_1` denote the acceleration, :math:`v` the velocity, :math:`r` the position or residual (defined as 0 in
friction dimensions), :math:`k` and :math:`b` the stiffness and damping of the virtual spring used to define the
reference acceleration :math:`a_{\rm ref} = -b v - k r`. Let :math:`d` be the constraint impedance, and :math:`a_0` the
acceleration in the absence of constraint force. Our earlier analysis revealed that the dynamics in constraint space are
approximately

.. math::
   a_1 + d \cdot (b v + k r) = (1 - d)\cdot a_0

Again, the parameters that are under the user's control are :math:`d, b, k`. The remaining quantities are functions of the
system state and are computed automatically at each time step.

First we explain the setting of the impedance :math:`d`. Recall that :math:`d` must lie between 0 and 1; internally
MuJoCo clamps it to the range [:ref:`mjMINIMP mjMAXIMP <glNumeric>`] which is currently set to [0.0001 0.9999]. It
causes the solver to interpolate between the unforced acceleration :math:`a_0` and reference acceleration
:math:`a_{\rm ref}`. Small values of :math:`d` correspond to soft/weak constraints while large values of :math:`d`
correspond to strong/hard constraints. The user can set :math:`d` to a constant, or take advantage of its interpolating
property and make it position-dependent, i.e., a function of :math:`r`. Position-dependent impedance can be used to
model soft contact layers around objects, or define equality constraints that become stronger with larger violation (so
as to approximate backlash for example). The shape of the function :math:`d(r)` is determined by the element-specific
parameter vector :at:`solimp`.

**solimp :** real(5), "0.9 0.95 0.001 0.5 2"

   The five numbers are (dmin, dmax, width, midpoint, power). They parameterize the function :math:`d(r)`. Prior to
   MuJoCo 2.0 this attribute had three parameters, plus a global option specifying the shape of the function. In MuJoCo
   2.0 we expanded the family of impedance functions while keeping it backward-compatible as follows. The user is
   allowed to set only the first three parameters, whose defaults are the same as in prior releases. The defaults for
   the last two parameters then generate the same function which was the default in prior releases (a sigmoid). The new
   parameterization further allows the sigmoid to become shifted and skewed, as shown in the plots below for different
   values of the additional parameters. The plots actually show two reflected sigmoids, because the impedance function
   :math:`d(r)` depends on the absolute value of :math:`r`. This flexibility was added to allow better control of remote
   contact forces, and can also be used for other constraints. The power (of the polynomial spline used to generate the
   function) must be 1 or greater. The midpoint (specifying the inflection point) must be between 0 and 1, and is
   expressed in units of width. Note that when the power is 1, the function is linear regardless of the midpoint.
   |image0|

   These plots show the impedance :math:`d(r)` on the vertical axis, as a function of the constraint violation :math:`r`
   on the horizontal axis. The quantity :math:`r` is computed as follows. For equality constraints, :math:`r` equals the
   constraint violation which can be either positive or negative. For friction loss or friction dimensions of elliptic
   cones, :math:`r` is always 0. For limits, normal directions of elliptic cones and all directions of pyramidal cones,
   :math:`r` is the (limit or contact) distance minus the margin at which the constraint becomes active; for contacts
   this margin is actually margin-gap. Therefore limit and contact constraints are active when the corresponding
   :math:`r` is negative.

Next we explain the setting of the stiffness :math:`k` and damping :math:`b`. The idea here is to re-parameterize the
model in terms of the time constant and damping ratio of the above mass-spring-damper system. By "time constant" we mean
the inverse of the natural frequency times the damping ratio. Constraints whose residual is identically 0 have first-
order dynamics and the mass-spring-damper analysis does not apply. In that case the time constant is the rate of
exponential decay of the constraint velocity, and the damping ratio is ignored. In addition to this format, MuJoCo 2.0
allows a second format where stiffness and damping are specified more directly.

**solref :** real(2), "0.02 1"
   There are two formats for this attribute, determined by the sign of the numbers. If both numbers are positive the
   specification is considered to be in the :math:`(\text{timeconst}, \text{dampratio})` format which has been available
   in MuJoCo all along. Otherwise the specification is considered to be in the new :math:`(-\text{stiffness}, -
   \text{damping})`, format introduced in MuJoCo 2.0. We first describe the original format where the two numbers are
   :math:`(\text{timeconst}, \text{dampratio})`. In this case we use a mass-spring-damper model to compute :math:`k, b`
   after suitable scaling. Note that the effective stiffness :math:`d(r) \cdot k` and damping :math:`d(r) \cdot b` are
   scaled by the impedance :math:`d(r)` which is a function of the distance :math:`r`. Thus we cannot always achieve the
   specified mass-spring-damper properties, unless we completely undo the scaling by :math:`d`. But the latter is
   undesirable because it would ruin the interpolating property, in particular the limit :math:`d=0` would no longer
   disable the constraint. Instead we scale the stiffness and damping so that the damping ratio remains constant, while
   the time constant increases when :math:`d(r)` gets smaller. The scaling formulas are

   .. math::
      \begin{aligned}
      b &= 2 / (d_\text{max}\cdot \text{timeconst}) \\
      k &= d(r) / (d_\text{max}^2 \cdot \text{timeconst}^2 \cdot \text{dampratio}^2) \\
      \end{aligned}

   The timeconst parameter should be at least two times larger than the simulation time step, otherwise the system can
   become too stiff relative to the numerical integrator (especially when Euler integration is used) and the simulation
   can go unstable. This is enforced internally, unless the :at:`refsafe` attribute of :ref:`flag <option-flag>` is set
   to false. The :math:`\text{dampratio}` parameter would normally be set to 1, corresponding to critical damping.
   Smaller values result in under-damped or bouncy constraints, while larger values result in over-damped constraints.
   Next we describe the new format where the two numbers are :math:`(-\text{stiffness}, -\text{damping})`. This allows
   more direct control over restitution in particular. We still apply some scaling so that the same numbers can be used
   with different impedances, but the scaling no longer depends on :math:`r` and the two numbers no longer interact. The
   scaling formulas are

   .. math::
      \begin{aligned}
      b &= \text{damping} / d_\text{max} \\
      k &= \text{stiffness} / d_\text{max}^2 \\
      \end{aligned}

.. _CContact:

Contact parameters
~~~~~~~~~~~~~~~~~~

The parameters of each contact were described in the :ref:`Contact <coContact>` section of the Computation
chapter. Here we explain how these parameters are set. If the geom pair is explicitly defined with the XML element
:ref:`pair <pair>`, it has attributes specifying all contact parameters directly. In that case the
parameters of the individual geoms are ignored. If on the other hand the contact is generated by the dynamic mechanism,
its parameters need to be inferred from the two geoms in the contact pair. If the two geoms have identical parameters
there is nothing to do, but what if their parameters are different? In that case we use the geom attributes
:at:`solmix` and :at:`priority` to decide how to combine them. The combination rules for each contact parameter
are as follows:

condim
   If one of the two geoms has higher priority, its condim is used. If both geoms have the same priority, the maximum of
   the two condims is used. In this way a frictionless geom and a frictional geom form a frictional contact, unless the
   frictionless geom has higher priority. The latter is desirable in particle systems for example, where we may not want
   the particles to stick to any objects.
friction
   Recall that contacts can have up to 5 friction coefficients: two tangential, one torsional, two rolling. Each contact
   in mjData.contact actually has all 5 of them, even if condim is less than 6 and not all coefficients are used. In
   contrast, geoms have only 3 friction coefficients: tangential (same for both axes), torsional, rolling (same for both
   axes). Each of these 3D vectors of friction coefficients is expanded into a 5D vector of friction coefficients by
   replicating the tangetial and rolling components. The contact friction coefficients are then computed according to
   the following rule: if one of the two geoms has higher priority, its friction coefficients are used. Otherwise the
   element-wise maximum of each friction coefficient over the two geoms is used. The rationale is similar to taking the
   maximum over condim: we want the more frictional geom to win.
   The reason for having 5 coefficients per contact and only 3 per geom is as follows. For a contact pair, we want to
   allow the most flexible model our solver can handle. As mentioned earlier, anisotropic friction can be exploited to
   model effects such as skating. This however requires knowing how the two axes of the contact tangent plane are
   oriented. For a predefined contact pair we know the two geom types in advance, and the corresponding collision
   function always generates contact frames oriented in the same way - which we do not describe here but it can be seen
   in the visualizer. For individual geoms however, we do not know which other geoms they might collide with and what
   their geom types might be, so there is no way to know how the contact tangent plane will be oriented when specifying
   an individual geom. This is why MuJoCo does not allow anisotropic friction in the individual geom specifications, but
   only in the explicit contact pair specifications.
margin, gap
   The maximum of the two geom margins (or gaps respectively) is used. The geom priority is ignored here, because the
   margin and gap are distance properties and a one-sided specification makes little sense.
solref, solimp
   If one of the two geoms has higher priority, its solref and solimp parameters are used. If both geoms have the same
   priority, the weighted average is used. The weights are proportional to the solmix attributes, i.e., weight1 =
   solmix1 / (solmix1 + solmix2) and similarly for weight2. There is one important exception to this weighted averaging
   rule. If solref for either geom is non-positive, i.e., it relies on the new direct format introduced in MuJoCo 2.0,
   then the element-wise minimum is used regardless of solmix. This is because averaging solref parameters in different
   formats would be meaningless.

.. _COverride:

Contact override
~~~~~~~~~~~~~~~~

MuJoCo uses an elaborate as well as novel :ref:`Constraint model <Constraint>` described in the
Computation chapter. Gaining an intuition for how this model works requires some experimentation. In order to
facilitate this process, we provide a mechanism to override some of the solver parameters, without making changes to
the actual model. Once the override is disabled, the simulation reverts to the parameters specified in the model. This
mechanism can also be used to implement continuation methods in the context of numerical optimization (such as optimal
control or state estimation). This is done by allowing contacts to act from a distance in the early phases of
optimization - so as to help the optimizer find a gradient and get close to a good solution - and reducing this effect
later to make the final solution physically realistic.

The relevant settings here are the :at:`override` attribute of :ref:`flag <option-flag>` which
enables and disables this mechanism, and the :at:`o_margin`, :at:`o_solref`, :at:`o_solimp` attributes of
:ref:`option <option>` which specify the new solver parameters. Note that the override applies only to
contacts, and not to other types of constraints. In principle there are many real-valued parameters in a MuJoCo model
that could benefit from a similar override mechanism. However we had to draw a line somewhere, and contacts are the
natural choice because they give rise to the richest yet most difficult-to-tune behavior. Furthermore, contact
dynamics often present a challenge in terms of numerical optimization, and experience has shown that continuation over
contact parameters can help avoid local minima.

.. _CUser:

User parameters
~~~~~~~~~~~~~~~

A number of MJCF elements have the optional attribute :at:`user`, which defines a custom element-specific parameter
array. This interacts with the corresponding "nuser_XXX" attribute of the :ref:`size <size>` element. If for example we
set :at:`nuser_geom` to 5, then every geom in mjModel will have a custom array of 5 real-valued parameters. These geom-
specific parameters are either defined in the MJCF file via the :at:`user` attribute of :ref:`geom <geom>`, or set to 0
by the compiler if this attribute is omitted. The default value of all "nuser_XXX" attributes is -1, which instructs the
compiler to automatically set this value to the length of the maximum associated :at:`user` attribute defined in the
model. MuJoCo does not use these parameters in any internal computations; instead they are available for custom
computations. The parser allows arrays of arbitrary length in the XML, and the compiler later resizes them to length
nuser_XXX.

Some element-specific parameters that are normally used in internal computations can also be used in custom
computations. This is done by installing user callbacks which override parts of the simulation pipeline. For example,
the :ref:`general <general>` actuator element has attributes :at:`dyntype` and :at:`dynprm`. If
:at:`dyntype` is set to "user", then MuJoCo will call :ref:`mjcb_act_dyn` to compute
the actuator dynamics instead of calling its internal function. The user function pointed to by
:ref:`mjcb_act_dyn` can interpret the parameters defined in :at:`dynprm` however it
wishes. However the length of this parameter array cannot be changed (unlike the custom arrays described earlier whose
length is defined in the MJCF file). The same applies to other callbacks.

In addition to the element-specific user parameters described above, one can include global data in the model via
:ref:`custom <custom>` elements. For data that change in the course of the simulation, there is also
the array mjData.userdata whose size is determined by the :at:`nuserdata` attribute of the
:ref:`size <size>` element.

.. _CAlgorithms:

Algorithms and related settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The computation of constraint forces and constrained accelerations involves solving an optimization problem
numerically. MuJoCo has three algorithms for solving this optimization problem: CG, Newton, PGS. Each of them can be
applied to a pyramidal or elliptic model of the friction cones, and with dense or sparse constraint Jacobians. In
addition, the user can specify the maximum number of iterations, and tolerance level which controls early termination.
There is also a second Noslip solver, which is a post-processing step enabled by specifying a positive number of
noslip iterations. All these algorithm settings can be specified in the :ref:`option <option>` element.

The default settings work well for most models, but in some cases it is necessary to tune the algorithm. The best way
to do this is to experiment with the relevant settings and use the visual profiler in `simulate.cc`_, which shows the timing of different computations as
well as solver statistics per iteration. We can offer the following general guidelines and observations:

-  The constraint Jacobian should be dense for small models and sparse for large models. The default setting is 'auto';
   it resolves to dense when the number of degrees of freedom is up to 60, and sparse over 60. Note however that the
   threshold is better defined in terms of number of active constraints, which is model and behavior dependent.
-  The choice between pyramidal and elliptic friction cones is a modeling choice rather than an algorithmic choice,
   i.e., it leads to a different optimization problem solved with the same algorithms. Elliptic cones correspond more
   closely to physical reality. However pyramidal cones can improve the performance of the algorithms - but not
   necessarily. While the default is pyramidal, we recommend trying the elliptic cones. When contact slip is a problem,
   the best way to suppress it is to use elliptic cones, large impratio, and the Newton algorithm with very small
   tolerance. If that is not sufficient, enable the Noslip solver.
-  The Newton algorithm is the best choice for most models. It has quadratic convergence near the global minimum and
   gets there in surprisingly few iterations - usually around 5, and rarely more than 20. It should be used with
   aggressive tolerance values, say 1e-10, because it is capable of achieving high accuracy without added delay (due to
   quadratic convergence at the end). The only situation where we have seen it slow down are large models with elliptic
   cones and many slipping contacts. In that regime the Hessian factorization needs a lot of updates. It may also slow
   down in some large models with unfortunate ordering of model elements that results in high fill-in (computing the
   optimal elimination order is NP-hard, so we are relying on a heuristic). Note that the number of non-zeros in the
   factorized Hessian can be monitored in the profiler.
-  The CG algorithm works well in the situation described above where Newton slows down. In general CG shows linear
   convergence with a good rate, but it cannot compete with Newton in terms of number of iterations, especially when
   high accuracy is desired. However its iterations are much faster, and are not affected by fill-in or increased
   complexity due to elliptic cones. If Newton proves to be too slow, try CG next.
-  The PGS solver used to be the default solver until recently, and was substantially improved in MuJoCo 1.50 by making
   it work with sparse models. However we have not yet found a situation where it is the best algorithm, which is not to
   say that such situations do not exist. PGS solves a constrained optimization problem and has sub-linear convergence
   in our experience, however it usually makes rapid progress on the first few iterations. So it is a good choice when
   inaccurate solutions can be tolerated. For systems with large mass ratios or other model properties causing poor
   conditioning, PGS convergence tends to be rather slow. Keep in mind that PGS performs sequential updates, and
   therefore breaks symmetry in systems where the physics should be symmetric. In contrast, CG and Newton perform
   parallel updates and preserve symmetry.
-  The Noslip solver is a modified PGS solver. It is executed as a post-processing step after the main solver (which can
   be Newton, CG or PGS). The main solver updates all unknowns. In contrast, the Noslip solver updates only the
   constraint forces in friction dimensions, and ignores constraint regularization. This has the effect of suppressing
   the drift or slip caused by the soft-constraint model. However, this cascade of optimization steps is no longer
   solving a well-defined optimization problem (or any other problem); instead it is just an adhoc mechanism. While it
   usually does its job, we have seen some instabilities in models with more complex interactions among multiple
   contacts.
-  PGS has a setup cost (in terms of CPU time) for computing the inverse inertia in constraint space. Similarly, Newton
   has a setup cost for the initial factorization of the Hessian, and incurs additional factorization costs depending on
   how many factorization updates are needed later. CG does not have any setup cost. Since the Noslip solver is also a
   PGS solver, the PGS setup cost will be paid whenever Noslip is enabled, even if the main solver is CG or Newton. The
   setup operation for the main PGS and Noslip PGS is the same, thus the setup cost is paid only once when both are
   enabled.

.. _CActuator:

Actuator shortcuts
~~~~~~~~~~~~~~~~~~

As explained in the :ref:`Actuation model <geActuation>` section of the Computation chapter, MuJoCo offers a flexible
actuator model with transmission, activation dynamics and force generation components that can be specified
independently. The full functionality can be accessed via the XML element :ref:`general <general>` which allows the user
to create a variety of custom actuators. In addition, MJCF provides shortcuts for configuring common actuators. This is
done via the XML elements :ref:`motor <motor>`, :ref:`position <position>`, :ref:`velocity <velocity>`,
:ref:`intvelocity <intvelocity>`, :ref:`cylinder<cylinder>`, and :ref:`muscle <muscle>`. These are *not* separate model
elements. Internally MuJoCo supports only one actuator type - which is why when an MJCF model is saved all actuators are
written as :el:`general`. Shortcuts create general actuators implicitly, set their attributes to suitable values, and
expose a subset of attributes with possibly different names. For example, :el:`position` creates a position servo with
attribute :at:`kp` which is the servo gain. However :el:`general` does not have an attribute :at:`kp`. Instead the parser
adjusts the gain and bias parameters of the general actuator in a coordinated way so as to mimic a position servo. The
same effect could have been achieved by using :el:`general` directly, and setting its attributes to certain values as
described below.

Actuator shortcuts also interact with defaults. Recall that the :ref:`default setting <CDefault>` mechanism involves
classes, each of which has a complete collection of dummy elements (one of each element type) used to initialize the
attributes of the actual model elements. In particular, each defaults class has only one general actuator element.
What happens if we specify :el:`position` and later :el:`velocity` in the same defaults class? The XML elements are
processed in order, and the attributes of the single general actuator are set every time an actuator-related element
is encountered. Thus :el:`velocity` has precedence. If however we specify :el:`general` in the defaults class, it will
only set the attributes that are given explicitly, and leave the rest unchanged. A similar complication arises when
creating actual model elements. Suppose the active defaults class specified :el:`position`, and now we create an
actuator using :el:`general` and omit some of its attributes. The missing attributes will be set to whatever values
are used to model a position servo, even though this actuator may not be intended as a position servo.

In light of these potential complications, we recommend a simple approach: use the same actuator shortcut in both the
defaults class and in the creation of actual model elements. If a given model requires different actuators, either
create multiple defaults classes, or avoid using defaults for actuators and instead specify all their attributes
explicitly.

.. _CActRange:

Activation clamping
~~~~~~~~~~~~~~~~~~~

As described in the :ref:`Actuation model <geActuation>` section of the Computation chapter, MuJoCo supports actuators
with internal dynamics whose states are called "activations". One useful application of these stateful actuators is the
"integrated-velocity" actuator. Different from the :ref:`pure velocity<velocity>` actuators, which implement direct
feedback on transmission target's velocity, *integrated-velocity* actuators couple an *integrator* with a *position-
feedback* actuator. In this case the semantics of the activation state are "the target of the position actuator", and
the semantics of the control signal are "the velocity of the target of the position actuator". Note that in real robotic
systems this integrated-velocity actuator is the most common implementation of actuators with velocity semantics, rather
than pure feedback on velocity which is often quite unstable (both in real life and in simulation). This actuator type
is implemented by the :ref:`intvelocity<intvelocity>` shortcut.

In the case of integrated-velocity actuators, it is often desirable to *clamp* the activation state, since otherwise the
position target would keep integrating beyond the joint limits, leading to loss of controllabillity. To see the effect
of activation clamping, load the example model below:

.. code-block:: xml

   <mujoco>
     <default>
       <joint axis="0 0 1" limited="true" range="-90 90" damping="0.3"/>
       <geom size=".1 .1 .1" type="box"/>
     </default>

     <worldbody>
       <body>
         <joint name="joint1"/>
         <geom/>
       </body>
       <body pos=".3 0 0">
         <joint name="joint2"/>
         <geom/>
       </body>
     </worldbody>

     <actuator>
       <general name="unclamped" joint="joint1" gainprm="1" biastype="affine"
{'fraction_non_alphanumeric': 0.05556117460638549, 'fraction_numerical': 0.0048773361203825446, 'mean_word_length': 4.37245668055304, 'pattern_counts': {'":': 0, '<': 175, '<?xml version=': 0, '>': 173, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 12}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2831607', 'n_tokens_mistral': 22213, 'n_tokens_neox': 20736, 'n_words': 13419}