@possumtech/rummy 2.0.1 → 2.2.0

package/audit/sweep/tune-mjcf/turns/turn_005.md

@@ -0,0 +1,2064 @@
+# turn 005
+
+tokens: prompt=8942 cached=1744 completion=250 reasoning=0 total=9192 cost=0
+created: 2026-05-01 23:53:49
+
+update: status=155 body=discovering MuJoCo docs for tuning params distillation
+
+---
+
+## reasoning (think)
+
+```
+* Still in Distillation Stage: 5 unresolved mujoco unknowns need sources distilled into known:// entries
+* Key sources already promoted: Isaac Gym tuning (Flex/PhysX params), MCP MuJoCo tuning skill (high-level), search results pointing to official MuJoCo docs
+* Need MuJoCo-specific tuning params: Distill from current sources + get official MuJoCo modeling/simulation docs (top search results, reasonable token cost)
+* Prioritize: tuning_params → correctness_test → eval_script/model_ref (files missing, may need sh/env later)
+* Budget ok: MuJoCo docs ~45k-67k tokens total but use line/limit if needed; get 2 key pages now
+* After gets: distill known://mujoco/tuning_params with <option>, <solver> etc. references
+* Continue 155 after discovering MuJoCo docs
+```
+
+## assistant emission
+
+```
+<think>
+* Still in Distillation Stage: 5 unresolved mujoco unknowns need sources distilled into known:// entries
+* Key sources already promoted: Isaac Gym tuning (Flex/PhysX params), MCP MuJoCo tuning skill (high-level), search results pointing to official MuJoCo docs
+* Need MuJoCo-specific tuning params: Distill from current sources + get official MuJoCo modeling/simulation docs (top search results, reasonable token cost)
+* Prioritize: tuning_params → correctness_test → eval_script/model_ref (files missing, may need sh/env later)
+* Budget ok: MuJoCo docs ~45k-67k tokens total but use line/limit if needed; get 2 key pages now
+* After gets: distill known://mujoco/tuning_params with <option>, <solver> etc. references
+* Continue 155 after discovering MuJoCo docs
+</think>
+
+<get path="https://mujoco.readthedocs.io/en/stable/modeling.html" line="1" limit="2000"/>
+<get path="https://mujoco.readthedocs.io/en/stable/programming/simulation.html"/>
+
+<update status="155">discovering MuJoCo docs for tuning params distillation</update>
+```
+
+## actions (chronological log entries)
+
+### `log://turn_5/get/https%3A/mujoco.readthedocs.io/en/stable/modeling.html`
+scheme=log action=get attrs={"path":"https://mujoco.readthedocs.io/en/stable/modeling.html","lineStart":1,"lineEnd":2000,"totalLines":2442,"action":"get"}
+
+```
+https://mujoco.readthedocs.io/en/stable/modeling.html
+[lines 1–2000 / 2442 total]
+# Modeling - MuJoCo Documentation
+
+## Introduction[#](#introduction "Link to this heading")
+
+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
+[XML Reference](https://mujoco.readthedocs.io/en/stable/XMLreference.html)
+chapter. The URDF documentation can be found elsewhere; here we only describe
+MuJoCo-specific [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
+[default setting](#cdefault) mechanism inspired by the idea of Cascading Style
+Sheets (CSS) inlined in HTML. It enables users to rapidly create new models and
+experiment with them. Experimentation is further aided by numerous
+[options](https://mujoco.readthedocs.io/en/stable/XMLreference.html#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.
+
+### Loading models[#](#loading-models "Link to this heading")
+
+As explained in
+[Model instances](https://mujoco.readthedocs.io/en/stable/overview.html#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
+[mj\_loadXML](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-loadxml)
+while MJB files are loaded with
+[mj\_loadModel](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#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
+[mjSpec](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjspec)
+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 mujoco for
+MJCF, and robot for URDF.
+
+### Compiling models[#](#compiling-models "Link to this heading")
+
+Once a high-level
+[mjSpec](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjspec)
+is created—by loading an MJCF file or a URDF file, or
+[programmatically](https://mujoco.readthedocs.io/en/stable/programming/modeledit.html)
+—it is compiled into
+[mjModel](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjmodel)
+. Compilation is independent of loading, meaning that the compiler works in the
+same way regardless of how
+[mjSpec](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjspec)
+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
+[mju\_user\_error](https://mujoco.readthedocs.io/en/stable/APIreference/APIglobals.html#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](https://mujoco.readthedocs.io/en/stable/programming/samples.html#sasimulate)
+code sample has a keyboard shortcut for re-loading the current model (Ctrl+L).
+
+### Saving models[#](#saving-models "Link to this heading")
+
+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
+[mj\_saveModel](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#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
+[mjSpec](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjspec)
+as MJCF with
+[mj\_saveLastXML](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#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
+[mjSpec](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjspec)
+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](https://mujoco.readthedocs.io/en/stable/_static/example.xml) MJCF file
+and the corresponding
+[saved example](https://mujoco.readthedocs.io/en/stable/_static/example_saved.xml)
+.
+
+### Editing models[#](#editing-models "Link to this heading")
+
+As of MuJoCo 3.2, it is possible to create and modify models using the
+[mjSpec](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjspec)
+struct and related API. For further documentation, please see the
+[Model Editing](https://mujoco.readthedocs.io/en/stable/programming/modeledit.html)
+chapter.
+
+## MJCF Mechanisms[#](#mjcf-mechanisms "Link to this heading")
+
+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.
+
+### Kinematic tree[#](#kinematic-tree "Link to this heading")
+
+The main part of the MJCF file is an XML tree created by nested
+[body](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body) elements.
+The top-level body is special and is called 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
+[joint](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-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
+[joint](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-joint) ,
+[geom](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-geom) ,
+[site](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-site) ,
+[camera](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera)
+, [light](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-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.
+
+### Default settings[#](#default-settings "Link to this heading")
+
+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.
+
+<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
+[default](https://mujoco.readthedocs.io/en/stable/XMLreference.html#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 chapter](https://mujoco.readthedocs.io/en/stable/XMLreference.html) .
+
+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 is 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 inertia, can be in a special undefined state. This
+instructs the compiler to infer the corresponding value from other information,
+in this case the inertias 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
+[Actuator shortcuts](#cactshortcuts) section below.
+
+### Coordinate frames[#](#coordinate-frames "Link to this heading")
+
+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 contains the element for geoms, joints, sites, cameras
+and lights.
+
+A related attribute is
+[compiler/angle](https://mujoco.readthedocs.io/en/stable/XMLreference.html#compiler-angle)
+. It specifies whether angles in the MJCF file are expressed in degrees or
+radians (after compilation, angles are always expressed in radians).
+
+Positions are specified using
+
+pos: real(3), “0 0 0”
+
+Position relative to parent.
+
+#### Frame orientations[#](#frame-orientations "Link to this heading")
+
+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 converted internally
+to a unit quaternion. Recall that a 3D rotation by angle aa around axis given by
+the unit vector (x,y,z)(x, y, z) corresponds to the quaternion (cos⁡(a/2),
+sin⁡(a/2)⋅(x,y,z))(\\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 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.
+
+quat: 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.
+
+axisangle: real(4), optional
+
+These are the quantities (x,y,z,a)(x, y, z, a) mentioned above. The last number
+is the angle of rotation, in degrees or radians as specified by the angle
+attribute of
+[compiler](https://mujoco.readthedocs.io/en/stable/XMLreference.html#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 (x,y,z)(x, y, z) is reversed this will result in
+the opposite rotation. Changing the sign of aa can also be used to specify the
+opposite rotation.
+
+euler: real(3), optional
+
+Rotation angles around three coordinate axes. The sequence of axes around which
+these rotations are applied is determined by the eulerseq attribute of
+[compiler](https://mujoco.readthedocs.io/en/stable/XMLreference.html#compiler)
+and is the same for the entire model.
+
+xyaxes: 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.
+
+zaxis: real(3), optional
+
+The Z axis of the frame. The compiler finds the minimal rotation that maps the
+vector (0,0,1)(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.
+
+### Solver parameters[#](#solver-parameters "Link to this heading")
+
+The constraint solver finds forces that satisfy soft constraints, parameterized
+by three quantities: the _impedance_ dd (how strongly to enforce the
+constraint), _stiffness_ kk, and _damping_ bb (how to respond to violations).
+These are described mathematically in the
+[Parameters](https://mujoco.readthedocs.io/en/stable/computation/index.html#soparameters)
+section of the Computation chapter. Here we explain how to set them. Setting is
+done indirectly, through the attributes solref and 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
+[option](https://mujoco.readthedocs.io/en/stable/XMLreference.html#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 a1\\ac denote the acceleration, vv the
+velocity, rr the position or residual (defined as 0 in friction dimensions), kk
+and bb the stiffness and damping of the virtual spring used to define the
+reference acceleration aref\=−bv−kr\\ar = -b v - k r (see
+[(12)](https://mujoco.readthedocs.io/en/stable/computation/index.html#equation-eq-aref)
+). Let dd be the constraint impedance, and a0\\au the acceleration in the
+absence of constraint force. Our earlier analysis revealed that the dynamics in
+constraint space are approximately
+
+(1)[#](#equation-eq-constraint "Permalink to this
+equation")a1+d⋅(bv+kr)\=(1−d)⋅a0\\ac + d \\cdot (b v + k r) = (1 - d)\\cdot \\au
+
+Again, the parameters that are under the user’s control are d,b,kd, b, k. The
+remaining quantities are functions of the system state and are computed
+automatically at each time step.
+
+#### Impedance[#](#impedance "Link to this heading")
+
+We begin by explaining the constraint impedance dd.
+
+Intuitive description of the **impedance**
+
+The _impedance_ d∈(0,1)d \\in (0, 1) corresponds to a constraint’s **ability to
+generate force**. Small values of dd correspond to weak constraints while large
+values of dd correspond to strong constraints. The impedance affects the
+constraint at all times, in particular when the system is at rest. Impedance is
+set using the solimp attribute.
+
+Recall that dd must lie between 0 and 1; internally MuJoCo clamps it to the
+range \[[mjMINIMP
+mjMAXIMP](https://mujoco.readthedocs.io/en/stable/APIreference/APIglobals.html#glnumericengine)\]
+which is currently set to \[0.0001 0.9999\]. It causes the solver to interpolate
+between the unforced acceleration a0\\au and reference acceleration aref\\ar.
+The user can set dd to a constant, or take advantage of its interpolating
+property and make it position-dependent, i.e., a function of the constraint
+violation rr. 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 d(r)d(r) is determined by the element-specific parameter vector solimp.
+
+**solimp :** real(5), “0.9 0.95 0.001 0.5 2”
+
+The five numbers (d0d\_0, dwidthd\_\\text{width}, width\\text{width},
+midpoint\\text{midpoint}, power\\text{power}) parameterize d(r)d(r) – the
+impedance dd as a function of the constraint violation rr.
+
+The first 3 values indicate that the impedance will vary smoothly as rr varies
+from 00 to width\\text{width}:
+
+d(0)\=d0,d(width)\=dwidthd(0) = d\_0, \\quad d(\\text{width}) = d\_\\text{width}
+
+The 4th and 5th values, midpoint\\text{midpoint} and power\\text{power}, control
+the shape of the sigmoidal function that interpolates between d0d\_0 and
+dwidthd\_\\text{width}, as shown in the plots below. The plots show two
+reflected sigmoids, because the impedance d(r)d(r) depends on the absolute value
+of rr. The power\\text{power} (of the polynomial spline used to generate the
+function) must be 1 or greater. The midpoint\\text{midpoint} (specifying the
+inflection point) must be between 0 and 1, and is expressed in units of
+width\\text{width}. Note that when power\\text{power} is 1, the function is
+linear regardless of the midpoint\\text{midpoint}.
+
+ [![\_images/impedance.png](https://mujoco.readthedocs.io/en/stable/_images/impedance.png)](https://mujoco.readthedocs.io/en/stable/_images/impedance.png)[![\_images/impedance\_dark.png](https://mujoco.readthedocs.io/en/stable/_images/impedance_dark.png)](https://mujoco.readthedocs.io/en/stable/_images/impedance_dark.png)
+
+These plots show the impedance d(r)d(r) on the vertical axis, as a function of
+the constraint violation rr on the horizontal axis.
+
+For equality constraints, rr is the constraint violation. For limits, normal
+directions of elliptic cones and all directions of pyramidal cones, rr is the
+(limit or contact) distance minus the margin at which the constraint becomes
+active; for contacts this margin is
+[margin](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-geom-margin)
+\-[gap](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-geom-gap).
+Limit and contact constraints are active when r<0r < 0 (penetration).
+
+For frictional constraints, see [Friction](#csolverfriction) .
+
+Smoothness and differentiability
+
+For completely smooth (differentiable) dynamics, limits and contacts should have
+d0\=0d\_0=0 (`solimp[0]=0`). Specifically for contacts, the
+[mixing rules](#solmixing) of geom-associated solver parameters should be kept
+in mind. See also discussion of derivatives in the
+[Computation chapter](https://mujoco.readthedocs.io/en/stable/computation/index.html#derivatives)
+and in the
+[mjd\_transitionFD](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mjd-transitionfd)
+documentation.
+
+#### Reference[#](#reference "Link to this heading")
+
+Next we explain the setting of the stiffness kk and damping bb which control the
+reference acceleration aref\\ar.
+
+Intuitive description of the **reference acceleration**
+
+The _reference acceleration_ aref\\ar determines the **motion that constraint is
+trying to achieve** in order to rectify violation. Imagine a body dropped onto
+the plane. Upon impact the constraint will generate a normal force which
+attempts to rectify the penetration using a particular motion; this motion is
+the reference acceleration.
+
+Another way of understanding the reference acceleration is to think of the
+unmodeled deformation variables described in the
+[Computation chapter](https://mujoco.readthedocs.io/en/stable/computation/index.html#soprimal)
+. Imagine two bodies pressed together, leading to deformation at the contact.
+Now pull the bodies apart very quickly; the motion of the deformation as it
+settles into its undeformed state is the reference acceleration.
+
+This acceleration is defined by two numbers, a stiffness kk and damping bb which
+can be set directly or re-parameterized as the time-constant and damping ratio
+of a mass-spring-damper system (a
+[harmonic oscillator](https://en.wikipedia.org/wiki/Harmonic_oscillator) ). The
+reference acceleration is controlled by the solref attribute.
+
+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
+(timeconst,dampratio)(\\text{timeconst}, \\text{dampratio}) format. If negative
+it is in the “direct” (−stiffness,−damping)(-\\text{stiffness},
+-\\text{damping}) format.
+
+For frictional constraints, the mass-spring-damper analysis below does not
+directly apply; see [Friction](#csolverfriction) .
+
+**solref :** real(2), “0.02 1”
+
+We first describe the default, positive-value format where the two numbers are
+(timeconst,dampratio)(\\text{timeconst}, \\text{dampratio}).
+
+The idea here is to re-parameterize the model in terms of the time constant and
+damping ratio of a mass-spring-damper system. By “time constant” we mean the
+inverse of the natural frequency times the damping ratio. Now recall that the
+products d⋅kd \\cdot k and d⋅bd \\cdot b in [(1)](#equation-eq-constraint) are
+the effective stiffness and damping in constraint space. Because the impedance
+d(r)d(r) varies with the position residual rr, we cannot achieve constant
+mass-spring-damper properties; completely undoing the scaling by dd is
+undesirable because the limit d\=0d = 0 would no longer disable the constraint.
+Instead, we absorb one factor of d(r)d(r) into kk (but not into bb), so that the
+damping ratio remains constant while the time constant scales with d(r)d(r). The
+formulas are
+
+(2)[#](#equation-eq-solref-standard "Permalink to this
+equation")b\=2/(dwidth⋅timeconst)k\=d(r)/(dwidth2⋅timeconst2⋅dampratio2)\\begin{aligned}
+b &= 2 / (d\_\\text{width}\\cdot \\text{timeconst}) \\\\ k &= d(r) /
+(d\_\\text{width}^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
+[refsafe](https://mujoco.readthedocs.io/en/stable/XMLreference.html#option-flag-refsafe)
+attribute of
+[flag](https://mujoco.readthedocs.io/en/stable/XMLreference.html#option-flag) is
+set to false. The dampratio\\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.
+Combining [(2)](#equation-eq-solref-standard) with
+[(1)](#equation-eq-constraint) , we can derive the following If the reference
+acceleration is given using the positive number format and the impedance is
+constant d\=d0\=dwidthd = d\_0 = d\_\\text{width}, then the penetration depth at
+rest is
+
+r\=a0⋅(1−d)⋅timeconst2⋅dampratio2r = \\au \\cdot (1 - d) \\cdot
+\\text{timeconst}^2 \\cdot \\text{dampratio}^2
+
+Next we describe the direct format where the two numbers are
+(−stiffness,−damping)(-\\text{stiffness}, -\\text{damping}). This allows 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 rr and the two numbers no longer interact. The scaling formulas are
+
+(3)[#](#equation-eq-solref-direct "Permalink to this
+equation")b\=damping/dwidthk\=stiffness⋅d(r)/dwidth2\\begin{aligned} b &=
+\\text{damping} / d\_\\text{width} \\\\ k &= \\text{stiffness} \\cdot d(r) /
+d\_\\text{width}^2 \\\\ \\end{aligned}
+
+Similarly to the derivation following [(2)](#equation-eq-solref-standard) , if
+the reference acceleration is given using the impedance is constant, then the
+penetration depth at rest is
+
+r\=a0(1−d)stiffnessr = \\frac{\\au (1 - d)}{\\text{stiffness}}
+
+Tip
+
+In the positive-value default format, the timeconst\\text{timeconst} parameter
+controls constraint **softness**. It is specified in units of time and means
+“how quickly is the constraint trying to resolve the violation”. Larger values
+correspond to softer constraints.
+
+The negative-value “direct” format is more flexible, for example allowing for
+perfectly elastic collisions (damping\=0\\text{damping} = 0). It is the
+recommended format for system identification.
+
+A dampratio\\text{dampratio} of 1 in the positive-value format is equivalent to
+damping\=2stiffness\\text{damping} = 2 \\sqrt{ \\text{stiffness} } in the direct
+format.
+
+#### Friction[#](#friction "Link to this heading")
+
+Friction loss constraints (in joints and tendons) and friction dimensions of
+elliptic contact cones have zero position violation: r≡0r \\equiv 0. This
+simplifies the constraint model (see also
+[Parameters](https://mujoco.readthedocs.io/en/stable/computation/index.html#soparameters)
+):
+
+*   The **impedance** is always d0d\_0 (solimp\[0\]), since d(r)d(r) is evaluated at
+    r\=0r=0. The sigmoid shape parameters (width\\text{width},
+    midpoint\\text{midpoint}, power\\text{power}) have no effect.
+    
+*   The dynamics are **first-order** (exponential decay of constraint velocity, no
+    spring): the stiffness kk is always 0.
+    
+*   In the standard solref format, the time constant controls exponential velocity
+    decay. The damping ratio is ignored (it only appears in the kk formula).
+    
+*   In the direct solref format, the damping (second value) is used but the
+    stiffness (first value) is ignored.
+    
+*   dwidthd\_\\text{width} (solimp\[1\]) still affects the damping bb as a scaling
+    denominator ([(2)](#equation-eq-solref-standard),
+    [(3)](#equation-eq-solref-direct) ), even though it does not affect the
+    impedance.
+    
+
+### Contact parameters[#](#contact-parameters "Link to this heading")
+
+The parameters of each contact were described in the
+[Contact](https://mujoco.readthedocs.io/en/stable/computation/index.html#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
+[pair](https://mujoco.readthedocs.io/en/stable/XMLreference.html#contact-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 solmix and 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 tangential and rolling components. See the
+[Contact](https://mujoco.readthedocs.io/en/stable/computation/index.html#cocontact)
+section in the Computation chapter for an intuitive description of the semantics
+of tangential, torsional and rolling coefficients.
+
+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 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 sum 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](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-geom-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 direct format,
+then the element-wise minimum is used regardless of solmix. This is because
+averaging solref parameters in different formats would be meaningless.
+
+### Contact override[#](#contact-override "Link to this heading")
+
+MuJoCo uses an elaborate as well as novel
+[Constraint model](https://mujoco.readthedocs.io/en/stable/computation/index.html#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 override attribute of
+[flag](https://mujoco.readthedocs.io/en/stable/XMLreference.html#option-flag)
+which enables and disables this mechanism, and the o\_margin, o\_solref,
+o\_solimp attributes of
+[option](https://mujoco.readthedocs.io/en/stable/XMLreference.html#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.
+
+### User parameters[#](#user-parameters "Link to this heading")
+
+A number of MJCF elements have the optional attribute user, which defines a
+custom element-specific parameter array. This interacts with the corresponding
+“nuser\_XXX” attribute of the
+[size](https://mujoco.readthedocs.io/en/stable/XMLreference.html#size) element.
+If for example we set 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 user attribute of
+[geom](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-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 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
+[general](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-general)
+actuator element has attributes dyntype and dynprm. If dyntype is set to “user”,
+then MuJoCo will call
+[mjcb\_act\_dyn](https://mujoco.readthedocs.io/en/stable/APIreference/APIglobals.html#mjcb-act-dyn)
+to compute the actuator dynamics instead of calling its internal function. The
+user function pointed to by
+[mjcb\_act\_dyn](https://mujoco.readthedocs.io/en/stable/APIreference/APIglobals.html#mjcb-act-dyn)
+can interpret the parameters defined in 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
+[custom](https://mujoco.readthedocs.io/en/stable/XMLreference.html#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 nuserdata attribute of
+the [size](https://mujoco.readthedocs.io/en/stable/XMLreference.html#size)
+element.
+
+### Solver settings[#](#solver-settings "Link to this heading")
+
+The computation of constraint forces and constrained accelerations involves
+solving an optimization problem numerically. MuJoCo has three algorithms for
+solving this optimization problem: Newton, CG, 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 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
+[option](https://mujoco.readthedocs.io/en/stable/XMLreference.html#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](https://mujoco.readthedocs.io/en/stable/programming/samples.html#sasimulate)
+, 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 is best when the number of degrees of freedom is larger than the
+    number of constraints. 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.
+    
+
+### Actuators[#](#actuators "Link to this heading")
+
+This section describes various aspects of using actuators in MuJoCo. See the
+[Actuation model](https://mujoco.readthedocs.io/en/stable/computation/index.html#geactuation)
+regarding the computational model.
+
+#### Group disable[#](#group-disable "Link to this heading")
+
+The
+[actuatorgroupdisable](https://mujoco.readthedocs.io/en/stable/XMLreference.html#option-actuatorgroupdisable)
+attribute, which can be changed at runtime by setting the
+[mjOption.disableactuator](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjoption)
+integer bitfield, allows the user to disable sets of actuators according to
+their
+[group](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-general-group)
+. This feature is convenient when one would like to use multiple types of
+actuators for the same kinematic tree. For example consider a robot with
+firmware that supports multiple control modes e.g., torque-control and
+position-control. In this case, one can define both types of actuators in the
+same MJCF model, assigning one type of actuator to group 0 and the other to
+group 1.
+
+The
+[actuatorgroupdisable](https://mujoco.readthedocs.io/en/stable/XMLreference.html#option-actuatorgroupdisable)
+MJCF attribute selects which groups are disabled by default, and
+[mjOption.disableactuator](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjoption)
+can be set at runtime to switch the active set. Note that the total number of
+actuators `mjModel.nu` remains unchanged, as do the actuator indices, so it is
+up to the user to know that the respective `mjData.ctrl` values of disabled
+actuators will be ignored and produce no force.
+[This example model](https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/actuation/actuator_group_disable.xml)
+has three actuator groups which can be toggled at runtime in the
+[simulate](https://mujoco.readthedocs.io/en/stable/programming/samples.html#sasimulate)
+interactive viewer. See
+[example model](https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/actuation/actuator_group_disable.xml)
+and associated screen-capture on the right.
+
+#### Shortcuts[#](#shortcuts "Link to this heading")
+
+As explained in the
+[Actuation model](https://mujoco.readthedocs.io/en/stable/computation/index.html#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
+[general](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-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
+[motor](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-motor)
+,
+[position](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-position)
+,
+[velocity](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-velocity)
+,
+[intvelocity](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-intvelocity)
+,
+[damper](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-damper)
+,
+[cylinder](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-cylinder)
+,
+[muscle](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-muscle)
+,
+[adhesion](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-adhesion)
+, and
+[dcmotor](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-dcmotor)
+. 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 general. Shortcuts create general actuators implicitly, set their
+attributes to suitable values, and expose a subset of attributes with possibly
+different names. For example, position creates a position servo with attribute
+kp which is the servo gain. However general does not have an attribute 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 general directly, and setting its attributes to certain
+values as described below.
+
+Actuator shortcuts also interact with defaults. Recall that the
+[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
+position and later 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 velocity has
+precedence. If however we specify 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 position, and now we create an actuator using
+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.
+
+#### Force limits[#](#force-limits "Link to this heading")
+
+Actuator forces are usually limited between lower and upper bounds. These limits
+can be enforced in three ways:
+
+Control clamping with [ctrlrange](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-general-ctrlrange):
+
+If this actuator attribute is set, the input control value will be clamped. For
+simple
+[motors](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-motor)
+, clamping the control input is equivalent to clamping the force output.
+
+Force clamping at actuator output with [forcerange](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-general-forcerange):
+
+If this actuator attribute is set, the actuator’s output force will be clamped.
+This attribute is useful for e.g.
+[position actuators](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-position)
+, to keep the forces within bounds. Note that position actuators usually also
+require control range clamping to avoid hitting joint limits.
+
+Force clamping at joint input with [joint/actuatorfrcrange](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-joint-actuatorfrcrange):
+
+This joint attribute clamps input forces from all actuators acting on the joint,
+after passing through the
+[transmission](https://mujoco.readthedocs.io/en/stable/computation/index.html#getransmission)
+. Clamping actuator forces at the joint is equivalent to clamping them at the
+actuator if the transmission is trivial (there is a one-to-one relationship
+between the actuator and the joint). However, in situations where multiple
+actuators act on one joint or one actuator acts on multiple joints—yet the
+actual torque is applied by a single physical actuator at the joint—it is
+desirable to clamp the forces at the joint itself. Below are three examples
+where it is desirable to clamp actuator forces at the joint, rather than the
+actuator:
+
+*   In
+    [this example model](https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/actuation/joint_force_clamp.xml)
+    , two actuators, a
+    [motor](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-motor)
+    and a
+    [damper](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-damper)
+    , act on a single joint.
+    
+*   In
+    [this example model](https://github.com/google-deepmind/mujoco/blob/main/model/car/car.xml)
+    (similar to a “Dubin’s Car”), two actuators act on two wheels via a
+    [fixed tendon](https://mujoco.readthedocs.io/en/stable/XMLreference.html#tendon-fixed)
+    transmission in order to apply symmetric (roll forward/back) and antisymmetric
+    (turn right/left) torques.
+    
+*   In
+    [this example model](https://github.com/google-deepmind/mujoco/tree/main/test/engine/testdata/actuation/refsite.xml)
+    , a
+    [site transmission](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-general-refsite)
+    implements a Cartesian controller of an arm end-effector. In order for the
+    computed torques to be realisable by individual, torque-limited joint motors,
+    they need to be clamped at the joints.
+    
+
+Note that in this case, where forces/torques are combined by the transmission,
+one should use the
+[jointactuatorfrc](https://mujoco.readthedocs.io/en/stable/XMLreference.html#sensor-jointactuatorfrc)
+sensor to report the total actuator force acting on a joint. The standard
+[actuatorfrc](https://mujoco.readthedocs.io/en/stable/XMLreference.html#sensor-actuatorfrc)
+sensor will continue to report the pre-clamped actuator force.
+
+Force clamping at tendon input with [tendon/actuatorfrcrange](https://mujoco.readthedocs.io/en/stable/XMLreference.html#tendon-spatial-actuatorfrcrange):
+
+This tendon attribute clamps input forces from all actuators acting on the
+tendon.
+
+The clamping options above are non-exclusive and can be combined as required.
+
+#### Length range[#](#length-range "Link to this heading")
+
+The field `mjModel.actuator_lengthrange` contains the range of feasible actuator
+lengths (or more precisely, lengths of the actuator’s transmission). This is
+needed to simulate [muscle actuators](#cmuscle) . Here we focus on what
+actuator\_lengthrange means and how to set it.
+
+Unlike all other fields of mjModel which are exact physical or geometric
+quantities, actuator\_lengthrange is an approximation. Intuitively it
+corresponds to the minimum and maximum length that the actuator’s transmission
+can reach over all “feasible” configurations of the model. However MuJoCo
+constraints are soft, so in principle any configuration is feasible. Yet we need
+a well-defined range for muscle modeling. There are three ways to set this
+range: (1) provide it explicitly using the attribute lengthrange available in
+all actuators; (2) copy it from the limits of the joint or tendon to which the
+actuator is attached; (3) compute it automatically, as explained in the rest of
+this section. There are many options here, controlled with the XML element
+[lengthrange](https://mujoco.readthedocs.io/en/stable/XMLreference.html#compiler-lengthrange)
+.
+
+Automatic computation of actuator length ranges is done at compile time, and the
+results are stored in mjModel.actuator\_lengthrange of the compiled model. If
+the model is then saved (either as XML or MJB), the computation does not need to
+be repeated at the next load. This is important because the computation can slow
+down the model compiler with large musculo-skeletal models. Indeed we have made
+the compiler multi-threaded just to speed up this operation (different actuators
+are processed in parallel in different threads).
+
+Automatic computation relies on modified physics simulation. For each actuator
+we apply force (negative when computing the minimum, positive when computing the
+maximum) through the actuator’s transmission, advance the simulation in a damped
+regime avoiding instabilities, give it enough time to settle and record the
+result. This is related to gradient descent with momentum, and indeed we have
+experimented with explicit gradient-based optimization, but the problem is that
+it is not clear what objective we should be optimizing (given the mix of soft
+constraints). By using simulation, we are essentially letting the physics tell
+us what to optimize. Keep in mind though that this is still an optimization
+process, and as such it has parameters that may need to be adjusted. We provide
+conservative defaults which should work with most models, but if they don’t, use
+the attributes of
+[lengthrange](https://mujoco.readthedocs.io/en/stable/XMLreference.html#compiler-lengthrange)
+for fine-tuning.
+
+It is important to keep in mind the geometry of the model when using this
+feature. The implicit assumption here is that feasible actuator lengths are
+indeed limited. Furthermore we do not consider contacts as limiting factors (in
+fact we disable contacts internally in this simulation, together with passive
+forces, gravity, friction loss and actuator forces). This is because models with
+contacts can tangle up and produce many local minima. So the actuator should be
+limited either because of joint or tendon limits defined in the model (which are
+enabled during this simulation) or due to geometry. To illustrate the latter,
+consider a tendon with one end attached to the world and the other end attached
+to an object spinning around a hinge joint attached to the world. In this case
+the minimum and maximum length of the tendon are well-defined and depend on the
+size of the circle that the attachment point traces in space, even though
+neither the joint nor the tendon have limits defined by the user. But if the
+actuator is attached to the joint, or to a fixed tendon equal to the joint, then
+it is unlimited. The compiler will return an error in this case, but it cannot
+tell if the error is due to lack of convergence or because the actuator length
+is unlimited. All of this sounds overly complicated, and it is in the sense that
+we are considering all possible corner cases here. In practice length ranges
+will almost always be used with muscle actuators attached to spatial tendons,
+and there will be joint limits defined in the model, effectively limiting the
+lengths of the muscle actuators. If you get a convergence error in such a model,
+the most likely explanation is that you forgot to include joint limits.
+
+#### Stateful actuators[#](#stateful-actuators "Link to this heading")
+
+As described in the
+[Actuation model](https://mujoco.readthedocs.io/en/stable/computation/index.html#geactuation)
+section of the Computation chapter, MuJoCo supports actuators with internal
+dynamics whose states are called “activations”.
+
+##### Activation limits[#](#activation-limits "Link to this heading")
+
+One useful application of stateful actuators is the “integrated-velocity”
+actuator, implemented by the
+[intvelocity](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-intvelocity)
+shortcut. Different from the
+[pure velocity](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-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 setpoint of the position actuator”, and the semantics of the control
+signal are “the velocity of the setpoint 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).
+
+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:
+
+Example model with activation limits
+
+<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"
+      biasprm="0 -1" dyntype="integrator"/>
+   <intvelocity name="clamped" joint="joint2" actrange="-1.57 1.57"/>
+</actuator>
+</mujoco>
+
+Note that the actrange attribute is always specified in native units (radians),
+even though the joint range can be either in degrees (the default) or radians,
+depending on the
+[compiler/angle](https://mujoco.readthedocs.io/en/stable/XMLreference.html#compiler)
+attribute.
+
+##### Muscles[#](#muscles "Link to this heading")
+
+We provide a set of tools for modeling biological muscles. Users who want to add
+muscles with minimum effort can do so with a single line of XML in the actuator
+section:
+
+<actuator>
+    <muscle name="mymuscle" tendon="mytendon"\>
+</actuator>
+
+Biological muscles look very different from each other, yet behave in remarkably
+similar ways once certain scaling is applied. Our default settings apply such
+scaling, which is why one can obtain a reasonable muscle model without adjusting
+any parameters. Constructing a more detailed model will of course require
+parameter adjustment, as explained in this section.
+
+Keep in mind that even though the muscle model is quite elaborate, it is still a
+type of MuJoCo actuator and obeys the same conventions as all other actuators. A
+muscle can be defined using
+[general](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-general)
+, but the shortcut
+[muscle](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-muscle)
+is more convenient. As with all other actuators, the force production mechanism
+and the transmission are defined independently. Nevertheless, muscles only make
+(bio)physical sense when attached to tendon or joint transmissions. For
+concreteness we will assume a tendon transmission here.
+
+First we discuss length and length scaling. The range of feasible lengths of the
+transmission (i.e., MuJoCo tendon) will play an important role; see
+[Length range](#clengthrange) section above. In biomechanics, a muscle and a
+tendon are attached in series and form a muscle-tendon actuator. Our convention
+is somewhat different: in MuJoCo the entity that has spatial properties (in
+particular length and velocity) is the tendon, while the muscle is an abstract
+force- generating mechanism that pulls on the tendon. Thus the tendon length in
+MuJoCo corresponds to the muscle+tendon length in biomechanics. We assume that
+the biological tendon is inelastic, with constant length LTL\_T, while the
+biological muscle length LML\_M varies over time. The MuJoCo tendon length is
+the sum of the biological muscle and tendon lengths:
+
+actuator\_length\=LT+LM\\texttt{actuator\\\_length} = L\_T + L\_M
+
+Another important constant is the optimal resting length of the muscle, denoted
+L0L\_0. It equals the length LML\_M at which the muscle generates maximum active
+force at zero velocity. We do not ask the user to specify L0L\_0 and LTL\_T
+directly, because it is difficult to know their numeric values given the spatial
+complexity of the tendon routing and wrapping. Instead we compute L0L\_0 and
+LTL\_T automatically as follows. The length range computation described above
+already provided the operating range for LT+LML\_T+L\_M. In addition, we ask the
+user to specify the operating range for the muscle length LML\_M scaled by the
+(still unknown) constant L0L\_0. This is done with the attribute range; the
+default scaled range is (0.75,1.05)(0.75, 1.05). Now we can compute the two
+constants, using the fact that the actual and scaled ranges have to map to each
+other:
+
+(actuator\_lengthrange\[0\]−LT)/L0\=range\[0\](actuator\_lengthrange\[1\]−LT)/L0\=range\[1\]\\begin{aligned}
+(\\texttt{actuator\\\_lengthrange\[0\]} - L\_T) / L\_0 &= \\texttt{range\[0\]}
+\\\\ (\\texttt{actuator\\\_lengthrange\[1\]} - L\_T) / L\_0 &=
+\\texttt{range\[1\]} \\\\ \\end{aligned}
+
+At runtime, we compute the scaled muscle length and velocity as:
+
+L\=(actuator\_length−LT)/L0V\=actuator\_velocity/L0\\begin{aligned} L &=
+(\\texttt{actuator\\\_length} - L\_T) / L\_0 \\\\ V &=
+\\texttt{actuator\\\_velocity} / L\_0 \\\\ \\end{aligned}
+
+The advantage of the scaled quantities is that all muscles behave similarly in
+that representation. The behavior is captured by the Force-Length-Velocity
+(FLV\\text{\\small FLV}) function measured in many experimental papers. We
+approximate this function as follows:
+
+ [![\_images/musclemodel.png](https://mujoco.readthedocs.io/en/stable/_images/musclemodel.png)](https://mujoco.readthedocs.io/en/stable/_images/musclemodel.png)[![\_images/musclemodel\_dark.png](https://mujoco.readthedocs.io/en/stable/_images/musclemodel_dark.png)](https://mujoco.readthedocs.io/en/stable/_images/musclemodel_dark.png)
+
+The function is in the form:
+
+FLV(L,V,act)\=FL(L)⋅FV(V)⋅act+FP(L)\\text{\\small FLV}(L, V, \\texttt{act}) =
+F\_L(L)\\cdot F\_V(V)\\cdot \\texttt{act} + F\_P(L)
+
+Comparing to the general form of a MuJoCo actuator, we see that FL⋅FVF\_L\\cdot
+F\_V is the actuator gain and FPF\_P is the actuator bias. FLF\_L is the active
+force as a function of length, while FVF\_V is the active force as a function of
+velocity. They are multiplied to obtain the overall active force (note the
+scaling by act which is the actuator activation). FPF\_P is the passive force
+which is always present regardless of activation. The output of the
+FLV\\text{\\small FLV} function is the scaled muscle force. We multiply the
+scaled force by a muscle-specific constant F0F\_0 to obtain the actual force:
+
+actuator\_force\=−FLV(L,V,act)⋅F0\\texttt{actuator\\\_force} = -\\text{\\small
+FLV}(L, V, \\texttt{act}) \\cdot F\_0
+
+The negative sign is because positive muscle activation generates pulling force.
+The constant F0F\_0 is the peak active force at zero velocity. It is related to
+the muscle thickness (i.e., physiological cross-sectional area or PCSA). If
+known, it can be set with the attribute force of element
+[muscle](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-muscle)
+. If it is not known, we set it to −1\-1 which is the default. In that case we
+rely on the fact that larger muscles tend to act on joints that move more
+weight. The attribute scale defines this relationship as:
+
+F0\=scale/actuator\_acc0F\_0 = \\text{scale} / \\texttt{actuator\\\_acc0}
+
+The quantity actuator\_acc0\\texttt{actuator\\\_acc0} is precomputed by the
+model compiler. It is the norm of the joint acceleration caused by unit force
+acting on the actuator transmission. Intuitively, scale\\text{scale} determines
+how strong the muscle is “on average” while its actual strength depends on the
+geometric and inertial properties of the entire model.
+
+Thus far we encountered three constants that define the properties of an
+individual muscle: LT,L0,F0L\_T, L\_0, F\_0. In addition, the function
+FLV\\text{\\small FLV} itself has several parameters illustrated in the above
+figure: lmin,lmax,vmax,fpmax,fvmaxl\_\\text{min}, l\_\\text{max},
+v\_\\text{max}, f\_\\text{pmax}, f\_\\text{vmax}. These are supposed to be the
+same for all muscles, however different experimental papers suggest different
+shapes of the FLV function, thus users familiar with that literature may want to
+adjust them. We provide the MATLAB function
+[FLV.m](https://mujoco.readthedocs.io/en/stable/_static/FLV.m) which was used to
+generate the above figure and shows how we compute the FLV\\text{\\small FLV}
+function.
+
+Before embarking on a mission to design more accurate FLV\\text{\\small FLV}
+functions, consider the fact that the operating range of the muscle has a bigger
+effect than the shape of the FLV\\text{\\small FLV} function, and in many cases
+this parameter is unknown. Below is a graphical illustration:
+
+ [![\_images/musclerange.png](https://mujoco.readthedocs.io/en/stable/_images/musclerange.png)](https://mujoco.readthedocs.io/en/stable/_images/musclerange.png)[![\_images/musclerange\_dark.png](https://mujoco.readthedocs.io/en/stable/_images/musclerange_dark.png)](https://mujoco.readthedocs.io/en/stable/_images/musclerange_dark.png)
+
+This figure format is common in the biomechanics literature, showing the
+operating range of each muscle superimposed on the normalized FL\\text{FL} curve
+(ignore the vertical displacement). Our default range is shown in black. The
+blue curves are experimental data for two arm muscles. One can find muscles with
+small range, large range, range spanning the ascending portion of the
+FL\\text{FL} curve, or the descending portion, or some of both. Now suppose you
+have a model with 50 muscles. Do you believe that someone did careful
+experiments and measured the operating range for every muscle in your model,
+taking into account all the joints that the muscle spans? If not, then it is
+better to think of musculo-skeletal models as having the same general behavior
+as the biological system, while being different in various details – including
+details that are of great interest to some research community. For most muscle
+properties which modelers consider constant and known, there is an experimental
+paper showing that they vary under some conditions. This is not to discourage
+people from building accurate models, but rather to discourage people from
+believing too strongly in their models.
+
+Coming back to our muscle model, there is the muscle activation `act` . This is
+the state of a first-order nonlinear filter whose input is the control signal.
+The filter dynamics are:
+
+∂∂tact\=ctrl−actτ(ctrl,act)\\frac{\\partial}{\\partial t}\\texttt{act} =
+\\frac{\\texttt{ctrl} - \\texttt{act}}{\\tau(\\texttt{ctrl}, \\texttt{act})}
+
+Internally the control signal is clamped to \[0, 1\] even if the actuator does
+not have a control range specified. There are two time constants specified with
+the attribute timeconst, namely timeconst\=(τact,τdeact)\\text{timeconst} =
+(\\tau\_\\text{act}, \\tau\_\\text{deact}) with defaults (0.01,0.04)(0.01,
+0.04). Following [Millard et al. (2013)](https://doi.org/10.1115/1.4023390) ,
+the effective time constant τ\\tau is then computed at runtime as:
+
+τ(ctrl,act)\={τact⋅(0.5+1.5⋅act)ctrl−act\>0τdeact/(0.5+1.5⋅act)ctrl−act≤0\\tau(\\texttt{ctrl},
+\\texttt{act}) = \\begin{cases} \\tau\_\\text{act} \\cdot (0.5 +
+1.5\\cdot\\texttt{act}) & \\texttt{ctrl}-\\texttt{act} \\gt 0 \\\\
+\\tau\_\\text{deact} / (0.5 + 1.5\\cdot\\texttt{act}) & \\texttt{ctrl} -
+\\texttt{act} \\leq 0 \\end{cases}
+
+Since the above equation describes discontinuous switching, which can be
+undesirable when using derivative-based optimization, we introduce the optional
+smoothing parameter
+[tausmooth](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-muscle-tausmooth)
+. When greater than 0, the switching is replaced by
+[mju\_sigmoid](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mju-sigmoid)
+, which will smoothly interpolate between the two values within the range
+(ctrl−act)±tausmooth/2(\\texttt{ctrl}-\\texttt{act}) \\pm \\text{tausmooth}/2.
+
+Now we summarize the attributes of element
+[muscle](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-muscle)
+which users may want to adjust, depending on their familiarity with the
+biomechanics literature and availability of detailed measurements with regard to
+a particular model:
+
+Defaults
+
+Use the built-in defaults everywhere. All you have to do is attach a muscle to a
+tendon, as shown at the beginning of this section. This yields a generic yet
+reasonable model.
+
+scale
+
+If you do not know the strength of individual muscles but want to make all
+muscles stronger or weaker, adjust scale. This can be adjusted separately for
+each muscle, but it makes more sense to set it once in the
+[default](https://mujoco.readthedocs.io/en/stable/XMLreference.html#default)
+element.
+
+force
+
+If you know the peak active force F0F\_0 of the individual muscles, enter it
+here. Many experimental papers contain this data.
+
+range
+
+The operating range of the muscle in scaled lengths is also available in some
+papers. It is not clear how reliable such measurements are (given that muscles
+act on many joints) but they do exist. Note that the range differs substantially
+between muscles.
+
+timeconst
+
+Muscles are composed of slow-twitch and fast-twitch fibers. The typical muscle
+is mixed, but some muscles have a higher proportion of one or the other fiber
+type, making them faster or slower. This can be modeled by adjusting the time
+constants. The vmax parameter of the FLV\\text{\\small FLV} function should also
+be adjusted accordingly.
+
+tausmooth
+
+When positive, smooths the transition between activation and de-activation
+time-constants. While a single
+[motor unit](https://en.wikipedia.org/wiki/Motor_unit) is either activating or
+de-activating, an entire muscle will have a mixture of many units, leading to a
+corresponding mixture of timescales.
+
+lmin, lmax, vmax, fpmax, fvmax
+
+These are the parameters controlling the shape of the FLV\\text{\\small FLV}
+function. Advanced users can experiment with them; see MATLAB function
+[FLV.m](https://mujoco.readthedocs.io/en/stable/_static/FLV.m) . Similar to the
+scale setting, if you want to change the FLV\\text{\\small FLV} parameters for
+all muscles, do so in the
+[default](https://mujoco.readthedocs.io/en/stable/XMLreference.html#default)
+element.
+
+Custom model
+
+Instead of adjusting the parameters of our muscle model, users can implement a
+different model, by setting gaintype, biastype and dyntype of a
+[general](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-general)
+actuator to “user” and providing callbacks at runtime. Or, leave some of these
+types set to “muscle” and use our model, while replacing the other components.
+Note that tendon geometry computations are still handled by the standard MuJoCo
+pipeline providing actuator\_length, actuator\_velocity and
+actuator\_lengthrange as inputs to the user’s muscle model. Custom callbacks
+could then simulate elastic tendons or any other detail we have chosen to omit.
+
+**Relation to OpenSim**
+
+The standard software used by researchers in biomechanics is OpenSim. We have
+designed our muscle model to be similar to the OpenSim model where possible,
+while making simplifications which result in significantly faster and more
+stable simulations. To help MuJoCo users convert OpenSim models, here we
+summarize the similarities and differences.
+
+The activation dynamics model is identical to OpenSim, including the default
+time constants.
+
+The FLV\\text{\\small FLV} function is not exactly the same, but both MuJoCo and
+OpenSim approximate the same experimental data, so they are very close. For a
+description of the OpenSim model and summary of relevant experimental data, see
+[Millard et al. (2013)](https://doi.org/10.1115/1.4023390) .
+
+We assume inelastic tendons while OpenSim can model tendon elasticity. We
+decided not to do that here, because tendon elasticity requires fast-equilibrium
+assumptions which in turn require various tweaks and are prone to simulation
+instability. In practice tendons are quite stiff, and their effect can be
+captured approximately by stretching the FL\\text{FL} curve corresponding to the
+inelastic case ([Zajac (1989)](https://pubmed.ncbi.nlm.nih.gov/2676342/)). This
+can be done in MuJoCo by shortening the muscle operating range.
+
+Pennation angle (i.e., the angle between the muscle and the line of force) is
+not modeled in MuJoCo and is assumed to be 0. This effect can be approximated by
+scaling down the muscle force and also adjusting the operating range.
+
+Tendon wrapping is also more limited in MuJoCo. We allow spheres and infinite
+cylinders as wrapping objects, and require two wrapping objects to be separated
+by a fixed site in the tendon path. This is to avoid the need for iterative
+computations of tendon paths. We also allow “side sites” to be placed inside the
+sphere or cylinder, which causes an inverse wrap: the tendon path is constrained
+to pass through the object instead of going around it. This can replace torus
+wrapping objects used in OpenSim to keep the tendon path within a given area.
+Overall, tendon wrapping is the most challenging part of converting an OpenSim
+model to a MuJoCo model, and requires some manual work. On the bright side,
+there is a small number of high-quality OpenSim models in use, so once they are
+converted we are done.
+
+Below we illustrate the four types of tendon wrapping available. Note that the
+curved sections of the wrapping tendons are rendered as straight, but the
+geometry pipeline works with the actual curves and computes their lengths and
+moments analytically:
+
+[![image3](https://mujoco.readthedocs.io/en/stable/_images/tendonwraps.png)
+](https://mujoco.readthedocs.io/en/stable/_images/tendonwraps.png)
+
+### Sensors[#](#sensors "Link to this heading")
+
+MuJoCo can simulate a wide variety of sensors as described in the
+[sensor](https://mujoco.readthedocs.io/en/stable/XMLreference.html#sensor)
+element below. User sensor types can also be defined, and are evaluated by the
+callback
+[mjcb\_sensor](https://mujoco.readthedocs.io/en/stable/APIreference/APIglobals.html#mjcb-sensor)
+. Sensors do not affect the simulation. Instead their outputs are copied in the
+array mjData.sensordata and are available for user processing.
+
+Here we describe the XML attributes common to all sensor types, so as to avoid
+repetition later.
+
+name: string, optional
+
+Name of the sensor.
+
+noise: real, “0”
+
+The standard deviation of the noise model of this sensor. This attribute does
+not affect the simulation; it serves as a convenient location for storing
+standard deviation information for later use.
+
+cutoff: real, “0”
+
+When this value is positive, it limits the absolute value of the sensor output.
+It is also used to normalize the sensor data plots in
+[simulate.cc](https://mujoco.readthedocs.io/en/stable/programming/samples.html#sasimulate)
+. Note that cutoff has a different meaning for
+[collision sensors](https://mujoco.readthedocs.io/en/stable/XMLreference.html#collision-sensors)
+.
+
+nsample: int, “0”
+
+If nsample is greater than 0, creates a time-indexed ring buffer with nsample
+slots of sensor data. During state advancement, the current sensor data is
+appended to the buffer with timestamp `time` , and the oldest sample is removed.
+Values in the history buffer can be read via
+[mj\_readSensor](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-readsensor)
+. A positive nsample is required for both [delay](#sensor-delay) and
+[interval](#sensor-interval) features.
+
+See [Delays](#cdelay) for details.
+
+interp: \[zoh, linear, cubic\], “zoh”
+
+The interpolation method used when reading from the history buffer. Corresponds
+to the `interp` argument in
+[mj\_readSensor](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-readsensor)
+.
+
+*   `zoh` : Zero-order hold (piecewise constant).
+    
+*   `linear` : Piecewise linear interpolation.
+    
+*   `cubic` : Cubic spline interpolation (Catmull-Rom).
+    
+
+The interp value is for advanced use-cases, see [Delays](#cdelay) for details.
+
+delay: real, “0”
+
+If greater than 0, sensor values in `mjData.sensordata` are read from the
+history buffer at `time - delay` rather than computed directly. Requires
+positive [nsample](#sensor-nsample) , cannot be negative.
+
+In the most common case, `delay = nsample * timestep` , see [Delays](#cdelay)
+for details.
+
+interval: real, “0 0”
+
+This attribute controls how often sensor values are recomputed. It is useful for
+modeling sensors that have a larger sampling period than the simulation
+timestep. Requires a history buffer ([nsample](#sensor-nsample) > 0).
+
+This attribute is defined by two real-valued numbers, both in units of time,
+called interval = “period phase”. It is possible to only specify the period, in
+which case the phase is assumed to be 0.
+
+The period specifies the interval period between recomputations. The default
+value of 0 has the special meaning “every simulation timestep”. Note that the
+period is not required to be an integer multiple of the timestep. For example,
+if the simulation timestep is 1.0, and period is 2.5, the sensor will be
+computed at times 0.0, 3.0, 5.0, 8.0, 10.0, 13.0, … with the actual interval
+alternating between 2 and 3 timesteps. period cannot be negative. Note that only
+`period > timestep` values make sense; values smaller than or equal to the
+timestep will not lead to an error but merely cause the sensor to be recomputed
+at every timestep.
+
+The phase only takes effect during history buffer initialization in
+[mj\_resetData](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-resetdata)
+. It specifies the last time that the sensor was computed “before the simulation
+started” in continuous time (i.e., disregarding the quantization of timesteps).
+It is useful for precisely controlling the _relative phase_ of sensor
+computation and simulation time, when interval is used. The default value of 0
+has the special meaning “\-period”, i.e. specifying that the sensor should be
+computed at the first timestep of the simulation. Continuing our example from
+earlier, if the timestep is 1.0 and interval is “2.5 -1.5”, the sensor will be
+computed at times 1.0, 4.0, 6.0, 9.0, 11.0, 14.0, etc. phase must be in the
+range (−period,0\](-\\text{period}, 0\].
+
+user: real(nuser\_sensor), “0 0 …”
+
+See [User parameters](#cuser) .
+
+### Delays[#](#delays "Link to this heading")
+
+Both actuators and sensors support time delays via a ring buffer that stores
+timestamped samples. When the integer attribute nsample
+([actuators](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-general-nsample),
+[sensors](#sensor-nsample) ) is positive, a buffer with nsample slots is
+included in the
+[physics state](https://mujoco.readthedocs.io/en/stable/programming/simulation.html#siphysicsstate)
+component `mjData.history` and the samples and current timestamps are written
+into the buffer upon state advancement.
+
+If additionally the real-valued delay attribute
+([actuators](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-general-delay),
+[sensors](#sensor-delay) ) is positive, then during the forward dynamics the
+control or sensor values are read from the history buffer (instead of being read
+from `ctrl` or recomputed, respectively). Positive delay requires positive
+nsample.
+
+Note that since reading happens before writing, the minimum positive delay is
+effectively one timestep, despite delay being real-valued.
+
+Delayed reading in the engine is triggered by positive delay, and performed by
+the API functions
+[mj\_readCtrl](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-readctrl)
+and
+[mj\_readSensor](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-readsensor)
+, which read from the buffer at `time - delay` , effectively implementing the
+requested delay. These functions take `time` as an argument and can be used
+whenever nsample is positive, allowing the user to inspect the contents of the
+history buffer at any time, including in a “history-only” mode (nsample > 0,
+delay = 0), where past values are accessible via the API but the simulation is
+unaffected.
+
+**Sensor Modes**
+
+Sensors support both [delay](#sensor-delay) and
+[interval/period](#sensor-interval) attributes. The combination determines
+behavior:
+
+  
+
+delay
+
+period
+
+Write / Read behavior
+
+\= 0
+
+\= 0
+
+History-only: computed every step, written to `sensordata` , pushed into history
+buffer
+
+\> 0
+
+\= 0
+
+Delayed: computed every step, `sensordata` contains delayed reading (read from
+buffer)
+
+\= 0
+
+\> 0
+
+Periodic: computed on period, `sensordata` contains last computed value (no
+delay)
+
+\> 0
+
+\> 0
+
+Periodic + Delayed: computed on period, `sensordata` contains delayed reading
+(read from buffer)
+
+**Initialization**
+
+History buffers are initialized by
+[mj\_resetData](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-resetdata)
+as follows:
+
+*   **Values**: Always initialized to zero. For custom initialization after reset,
+    call
+    [mj\_initCtrlHistory](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-initctrlhistory)
+    and
+    [mj\_initSensorHistory](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-initsensorhistory)
+    .
+    
+*   **Actuator timestamps**: `[..., -2*dt, -dt]` .
+    
+*   **Sensor timestamps** without [interval](#sensor-interval) : `[..., -2*dt, -dt]`
+    .
+    
+*   **Sensor timestamps** with [interval](#sensor-interval) : Samples are spaced at
+    `period` intervals rather than `dt` . The continuous-time timestamps
+    `[..., phase-2*period, phase-period, phase]` are rounded up to the nearest
+    multiple of `dt` , since that is when samples could have been computed. If
+    `phase = 0` (the default), it is interpreted as `-period` , meaning the first
+    sample will be computed at `t = 0` .
+    
+
+**Causality and interpolation**
+
+The most common positive delay value is `delay = timestep * nsample` , which
+implements a simple history buffer, with no causality issues.
+
+Warning
+
+If `delay > timestep * nsample` , then data will be read before the earliest
+buffer bound, resulting in non-causal extrapolation: using a value from before
+it was actually recorded. This scenario will not lead to a runtime error, so it
+is up to the user to avoid it.
+
+Setting `delay < timestep * nsample` is not problematic and can be useful for
+system identification and stochastic delays. In these use cases, one should
+choose a maximum possible `delay_max` and set
+`nsample = ceil(delay_max / timestep)` . Then at run-time or sysID-time, the
+[mjModel](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjmodel)
+fields `actuator_delay` or `sensor_delay` can be safely modified, so long as
+`delay_max` is not exceeded.
+
+ [![\_images/delay\_buffer\_light.svg](https://mujoco.readthedocs.io/en/stable/_images/delay_buffer_light.svg)](https://mujoco.readthedocs.io/en/stable/_images/delay_buffer_light.svg)[![\_images/delay\_buffer\_dark.svg](https://mujoco.readthedocs.io/en/stable/_images/delay_buffer_dark.svg)](https://mujoco.readthedocs.io/en/stable/_images/delay_buffer_dark.svg)
+
+These two use cases are the reason for including the interp attribute
+([actuators](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-general-interp),
+[sensors](#sensor-interp) ). While real-world exogenous delays are generally a
+zero-order-hold phenomenon, this implies discontinuity: a small change in the
+delay has no effect, until the timestep threshold is crossed. For example with
+`dt = 0.1` and `nsample = 2` , there is no functional difference between
+`delay = 0.2` and `delay = 0.101` (both read from the oldest sample), but
+stepping from `delay = 0.101` to `delay = 0.1` crosses a threshold and changes
+behavior. By allowing higher order interpolation, the effect of delays becomes
+continuous (`interp = linear`) and differentiable (`interp = cubic`).
+
+Note that interpolation does not makes sense for some types of sensors, for
+example sensors that report integer values (e.g.
+[insidesite](https://mujoco.readthedocs.io/en/stable/XMLreference.html#sensor-insidesite)
+).
+
+### Cameras[#](#cameras "Link to this heading")
+
+Besides the default, user-controllable, free camera, “fixed” cameras can be
+attached to the kinematic tree.
+
+Extrinsics
+
+By default, camera frames are attached to the containing body. The optional
+[mode](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-mode)
+and
+[target](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-target)
+attributes can be used to specify cameras that track (move with) or target (look
+at) a body or subtree. Cameras look towards the negative Z axis of the camera
+frame, while positive X and Y correspond to _right_ and _up_ in the image plane,
+respectively.
+
+Projection
+
+Cameras use
+[perspective](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-projection)
+projection by default. Setting
+[projection](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-projection)
+to `orthographic` switches to an orthographic projection, where the
+[fovy](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-fovy)
+attribute is interpreted as the vertical extent in length units rather than
+degrees.
+
+Intrinsics
+
+Camera intrinsics are specified using
+[ipd](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-ipd)
+(inter-pupilary distance, required for stereoscopic rendering and VR) and
+[fovy](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-fovy)
+(vertical field of view, in degrees).
+
+The above specification implies a perfect point camera with no aberrations.
+However when calibrating real cameras, two types of linear aberration can be
+expressed using standard rendering pipelines. The first is different focal
+lengths in the vertical and horizontal directions (axis-aligned astigmatism).
+The second is a non-centered principal point. These can be specified using the
+[focal](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-focal)
+and
+[principal](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-principal)
+attributes. When these calibration-related attributes are used, the physical
+[sensor size](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-sensorsize)
+and camera
+[resolution](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera-resolution)
+must also be specified. In this case, the rendering frustum can be visualized.
+
+### Composite objects[#](#composite-objects "Link to this heading")
+
+Composite objects are collections of existing elements originally designed to
+simulate particle systems, ropes, cloth, and soft bodies. Over time, most of
+these types have been replaced by
+[replicate](https://mujoco.readthedocs.io/en/stable/XMLreference.html#replicate)
+(for repeated objects) and
+[flexcomp](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-flexcomp)
+(for soft objects). Therefore, the only supported composite type is now `cable`
+, which produces an inextensible chain of bodies connected with ball joints.
+
+Composite objects are made up of regular MuJoCo bodies, which we call “element
+bodies” in this context. The collection of element bodies is generated by the
+model compiler automatically. The user configures the automatic generator on a
+high level, using the XML element
+[composite](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-composite)
+and its attributes and sub-elements, as described in the XML reference chapter.
+If the compiled model is then saved, composite is no longer present and is
+replaced with the collection of regular model elements that were automatically
+generated. So think of it as a macro that gets expanded by the model compiler.
+The element bodies are created as children of the body within which composite
+appears; thus a composite object appears in the same place in the XML where a
+regular child body may have been defined. Each automatically-generated element
+body has a single geom attached to it. We have designed the composite object
+generator to have intuitive high-level controls as much as possible, but at the
+same time it exposes a large number of options that interact with each other and
+can profoundly affect the resulting physics. So at some point users should read
+the
+[reference documentation](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-composite)
+carefully.
+
+In addition to setting up the physics, the composite object generator creates
+suitable rendering. Objects can be rendered as
+[skins](https://mujoco.readthedocs.io/en/stable/XMLreference.html#asset-skin) .
+The skin is generated automatically, and can be textured as well as subdivided
+using bi-cubic interpolation. The actual physics and in particular the collision
+detection are based on the element bodies and their geoms, while the skin is
+purely a visualization object. Yet in some situations we prefer to look at the
+skin representation, as in
+[this model](https://github.com/google-deepmind/mujoco/blob/main/model/plugin/elasticity/belt.xml)
+, whose skin is a continuous flexible surface and not a collection of
+discontinuous thin boxes. However when fine-tuning the model and trying to
+understand the physics behind it, it is useful to be able to render the geoms.
+To switch the rendering style, disable the rendering of skins and enable group 3
+for geoms and tendons.
+
+**Cable**.
+
+As a quick start, MuJoCo comes with an example of composite cables. In all
+examples we have a static scene which is included in the model, followed by a
+single composite object. The XML snippets below are just the definition of the
+composite object; see the XML model files in the distribution for the complete
+examples.
+
+[![coil](https://mujoco.readthedocs.io/en/stable/_images/coil.png)
+](https://mujoco.readthedocs.io/en/stable/_images/coil.png)
+
+<extension>
+   <plugin plugin="mujoco.elasticity.cable"/>
+</extension>
+
+<worldbody>
+   <composite prefix="actuated" type="cable" curve="cos(s) sin(s) s" count="41 1 1"
+              size="0.25 .1 4" offset="0.25 0 .05" initial="none"\>
+      <plugin plugin="mujoco.elasticity.cable"\>
+         <!--Units are in Pa (SI)-->
+         <config key="twist" value="5e8"/>
+         <config key="bend" value="15e8"/>
+         <config key="vmax" value="0"/>
+      </plugin>
+      <joint kind="main" damping="0.15" armature="0.01"/>
+      <geom type="capsule" size=".005" rgba=".8 .2 .1 1"/>
+   </composite>
+</worldbody>
+
+The cable simulates an inextensible elastic 1D object having twist and bending
+stiffness. It is discretized using a sequence of capsules or boxes. Its
+stiffness and inertia properties are computed directly from the given parameters
+and the shape of the cross section, which allows for anisotropic behaviors,
+which can be found in e.g. belts or computer cables. It is a single kinematic
+tree, so it is exactly inextensible without the use of additional constraints,
+enabling the use of large time steps. The elastic model is geometrically exact
+and based on computing the Bishop or twist-free frame of the centerline, i.e.,
+the line passing through the center of the cross section. The orientations of
+the geoms are expressed with respect to this frame and then decomposed into
+twist and bending components, hence different stiffnesses can be set
+independently. Moreover, it is possible to specify if the stress-free
+configuration is flat or curve, such as in the case of coil springs. The cable
+requires using a first-party
+[engine plugin](https://mujoco.readthedocs.io/en/stable/programming/extension.html#explugin)
+, which may be integrated directly into the engine in the future.
+
+**Deprecated types**.
+
+All composite types other than `cable` have been deprecated or removed. Use
+[replicate](https://mujoco.readthedocs.io/en/stable/XMLreference.html#replicate)
+for repeated objects (e.g., particle systems) and [flex](#cdeformable)
+deformable objects for soft bodies (ropes, cloth, volumetric solids).
+
+### Deformable objects[#](#deformable-objects "Link to this heading")
+
+The [composite objects](#ccomposite) described earlier were intended to emulate
+soft bodies in what is effectively a rigid-body simulator. This was possible
+because MuJoCo constraints are soft, but nevertheless it was limited in
+functionality and modeling power. In MuJoCo 3.0 we have introduced true
+deformable objects involving new model elements. The
+[skin](https://mujoco.readthedocs.io/en/stable/XMLreference.html#deformable-skin)
+described earlier was actually one such element, but it is merely used for
+visualization. We now have a related element
+[flex](https://mujoco.readthedocs.io/en/stable/XMLreference.html#deformable-flex)
+which generates contact forces, constraint forces and passive forces as needed
+to model a wide range of deformable entities. Both skins and flexes are now
+defined within a new grouping element in the XML called
+[deformable](https://mujoco.readthedocs.io/en/stable/XMLreference.html#deformable)
+. A flex is a low-level element that specifies everything needed at runtime, but
+is difficult to design at modeling time. To aid with modeling, we have further
+introduced the element
+[flexcomp](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-flexcomp)
+which automates the creation of the low-level flex, similar to how
+[composite](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-composite)
+automates the creation of (collections of) MuJoCo objects needed to emulate a
+soft body. Flexes may eventually supersede composites, but for now both are
+useful for somewhat different purposes.
+
+A flex is a collection of MuJoCo bodies that are connected with massless
+stretchable elements. These elements can be capsules (1D flex), triangles (2D
+flex), or tetrahedra (3D flex). In all cases we allow a radius, which makes the
+elements smooth and also volumetric in 1D and 2D. The primitive elements are
+illustrated below:
+
+[![\_images/flexelem.png](https://mujoco.readthedocs.io/en/stable/_images/flexelem.png)](https://mujoco.readthedocs.io/en/stable/_images/flexelem.png)
+
+Thus far these look like geoms. But the key difference is that they deform: as
+the bodies (vertices) move independently of each other, the shape of the
+elements changes in real time. Collisions and contact forces are now generalized
+to handle these deformable geometric elements. Note that when two such elements
+collide, the contact no longer involves just two bodies, but can involve up to 8
+bodies (if both elements are tetrahedra). Contact forces are computed as before,
+given the contact frame and relevant quantities expressed in that frame. But
+then the contact force is distributed among all interacting bodies. The notion
+of contact Jacobian is complicated because the contact point cannot be
+considered fixed in any body frame. Instead we use a weighting scheme to
+“assign” each contact point to multiple bodies. It is also possible to create a
+rigid flex, by assigning all vertices to the same body. This is a way to
+re-purpose the new flex collision machinery to implement rigid non-convex mesh
+collisions (unlike mesh geoms which are convexified for collision purposes).
+
+**Deformation model**.
+
+In order to preserve the shape of the flex (in a soft sense), we need to
+generate passive or constraint forces. Prior to MuJoCo 3.0 this would involve a
+large number of tendons plus constraints on tendons and joints. This is still
+possible here, but inefficient both in terms of modeling and in terms of
+simulation when the flex is large. Instead, the design philosophy is to use a
+single set of parameters and provide two modeling choices: a new (soft) equality
+constraint type that applies to all edges of a given flex, which permits large
+time steps, or a discretized continuum representation, where each element is in
+a constant stress state, which is equivalent to piecewise linear finite elements
+and achieves improved realism and accuracy. The edge-based model could be seen
+as a “lumped” stiffness model, where the correct coupling of deformation modes
+(e.g. shear and volumetric) is averaged in a single quantity. The continuum
+model enables instead to specify shear and volumetric stiffnesses separately
+using the [Poisson’s ratio](https://en.wikipedia.org/wiki/Poisson%27s_ratio) of
+the material. For more details, see the
+[Saint Venant-Kirchhoff](https://en.wikipedia.org/wiki/Hyperelastic_material#Saint_Venant%E2%80%93Kirchhoff_model)
+hyperelastic model.
+
+**Parametrization types**.
+
+While the default behavior of flexcomp produces a “full” flex where every node
+corresponds to a MuJoCo body, it also supports specialized
+[parametrizations](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-flexcomp-dof)
+for volumetric objects: **trilinear** and **quadratic**. Instead of directly
+simulating all nodes, these options define a background grid of cells. The
+positions of the interior vertices are computed by interpolating the positions
+of the cell corners. Trilinear flexes use 8-node hexahedral cells with linear
+interpolation along each axis, while quadratic flexes use 27-node cells with
+quadratic interpolation, allowing for curved deformation modes. These grid-based
+parametrizations require fewer degrees of freedom than full flexes and can
+result in significantly faster simulation times, especially for large volumetric
+soft bodies.
+
+**Creation and visualization**.
+
+<option timestep=".001"/>
+
+<worldbody>
+   <flexcomp type="grid" count="24 4 4" spacing=".1 .1 .1" pos=".1 0 1.5"
+             radius=".0" rgba="0 .7 .7 1" name="softbody" dim="3" mass="7"\>
+      <contact condim="3" solref="0.01 1" solimp=".95 .99 .0001" selfcollide="none"/>
+      <edge damping="1"/>
+      <elasticity poisson="0.2" young="5e4"\>
+   </flexcomp>
+</worldbody>
+
+Using the
+[flexcomp](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-flexcomp)
+element, we can create flexes from meshes, including tetrahedral meshes, and
+automatically generate all the bodies/vertices and connect them with suitable
+elements. We can also create grids and other topologies automatically. This
+machinery makes it easy to create very large flexes, involving thousands or even
+tens of thousands of bodies, elements and edges. Obviously such simulations will
+not be fast. Even for medium-sized flexes, pruning of collision pairs is
+essential. This is why we have developed elaborate methods for pruning
+self-collisions; see XML reference.
+
+In case of 3D flexes made of tetrahedra, it may be useful to examine how the
+flex is “triangulated” internally. We have a special visualization mode that
+peels off the outer layers. Below is an example with the Stanford Bunny. Note
+how it has smaller tetrahedra on the outside and larger ones on the inside. This
+mesh design makes sense, because we want the collision surface to be accurate,
+but on the inside we just need soft material properties – which require less
+spatial resolution. In order to convert a surface mesh to a tetrahedral mesh, we
+recommend open tools like the
+[fTetWild library](https://github.com/wildmeshing/fTetWild) .
+
+[![bunny1](https://mujoco.readthedocs.io/en/stable/_images/bunny1.png)
+](https://mujoco.readthedocs.io/en/stable/_images/bunny1.png)
+[![bunny2](https://mujoco.readthedocs.io/en/stable/_images/bunny2.png)
+](https://mujoco.readthedocs.io/en/stable/_images/bunny2.png)
+
+### Including files[#](#including-files "Link to this heading")
+
+MJCF files can include other XML files using the
+[include](https://mujoco.readthedocs.io/en/stable/XMLreference.html#include)
+element. Mechanistically, the parser replaces the DOM node corresponding to the
+include element in the master file with the list of XML elements that are
+children of the top-level element in the included file. The top-level element
+itself is discarded, because it is a grouping element for XML purposes and would
+violate the MJCF format if included.
+
+This functionality enables modular MJCF models; see the MPL family of models in
+the model library. One example of modularity is constructing a model of a robot
+(which tends to be elaborate) and then including it in multiple “scenes”, i.e.,
+MJCF models defining the objects in the robot’s environment. Another example is
+creating a file with commonly used assets (say materials with carefully adjusted
+rgba values) and including it in multiple models which reference those assets.
+
+The included files are not required to be valid MJCF files on their own, but
+they usually are. Indeed we have designed this mechanism to allow MJCF models to
+be included in other MJCF models. To make this possible, repeated MJCF sections
+are allowed even when that does not make sense semantically in the context of a
+single model. For example, we allow the kinematic tree to have multiple roots
+(i.e., multiple worldbody elements) which are merged automatically by the
+parser. Otherwise including robots into scenes would be impossible.
+
+The flexibility of repeated MJCF sections comes at a price: global settings that
+apply to the entire model, such as the angle attribute of
+[compiler](https://mujoco.readthedocs.io/en/stable/XMLreference.html#compiler)
+for example, can be defined multiple times. MuJoCo allows this, and uses the
+last definition encountered in the composite model, after all include elements
+have been processed. So if model A is defined in degrees and model B is defined
+in radians, and A is included in B after the compiler element in B, the entire
+composite model will be treated as if it was defined in degrees – leading to
+undesirable consequences in this case. The user has to make sure that models
+included in each other are compatible in this sense; local vs. global
+coordinates is another compatibility requirement.
+
+Finally, as explained next, element names must be unique among all elements of
+the same type. So for example if the same geom name is used in two models, and
+one model is included in the other, this will result in compile error. Including
+the same XML file more than once is a parsing error. The reason for this
+restriction is that we want to avoid repeated element names as well as infinite
+recursion caused by inclusion.
+
+### Naming elements[#](#naming-elements "Link to this heading")
+
+Most model elements in MJCF can have names. They are defined with the attribute
+name of the corresponding XML element. When a given model element is named, its
+name must be unique among all elements of the same type. Names are
+case-sensitive. They are used at compile time to reference the corresponding
+element, and are also saved in mjModel for user convenience at runtime.
+
+The name is usually an optional attribute. We recommend leaving it undefined (so
+as to keep the model file shorter) unless there is a specific reason to define
+it. There can be several such reasons:
+
+*   Some model elements need to reference other elements as part of their creation.
+    For example, a spatial tendon needs to reference sites in order to specify the
+    via points it passes through. Referencing can only be done by name. Note that
+    assets exist for the sole purpose of being referenced, so they must have a name,
+    however it can be omitted and set implicitly from the corresponding file name.
+    
+*   The visualizer offers the option to label all model elements of a given type.
+    When a name is available, it is printed next to the object in the 3D view;
+    otherwise a generic label in the format “body 7” is printed.
+    
+*   The function
+    [mj\_name2id](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-name2id)
+    returns the index of the model element with given type and name. Conversely, the
+    function
+    [mj\_id2name](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html#mj-id2name)
+    returns the name given the index. This is useful for custom computations
+    involving a model element that is identified by its name in the XML (as opposed
+    to relying on a fixed index which can change when the model is edited).
+    
+*   The model file could in principle become more readable by naming certain
+    elements. Keep in mind however that XML itself has a commenting mechanism, and
+    that mechanism is more suitable for achieving readability – especially since
+    most text editors provide syntax highlighting which detects XML comments.
+    
+
+### URDF extensions[#](#urdf-extensions "Link to this heading")
+
+The Unified Robot Description Format (URDF) is a popular XML file format in
+which many existing robots have been modeled. This is why we have implemented
+```
+
+### `log://turn_5/get/https%3A/mujoco.readthedocs.io/en/stable/programming/simulation.html`
+scheme=log action=get attrs={"path":"https://mujoco.readthedocs.io/en/stable/programming/simulation.html","action":"get"}
+
+```
+https://mujoco.readthedocs.io/en/stable/programming/simulation.html promoted
+```
+
+### `log://turn_5/update/discovering_MuJoCo_docs_for_tuning_params_distillation`
+scheme=log action=update attrs={"status":155,"action":"update"}
+
+```
+discovering MuJoCo docs for tuning params distillation
+```
+