chenlin/Mujoco_WASM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial open sourcing of MuJoCo.

Browse Source 
PiperOrigin-RevId: 450374687
Change-Id: Ie3225a46ce095fc28ae8e63c326a640261f562bb
This commit is contained in:
Saran Tunyasuvunakool
2022-05-23 01:08:10 -07:00
committed by Copybara-Service
parent 0e5d062302
commit 1913a02b40
275 changed files with 99607 additions and 935 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/APIreference.rst
+81 -81
View File
@@ -38,7 +38,7 @@ mjtNum
typedef float mjtNum;
#endif
| Defined in `mjtnum.h <https://github.com/deepmind/mujoco/blob/main/include/mjtnum.h>`_
| Defined in `mjtnum.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjtnum.h>`_
| This is the floating-point type used throughout the simulator. If the symbol ``mjUSEDOUBLE`` is defined in
``mjmodel.h``, this type is defined as ``double``, otherwise it is defined as ``float``. Currently only the
@@ -61,7 +61,7 @@ mjtByte
typedef unsigned char mjtByte;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Byte type used to represent boolean variables.
@@ -90,7 +90,7 @@ mjtDisableBit
mjNDISABLE = 12 // number of disable flags
} mjtDisableBit;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Constants which are powers of 2. They are used as bitmasks for the field ``disableflags`` of :ref:`mjOption`.
At runtime this field is ``m->opt.disableflags``. The number of these constants is given by ``mjNDISABLE`` which is
@@ -117,7 +117,7 @@ mjtEnableBit
mjNENABLE = 5 // number of enable flags
} mjtEnableBit;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Constants which are powers of 2. They are used as bitmasks for the field ``enableflags`` of :ref:`mjOption`.
At runtime this field is ``m->opt.enableflags``. The number of these constants is given by ``mjNENABLE`` which is also
@@ -138,7 +138,7 @@ mjtJoint
mjJNT_HINGE // rotation angle (rad) around body-fixed axis (1)
} mjtJoint;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Primitive joint types. These values are used in ``m->jnt_type``. The numbers in the comments indicate how many
positional coordinates each joint type has. Note that ball joints and rotational components of free joints are
@@ -176,7 +176,7 @@ mjtGeom
mjGEOM_NONE = 1001 // missing geom type
} mjtGeom;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Geometric types supported by MuJoCo. The first group are "official" geom types that can be used in the model. The
second group are geom types that cannot be used in the model but are used by the visualizer to add decorative
@@ -198,7 +198,7 @@ mjtCamLight
mjCAMLIGHT_TARGETBODYCOM // pos fixed in body, rot tracks target subtree com
} mjtCamLight;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Dynamic modes for cameras and lights, specifying how the camera/light position and orientation are computed. These
values are used in ``m->cam_mode`` and ``m->light_mode``.
@@ -217,7 +217,7 @@ mjtTexture
mjTEXTURE_SKYBOX // cube texture used as skybox
} mjtTexture;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Texture types, specifying how the texture will be mapped. These values are used in ``m->tex_type``.
@@ -234,7 +234,7 @@ mjtIntegrator
mjINT_RK4 // 4th-order Runge Kutta
} mjtIntegrator;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Numerical integrator types. These values are used in ``m->opt.integrator``.
@@ -252,7 +252,7 @@ mjtCollision
mjCOL_DYNAMIC // test dynamic pairs only
} mjtCollision;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Collision modes specifying how candidate geom pairs are generated for near-phase collision checking. These values are
used in ``m->opt.collision``.
@@ -270,7 +270,7 @@ mjtCone
mjCONE_ELLIPTIC // elliptic
} mjtCone;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Available friction cone types. These values are used in ``m->opt.cone``.
@@ -288,7 +288,7 @@ mjtJacobian
mjJAC_AUTO // dense if nv<=60, sparse otherwise
} mjtJacobian;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Available Jacobian types. These values are used in ``m->opt.jacobian``.
@@ -306,7 +306,7 @@ mjtSolver
mjSOL_NEWTON // Newton (primal)
} mjtSolver;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Available constraint solver algorithms. These values are used in ``m->opt.solver``.
@@ -326,7 +326,7 @@ mjtEq
mjEQ_DISTANCE // fix the contact distance betweent two geoms
} mjtEq;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Equality constraint types. These values are used in ``m->eq_type``.
@@ -347,7 +347,7 @@ mjtWrap
mjWRAP_CYLINDER // wrap around (infinite) cylinder
} mjtWrap;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Tendon wrapping object types. These values are used in ``m->wrap_type``.
@@ -369,7 +369,7 @@ mjtTrn
mjTRN_UNDEFINED = 1000 // undefined transmission type
} mjtTrn;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Actuator transmission types. These values are used in ``m->actuator_trntype``.
@@ -389,7 +389,7 @@ mjtDyn
mjDYN_USER // user-defined dynamics type
} mjtDyn;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Actuator dynamics types. These values are used in ``m->actuator_dyntype``.
@@ -407,7 +407,7 @@ mjtGain
mjGAIN_USER // user-defined gain type
} mjtGain;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Actuator gain types. These values are used in ``m->actuator_gaintype``.
@@ -426,7 +426,7 @@ mjtBias
mjBIAS_USER // user-defined bias type
} mjtBias;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Actuator bias types. These values are used in ``m->actuator_biastype``.
@@ -465,7 +465,7 @@ mjtObj
mjOBJ_KEY // keyframe
} mjtObj;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| MuJoCo object types. These values are used in the support functions :ref:`mj_name2id` and
:ref:`mj_id2name` to convert between object names and integer ids.
@@ -489,7 +489,7 @@ mjtConstraint
mjCNSTR_CONTACT_ELLIPTIC // frictional contact, elliptic friction cone
} mjtConstraint;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Constraint types. These values are not used in mjModel, but are used in the mjData field ``d->efc_type`` when the list
of active constraints is constructed at each simulation time step.
@@ -510,7 +510,7 @@ mjtConstraintState
mjCNSTRSTATE_CONE // squared distance to cone cost (elliptic contact)
} mjtConstraintState;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| These values are used by the solver internally to keep track of the constraint states.
@@ -574,7 +574,7 @@ mjtSensor
mjSENS_USER // sensor data provided by mjcb_sensor callback
} mjtSensor;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| Sensor types. These values are used in ``m->sensor_type``.
@@ -593,7 +593,7 @@ mjtStage
mjSTAGE_ACC // acceleration/force-dependent computations
} mjtStage;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| These are the compute stages for the skipstage parameters of :ref:`mj_forwardSkip` and
:ref:`mj_inverseSkip`.
@@ -613,7 +613,7 @@ mjtDataType
mjDATATYPE_QUATERNION // unit quaternion
} mjtDataType;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| These are the possible sensor data types, used in ``mjData.sensor_datatype``.
@@ -638,7 +638,7 @@ mjtWarning
mjNWARNING // number of warnings
} mjtWarning;
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mjdata.h>`_
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`_
| Warning types. The number of warning types is given by ``mjNWARNING`` which is also the length of the array
``mjData.warning``.
@@ -674,7 +674,7 @@ mjtTimer
mjNTIMER // number of timers
} mjtTimer;
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mjdata.h>`_
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`_
| Timer types. The number of timer types is given by ``mjNTIMER`` which is also the length of the array
``mjData.timer``, as well as the length of the string array :ref:`mjTIMERSTRING` with timer names.
@@ -694,7 +694,7 @@ mjtCatBit
mjCAT_ALL = 7 // select all categories
} mjtCatBit;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| These are the available categories of geoms in the abstract visualizer. The bitmask can be used in the function
:ref:`mjr_render` to specify which categories should be rendered.
@@ -717,7 +717,7 @@ mjtMouse
mjMOUSE_SELECT // selection
} mjtMouse;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| These are the mouse actions that the abstract visualizer recognizes. It is up to the user to intercept mouse events
and translate them into these actions, as illustrated in ``simulate.cc``.
@@ -735,7 +735,7 @@ mjtPertBit
mjPERT_ROTATE = 2 // rotation
} mjtPertBit;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| These bitmasks enable the translational and rotational components of the mouse perturbation. For the regular mouse,
only one can be enabled at a time. For the 3D mouse (SpaceNavigator) both can be enabled simultaneously. They are used
@@ -756,7 +756,7 @@ mjtCamera
mjCAMERA_USER // user is responsible for setting OpenGL camera
} mjtCamera;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| These are the possible camera types, used in ``mjvCamera.type``.
@@ -787,7 +787,7 @@ mjtLabel
mjNLABEL // number of label types
} mjtLabel;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| These are the abstract visualization elements that can have text labels. Used in ``mjvOption.label``.
@@ -811,7 +811,7 @@ mjtFrame
mjNFRAME // number of visualization frames
} mjtFrame;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| These are the MuJoCo objects whose spatial frames can be rendered. Used in ``mjvOption.frame``.
@@ -850,7 +850,7 @@ mjtVisFlag
mjNVISFLAG // number of visualization flags
} mjtVisFlag;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| These are indices in the array ``mjvOption.flags``, whose elements enable/disable the visualization of the
corresponding model or decoration element.
@@ -877,7 +877,7 @@ mjtRndFlag
mjNRNDFLAG // number of rendering flags
} mjtRndFlag;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| These are indices in the array ``mjvScene.flags``, whose elements enable/disable OpenGL rendering effects.
@@ -895,7 +895,7 @@ mjtStereo
mjSTEREO_SIDEBYSIDE // side-by-side
} mjtStereo;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| These are the possible stereo rendering types. They are used in ``mjvScene.stereo``.
@@ -914,7 +914,7 @@ mjtGridPos
mjGRID_BOTTOMRIGHT // bottom right
} mjtGridPos;
| Defined in `mjrender.h <https://github.com/deepmind/mujoco/blob/main/include/mjrender.h>`_
| Defined in `mjrender.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`_
| These are the possible grid positions for text overlays. They are used as an argument to the function
:ref:`mjr_overlay`.
@@ -932,7 +932,7 @@ mjtFramebuffer
mjFB_OFFSCREEN // offscreen buffer
} mjtFramebuffer;
| Defined in `mjrender.h <https://github.com/deepmind/mujoco/blob/main/include/mjrender.h>`_
| Defined in `mjrender.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`_
| These are the possible framebuffers. They are used as an argument to the function :ref:`mjr_setBuffer`.
@@ -953,7 +953,7 @@ mjtFontScale
mjFONTSCALE_300 = 300 // 300% scale
} mjtFontScale;
| Defined in `mjrender.h <https://github.com/deepmind/mujoco/blob/main/include/mjrender.h>`_
| Defined in `mjrender.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`_
| These are the possible font sizes. The fonts are predefined bitmaps stored in the dynamic library at three different
sizes.
@@ -972,7 +972,7 @@ mjtFont
mjFONT_BIG // big font (for user alerts)
} mjtFont;
| Defined in `mjrender.h <https://github.com/deepmind/mujoco/blob/main/include/mjrender.h>`_
| Defined in `mjrender.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`_
| These are the possible font types.
@@ -991,7 +991,7 @@ mjtButton
mjBUTTON_MIDDLE // middle button
} mjtButton;
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_
| Mouse button IDs used in the UI framework.
@@ -1013,7 +1013,7 @@ mjtEvent
mjEVENT_RESIZE // resize
} mjtEvent;
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_
| Event types used in the UI framework.
@@ -1046,7 +1046,7 @@ mjtItem
mjNITEM // number of item types
} mjtItem;
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_
| Item types used in the UI framework.
@@ -1055,8 +1055,8 @@ mjtItem
Function types
^^^^^^^^^^^^^^
MuJoCo callbacks have corresponding function types. They are defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mjdata.h>`_ and in
`mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_. The actual callback functions are documented later.
MuJoCo callbacks have corresponding function types. They are defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`_ and in
`mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_. The actual callback functions are documented later.
.. _mjfGeneric:
@@ -1163,7 +1163,7 @@ mjVFS
};
typedef struct _mjVFS mjVFS;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| This is the data structure with the virtual file system. It can only be constructed programmatically, and does not
have an analog in MJCF.
@@ -1213,7 +1213,7 @@ mjOption
};
typedef struct _mjOption mjOption;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| This is the data structure with simulation options. It corresponds to the MJCF element
:ref:`option <option>`. One instance of it is embedded in mjModel.
@@ -1319,7 +1319,7 @@ mjVisual
};
typedef struct _mjVisual mjVisual;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| This is the data structure with abstract visualization options. It corresponds to the MJCF element
:ref:`visual <visual>`. One instance of it is embedded in mjModel.
@@ -1341,7 +1341,7 @@ mjStatistic
};
typedef struct _mjStatistic mjStatistic;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| This is the data structure with model statistics precomputed by the compiler or set by the user. It corresponds to the
MJCF element :ref:`statistic <statistic>`. One instance of it is embedded in mjModel.
@@ -1751,7 +1751,7 @@ mjModel
};
typedef struct _mjModel mjModel;
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`_
| Defined in `mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_
| This is the main data structure holding the MuJoCo model. It is treated as constant by the simulator.
@@ -1792,7 +1792,7 @@ mjContact
};
typedef struct _mjContact mjContact;
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mjdata.h>`_
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`_
| This is the data structure holding information about one contact. ``mjData.contact`` is a preallocated array of
mjContact data structures, populated at runtime with the contacts found by the collision detector. Additional contact
@@ -1812,7 +1812,7 @@ mjWarningStat
};
typedef struct _mjWarningStat mjWarningStat;
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mjdata.h>`_
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`_
| This is the data structure holding information about one warning type. ``mjData.warning`` is a preallocated array of
mjWarningStat data structures, one for each warning type.
@@ -1831,7 +1831,7 @@ mjTimerStat
};
typedef struct _mjTimerStat mjTimerStat;
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mjdata.h>`_
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`_
| This is the data structure holding information about one timer. ``mjData.timer`` is a preallocated array of
mjTimerStat data structures, one for each timer type.
@@ -1855,7 +1855,7 @@ mjSolverStat
};
typedef struct _mjSolverStat mjSolverStat;
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mjdata.h>`_
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`_
| This is the data structure holding information about one solver iteration. ``mjData.solver`` is a preallocated array
of mjSolverStat data structures, one for each iteration of the solver, up to a maximum of mjNSOLVER. The actual number
@@ -2042,11 +2042,11 @@ mjData
mjtNum* qfrc_actuator; // actuator force (nv x 1)
// computed by mj_fwdAcceleration
mjtNum* qfrc_unc; // net unconstrained force (nv x 1)
mjtNum* qacc_unc; // unconstrained acceleration (nv x 1)
mjtNum* qfrc_smooth; // net unconstrained force (nv x 1)
mjtNum* qacc_smooth; // unconstrained acceleration (nv x 1)
// computed by mj_fwdConstraint/mj_inverse
mjtNum* efc_b; // linear cost term: J*qacc_unc - aref (njmax x 1)
mjtNum* efc_b; // linear cost term: J*qacc_smooth - aref (njmax x 1)
mjtNum* efc_force; // constraint force in constraint space (njmax x 1)
int* efc_state; // constraint state (mjtConstraintState) (njmax x 1)
mjtNum* qfrc_constraint; // constraint force (nv x 1)
@@ -2062,7 +2062,7 @@ mjData
};
typedef struct _mjData mjData;
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mjdata.h>`_
| Defined in `mjdata.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`_
| This is the main data structure holding the simulation state. It is the workspace where all functions read their
modifiable inputs and write their outputs.
@@ -2086,7 +2086,7 @@ mjvPerturb
};
typedef struct _mjvPerturb mjvPerturb;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| This is the data structure holding information about mouse perturbations.
@@ -2112,7 +2112,7 @@ mjvCamera
};
typedef struct _mjvCamera mjvCamera;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| This is the data structure describing one abstract camera.
@@ -2139,7 +2139,7 @@ mjvGLCamera
};
typedef struct _mjvGLCamera mjvGLCamera;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| This is the data structure describing one OpenGL camera.
@@ -2182,7 +2182,7 @@ mjvGeom
};
typedef struct _mjvGeom mjvGeom;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| This is the data structure describing one abstract visualization geom - which could correspond to a model geom or to a
decoration element constructed by the visualizer.
@@ -2210,7 +2210,7 @@ mjvLight
};
typedef struct _mjvLight mjvLight;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| This is the data structure describing one OpenGL light.
@@ -2234,7 +2234,7 @@ mjvOption
};
typedef struct _mjvOption mjvOption;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| This structure contains options that enable and disable the visualization of various elements.
@@ -2280,7 +2280,7 @@ mjvScene
};
typedef struct _mjvScene mjvScene;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| This structure contains everything needed to render the 3D scene in OpenGL.
@@ -2334,7 +2334,7 @@ mjvFigure
};
typedef struct _mjvFigure mjvFigure;
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`_
| Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
| This structure contains everything needed to render a 2D plot in OpenGL. The buffers for line points etc. are
preallocated, and the user has to populate them before calling the function :ref:`mjr_figure` with this
@@ -2356,7 +2356,7 @@ mjrRect
};
typedef struct _mjrRect mjrRect;
| Defined in `mjrender.h (57) <https://github.com/deepmind/mujoco/blob/main/include/mjrender.h#L57>`_
| Defined in `mjrender.h (57) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjrender.h#L57>`_
| This structure specifies a rectangle.
@@ -2451,7 +2451,7 @@ mjrContext
};
typedef struct _mjrContext mjrContext;
| Defined in `mjrender.h (67) <https://github.com/deepmind/mujoco/blob/main/include/mjrender.h#L67>`_
| Defined in `mjrender.h (67) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjrender.h#L67>`_
| This structure contains the custom OpenGL rendering context, with the ids of all OpenGL resources uploaded to the GPU.
@@ -2502,7 +2502,7 @@ mjuiState
};
typedef struct _mjuiState mjuiState;
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_
| This structure contains the keyboard and mouse state used by the UI framework.
@@ -2529,7 +2529,7 @@ mjuiThemeSpacing
};
typedef struct _mjuiThemeSpacing mjuiThemeSpacing;
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_
| This structure defines the spacing of UI items in the theme.
@@ -2566,7 +2566,7 @@ mjuiThemeColor
};
typedef struct _mjuiThemeColor mjuiThemeColor;
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_
| This structure defines the colors of UI items in the theme.
@@ -2624,7 +2624,7 @@ mjuiItem
};
typedef struct _mjuiItem mjuiItem;
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_
| This structure defines one UI item.
@@ -2651,7 +2651,7 @@ mjuiSection
};
typedef struct _mjuiSection mjuiSection;
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_
| This structure defines one section of the UI.
@@ -2698,7 +2698,7 @@ mjUI
};
typedef struct _mjUI mjUI;
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_
| This structure defines the entire UI.
@@ -2719,7 +2719,7 @@ mjuiDef
};
typedef struct _mjuiDef mjuiDef;
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`_
| Defined in `mjui.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_
| This structure defines one entry in the definition table used for simplified UI construction.
@@ -2730,7 +2730,7 @@ X Macros
The X Macros are not needed in most user projects. They are used internally to allocate the model, and are also
available for users who know how to use this programming technique. See the header file
`mjxmacro.h <https://github.com/deepmind/mujoco/blob/main/include/mjxmacro.h>`_ for the actual definitions. They are particularly useful in writing MuJoCo wrappers
`mjxmacro.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjxmacro.h>`_ for the actual definitions. They are particularly useful in writing MuJoCo wrappers
for scripting languages, where dynamic structures matching the MuJoCo data structures need to be constructed
programmatically.
@@ -3231,7 +3231,7 @@ Numeric constants
API functions
-------------
The main header `mujoco.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco.h>`_ exposes a very large number
The main header `mujoco.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mujoco.h>`_ exposes a very large number
of functions. However the functions that most users are likely to need are a small fraction. For example,
``simulate.cc`` which is as elaborate as a MuJoCo application is likely to get, calls around 40 of these functions,
while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for them. This includes us as
@@ -3852,7 +3852,7 @@ mj_fwdActuation
void mj_fwdActuation(const mjModel* m, mjData* d);
Compute actuator force qfrc_actuation.
Compute actuator force qfrc_actuator.
.. _mj_fwdAcceleration:
@@ -3863,7 +3863,7 @@ mj_fwdAcceleration
void mj_fwdAcceleration(const mjModel* m, mjData* d);
Add up all non-constraint forces, compute qacc_unc.
Add up all non-constraint forces, compute qacc_smooth.
.. _mj_fwdConstraint:
@@ -6118,7 +6118,7 @@ mju_mulQuat
void mju_mulQuat(mjtNum res[4], const mjtNum quat1[4], const mjtNum quat2[4]);
Muiltiply quaternions.
Multiply quaternions.
.. _mju_mulQuatAxis:
@@ -6129,7 +6129,7 @@ mju_mulQuatAxis
void mju_mulQuatAxis(mjtNum res[4], const mjtNum quat[4], const mjtNum axis[3]);
Muiltiply quaternion and axis.
Multiply quaternion and axis.
.. _mju_axisAngle2Quat:
doc/XMLreference.rst
+130 -116
View File
@@ -12,10 +12,10 @@ This chapter is the reference manual for the MJCF modeling language used in MuJo
XML schema
~~~~~~~~~~
| The table below summarizes the XML elements and their attributes in MJCF. It is generated automatically with the
function :ref:`mj_printSchema` which prints out the custom schema used by the parser to validate the model file.
Note that all information in MJCF is entered through elements and attributes. Text content in elements is not used;
if present, the parser ignores it. The symbols in the second column of the table have the following meaning:
The table below summarizes the XML elements and their attributes in MJCF. It is generated automatically with the
function :ref:`mj_printSchema` which prints out the custom schema used by the parser to validate the model file.
Note that all information in MJCF is entered through elements and attributes. Text content in elements is not used;
if present, the parser ignores it. The symbols in the second column of the table have the following meaning:
====== ===================================================
**!** required element, can appear only once
@@ -24,8 +24,6 @@ XML schema
**R** optional element, can appear many times recursively
====== ===================================================
|
+--------------------------+----+------------------------------------------------------------------------------------+
| :el:`mujoco` | ! | .. table:: |
| | | :class: mjcf-attributes |
@@ -355,15 +353,17 @@ XML schema
| | | :class: mjcf-attributes |
| | | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`ctrllimited` | :at:`forcelimited` | :at:`ctrlrange` | |
| | | | :at:`ctrllimited` | :at:`forcelimited` | :at:`actlimited` | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`forcerange` | :at:`gear` | :at:`cranklength` | |
| | | | :at:`ctrlrange` | :at:`forcerange` | :at:`actrange` | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`user` | :at:`group` | :at:`dyntype` | |
| | | | :at:`gear` | :at:`cranklength` | | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`gaintype` | :at:`biastype` | :at:`dynprm` | |
| | | | :at:`user` | :at:`group` | | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`gainprm` | :at:`biasprm` | | |
| | | | :at:`dyntype` | :at:`gaintype` | :at:`biastype` | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`dynprm` | :at:`gainprm` | :at:`biasprm` | |
| | | +-------------------------+-------------------------+-------------------------+ |
+--------------------------+----+------------------------------------------------------------------------------------+
| |_2|:el:`motor` | ? | .. table:: |
@@ -891,19 +891,21 @@ XML schema
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`name` | :at:`class` | :at:`group` | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`ctrllimited` | :at:`forcelimited` | :at:`ctrlrange` | |
| | | | :at:`ctrllimited` | :at:`forcelimited` | :at:`actlimited` | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`forcerange` | :at:`lengthrange` | :at:`gear` | |
| | | | :at:`ctrlrange` | :at:`forcerange` | :at:`actrange` | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`cranklength` | :at:`user` | :at:`joint` | |
| | | | :at:`joint` | :at:`tendon` | :at:`site` | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`jointinparent` | :at:`tendon` | :at:`slidersite` | |
| | | | :at:`lengthrange` | :at:`gear` | :at:`jointinparent` | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`cranksite` | :at:`site` | :at:`dyntype` | |
| | | | :at:`cranklength` | :at:`cranksite` | :at:`slidersite` | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`gaintype` | :at:`biastype` | :at:`dynprm` | |
| | | | :at:`user` | | | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`gainprm` | :at:`biasprm` | | |
| | | | :at:`dyntype` | :at:`gaintype` | :at:`biastype` | |
| | | +-------------------------+-------------------------+-------------------------+ |
| | | | :at:`dynprm` | :at:`gainprm` | :at:`biasprm` | |
| | | +-------------------------+-------------------------+-------------------------+ |
+--------------------------+----+------------------------------------------------------------------------------------+
| |_2|:el:`motor` | \* | .. table:: |
@@ -1913,7 +1915,7 @@ possibly slower speed. Note that `simulate.cc <https://github.com/deepmind/mujoc
displays the frames per second (FPS). The target FPS is 60 Hz; if the number shown in the visualizer is substantially
lower, this means that the GPU is over-loaded and the visualization should somehow be simplified.
:at:`shadowsize`: :at-val:`int, "1024"`
:at:`shadowsize`: :at-val:`int, "4096"`
This attribute specifies the size of the square texture used for shadow mapping. Higher values result is smoother
shadows. The size of the area over which a :ref:`light <light>` can cast shadows also affects smoothness, so these
settings should be adjusted jointly. The default here is somewhat conservative. Most modern GPUs are able to handle
@@ -2743,39 +2745,42 @@ practice this is rarely needed.
:el-prefix:`asset/` **skin** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| Skinned meshes (or skins) were added in MuJoCo 2.0. These are deformable meshes whose vertex positions and normals are
computed each time the model is rendered. MuJoCo skins are only used for visualization and do not affect the physics
in any way. In particular, collisions involve the geoms of the bodies to which the skin is attached, and not the skin
itself. Unlike regular meshes which are referenced from geoms and participate in collisions, the skin is not
referenced from anywhere else in the model. It is a stand-alone asset that is used by renderer and not by the
simulator.
| The skin has vertex positions and normals updated at runtime, and triangle faces and optional texture coordinates
which are predefined. It also has "bones" used for updating. Bones are regular MuJoCo bodies referenced with the
:el:`bone` subelement. Each bone has a list of vertex indices and corresponding real-valued weights which specify how
much the bone position and orientation influence the corresponding vertex. The vertex has local coordinates with
respect to every bone that influences it. The local coordinates are computed by the model compiler, given global
vertex coordinates and global bind poses for each body. The bind poses do not have to correspond to the model
reference configuration qpos0. Note that the vertex positions and bone bind poses provided in the skin definition are
always global, even if the model itself is defined in local coordinates.
| At runtime the local coordinates of each vertex with respect to each bone that influences it are converted to global
coordinates, and averaged in proportion to the corresponding weights to obtain a single set of 3D coordinates for each
vertex. Normals then are computed automatically given the resulting global vertex positions and face information.
Finally, the skin can be inflated by applying an offset to each vertex position along its (computed) normal.
| Skins are one-sided for rendering purposes; this is because back-face culling is needed to avoid shading and aliasing
artifacts. When the skin is a closed 3D shape this does not matter because the back sides cannot be seen. But if the
skin is a 2D object, we have to specify both sides and offset them slightly to avoid artifacts. Note that the
composite objects introduced in MuJoCo 2.0 generate skins automatically. So one can save an XML model with a composite
object, and obtain an elaborate example of how a skin is specified in the XML.
| Similar to meshes, skins can be specified directly in the XML via attributes documented later, or loaded from a binary
SKN file which is in a custom format. The specification of skins is more complex than meshes because of the bone
subelements. The file format starts with a header of 4 integers: nvertex, ntexcoord, nface, nbone. The first three are
the same as in meshes, and specify the total number of vertices, texture coordinate pairs, and triangle faces in the
skin. ntexcoord can be zero or equal to nvertex. nbone specifies the number of MuJoCo bodies that will be used as
bones in the skin. The header is followed by the vertex, texcoord and face data, followed by a specification for each
bone. The bone specification contains the name of the corresponding model body, 3D bind position, 4D bind quaterion,
number of vertices influenced by the bone, and the vertex index array and weight array. Body names are represented as
fixed-length character arrays and are expected to be 0-terminated. Characters after the first 0 are ignored. The
contents of the SKN file are:
Skinned meshes (or skins) were added in MuJoCo 2.0. These are deformable meshes whose vertex positions and normals are
computed each time the model is rendered. MuJoCo skins are only used for visualization and do not affect the physics
in any way. In particular, collisions involve the geoms of the bodies to which the skin is attached, and not the skin
itself. Unlike regular meshes which are referenced from geoms and participate in collisions, the skin is not
referenced from anywhere else in the model. It is a stand-alone asset that is used by renderer and not by the
simulator.
The skin has vertex positions and normals updated at runtime, and triangle faces and optional texture coordinates
which are predefined. It also has "bones" used for updating. Bones are regular MuJoCo bodies referenced with the
:el:`bone` subelement. Each bone has a list of vertex indices and corresponding real-valued weights which specify how
much the bone position and orientation influence the corresponding vertex. The vertex has local coordinates with
respect to every bone that influences it. The local coordinates are computed by the model compiler, given global
vertex coordinates and global bind poses for each body. The bind poses do not have to correspond to the model
reference configuration qpos0. Note that the vertex positions and bone bind poses provided in the skin definition are
always global, even if the model itself is defined in local coordinates.
At runtime the local coordinates of each vertex with respect to each bone that influences it are converted to global
coordinates, and averaged in proportion to the corresponding weights to obtain a single set of 3D coordinates for each
vertex. Normals then are computed automatically given the resulting global vertex positions and face information.
Finally, the skin can be inflated by applying an offset to each vertex position along its (computed) normal.
Skins are one-sided for rendering purposes; this is because back-face culling is needed to avoid shading and aliasing
artifacts. When the skin is a closed 3D shape this does not matter because the back sides cannot be seen. But if the
skin is a 2D object, we have to specify both sides and offset them slightly to avoid artifacts. Note that the
composite objects introduced in MuJoCo 2.0 generate skins automatically. So one can save an XML model with a composite
object, and obtain an elaborate example of how a skin is specified in the XML.
Similar to meshes, skins can be specified directly in the XML via attributes documented later, or loaded from a binary
SKN file which is in a custom format. The specification of skins is more complex than meshes because of the bone
subelements. The file format starts with a header of 4 integers: nvertex, ntexcoord, nface, nbone. The first three are
the same as in meshes, and specify the total number of vertices, texture coordinate pairs, and triangle faces in the
skin. ntexcoord can be zero or equal to nvertex. nbone specifies the number of MuJoCo bodies that will be used as
bones in the skin. The header is followed by the vertex, texcoord and face data, followed by a specification for each
bone. The bone specification contains the name of the corresponding model body, 3D bind position, 4D bind quaterion,
number of vertices influenced by the bone, and the vertex index array and weight array. Body names are represented as
fixed-length character arrays and are expected to be 0-terminated. Characters after the first 0 are ignored. The
contents of the SKN file are:
.. code:: Text
@@ -3030,7 +3035,7 @@ unit quaternions.
The **hinge** type creates a hinge joint with one rotational degree of freedom. The rotation takes place around a
specified axis through a specified position. This is the most common type of joint and is therefore the default. Most
models contact only hinge and free joints.
models contain only hinge and free joints.
:at:`group`: :at-val:`int, "0"`
Integer group to which the joint belongs. This attribute can be used for custom tags. It is also used by the
visualizer to enable and disable the rendering of entire groups of joints.
@@ -3121,18 +3126,19 @@ mjModel. If the XML model is saved, it will appear as a regular joint of type "f
:el-prefix:`body/` **geom** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| This element creates a geom, and attaches it rigidly to the body within which the geom is defined. Multiple geoms can
be attached to the same body. At runtime they determine the appearance and collision properties of the body. At
compile time they can also determine the inertial properties of the body, depending on the presence of the
:ref:`inertial <inertial>` element and the setting of the inertiafromgeom attribute of :ref:`compiler <compiler>`.
This is done by summing the masses and inertias of all geoms attached to the body with geom group in the range
specified by the inertiagrouprange attribute of :ref:`compiler <compiler>`. The geom masses and inertias are computed
using the geom shape, a specified density or a geom mass which implies a density, and the assumption of uniform
density.
| Geoms are not strictly required for physics simulation. One can create and simulate a model that only has bodies and
joints. Such a model can even be visualized, using equivalent inertia boxes to represent bodies. Only contact forces
would be missing from such a simulation. We do not recommend using such models, but knowing that this is possible
helps clarify the role of bodies and geoms in MuJoCo.
This element creates a geom, and attaches it rigidly to the body within which the geom is defined. Multiple geoms can
be attached to the same body. At runtime they determine the appearance and collision properties of the body. At
compile time they can also determine the inertial properties of the body, depending on the presence of the
:ref:`inertial <inertial>` element and the setting of the inertiafromgeom attribute of :ref:`compiler <compiler>`.
This is done by summing the masses and inertias of all geoms attached to the body with geom group in the range
specified by the inertiagrouprange attribute of :ref:`compiler <compiler>`. The geom masses and inertias are computed
using the geom shape, a specified density or a geom mass which implies a density, and the assumption of uniform
density.
Geoms are not strictly required for physics simulation. One can create and simulate a model that only has bodies and
joints. Such a model can even be visualized, using equivalent inertia boxes to represent bodies. Only contact forces
would be missing from such a simulation. We do not recommend using such models, but knowing that this is possible
helps clarify the role of bodies and geoms in MuJoCo.
:at:`name`: :at-val:`string, optional`
Name of the geom.
@@ -3978,19 +3984,19 @@ can also represent different forms of mechanical coupling.
:width: 400px
:align: right
| This element creates a spatial tendon, which is a minimum-length path passing through specified via-points and
wrapping around specified obstacle geoms. The objects along the path are defined with the sub-elements
:ref:`site <spatial-site>` and :ref:`geom <spatial-geom>` below. One can also define :ref:`pulleys <spatial-pulley>`
which split the path in multiple branches. Each branch of the tendon path must start and end with a site, and if it
has multiple obstacle geoms they must be separated by sites - so as to avoid the need for an iterative solver at the
tendon level. This example illustrates a multi-branch tendon acting as a finger extensor, with a counter-weight
instead of an actuator.
This element creates a spatial tendon, which is a minimum-length path passing through specified via-points and
wrapping around specified obstacle geoms. The objects along the path are defined with the sub-elements
:ref:`site <spatial-site>` and :ref:`geom <spatial-geom>` below. One can also define :ref:`pulleys <spatial-pulley>`
which split the path in multiple branches. Each branch of the tendon path must start and end with a site, and if it
has multiple obstacle geoms they must be separated by sites - so as to avoid the need for an iterative solver at the
tendon level. This example illustrates a multi-branch tendon acting as a finger extensor, with a counter-weight
instead of an actuator.
| MuJoCo 2.0 introduced a second form of wrapping, where the tendon is constrained to pass through a geom rather than
wrap around it. This is enabled automatically when a sidesite is specified and its position is inside the volume of
the obstacle geom.
MuJoCo 2.0 introduced a second form of wrapping, where the tendon is constrained to pass through a geom rather than
wrap around it. This is enabled automatically when a sidesite is specified and its position is inside the volume of
the obstacle geom.
| `tendon.xml <_static/tendon.xml>`__
`tendon.xml <_static/tendon.xml>`__
:at:`name`: :at-val:`string, optional`
Name of the tendon.
@@ -4147,16 +4153,23 @@ specify them independently.
Integer group to which the actuator belongs. This attribute can be used for custom tags. It is also used by the
visualizer to enable and disable the rendering of entire groups of actuators.
:at:`ctrllimited`: :at-val:`[false, true], "false"`
If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input
clamping is disabled. Note that control input clamping can also be globally disabled with the clampctrl attribute of
option/ :ref:`flag <option-flag>`.
If true, the control input to this actuator is automatically clamped to :at:`ctrlrange` at runtime. If false, control
input clamping is disabled. Note that control input clamping can also be globally disabled with the :at:`clampctrl`
attribute of :ref:`option/flag <option-flag>`.
:at:`forcelimited`: :at-val:`[false, true], "false"`
If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force output
If true, the force output of this actuator is automatically clamped to :at:`forcerange` at runtime. If false, force
clamping is disabled.
:at:`actlimited`: :at-val:`[false, true], "false"`
If true, the internal state (activation) associated with this actuator is automatically clamped to :at:`actrange` at
runtime. If false, activation clamping is disabled. See the :ref:`Activation clamping <CActRange>` section for more
details.
:at:`ctrlrange`: :at-val:`real(2), "0 0"`
Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
:at:`forcerange`: :at-val:`real(2), "0 0"`
Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
:at:`actrange`: :at-val:`real(2), "0 0"`
Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
See the :ref:`Activation clamping <CActRange>` section for more details.
:at:`lengthrange`: :at-val:`real(2), "0 0"`
Range of feasible lengths of the actuator's transmission. See :ref:`Length Range <CLengthRange>`.
:at:`gear`: :at-val:`real(6), "1 0 0 0 0 0"`
@@ -4262,12 +4275,13 @@ specify them independently.
:el-prefix:`actuator/` **motor** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| This and the next three elements are the :ref:`Actuator shortcuts <CActuator>` discussed earlier. When a
such shortcut is encountered, the parser creates a :el:`general` actuator and sets its dynprm, gainprm and biasprm
attributes to the internal defaults shown above, regardless of any default settings. It then adjusts dyntype, gaintype
and biastype depending on the shortcut, parses any custom attributes (beyond the common ones), and translates them
into regular attributes (i.e., attributes of the :el:`general` actuator type) as explained here.
| This element creates a direct-drive actuator. The underlying :el:`general` attributes are set as follows:
This and the next three elements are the :ref:`Actuator shortcuts <CActuator>` discussed earlier. When a
such shortcut is encountered, the parser creates a :el:`general` actuator and sets its dynprm, gainprm and biasprm
attributes to the internal defaults shown above, regardless of any default settings. It then adjusts dyntype, gaintype
and biastype depending on the shortcut, parses any custom attributes (beyond the common ones), and translates them
into regular attributes (i.e., attributes of the :el:`general` actuator type) as explained here.
This element creates a direct-drive actuator. The underlying :el:`general` attributes are set as follows:
========= ======= ========= =======
Attribute Setting Attribute Setting
@@ -4277,8 +4291,8 @@ gaintype fixed gainprm 1 0 0
biastype none biasprm 0 0 0
========= ======= ========= =======
|
| This element does not have custom attributes. It only has common attributes, which are:
This element does not have custom attributes. It only has common attributes, which are:
.. |actuator/motor attrib list| replace::
@@ -4294,7 +4308,7 @@ biastype none biasprm 0 0 0
:el-prefix:`actuator/` **position** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| This element creates a position servo. The underlying :el:`general` attributes are set as follows:
This element creates a position servo. The underlying :el:`general` attributes are set as follows:
========= ======= ========= =======
Attribute Setting Attribute Setting
@@ -4304,8 +4318,8 @@ gaintype fixed gainprm kp 0 0
biastype affine biasprm 0 -kp 0
========= ======= ========= =======
|
| This element has one custom attribute in addition to the common attributes:
This element has one custom attribute in addition to the common attributes:
.. |actuator/position attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`, :at:`forcerange`,
@@ -4322,9 +4336,9 @@ biastype affine biasprm 0 -kp 0
:el-prefix:`actuator/` **velocity** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| This element creates a velocity servo. Note that in order create a PD controller, one has to define two actuators: a
position servo and a velocity servo. This is because MuJoCo actuators are SISO while a PD controller takes two control
inputs (reference position and reference velocity). The underlying :el:`general` attributes are set as follows:
This element creates a velocity servo. Note that in order create a PD controller, one has to define two actuators: a
position servo and a velocity servo. This is because MuJoCo actuators are SISO while a PD controller takes two control
inputs (reference position and reference velocity). The underlying :el:`general` attributes are set as follows:
========= ======= ========= =======
Attribute Setting Attribute Setting
@@ -4334,8 +4348,8 @@ gaintype fixed gainprm kv 0 0
biastype affine biasprm 0 0 -kv
========= ======= ========= =======
|
| This element has one custom attribute in addition to the common attributes:
This element has one custom attribute in addition to the common attributes:
.. |actuator/velocity attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`, :at:`forcerange`,
@@ -4352,8 +4366,8 @@ biastype affine biasprm 0 0 -kv
:el-prefix:`actuator/` **cylinder** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| This element is suitable for modeling pneumatic or hidraulic cylinders. The underlying :el:`general` attributes are
set as follows:
This element is suitable for modeling pneumatic or hidraulic cylinders. The underlying :el:`general` attributes are
set as follows:
========= ======= ========= =============
Attribute Setting Attribute Setting
@@ -4363,8 +4377,8 @@ gaintype fixed gainprm area 0 0
biastype affine biasprm bias(3)
========= ======= ========= =============
|
| This element has four custom attributes in addition to the common attributes:
This element has four custom attributes in addition to the common attributes:
.. |actuator/cylinder attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`, :at:`forcerange`,
@@ -4387,8 +4401,8 @@ biastype affine biasprm bias(3)
:el-prefix:`actuator/` **muscle** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| This element is used to model a muscle actuator, as described in the :ref:`Muscles actuators <CMuscle>`
section. The underlying :el:`general` attributes are set as follows:
This element is used to model a muscle actuator, as described in the :ref:`Muscles actuators <CMuscle>`
section. The underlying :el:`general` attributes are set as follows:
========= ======= ========= ======================================================
Attribute Setting Attribute Setting
@@ -4398,8 +4412,8 @@ gaintype muscle gainprm range(2), force, scale, lmin, lmax, vmax, fpmax, fvm
biastype muscle biasprm same as gainprm
========= ======= ========= ======================================================
|
| This element has nine custom attributes in addition to the common attributes:
This element has nine custom attributes in addition to the common attributes:
.. |actuator/muscle attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`, :at:`forcerange`,
@@ -4436,14 +4450,15 @@ biastype muscle biasprm same as gainprm
**sensor** (*)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
| This is a grouping element for sensor definitions. It does not have attributes. The outputs of all sensors are
concatenated in the field mjData.sensordata which has size mjModel.nsensordata. This data is not used in any internal
computations.
| In addition to the sensors created with the elements below, the top-level function
:ref:`mj_step` computes the quantities mjData.cacc, mjData.cfrc_int and mjData.crfc_ext
corresponding to body accelerations and interaction forces. Some of these quantities are used to compute the output of
certain sensors (force, acceleration etc.) but even if no such sensors are defined in the model, these quantities
themselves are "features" that could be of interest to the user.
This is a grouping element for sensor definitions. It does not have attributes. The outputs of all sensors are
concatenated in the field mjData.sensordata which has size mjModel.nsensordata. This data is not used in any internal
computations.
In addition to the sensors created with the elements below, the top-level function
:ref:`mj_step` computes the quantities mjData.cacc, mjData.cfrc_int and mjData.crfc_ext
corresponding to body accelerations and interaction forces. Some of these quantities are used to compute the output of
certain sensors (force, acceleration etc.) but even if no such sensors are defined in the model, these quantities
themselves are "features" that could be of interest to the user.
.. _sensor-touch:
@@ -4511,10 +4526,9 @@ simulate an inertial measurement unit (IMU).
This element creates a 3-axis force sensor. The sensor outputs three numbers, which are the interaction force between a
child and a parent body, expressed in the site frame defining the sensor. The convention is that the site is attached to
the child body, and the force points from the child towards the parent. To change the sign of the sensor reading, use
the scale attribute. The computation here takes into account all forces acting on the system, including contacts as well
as external perturbations. Using this sensor often requires creating a dummy body welded to its parent (i.e., having no
joint elements).
the child body, and the force points from the child towards the parent. The computation here takes into account all
forces acting on the system, including contacts as well as external perturbations. Using this sensor often requires
creating a dummy body welded to its parent (i.e., having no joint elements).
:at:`name`, :at:`noise`, :at:`cutoff`, :at:`user`
See :ref:`CSensor`.
doc/changelog.rst
+58 -1
View File
@@ -2,6 +2,63 @@
Changelog
=========
Version 2.2.0 (May 23, 2022)
-----------------------------
Open Sourcing
^^^^^^^^^^^^^
1. MuJoCo is now fully open-source software. Newly available top level directories are:
a. ``src/``: All source files. Subrirectories correspond to the modules described in the Programming chapter
:ref:`introduction<inIntro>`:
- ``src/engine/``: Core engine.
- ``src/xml/``: XML parser.
- ``src/user/``: Model compiler.
- ``src/visualize/``: Abstract visualizer.
- ``src/ui/``: UI framework.
b. ``test/``: Tests and corresponding asset files.
c. ``dist/``: Files related to packaging and binary distribution.
#. Added `contributor's guide <https://github.com/deepmind/mujoco/blob/main/CONTRIBUTING.md>`_ and
`style guide <https://github.com/deepmind/mujoco/blob/main/STYLEGUIDE.md>`_.
General
^^^^^^^
3. Added :at:`actlimited` and :at:`actrange` attributes to :ref:`general actuators<general>`, for clamping actuator
internal states (activations). This clamping is useful for integrated-velocity actuators, see the :ref:`Activation
clamping <CActRange>` section for details.
#. ``mjData`` fields ``qfrc_unc`` (unconstrained forces) and ``qacc_unc`` (unconstrained accelerations) were renamed
``qfrc_smooth`` and ``qacc_smooth``, respectively. While "unconstrained" is precise, "smooth" is more intelligible
than "unc".
#. Public headers have been moved from ``/include`` to ``/include/mujoco/``, in line with the directory layout common in
other open source projects. Developers are encouraged to include MuJoCo public headers in their own codebase via
``#include <mujoco/filename.h>``.
#. The default shadow resolution specified by the :ref:`shadowsize<quality>` attribute was increased from 1024 to 4096.
#. Saved XMLs now use 2-space indents.
Bug fixes
^^^^^^^^^
8. Antialiasing was disabled for segmentation rendering. Before this change, if the :ref:`offsamples<quality>`
attribute was greater than 0 (the default value is 4), pixels that overlapped with multiple geoms would receive
averaged segmentation IDs, leading to incorrect or non-existant IDs. After this change :at:`offsamples` is ignored
during segmentation rendering.
#. The value of the enable flag for the experimental multiCCD feature was made sequential with other enable flags.
Sequentiality is assumed in the ``simulate`` UI and elsewhere.
#. Fix issue of duplicated meshes when saving models with OBJ meshes using mj_saveLastXML.
Version 2.1.5 (Apr. 13, 2022)
-----------------------------
@@ -106,7 +163,7 @@ API changes
^^^^^^^^^^^
4. Moved definition of ``mjtNum`` floating point type into a new header
`mjtnum.h <https://github.com/deepmind/mujoco/blob/main/include/mjtnum.h>`_.
`mjtnum.h <https://github.com/deepmind/mujoco/blob/3577e2cf8bf841475b489aefff52276a39f24d51/include/mjtnum.h>`_.
#. Renamed header `mujoco_export.h` to :ref:`mjexport.h<inHeader>`.
#. Added ``mj_printFormattedData``, which accepts a format string for floating point numbers, for example to increase
precision.
doc/computation.rst
+1 -1
View File
@@ -314,7 +314,7 @@ Putting all this together, the net force in generalized coordinates contributed
.. math::
\sum_i \nabla l_i(q) \; p_i \left(u_i, w_i, l_i(q), \dot{l}_i(q, v) \right)
This quantity is stored in ``mjData.qfrc_actuation``. It is added to the applied force vector :math:`\tau`, together
This quantity is stored in ``mjData.qfrc_actuator``. It is added to the applied force vector :math:`\tau`, together
with any user-defined forces in joint or Cartesian coordinates (which are stored in ``mjData.qfrc_applied`` and
``mjData.xfrc_applied`` respectively).
doc/conf.py
+2
View File
@@ -26,6 +26,7 @@ sys.path.insert(0, os.path.abspath('../'))
sys.path.append(os.path.abspath('ext'))
import sphinxcontrib.katex as katex # pylint: disable=g-import-not-at-top
import sphinxcontrib.youtube as youtube # pylint: disable=g-import-not-at-top
# -- Project information -----------------------------------------------------
@@ -42,6 +43,7 @@ master_doc = 'index'
# ones.
extensions = [
'sphinxcontrib.katex',
'sphinxcontrib.youtube',
'sphinx_reredirects',
]
doc/modeling.rst
+290 -216
View File
@@ -243,13 +243,13 @@ coordinates, but that effort is rarely justified.
Frame orientations
~~~~~~~~~~~~~~~~~~
Several model elements have right-handed spatial frames associated with them. These are all the elements defined in
the kinematic tree except for joints. A spatial frame is defined by its position and orientation. Specifying 3D
positions is straightforward, but specifying 3D orientations can be challenging. This is why MJCF provides several
alternative mechanisms. No matter which mechanism the user chooses, the frame orientation is always represented as a
unit quaternion after compilation. Recall that a 3D rotation by angle *a* around axis given by the unit vector (*x, y,
z*) corresponds to the quaternion (cos(*a*/2), sin(*a*/2) \* (*x, y, z*)). Also recall that every 3D orientation can
be uniquely specified by a single 3D rotation by some angle around some axis.
Several model elements have right-handed spatial frames associated with them. These are all the elements defined in the
kinematic tree except for joints. A spatial frame is defined by its position and orientation. Specifying 3D positions is
straightforward, but specifying 3D orientations can be challenging. This is why MJCF provides several alternative
mechanisms. No matter which mechanism the user chooses, the frame orientation is always represented as a unit quaternion
after compilation. Recall that a 3D rotation by angle :math:`a` around axis given by the unit vector :math:`(x, y, z)`
corresponds to the quaternion :math:`(\cos(a/2), \: \sin(a/2) \cdot (x, y, z))`. Also recall that every 3D orientation
can be uniquely specified by a single 3D rotation by some angle around some axis.
All MJCF elements that have spatial frames allow the five attributes listed below. The frame orientation is specified
using at most one of these attributes. The :at:`quat` attribute has a default value corresponding to the null
@@ -261,12 +261,12 @@ specified by the user, the frame is not rotated.
conversions. Instead it is normalized to unit length and copied into mjModel during compilation. When a model is
saved as MJCF, all frame orientations are expressed as quaternions using this attribute.
:at:`axisangle`: :at-val:`real(4), optional`
These are the quantities (*x, y, z, a*) mentioned above. The last number is the angle of rotation, in degrees or
radians as specified by the :at:`angle` attribute of :ref:`compiler <compiler>`. The first three
numbers determine a 3D vector which is the rotation axis. This vector is normalized to unit length during
compilation, so the user can specify a vector of any non-zero length. Keep in mind that the rotation is right-handed;
if the direction of the vector (*x, y, z*) is reversed this will result in the opposite rotation. Changing the sign
of *a* can also be used to specify the opposite rotation.
These are the quantities :math:`(x, y, z, a)` mentioned above. The last number is the angle of rotation, in degrees
or radians as specified by the :at:`angle` attribute of :ref:`compiler <compiler>`. The first three numbers determine
a 3D vector which is the rotation axis. This vector is normalized to unit length during compilation, so the user can
specify a vector of any non-zero length. Keep in mind that the rotation is right-handed; if the direction of the
vector :math:`(x, y, z)` is reversed this will result in the opposite rotation. Changing the sign of :math:`a` can
also be used to specify the opposite rotation.
:at:`euler`: :at-val:`real(3), optional`
Rotation angles around three coordinate axes. The sequence of axes around which these rotations are applied is
determined by the :at:`eulerseq` attribute of :ref:`compiler <compiler>` and is the same for the
@@ -275,96 +275,110 @@ specified by the user, the frame is not rotated.
The first 3 numbers are the X axis of the frame. The next 3 numbers are the Y axis of the frame, which is
automatically made orthogonal to the X axis. The Z axis is then defined as the cross-product of the X and Y axes.
:at:`zaxis`: :at-val:`real(3), optional`
The Z axis of the frame. The compiler finds the minimal rotation that maps the vector (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.
The Z axis of the frame. The compiler finds the minimal rotation that maps the vector :math:`(0, 0, 1)` into the
vector specified here. This determines the X and Y axes of the frame implicitly. This is useful for geoms with
rotational symmetry around the Z axis, as well as lights - which are oriented along the Z axis of their frame.
.. _CSolver:
Solver parameters
~~~~~~~~~~~~~~~~~
The solver :ref:`Parameters <soParameters>` section of the Computation chapter explained the
mathematical and algorithmic meaning of the quantities d, b, k which determine the behavior of the constraints in
MuJoCo. Here we explain how to set them. Setting is done indirectly, through the attributes :at:`solref` and
:at:`solimp` which are available in all MJCF elements involving constraints. These parameters can be adjusted per
constraint, or per defaults class, or left undefined - in which case MuJoCo uses the internal defaults shown below.
Note also the override mechanism available in :ref:`option <option>`; it can be used to change all
contact-related solver parameters at runtime, so as to experiment interactively with parameter settings or implement
continuation methods for numerical optimization.
The solver :ref:`Parameters <soParameters>` section of the Computation chapter explained the mathematical and
algorithmic meaning of the quantities :math:`d, b, k` which determine the behavior of the constraints in MuJoCo. Here we
explain how to set them. Setting is done indirectly, through the attributes :at:`solref` and :at:`solimp` which are
available in all MJCF elements involving constraints. These parameters can be adjusted per constraint, or per defaults
class, or left undefined - in which case MuJoCo uses the internal defaults shown below. Note also the override mechanism
available in :ref:`option <option>`; it can be used to change all contact-related solver parameters at runtime, so as to
experiment interactively with parameter settings or implement continuation methods for numerical optimization.
Here we focus on a single scalar constraint. Using slightly different notation from the Computation chapter, let a1
denote the acceleration, v the velocity, r the position or residual (defined as 0 in friction dimensions), k and b the
stiffness and damping of the virtual spring used to define the reference acceleration aref = -b*v - k*r. Let d be the
constraint impedance, and a0 the acceleration in the absence of constraint force. Our earlier analysis revealed that
the dynamics in constraint space are approximately
Here we focus on a single scalar constraint. Using slightly different notation from the Computation chapter, let
:math:`a_1` denote the acceleration, :math:`v` the velocity, :math:`r` the position or residual (defined as 0 in
friction dimensions), :math:`k` and :math:`b` the stiffness and damping of the virtual spring used to define the
reference acceleration :math:`a_{\rm ref} = -b v - k r`. Let :math:`d` be the constraint impedance, and :math:`a_0` the
acceleration in the absence of constraint force. Our earlier analysis revealed that the dynamics in constraint space are
approximately
a1 + d \* (b v + k r) = (1 - d) \* a0
.. math::
a_1 + d \cdot (b v + k r) = (1 - d)\cdot a_0
Again, the parameters that are under the user's control are d, b, k. The remaining quantities are functions of the
Again, the parameters that are under the user's control are :math:`d, b, k`. The remaining quantities are functions of the
system state and are computed automatically at each time step.
First we explain the setting of the impedance d. Recall that d must lie between 0 and 1; internally MuJoCo clamps it
to the range [:ref:`mjMINIMP mjMAXIMP <glNumeric>`] which is currently set to [0.0001 0.9999]. It
causes the solver to interpolate between the unforced acceleration a0 and reference acceleration aref. Small values of
d correspond to soft/weak constraints while large values of d correspond to strong/hard constraints. The user can set
d to a constant, or take advantage of its interpolating property and make it position-dependent, i.e., a function of r.
Position-dependent impedance can be used to model soft contact layers around objects, or define equality constraints
that become stronger with larger violation (so as to approximate backlash for example). The shape of the function d(r)
is determined by the element-specific parameter vector :at:`solimp`.
First we explain the setting of the impedance :math:`d`. Recall that :math:`d` must lie between 0 and 1; internally
MuJoCo clamps it to the range [:ref:`mjMINIMP mjMAXIMP <glNumeric>`] which is currently set to [0.0001 0.9999]. It
causes the solver to interpolate between the unforced acceleration :math:`a_0` and reference acceleration
:math:`a_{\rm ref}`. Small values of :math:`d` correspond to soft/weak constraints while large values of :math:`d`
correspond to strong/hard constraints. The user can set :math:`d` to a constant, or take advantage of its interpolating
property and make it position-dependent, i.e., a function of :math:`r`. Position-dependent impedance can be used to
model soft contact layers around objects, or define equality constraints that become stronger with larger violation (so
as to approximate backlash for example). The shape of the function :math:`d(r)` is determined by the element-specific
parameter vector :at:`solimp`.
**solimp :** real(5), "0.9 0.95 0.001 0.5 2"
The five numbers are (dmin, dmax, width, midpoint, power). They parameterize the function d(r). Prior to MuJoCo 2.0
this attribute had three parameters, plus a global option specifying the shape of the function. In MuJoCo 2.0 we
expanded the family of impedance functions while keeping it backward-compatible as follows. The user is allowed to
set only the first three parameters, whose defaults are the same as in prior releases. The defaults for the last two
parameters then generate the same function which was the default in prior releases (a sigmoid). The new
The five numbers are (dmin, dmax, width, midpoint, power). They parameterize the function :math:`d(r)`. Prior to
MuJoCo 2.0 this attribute had three parameters, plus a global option specifying the shape of the function. In MuJoCo
2.0 we expanded the family of impedance functions while keeping it backward-compatible as follows. The user is
allowed to set only the first three parameters, whose defaults are the same as in prior releases. The defaults for
the last two parameters then generate the same function which was the default in prior releases (a sigmoid). The new
parameterization further allows the sigmoid to become shifted and skewed, as shown in the plots below for different
values of the additional parameters. The plots actually show two reflected sigmoids, because the impedance function
d(r) depends on the absolute value of r. This flexibility was added to allow better control of remote contact forces,
and can also be used for other constraints. The power (of the polynomial spline used to generate the function) must
be 1 or greater. The midpoint (specifying the inflection point) must be between 0 and 1, and is expressed in units of
width. Note that when the power is 1, the function is linear regardless of the midpoint.
:math:`d(r)` depends on the absolute value of :math:`r`. This flexibility was added to allow better control of remote
contact forces, and can also be used for other constraints. The power (of the polynomial spline used to generate the
function) must be 1 or greater. The midpoint (specifying the inflection point) must be between 0 and 1, and is
expressed in units of width. Note that when the power is 1, the function is linear regardless of the midpoint.
|image0|
These plots show the impedance d(r) on the vertical axis, as a function of the constraint violation r on the
horizontal axis. The quantity r is computed as follows. For equality constraints, r equals the constraint violation
which can be either positive or negative. For friction loss or friction dimensions of elliptic cones, r is always 0.
For limits, normal directions of elliptic cones and all directions of pyramidal cones, r is the (limit or contact)
distance minus the margin at which the constraint becomes active; for contacts this margin is actually margin-gap.
Therefore limit and contact constraints are active when the corresponding r is negative.
These plots show the impedance :math:`d(r)` on the vertical axis, as a function of the constraint violation :math:`r`
on the horizontal axis. The quantity :math:`r` is computed as follows. For equality constraints, :math:`r` equals the
constraint violation which can be either positive or negative. For friction loss or friction dimensions of elliptic
cones, :math:`r` is always 0. For limits, normal directions of elliptic cones and all directions of pyramidal cones,
:math:`r` is the (limit or contact) distance minus the margin at which the constraint becomes active; for contacts
this margin is actually margin-gap. Therefore limit and contact constraints are active when the corresponding
:math:`r` is negative.
Next we explain the setting of the stiffness k and damping b. The idea here is to re-parameterize the model in terms of
the time constant and damping ratio of the above mass-spring-damper system. By "time constant" we mean the inverse of
the natural frequency times the damping ratio. Constraints whose residual is identically 0 have first-order dynamics and
the mass-spring-damper analysis does not apply. In that case the time constant is the rate of exponential decay of the
constraint velocity, and the damping ratio is ignored. In addition to this format, MuJoCo 2.0 allows a second format
where stiffness and damping are specified more directly.
Next we explain the setting of the stiffness :math:`k` and damping :math:`b`. The idea here is to re-parameterize the
model in terms of the time constant and damping ratio of the above mass-spring-damper system. By "time constant" we mean
the inverse of the natural frequency times the damping ratio. Constraints whose residual is identically 0 have first-
order dynamics and the mass-spring-damper analysis does not apply. In that case the time constant is the rate of
exponential decay of the constraint velocity, and the damping ratio is ignored. In addition to this format, MuJoCo 2.0
allows a second format where stiffness and damping are specified more directly.
**solref :** real(2), "0.02 1"
There are two formats for this attribute, determined by the sign of the numbers. If both numbers are positive the
specification is considered to be in the (timeconst, dampratio) format which has been available in MuJoCo all along.
Otherwise the specification is considered to be in the new (-stiffness, -damping) format introduced in MuJoCo 2.0.
We first describe the original format where the two numbers are (timeconst, dampratio). In this case we use a
mass-spring-damper model to compute k, b after suitable scaling. Note that the effective stiffness d(r)*k and damping
d(r)*b are scaled by the impedance d(r) which is a function of the distance r. Thus we cannot always achieve the
specified mass-spring-damper properties, unless we completely undo the scaling by d. But the latter is undesirable
because it would ruin the interpolating property, in particular the limit d = 0 would no longer disable the
constraint. Instead we scale the stiffness and damping so that the damping ratio remains constant, while the time
constant increases when d(r) gets smaller. The scaling formulas are
b = 2 / (dmax \* timeconst)
k = d(r) / (dmax \* dmax \* timeconst \* timeconst \* dampratio \* dampratio)
specification is considered to be in the :math:`(\text{timeconst}, \text{dampratio})` format which has been available
in MuJoCo all along. Otherwise the specification is considered to be in the new :math:`(-\text{stiffness}, -
\text{damping})`, format introduced in MuJoCo 2.0. We first describe the original format where the two numbers are
:math:`(\text{timeconst}, \text{dampratio})`. In this case we use a mass-spring-damper model to compute :math:`k, b`
after suitable scaling. Note that the effective stiffness :math:`d(r) \cdot k` and damping :math:`d(r) \cdot b` are
scaled by the impedance :math:`d(r)` which is a function of the distance :math:`r`. Thus we cannot always achieve the
specified mass-spring-damper properties, unless we completely undo the scaling by :math:`d`. But the latter is
undesirable because it would ruin the interpolating property, in particular the limit :math:`d=0` would no longer
disable the constraint. Instead we scale the stiffness and damping so that the damping ratio remains constant, while
the time constant increases when :math:`d(r)` gets smaller. The scaling formulas are
.. math::
\begin{aligned}
b &= 2 / (d_\text{max}\cdot \text{timeconst}) \\
k &= d(r) / (d_\text{max}^2 \cdot \text{timeconst}^2 \cdot \text{dampratio}^2) \\
\end{aligned}
The timeconst parameter should be at least two times larger than the simulation time step, otherwise the system can
become too stiff relative to the numerical integrator (especially when Euler integration is used) and the simulation
can go unstable. This is enforced internally, unless the :at:`refsafe` attribute of
:ref:`flag <option-flag>` is set to false. The dampratio parameter would normally be set to 1,
corresponding to critical damping. Smaller values result in under-damped or bouncy constraints, while larger values
result in over-damped constraints.
Next we describe the new format where the two numbers are (-stiffness, -damping). This allows more direct control
over restitution in particular. We still apply some scaling so that the same numbers can be used with different
impedances, but the scaling no longer depends on r and the two numbers no longer interact. The scaling formulas are
b = damping / dmax
k = stiffness / (dmax \* dmax)
can go unstable. This is enforced internally, unless the :at:`refsafe` attribute of :ref:`flag <option-flag>` is set
to false. The :math:`\text{dampratio}` parameter would normally be set to 1, corresponding to critical damping.
Smaller values result in under-damped or bouncy constraints, while larger values result in over-damped constraints.
Next we describe the new format where the two numbers are :math:`(-\text{stiffness}, -\text{damping})`. This allows
more direct control over restitution in particular. We still apply some scaling so that the same numbers can be used
with different impedances, but the scaling no longer depends on :math:`r` and the two numbers no longer interact. The
scaling formulas are
.. math::
\begin{aligned}
b &= \text{damping} / d_\text{max} \\
k &= \text{stiffness} / d_\text{max}^2 \\
\end{aligned}
.. _CContact:
@@ -530,20 +544,18 @@ well as solver statistics per iteration. We can offer the following general guid
Actuator shortcuts
~~~~~~~~~~~~~~~~~~
As explained in the :ref:`Actuation model <geActuation>` section of the Computation chapter, MuJoCo
offers a flexible actuator model with transmission, activation dynamics and force generation components that can be
specified independently. The full functionality can be accessed via the XML element
:ref:`general <general>` which allows the user to create a variety of custom actuators. In addition,
MJCF provides shortcuts for configuring common actuators. This is done via the XML elements
:ref:`motor <motor>`, :ref:`position <position>`,
:ref:`velocity <velocity>`, :ref:`cylinder <cylinder>`,
:ref:`muscle <muscle>`. These are *not* separate model elements. Internally MuJoCo supports only one
As explained in the :ref:`Actuation model <geActuation>` section of the Computation chapter, MuJoCo offers a flexible
actuator model with transmission, activation dynamics and force generation components that can be specified
independently. The full functionality can be accessed via the XML element :ref:`general <general>` which allows the user
to create a variety of custom actuators. In addition, MJCF provides shortcuts for configuring common actuators. This is
done via the XML elements :ref:`motor <motor>`, :ref:`position <position>`, :ref:`velocity <velocity>`, :ref:`cylinder
<cylinder>`, :ref:`muscle <muscle>`. These are *not* separate model elements. Internally MuJoCo supports only one
actuator type - which is why when an MJCF model is saved all actuators are written as :el:`general`. Shortcuts create
general actuators implicitly, set their attributes to suitable values, and expose a subset of attributes with possibly
different names. For example, :el:`position` creates a position servo with attribute :at:`kp` which is the servo
gain. However :el:`general` does not have an attribute :at:`kp`. Instead the parser adjusts the gain and bias
parameters of the general actuator in a coordinated way so as to mimic a position servo. The same effect could have
been achieved by using :el:`general` directly, and setting its attributes to certain values as described below.
different names. For example, :el:`position` creates a position servo with attribute :at:`kp` which is the servo gain.
However :el:`general` does not have an attribute :at:`kp`. Instead the parser adjusts the gain and bias parameters of
the general actuator in a coordinated way so as to mimic a position servo. The same effect could have been achieved by
using :el:`general` directly, and setting its attributes to certain values as described below.
Actuator shortcuts also interact with defaults. Recall that the :ref:`default setting <CDefault>` mechanism involves
classes, each of which has a complete collection of dummy elements (one of each element type) used to initialize the
@@ -561,6 +573,53 @@ defaults class and in the creation of actual model elements. If a given model re
create multiple defaults classes, or avoid using defaults for actuators and instead specify all their attributes
explicitly.
.. _CActRange:
Activation clamping
~~~~~~~~~~~~~~~~~~~
As described in the :ref:`Actuation model <geActuation>` section of the Computation chapter, MuJoCo supports actuators
with internal dynamics whose states are called "activations". One useful application of these stateful actuators is the
"integrated-velocity" actuator. Different from the :ref:`pure velocity<velocity>` actuators, which implement direct
feedback on transmission target's velocity, *integrated-velocity* actuators couple an *integrator* with a *position-
feedback* actuator. In this case the semantics of the activation state are "the target of the position actuator", and
the semantics of the control signal are "the velocity of the target of the position actuator". Note that in real robotic
systems this integrated-velocity actuator is the most common implementation of actuators with velocity semantics, rather
than pure feedback on velocity which is often quite unstable (both in real life and in simulation).
In the case of integrated-velocity actuators, it is often desirable to *clamp* the activation state, since otherwise the
position target would keep integrating beyond the joint limits, leading to loss of controllabillity. To see the effect
of activation clamping, load the example model below:
.. code-block:: xml
<mujoco>
<default>
<joint axis="0 0 1" limited="true" range="-90 90" damping="0.3"/>
<geom size=".1 .1 .1" type="box"/>
<general gainprm="1" biastype="affine" biasprm="0 -1" dyntype="integrator"/>
</default>
<worldbody>
<body>
<joint name="joint 1"/>
<geom/>
</body>
<body pos=".3 0 0">
<joint name="joint 2"/>
<geom/>
</body>
</worldbody>
<actuator>
<general name="unclamped" joint="joint 1"/>
<general name="clamped" actlimited="true" actrange="-1.57 1.57"/>
</actuator>
</mujoco>
Note that the :at:`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 :ref:`compiler/angle <compiler>` attribute.
.. _CLengthRange:
Actuator length range
@@ -637,103 +696,120 @@ the shortcut :ref:`muscle <muscle>` is more convenient. As with all other actuat
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 :ref:`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 LT, while the
biological muscle length LM varies over time. The MuJoCo tendon length is the sum of the biological muscle and tendon
lengths:
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 :ref:`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 :math:`L_T`, while the
biological muscle length :math:`L_M` varies over time. The MuJoCo tendon length is the sum of the biological muscle and
tendon lengths:
actuator_length = LT + LM
.. math::
\texttt{actuator\_length} = L_T + L_M
Another important constant is the optimal resting length of the muscle, denoted L0. It equals the length LM at which
the muscle generates maximum active force at zero velocity. We do not ask the user to specify L0 and LT directly,
because it is difficult to know their numeric values given the spatial complexity of the tendon routing and wrapping.
Instead we compute L0 and LT automatically as follows. The length range computation described above already provided
the operating range for LT + LM. In addition, we ask the user to specify the operating range for the muscle length LM
scaled by the (still unknown) constant L0. This is done with the attribute range; the default scaled range is (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:
Another important constant is the optimal resting length of the muscle, denoted :math:`L_0`. It equals the length
:math:`L_M` at which the muscle generates maximum active force at zero velocity. We do not ask the user to specify
:math:`L_0` and :math:`L_T` directly, because it is difficult to know their numeric values given the spatial complexity
of the tendon routing and wrapping. Instead we compute :math:`L_0` and :math:`L_T` automatically as follows. The length
range computation described above already provided the operating range for :math:`L_T+L_M`. In addition, we ask the user
to specify the operating range for the muscle length :math:`L_M` scaled by the (still unknown) constant :math:`L_0`.
This is done with the attribute range; the default scaled range is :math:`(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]
.. math::
\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) / L0
V = actuator_velocity / L0
.. math::
\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) function measured in many experimental papers. We approximate this
function as follows:
captured by the Force-Length-Velocity (:math:`\text{\small FLV}`) function measured in many experimental papers. We
approximate this function as follows:
|image1|
The function is in the form:
FLV(L, V, act) = FL(L)*FV(V)*act + FP(L)
.. math::
\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*FV is the actuator gain and FP is the actuator
bias. FL is the active force as a function of length, while FV 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). FP is the
passive force which is always present regardless of activation. The output of the FLV function is the scaled muscle
force. We multiply the scaled force by a muscle-specific constant F0 to obtain the actual force:
Comparing to the general form of a MuJoCo actuator, we see that :math:`F_L\cdot F_V` is the actuator gain and
:math:`F_P` is the actuator bias. :math:`F_L` is the active force as a function of length, while :math:`F_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). :math:`F_P` is the passive force which is always present regardless of activation.
The output of the :math:`\text{\small FLV}` function is the scaled muscle force. We multiply the scaled force by a
muscle-specific constant :math:`F_0` to obtain the actual force:
actuator_force = - FLV(L, V, act) \* F0
.. math::
\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 F0 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 :ref:`muscle <muscle>`. If it is not known, we
set it to -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:
The negative sign is because positive muscle activation generates pulling force. The constant :math:`F_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 :ref:`muscle <muscle>`. If it is not known, we set it to
:math:`-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_acc0
.. math::
F_0 = \text{scale} / \texttt{actuator\_acc0}
The quantity 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 determines how strong the muscle is "on average"
while its actual strength depends on the geometric and inertial properties of the entire model.
The quantity :math:`\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, :math:`\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, F0. In addition,
the function FLV itself has several parameters illustrated in the above figure: lmin, lmax, vmax, fpmax, fvmax. 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 <_static/FLV.m>`__ which was used to generate the above figure and shows how we compute the FLV function.
Thus far we encountered three constants that define the properties of an individual muscle: :math:`L_T, L_0, F_0`. In
addition, the function :math:`\text{\small FLV}` itself has several parameters illustrated in the above figure:
:math:`l_\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 <_static/FLV.m>`__ which was used to
generate the above figure and shows how we compute the :math:`\text{\small FLV}` function.
Before embarking on a mission to design more accurate FLV functions, consider the fact that the operating range of the
muscle has a bigger effect than the shape of the FLV function, and in many cases this parameter is unknown. Below is a
graphical illustration:
Before embarking on a mission to design more accurate :math:`\text{\small FLV}` functions, consider the fact that the
operating range of the muscle has a bigger effect than the shape of the :math:`\text{\small FLV}` function, and in many
cases this parameter is unknown. Below is a graphical illustration:
|image2|
This figure format is common in the biomechanics literature, showing the operating range of each muscle superimposed
on the normalized 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 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
This figure format is common in the biomechanics literature, showing the operating range of each muscle superimposed on
the normalized :math:`\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 :math:`\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. Modeling in biology is quite different from modeling in physics and engineering... which is
why we find it ironic when people in Robotics complain that building accurate robot models is hard.
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. Modeling in biology is quite different from modeling in physics and engineering... which is why we find
it ironic when people in Robotics complain that building accurate robot models is hard.
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:
d act / dt = (ctrl - act) / tau(ctrl, act)
.. math::
\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 = (tau_act, tau_deact) with defaults
(0.01, 0.04). The effective time constant tau is then computed at runtime as:
are two time constants specified with the attribute timeconst, namely :math:`\text{timeconst} = (\tau_\text{act},
\tau_\text{deact})` with defaults :math:`(0.01, 0.04)`. Following `Millard et al. (2013)
<https://doi.org/10.1115/1.4023390>`__, the effective time constant :math:`\tau` is then computed at runtime as:
tau(ctrl, act) = tau_act \* (0.5 + 1.5*act), if ctrl > act
tau(ctrl, act) = tau_deact / (0.5 + 1.5*act), if ctrl <= act
.. math::
\tau(\texttt{ctrl}, \texttt{act}) =
\begin{cases}
\tau_\text{act} \cdot (0.5 + 1.5\cdot\texttt{act}) & \texttt{ctrl} \gt \texttt{act} \\
\tau_\text{deact} / (0.5 + 1.5\cdot\texttt{act}) & \texttt{ctrl} \leq \texttt{act}
\end{cases}
Now we summarize the attributes of element :ref:`muscle <muscle>` which users may want to adjust,
depending on their familiarity with the biomechanics literature and availability of detailed measurements with regard
@@ -747,8 +823,8 @@ scale
This can be adjusted separately for each muscle, but it makes more sense to set it once in the
:ref:`default <default>` element.
force
If you know the peak active force F0 of the individual muscles, enter it here. Many experimental papers contain this
data.
If you know the peak active force :math:`F_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
@@ -756,11 +832,11 @@ range
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 function should also be adjusted accordingly.
time constants. The vmax parameter of the :math:`\text{\small FLV}` function should also be adjusted accordingly.
lmin, lmax, vmax, fpmax, fvmax
These are the parameters controlling the shape of the FLV function. Advanced users can experiment with them; see
MATLAB function `FLV.m <_static/FLV.m>`__. Similar to the scale setting, if you want to change the FLV
parameters for all muscles, do so in the :ref:`default <default>` element.
These are the parameters controlling the shape of the :math:`\text{\small FLV}` function. Advanced users can
experiment with them; see MATLAB function `FLV.m <_static/FLV.m>`__. Similar to the scale setting, if you want to
change the :math:`\text{\small FLV}` parameters for all muscles, do so in the :ref:`default <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 :ref:`general <general>` actuator to "user" and providing callbacks at
@@ -777,17 +853,15 @@ simulations. To help MuJoCo users convert OpenSim models, here we summarize the
The activation dynamics model is identical to OpenSim, including the default time constants.
The 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, "Flexing computational muscle: modeling and simulation of musculotendon dynamics", J Biomech Eng. 2013
Feb;135(2)
The :math:`\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
curve corresponding to the inelastic case (Zajac 89). This can be done in MuJoCo by shortening the muscle operating
range.
instability. In practice tendons are quite stiff, and their effect can be captured approximately by stretching the
:math:`\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.
@@ -885,9 +959,9 @@ see the XML model files in the distribution for the complete examples.
.. code-block:: xml
<worldbody>
<composite type="particle" count="10 10 10" spacing="0.07" offset="0 0 1">
<geom size=".02" rgba=".8 .2 .1 1"/>
</composite>
<composite type="particle" count="10 10 10" spacing="0.07" offset="0 0 1">
<geom size=".02" rgba=".8 .2 .1 1"/>
</composite>
</worldbody>
The above XML is all it takes to create a system with 1000 particles with initial positions on a 10-10-10 grid, and
@@ -908,11 +982,11 @@ simulation at much larger timesteps (this model is stable at 30 ms timestep and
.. code-block:: xml
<composite type="grid" count="20 1 1" spacing="0.045" offset="0 0 1">
<joint kind="main" damping="0.001"/>
<tendon kind="main" width="0.01"/>
<geom size=".02" rgba=".8 .2 .1 1"/>
<pin coord="1"/>
<pin coord="13"/>
<joint kind="main" damping="0.001"/>
<tendon kind="main" width="0.01"/>
<geom size=".02" rgba=".8 .2 .1 1"/>
<pin coord="1"/>
<pin coord="13"/>
</composite>
The grid type can create 1D or 2D grids, depending on the :at:`count` attribute. Here we illustrate 1D grids. These
@@ -930,10 +1004,10 @@ example; in that case the parent body would be moving, and the first element bod
.. code-block:: xml
<composite type="grid" count="9 9 1" spacing="0.05" offset="0 0 1">
<skin material="matcarpet" inflate="0.001" subgrid="3" texcoord="true"/>
<geom size=".02"/>
<pin coord="0 0"/>
<pin coord="8 0"/>
<skin material="matcarpet" inflate="0.001" subgrid="3" texcoord="true"/>
<geom size=".02"/>
<pin coord="0 0"/>
<pin coord="8 0"/>
</composite>
A 2D grid can be used to simulate cloth. What it really simulates is a 2D grid of spheres connected with
@@ -950,11 +1024,11 @@ absence of textures. When textures are present (left) the benefits of subdivisio
.. code-block:: xml
<body name="B10" pos="0 0 1">
<freejoint/>
<composite type="rope" count="21 1 1" spacing="0.04" offset="0 0 2">
<joint kind="main" damping="0.005"/>
<geom type="capsule" size=".01 .015" rgba=".8 .2 .1 1"/>
</composite>
<freejoint/>
<composite type="rope" count="21 1 1" spacing="0.04" offset="0 0 2">
<joint kind="main" damping="0.005"/>
<geom type="capsule" size=".01 .015" rgba=".8 .2 .1 1"/>
</composite>
</body>
The remaining composite object types create kinematic trees of element bodies, and the parent body becomes the root of
@@ -978,12 +1052,12 @@ The loop is similar to a rope but the first and last element bodies are connecte
.. code-block:: xml
<body name="B3_5" pos="0 0 1">
<freejoint/>
<composite type="cloth" count="9 9 1" spacing="0.05" flatinertia="0.01">
<joint kind="main" damping="0.001"/>
<skin material="matcarpet" texcoord="true" inflate="0.005" subgrid="2"/>
<geom type="capsule" size="0.015 0.01" rgba=".8 .2 .1 1"/>
</composite>
<freejoint/>
<composite type="cloth" count="9 9 1" spacing="0.05" flatinertia="0.01">
<joint kind="main" damping="0.001"/>
<skin material="matcarpet" texcoord="true" inflate="0.005" subgrid="2"/>
<geom type="capsule" size="0.015 0.01" rgba=".8 .2 .1 1"/>
</composite>
</body>
The cloth type is an alternative to a 2D grid, and has somewhat different properties. Similar to rope vs. 1D grid, the
@@ -1004,11 +1078,11 @@ some damping for stable integration. The parameters can be found in the XML mode
.. code-block:: xml
<body pos="0 0 1">
<freejoint/>
<composite type="box" count="7 7 7" spacing="0.04">
<skin texcoord="true" material="matsponge" rgba=".7 .7 .7 1"/>
<geom type="capsule" size=".015 0.05" rgba=".8 .2 .1 1"/>
</composite>
<freejoint/>
<composite type="box" count="7 7 7" spacing="0.04">
<skin texcoord="true" material="matsponge" rgba=".7 .7 .7 1"/>
<geom type="capsule" size=".015 0.05" rgba=".8 .2 .1 1"/>
</composite>
</body>
The box type, as well as the cylinder and ellipsoid types below, are used to model soft 3D objects. The element bodies
@@ -1036,11 +1110,11 @@ points to the outside, thus creating a thicker shell which is harder to penetrat
.. code-block:: xml
<body pos="0 0 1">
<freejoint/>
<composite type="ellipsoid" count="5 7 9" spacing="0.05">
<skin texcoord="true" material="matsponge" rgba=".7 .7 .7 1"/>
<geom type="capsule" size=".015 0.05" rgba=".8 .2 .1 1"/>
</composite>
<freejoint/>
<composite type="ellipsoid" count="5 7 9" spacing="0.05">
<skin texcoord="true" material="matsponge" rgba=".7 .7 .7 1"/>
<geom type="capsule" size=".015 0.05" rgba=".8 .2 .1 1"/>
</composite>
</body>
Cylinders and ellipsoids are created in the same way as boxes. The only difference is that the reference positions of
@@ -1141,11 +1215,11 @@ Here is an example extension section of a URDF model:
.. code-block:: xml
<robot name="darwin">
<mujoco>
<compiler meshdir="../mesh/darwin/" balanceinertia="true"/>
</mujoco>
<link name="MP_BODY">
...
<mujoco>
<compiler meshdir="../mesh/darwin/" balanceinertia="true"/>
</mujoco>
<link name="MP_BODY">
...
</robot>
The above extensions make URDF more usable but still limited. If the user wants to build models taking full advantage of
@@ -1179,8 +1253,8 @@ orientation:
.. code-block:: xml
<body>
<joint name="J1" type="hinge" pos="0 0 0" axis="0 0 1" armature="0.01"/>
<joint name="J2" type="hinge" pos="0 0 0" axis="0 0 1" limited="true" range="-1 1"/>
<joint name="J1" type="hinge" pos="0 0 0" axis="0 0 1" armature="0.01"/>
<joint name="J2" type="hinge" pos="0 0 0" axis="0 0 1" limited="true" range="-1 1"/>
</body>
Thus the overall rotation of the body relative to its parent is J1+J2. Now define an actuator acting only on J1. The
@@ -1249,12 +1323,12 @@ in a visible way, and the energy fluctuates around the initial value instead of
.. code-block:: xml
<worldbody>
<geom type="plane" size="1 1 .1"/>
<geom type="plane" size="1 1 .1"/>
<body pos="0 0 1">
<freejoint/>
<geom type="sphere" size="0.1" solref="-1000 0"/>
</body>
<body pos="0 0 1">
<freejoint/>
<geom type="sphere" size="0.1" solref="-1000 0"/>
</body>
</worldbody>
.. _CSize:
doc/overview.rst
+29 -3
View File
@@ -640,6 +640,32 @@ interpreted as MKS, then forces and torques are in Newton and Newton-Meter, resp
are using MKS, angular velocities reported by :ref:`gyroscopes<sensor-gyro>` would be in rad/s while stiffness of hinge
joints would be in Nm/rad.
.. _SurprisingCollisions:
Surprising Collisions
~~~~~~~~~~~~~~~~~~~~~
MuJoCo by default excludes collisions between geoms that belong to body pairs which have a direct parent-child
relationship. For example, consider the arm model in the :ref:`Examples` section above: there is no collision at the
"elbow" even though the capsule geoms are penetrating, because the forearm is an immediate child of the upper arm.
However, this exclusion is **not applied if the parent is a static body** i.e., the world body, or a body without any
degrees of freedom relative to the world body. This behavior, documented in the :ref:`Collision detection<Collision>`
section, prevents objects from falling through the floor or moving through walls. However, this behavior often leads to
the following situation:
The user comments out the root joint of a floating-base model, perhaps in order to prevent it from falling; now that the
base body is counted as static, new collisions appear that were not there before and the user is confused. There are two
easy ways to avoid this problem:
1. Don't remove the root joint. Perhaps it is enough to :ref:`disable gravity<option-flag>` and possibly add some
:ref:`fluid viscosity<option>` in order to prevent your model from moving around too much.
2. Use :ref:`collision filtering<Collision>` to explicitly disable the unwanted collisions, either by setting the
relevant :at:`contype` and :at:`conaffinity` attributes, or by using a contact :ref:`exclude <exclude>` directive.
.. _NotObject:
Not object-oriented
@@ -707,7 +733,7 @@ first, followed by the limits of the second joint etc. This ordering reflects th
row-major format.
The available element types are defined in
`mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h#L243>`_, in the enum type :ref:`mjtObj`.
`mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h#L243>`_, in the enum type :ref:`mjtObj`.
These enums are mostly used internally. One exception are the functions :ref:`mj_name2id` and :ref:`mj_id2name` in the
MuJoCo API, which map element names to integer ids and vice versa. These functions take an element type as input.
@@ -761,8 +787,8 @@ properties.
Sites are light geoms. They have the same appearance properties but cannot participate in collisions and cannot be used
to infer body masses. On the other hand sites can do things that geoms cannot do: they can specify the volumes of touch
sensors, the attachment of IMU sensors, the routing of spatial tendons, the end-points of slider-crank actuators. These
are all spatial quantities, and yet they do not correspond to entities that should have mass or collide other entities -
which is why the site element was created. Sites can also be used to specify points (or rather frames) of interest to
are all spatial quantities, and yet they do not correspond to entities that should have mass or collide other entities
-- which is why the site element was created. Sites can also be used to specify points (or rather frames) of interest to
the user.
The following example illustrates the point that multiple sites and geoms can be attached to the same body: two sites
doc/programming.rst
+183 -160
View File
@@ -2,6 +2,8 @@
Programming
===========
.. _inIntro:
Introduction
------------
@@ -10,32 +12,16 @@ is a dynamic library compatible with Windows, Linux and macOS, which requires a
library exposes the full functionality of the simulator through a compiler-independent shared-memory C API. It can also
be used in C++ programs.
MuJoCo is a free product currently distributed as a pre-built dynamic library and will soon be made available as an
open-source project. The software distribution contains a compiled version of GLFW which is used in the code samples to
create an OpenGL window and direct user input to it. The distribution for each platform contains the following dynamic
library:
.. code-block:: Text
Windows: mujoco.dll (stub library: mujoco.lib)
Linux: mujoco.so.2.1.5
macOS: mujoco.2.1.5.dylib
Even though MuJoCo is a single dynamic library with unified C API, it contains several modules, some of which are
implemented in C++. We have taken advantage of the convenience of C++ for functionality that is used before the
simulation starts (namely the parser and compiler), and have gone to the trouble of writing carefully-tuned C code for
all runtime functionality. The modules are:
The MuJoCo codebase is organized into subdirectories corresponding to different major areas of functionality:
Engine
The simulator (or physics engine) is written in C. It is responsible for all runtime computations.
Parser
The XML parser is written in C++. It can parse MJCF models and URDF models, converting them into an internal mjCModel
C++ object which is not directly exposed to the user.
Compiler
The compiler is written in C++. It takes an mjCModel C++ object constructed by the parser, and converts it into an
mjModel C structure used at runtime.
Simulator
The simulator (or physics engine) is written in C. It is responsible for all runtime computations.
Abstract visualizer
The abstract visualizer is written in C. It generates a list of abstract geometric entities representing the
simulation state, with all information needed for actual rendering. It also provides abstract mouse hooks for camera
@@ -54,43 +40,83 @@ UI framework
Getting started
~~~~~~~~~~~~~~~
The software distribution is a single .zip (Windows) or .tar.gz (Mac and Linux) archive whose name contains the platform
and software version, e.g. mujoco210_windows.zip. There is no installer. Simply unzip this archive in a directory of
your choice (where you have write access). You may need to use chmod to set execute permissions or otherwise give
permissions to run the libraries. From the bin subdirectory, you can now run the precompiled code samples, for example:
MuJoCo is an open source project. Pre-built dynamic libraries are available for x86_64 and arm64 machines running
Windows, Linux, and macOS. These can be downloaded from the `GitHub Releases page <https://github.com/deepmind/mujoco/releases>`_.
Users who do not intend to develop or modify core MuJoCo code are encouraged to use our pre-built libraries, as these
come bundled with the same versions of dependencies those that we regularly test against, and benefit from build flags
that have been tuned for performance. Our pre-built libraries are almost entirely self-contained and do not require
other any library to be present, other than the standard C runtime. We also hide all symbols corresponding apart from
those that form MuJoCo's public API, thus ensuring that it can coexist with any other libraries that may be loaded into
the process (including other versions of libraries that MuJoCo depends on).
The pre-built distribution is a single .zip on Windows, .dmg on macOS, and .tar.gz on Linux. There is no installer.
On Windows and Linux, simply extract the archive in a directory of your choice. From the ``bin`` subdirectory, you can
now run the precompiled code samples, for example:
.. code-block:: Text
Windows: simulate ..\model\humanoid.xml
Linux and macOS: ./simulate ../model/humanoid.xml
Prior to MuJoCo 2.0, running the code samples needed LD_LIBRARY_PATH on Linux. As of MuJoCo 2.0, they are compiled with
"rpath $ORIGIN" so the library is found in the executable directory (if it is not in the path).
The directory structure is shown below. Users can re-organize it if needed, as well as install the dynamic libraries in
other directories and set the path accordingly. The only file created automatically is MUJOCO_LOG.TXT in the executable
directory; it contains error and warning messages, and can be deleted at any time.
.. code-block:: Text
mujoco210
bin - dynamic libraries, executables, MUJOCO_LOG.TXT
doc - README.txt and REFERENCE.txt
include - header files needed to develop with MuJoCo
model - model collection (extra models available on the Forum)
sample - code samples and makefile need to build them
bin - dynamic libraries, executables, MUJOCO_LOG.TXT
doc - README.txt and REFERENCE.txt
include - header files needed to develop with MuJoCo
model - model collection
sample - code samples and makefile need to build them
After verifying that the simulator works, the next step is to re-compile the code samples so as to ensure that the
development environment is properly installed. The distribution includes a platform-specific makefile in the sample
subdirectory, which assumes Visual Studio on Windows, GCC on Linux and Clang on macOS. On Windows, remember to open a
Visual Studio command prompt with native x64 tools. Assuming the compilation succeeded and the resulting executables in
the bin subdirectory work, you are ready to start developing with MuJoCo.
After verifying that the simulator works, you may also want to re-compile the code samples to ensure that you have a
working development environment. We provide Makefiles for `Windows <https://github.com/deepmind/mujoco/blob/main/sample/Makefile.windows>`_,
`macOS <https://github.com/deepmind/mujoco/blob/main/sample/Makefile.macos>`_, and
`Linux <https://github.com/deepmind/mujoco/blob/main/sample/Makefile>`_, and also a cross-platform
`CMake <https://github.com/deepmind/mujoco/blob/main/sample/CMakeLists.txt>`_ setup that can be used to build sample
applications independently of the MuJoCo library itself. If you are using the vanilla Makefile, we assume that you are
using Visual Studio on Windows and LLVM/Clang on Linux. On Windows, you also need to either open a Visual Studio command
prompt with native x64 tools or call the ``vcvarsall.bat`` script that comes with your MSVC installation to set up the
appropriate environment variables.
As already mentioned, MuJoCo is a compiler-independent library. In theory the user should be able to switch to any
compiler of their choice. In practice we are using C++11 features as well as std:: functionality internally, and despite
our efforts to statically link all necessary runtime libraries, this is not always possible - especially on Linux where
licensing restrictions prevent static linking. If MuJoCo fails to start because of missing or incompatible dynamic
libraries, please install the necessary libraries.
On macOS, the DMG disk image contains ``MuJoCo.app``, which you can double-click to launch the ``simulate`` GUI.
You can also drag ``MuJoCo.app`` into the ``/Application`` on your system, as you would to install any other app.
While ``MuJoCo.app`` may look like a file, it is in fact an `Application Bundle <https://developer.apple.com/go/?id=bundle-structure>`_,
which is a directory that contains executable binaries for all of MuJoCo's sample applications, along with an embedded
`framework <https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html>`_,
which is a subdirectory containing the MuJoCo dynamic library and all of its public headers. In other words,
``MuJoCo.app`` contains all the same files that are shipped in the archive on Windows and Linux. To see this, right
click (or control-click) on ``MuJoCo.app`` and click "Show Package Contents".
As mentioned above, ``mujoco.framework`` contains the library and headers that are necessary to build any application
that depends on MuJoCo. If you are using Xcode, you can import it as a framework dependency on your project. (This also
works for Swift projects without any modification). If you are building manually, you can use ``-F`` and
``-framework mujoco`` to specify the header search path and the library search path respectively. The macOS Makefile
provides an example for this.
.. _inBuild:
Building MuJoCo from source
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build MuJoCo from source, you will need CMake and a working C++17 compiler installed. The steps are:
#. Clone the ``mujoco`` repository from GitHub.
#. Create a new build directory somewhere, and ``cd`` into it.
#. Run ``cmake $PATH_TO_CLONED_REPO`` to configure the build.
#. Run ``cmake --build .`` to build.
MuJoCo's build system automatically fetches dependencies from upstream repositories over the Internet using CMake's
`FetchContent <https://cmake.org/cmake/help/latest/module/FetchContent.html>`_ module.
The main CMake setup will build the MuJoCo library itself along with all sample applications, but the Python
bindings are not built. Those come with their own build instructions, which can be found in the :doc:`python`
section of the documentation.
Additionally, the CMake setup also implements an installation phase which will copy and organize the output files to a
target directory. Specify the directory using ``cmake $PATH_TO_CLONED_REPO -DCMAKE_INSTALL_PREFIX=<my_install_dir>``.
After successfully building MuJoCo following the instructions above, you can install it using ``cmake --install .``.
.. _inHeader:
@@ -100,29 +126,29 @@ Header files
The distribution contains several header files which are identical on all platforms. They are also available from the
links below, to make this documentation self-contained.
mujoco.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mujoco.h>`__
mujoco.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mujoco.h>`__
This is the main header file and must be included in all programs using MuJoCo. It defines all API functions and
global variables, and includes the next 5 files which provide the necessary type definitions.
mjmodel.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mjmodel.h>`__
mjmodel.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`__
This file defines the C structure :ref:`mjModel` which is the runtime representation of the
model being simulated. It also defines a number of primitive types and other structures needed to define mjModel.
mjdata.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mjdata.h>`__
mjdata.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`__
This file defines the C structure :ref:`mjData` which is the workspace where all computations
read their inputs and write their outputs. It also defines primitive types and other structures needed to define
mjData.
mjvisualize.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mjvisualize.h>`__
mjvisualize.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`__
This file defines the primitive types and structures needed by the abstract visualizer.
mjrender.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mjrender.h>`__
mjrender.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`__
This file defines the primitive types and structures needed by the OpenGL renderer.
mjui.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mjui.h>`__
mjui.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjui.h>`__
This file defines the primitive types and structures needed by the UI framework.
mjtnum.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mjtnum.h>`__
mjtnum.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjtnum.h>`__
Defines MuJoCo's ``mjtNum`` floating-point type to be either ``double`` or ``float``. See :ref:`mjtNum`.
mjxmacro.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mjxmacro.h>`__
mjxmacro.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjxmacro.h>`__
This file is optional and is not included by mujoco.h. It defines :ref:`X Macros <tyXMacro>` that can
automate the mapping of mjModel and mjData into scripting languages, as well as other operations that require
accessing all fields of mjModel and mjData. See code sample :ref:`testxml.cc <saTestXML>`.
mjexport.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mjexport.h>`__
mjexport.h   `(source) <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjexport.h>`__
Macros used for exporting public symbols from the MuJoCo library. This header should not be used directly by client
code.
glfw3.h
@@ -152,7 +178,7 @@ the symbol :ref:`mjVERSION_HEADER <glNumeric>` and the library provides the func
// recommended version check
if( mjVERSION_HEADER!=mj_version() )
complain();
complain();
Note that only the main header defines this symbol. We assume that the collection of headers released with each software
version will stay together and will not be mixed between versions. To avoid complications with floating-point
@@ -309,7 +335,10 @@ This code sample is a full-featured interactive simulator. It opens an OpenGL wi
GLFW library, and renders the simulation state in it. There is built-in help, simulation statistics, profiler, sensor
data plots. The model file can be specified as a command-line argument, or loaded at runtime using drag-and-drop
functionality. As of MuJoCo 2.0, this code sample uses the native UI to render various controls, and provides an
illustration of how the new UI framework is intended to be used.
illustration of how the new UI framework is intended to be used. Below is a screen-capture of ``simulate`` in action:
.. youtube:: 0ORsj_E17B0
:align: center
Interaction is done with the mouse; see the built-in help for summary of available commands. Briefly, an object is
selected by left-double-click. The user can then apply forces and torques on the selected object by holding Ctrl and
@@ -556,7 +585,7 @@ function :ref:`mj_step` in a loop such as
// simulate until t = 10 seconds
while( d->time<10 )
mj_step(m, d);
mj_step(m, d);
This by itself will simulate the passive dynamics, because we have not provided any control signals or applied forces.
The default (and recommended) way to control the system is to implement a control callback, for example
@@ -566,8 +595,8 @@ The default (and recommended) way to control the system is to implement a contro
// simple controller applying damping to each dof
void mycontroller(const mjModel* m, mjData* d)
{
if( m->nu==m->nv )
mju_scl(d->ctrl, d->qvel, -0.1, m->nv);
if( m->nu==m->nv )
mju_scl(d->ctrl, d->qvel, -0.1, m->nv);
}
This illustrates two concepts. First, we are checking if the number of controls ``mjModel.nu`` equals the number of
@@ -595,10 +624,9 @@ control callback) would become
.. code-block:: C
while( d->time<10 )
{
// set d->ctrl or d->qfrc_applied or d->xfrc_applied
mj_step(m, d);
while( d->time<10 ) {
// set d->ctrl or d->qfrc_applied or d->xfrc_applied
mj_step(m, d);
}
Why would we not be able to compute the controls before ``mj_step`` is called? After all, isn't this what causality means?
@@ -619,11 +647,10 @@ before the control is needed, and after the control is needed. The simulation lo
.. code-block:: C
while( d->time<10 )
{
mj_step1(m, d);
// set d->ctrl or d->qfrc_applied or d->xfrc_applied
mj_step2(m, d);
while( d->time<10 ) {
mj_step1(m, d);
// set d->ctrl or d->qfrc_applied or d->xfrc_applied
mj_step2(m, d);
}
There is one complication however: this only works with Euler integration. The Runge-Kutta integrator (as well as other
@@ -637,23 +664,22 @@ omitting some code that computes timing diagnostics. The main simulation functio
.. code-block:: C
void mj_step(const mjModel* m, mjData* d)
{
// common to all integrators
mj_checkPos(m, d);
mj_checkVel(m, d);
mj_forward(m, d);
mj_checkAcc(m, d);
void mj_step(const mjModel* m, mjData* d) {
// common to all integrators
mj_checkPos(m, d);
mj_checkVel(m, d);
mj_forward(m, d);
mj_checkAcc(m, d);
// compare forward and inverse solutions if enabled
if( mjENABLED(mjENBL_FWDINV) )
mj_compareFwdInv(m, d);
// compare forward and inverse solutions if enabled
if( mjENABLED(mjENBL_FWDINV) )
mj_compareFwdInv(m, d);
// use selected integrator
if( m->opt.integrator==mjINT_RK4 )
mj_RungeKutta(m, d, 4);
else
mj_Euler(m, d);
// use selected integrator
if( m->opt.integrator==mjINT_RK4 )
mj_RungeKutta(m, d, 4);
else
mj_Euler(m, d);
}
The checking functions reset the simulation automatically if any numerical values have become invalid or too large.
@@ -668,34 +694,34 @@ mj_step2 regardless of the setting of ``mjModel.opt.integrator``.
void mj_step1(const mjModel* m, mjData* d)
{
mj_checkPos(m, d);
mj_checkVel(m, d);
mj_fwdPosition(m, d);
mj_sensorPos(m, d);
mj_energyPos(m, d);
mj_fwdVelocity(m, d);
mj_sensorVel(m, d);
mj_energyVel(m, d);
mj_checkPos(m, d);
mj_checkVel(m, d);
mj_fwdPosition(m, d);
mj_sensorPos(m, d);
mj_energyPos(m, d);
mj_fwdVelocity(m, d);
mj_sensorVel(m, d);
mj_energyVel(m, d);
// if we had a callback we would be using mj_step, but call it anyway
if( mjcb_control )
mjcb_control(m, d);
// if we had a callback we would be using mj_step, but call it anyway
if( mjcb_control )
mjcb_control(m, d);
}
void mj_step2(const mjModel* m, mjData* d)
{
mj_fwdActuation(m, d);
mj_fwdAcceleration(m, d);
mj_fwdConstraint(m, d);
mj_sensorAcc(m, d);
mj_checkAcc(m, d);
mj_fwdActuation(m, d);
mj_fwdAcceleration(m, d);
mj_fwdConstraint(m, d);
mj_sensorAcc(m, d);
mj_checkAcc(m, d);
// compare forward and inverse solutions if enabled
if( mjENABLED(mjENBL_FWDINV) )
mj_compareFwdInv(m, d);
// compare forward and inverse solutions if enabled
if( mjENABLED(mjENBL_FWDINV) )
mj_compareFwdInv(m, d);
// integrate with Euler; ignore integrator option
mj_Euler(m, d);
// integrate with Euler; ignore integrator option
mj_Euler(m, d);
}
.. _siStateControl:
@@ -830,37 +856,35 @@ skip arguments (mjSTAGE_NONE, 0), where the latter function is implemented as
.. code-block:: C
void mj_forwardSkip(const mjModel* m, mjData* d,
int skipstage, int skipsensor)
{
// position-dependent
if( skipstage<mjSTAGE_POS )
{
mj_fwdPosition(m, d);
if( !skipsensor )
mj_sensorPos(m, d);
if( mjENABLED(mjENBL_ENERGY) )
mj_energyPos(m, d);
}
// velocity-dependent
if( skipstage<mjSTAGE_VEL )
{
mj_fwdVelocity(m, d);
if( !skipsensor )
mj_sensorVel(m, d);
if( mjENABLED(mjENBL_ENERGY) )
mj_energyVel(m, d);
}
// acceleration-dependent
if( mjcb_control )
mjcb_control(m, d);
mj_fwdActuation(m, d);
mj_fwdAcceleration(m, d);
mj_fwdConstraint(m, d);
void mj_forwardSkip(const mjModel* m, mjData* d, int skipstage, int skipsensor) {
// position-dependent
if( skipstage<mjSTAGE_POS )
{
mj_fwdPosition(m, d);
if( !skipsensor )
mj_sensorAcc(m, d);
mj_sensorPos(m, d);
if( mjENABLED(mjENBL_ENERGY) )
mj_energyPos(m, d);
}
// velocity-dependent
if( skipstage<mjSTAGE_VEL )
{
mj_fwdVelocity(m, d);
if( !skipsensor )
mj_sensorVel(m, d);
if( mjENABLED(mjENBL_ENERGY) )
mj_energyVel(m, d);
}
// acceleration-dependent
if( mjcb_control )
mjcb_control(m, d);
mj_fwdActuation(m, d);
mj_fwdAcceleration(m, d);
mj_fwdConstraint(m, d);
if( !skipsensor )
mj_sensorAcc(m, d);
}
Note that this is the same sequence of calls as in mj_step1 and mj_step2 above, except that checking of real values
@@ -985,17 +1009,17 @@ management.
// parallel section
#pragma omp parallel
{
int n = omp_get_thread_num(); // thread-private variable with thread id (0 to nthread-1)
int n = omp_get_thread_num(); // thread-private variable with thread id (0 to nthread-1)
// ... initialize d[n] from results in serial code
// ... initialize d[n] from results in serial code
// thread function
worker(m, d[n]); // shared mjModel (read-only), per-thread mjData (read-write)
// thread function
worker(m, d[n]); // shared mjModel (read-only), per-thread mjData (read-write)
}
// delete per-thread mjData
for( int n=0; n<nthread; n++ )
mj_deleteData(d[n]);
mj_deleteData(d[n]);
Since all top-level API functions threat mjModel as ``const``, this multi-threading scheme is safe. Each thread only
writes to its own mjData. Therefore no further synchronization among threads is needed.
@@ -1310,11 +1334,11 @@ the total energy indicate inaccuracies in numerical integration. For such system
better performance than the default semi-implicit Euler integrator.
Finally, the user can implement additional diagnostics as needed. Two examples were provided in the code samples
``testxml.cc`` and ``derivative.cc``, where we computed model mismatches after save and load, and assessed the accuracy of the
numerical derivatives respectively. Key to such diagnostics is to implement two different algorithms or simulation
paths that compute the same quantity, and compare the results numerically. This type of sanity check is essential when
dealing with complex dynamical systems where we do not really know what the numerical output should be; if we knew
that, we would not be using a simulator in the first place.
``testxml.cc`` and ``derivative.cc``, where we computed model mismatches after save and load, and assessed the accuracy
of the numerical derivatives respectively. Key to such diagnostics is to implement two different algorithms or
simulation paths that compute the same quantity, and compare the results numerically. This type of sanity check is
essential when dealing with complex dynamical systems where we do not really know what the numerical output should be;
if we knew that, we would not be using a simulator in the first place.
.. _siJacobian:
@@ -1529,29 +1553,28 @@ one of its derivatives.
// ... install GLFW keyboard and mouse callbacks
// run main loop, target real-time simulation and 60 fps rendering
while( !glfwWindowShouldClose(window) )
{
// advance interactive simulation for 1/60 sec
// Assuming MuJoCo can simulate faster than real-time, which it usually can,
// this loop will finish on time for the next frame to be rendered at 60 fps.
// Otherwise add a cpu timer and exit this loop when it is time to render.
mjtNum simstart = d->time;
while( d->time - simstart < 1.0/60.0 )
mj_step(m, d);
while( !glfwWindowShouldClose(window) ) {
// advance interactive simulation for 1/60 sec
// Assuming MuJoCo can simulate faster than real-time, which it usually can,
// this loop will finish on time for the next frame to be rendered at 60 fps.
// Otherwise add a cpu timer and exit this loop when it is time to render.
mjtNum simstart = d->time;
while( d->time - simstart < 1.0/60.0 )
mj_step(m, d);
// get framebuffer viewport
mjrRect viewport = {0, 0, 0, 0};
glfwGetFramebufferSize(window, &viewport.width, &viewport.height);
// get framebuffer viewport
mjrRect viewport = {0, 0, 0, 0};
glfwGetFramebufferSize(window, &viewport.width, &viewport.height);
// update scene and render
mjv_updateScene(m, d, &opt, NULL, &cam, mjCAT_ALL, &scn);
mjr_render(viewport, &scn, &con);
// update scene and render
mjv_updateScene(m, d, &opt, NULL, &cam, mjCAT_ALL, &scn);
mjr_render(viewport, &scn, &con);
// swap OpenGL buffers (blocking call due to v-sync)
glfwSwapBuffers(window);
// swap OpenGL buffers (blocking call due to v-sync)
glfwSwapBuffers(window);
// process pending GUI events, call GLFW callbacks
glfwPollEvents();
// process pending GUI events, call GLFW callbacks
glfwPollEvents();
}
// close GLFW, free visualization storage
doc/python.rst
-3
View File
@@ -2,9 +2,6 @@
Python Bindings
===============
Introduction
------------
Starting with version 2.1.2, MuJoCo comes with native Python bindings that are developed in C++ using
`pybind11 <https://pybind11.readthedocs.io/>`__. Unlike previous Python bindings, these are officially supported by the
MuJoCo development team and will be kept up-to-date with the latest developments in MuJoCo itself.
doc/requirements.txt
+1
View File
@@ -1,6 +1,7 @@
sphinx==3.5.4
sphinx_rtd_theme==0.5.2
sphinxcontrib-katex==0.8.6
sphinxcontrib-youtube==1.1.0
sphinx-reredirects==0.0.1
nbsphinx==0.8.0
pandoc==1.0.2
doc/unity.rst
+2 -2
View File
@@ -29,14 +29,14 @@ _____
The MuJoCo app needs to be run at least once before the native library can be used, in order to register the library as
a trusted binary. Then, copy the dynamic library file from
``/Applications/MuJoCo.app/Contents/Frameworks/MuJoCo.framework/Versions/Current/libmujoco.2.1.5.dylib`` (it can be
``/Applications/MuJoCo.app/Contents/Frameworks/mujoco.framework/Versions/Current/libmujoco.2.2.0.dylib`` (it can be
found by browsing the contents of ``MuJoCo.app``) and rename it as ``mujoco.dylib``.
Linux
_____
Expand the ``tar.gz`` archive to ``~/.mujoco``. Then copy the dynamic library from
``~/.mujoco/mujoco-2.1.5/lib/libmujoco.so.2.1.5`` and rename it as ``libmujoco.so``.
``~/.mujoco/mujoco-2.2.0/lib/libmujoco.so.2.2.0`` and rename it as ``libmujoco.so``.
Windows
_______