From 171b0d6e0646528ae4cf8299da8364dff1e7fd64 Mon Sep 17 00:00:00 2001 From: Yuval Tassa Date: Mon, 10 Jun 2024 10:00:03 -0700 Subject: [PATCH] Improve order and categorization in function API reference. Also, move macros to the globals section. PiperOrigin-RevId: 641936967 Change-Id: I5b1f6aa52c69e68cc6310093c5811f0f20828bab --- doc/APIreference/APIfunctions.rst | 141 +--- doc/APIreference/APIglobals.rst | 76 ++ doc/APIreference/functions.rst | 1200 ++++++++++++++--------------- 3 files changed, 718 insertions(+), 699 deletions(-) diff --git a/doc/APIreference/APIfunctions.rst b/doc/APIreference/APIfunctions.rst index 81a01e6d..b63981d2 100644 --- a/doc/APIreference/APIfunctions.rst +++ b/doc/APIreference/APIfunctions.rst @@ -9,105 +9,48 @@ large number of functions. However the functions that most users are likely to n API function can be classified as: -- :ref:`Parse and compile` an :ref:`mjModel` from XML files and assets. -- :ref:`Main simulation` entry points, including :ref:`mj_step`. -- :ref:`Support` functions requiring :ref:`mjModel` and :ref:`mjData`. -- :ref:`Components` of the simulation pipeline, called from :ref:`mj_step`, :ref:`mj_forward` and :ref:`mj_inverse`. -- :ref:`Sub components` of the simulation pipeline. -- :ref:`Ray collisions`. -- :ref:`Printing` of various quantities. -- :ref:`Virtual file system`, used to load assets from memory. -- :ref:`Initialization` of data structures. -- :ref:`Abstract interaction`: mouse control of cameras and perturbations. -- :ref:`Abstract Visualization`. -- :ref:`OpenGL rendering`. -- :ref:`UI framework`. -- :ref:`Error and memory`. -- :ref:`Aliases for C standard math` functions. -- :ref:`Vector math`. -- :ref:`Quaternions`. -- :ref:`Poses transformations`. -- :ref:`Matrix decompositions and solvers`. -- :ref:`Miscellaneous` functions. -- :ref:`Derivatives`. -- :ref:`Plugin` related functions. -- :ref:`Macros`. -- :ref:`Thread` related functions. +- **Main entry points** + - :ref:`Parse and compile` an :ref:`mjModel` from XML files and assets. + - :ref:`Main simulation` entry points, including :ref:`mj_step`. -.. TODO(b/273075045): Better category-label namespacing. +- **Support functions** + - :ref:`Support` functions requiring :ref:`mjModel` and :ref:`mjData`. + - Pipeline :ref:`components`, called from :ref:`mj_step`, :ref:`mj_forward` and :ref:`mj_inverse`. + - :ref:`Sub components` of the simulation pipeline. + - :ref:`Ray casting`. + - :ref:`Printing` of various quantities. + - :ref:`Virtual file system`, used to load assets from memory. + - :ref:`Initialization` of data structures. + - :ref:`Error and memory`. + - :ref:`Miscellaneous` functions. + +- **Visualization, Rendering, UI** + - :ref:`Abstract interaction`: mouse control of cameras and perturbations. + - :ref:`Abstract Visualization`. + - :ref:`OpenGL rendering`. + - :ref:`UI framework`. + +- **Threads, Plugins, Derivatives** + - :ref:`Derivatives`. + - :ref:`Thread` |-| -related functions. + - :ref:`Plugin` |-| -related functions. + +- **Math** + - Aliases for C :ref:`standard math` functions. + - :ref:`Vector math`. + - :ref:`Quaternions`. + - :ref:`Pose transformations`. + - :ref:`Matrix decompositions and solvers`. + +- **Model editing** + - :ref:`Attachment`. + - :ref:`Tree elements`. + - :ref:`Non-tree elements`. + - :ref:`Assets`. + - :ref:`Find and get utilities`. + - :ref:`Attribute setters`. + - :ref:`Attribute getters`. + - :ref:`Spec utilities`. + - :ref:`Element initialization`. .. include:: functions.rst - -.. _Macros: - -Macros -^^^^^^ - -.. _mjDISABLED: - -mjDISABLED -~~~~~~~~~~ - -.. code-block:: C - - #define mjDISABLED(x) (m->opt.disableflags & (x)) - -Check if a given standard feature has been disabled via the physics options, assuming mjModel\* m is defined. x is of -type :ref:`mjtDisableBit`. - - -.. _mjENABLED: - -mjENABLED -~~~~~~~~~ - -.. code-block:: C - - #define mjENABLED(x) (m->opt.enableflags & (x)) - -Check if a given optional feature has been enabled via the physics options, assuming mjModel\* m is defined. x is of -type :ref:`mjtEnableBit`. - - -.. _mjMAX: - -mjMAX -~~~~~ - -.. code-block:: C - - #define mjMAX(a,b) (((a) > (b)) ? (a) : (b)) - -Return maximum value. To avoid repeated evaluation with mjtNum types, use the function :ref:`mju_max`. - - -.. _mjMIN: - -mjMIN -~~~~~ - -.. code-block:: C - - #define mjMIN(a,b) (((a) < (b)) ? (a) : (b)) - -Return minimum value. To avoid repeated evaluation with mjtNum types, use the function :ref:`mju_min`. - - -.. _mjPLUGIN_LIB_INIT: - -mjPLUGIN_LIB_INIT -~~~~~~~~~~~~~~~~~ - -.. code-block:: C - - #define mjPLUGIN_LIB_INIT \ - static void _mjplugin_dllmain(void); \ - mjEXTERNC int __stdcall mjDLLMAIN(void* hinst, unsigned long reason, void* reserved) { \ - if (reason == 1) { \ - _mjplugin_dllmain(); \ - } \ - return 1; \ - } \ - static void _mjplugin_dllmain(void) - -Register a plugin as a dynamic library. See :ref:`plugin registration` for more details. diff --git a/doc/APIreference/APIglobals.rst b/doc/APIreference/APIglobals.rst index 2f4e0989..f1ad2c5b 100644 --- a/doc/APIreference/APIglobals.rst +++ b/doc/APIreference/APIglobals.rst @@ -13,6 +13,7 @@ Global variable and constant definitions can be classified as: - The :ref:`collision table` containing narrow-phase collision functions. - :ref:`String constants`. - :ref:`Numeric constants`. +- :ref:`Macros`. - :ref:`X Macros`. .. _glError: @@ -528,6 +529,81 @@ shown in the table below. Their names are in the format ``mjKEY_XXX``. They corr number with the same meaning but for the compiled library. +.. _Macros: + +Macros +^^^^^^ + +.. _mjDISABLED: + +mjDISABLED +~~~~~~~~~~ + +.. code-block:: C + + #define mjDISABLED(x) (m->opt.disableflags & (x)) + +Check if a given standard feature has been disabled via the physics options, assuming mjModel\* m is defined. x is of +type :ref:`mjtDisableBit`. + + +.. _mjENABLED: + +mjENABLED +~~~~~~~~~ + +.. code-block:: C + + #define mjENABLED(x) (m->opt.enableflags & (x)) + +Check if a given optional feature has been enabled via the physics options, assuming mjModel\* m is defined. x is of +type :ref:`mjtEnableBit`. + + +.. _mjMAX: + +mjMAX +~~~~~ + +.. code-block:: C + + #define mjMAX(a,b) (((a) > (b)) ? (a) : (b)) + +Return maximum value. To avoid repeated evaluation with mjtNum types, use the function :ref:`mju_max`. + + +.. _mjMIN: + +mjMIN +~~~~~ + +.. code-block:: C + + #define mjMIN(a,b) (((a) < (b)) ? (a) : (b)) + +Return minimum value. To avoid repeated evaluation with mjtNum types, use the function :ref:`mju_min`. + + +.. _mjPLUGIN_LIB_INIT: + +mjPLUGIN_LIB_INIT +~~~~~~~~~~~~~~~~~ + +.. code-block:: C + + #define mjPLUGIN_LIB_INIT \ + static void _mjplugin_dllmain(void); \ + mjEXTERNC int __stdcall mjDLLMAIN(void* hinst, unsigned long reason, void* reserved) { \ + if (reason == 1) { \ + _mjplugin_dllmain(); \ + } \ + return 1; \ + } \ + static void _mjplugin_dllmain(void) + +Register a plugin as a dynamic library. See :ref:`plugin registration` for more details. + + .. _tyXMacro: X Macros diff --git a/doc/APIreference/functions.rst b/doc/APIreference/functions.rst index 951795ee..3ecf8df8 100644 --- a/doc/APIreference/functions.rst +++ b/doc/APIreference/functions.rst @@ -1,5 +1,5 @@ .. - AUTOGENERATE: DO NOT EDIT + AUTOGENERATED: DO NOT EDIT MANUALLY .. _Parseandcompile: @@ -1498,6 +1498,376 @@ mj_deleteSpec Free memory allocation in mjSpec. +.. _Errorandmemory: + +Error and memory +^^^^^^^^^^^^^^^^ + +.. _mju_error: + +mju_error +~~~~~~~~~ + +.. mujoco-include:: mju_error + +Main error function; does not return to caller. + +.. _mju_error_i: + +mju_error_i +~~~~~~~~~~~ + +.. mujoco-include:: mju_error_i + +Deprecated: use mju_error. + +.. _mju_error_s: + +mju_error_s +~~~~~~~~~~~ + +.. mujoco-include:: mju_error_s + +Deprecated: use mju_error. + +.. _mju_warning: + +mju_warning +~~~~~~~~~~~ + +.. mujoco-include:: mju_warning + +Main warning function; returns to caller. + +.. _mju_warning_i: + +mju_warning_i +~~~~~~~~~~~~~ + +.. mujoco-include:: mju_warning_i + +Deprecated: use mju_warning. + +.. _mju_warning_s: + +mju_warning_s +~~~~~~~~~~~~~ + +.. mujoco-include:: mju_warning_s + +Deprecated: use mju_warning. + +.. _mju_clearHandlers: + +mju_clearHandlers +~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_clearHandlers + +Clear user error and memory handlers. + +.. _mju_malloc: + +mju_malloc +~~~~~~~~~~ + +.. mujoco-include:: mju_malloc + +Allocate memory; byte-align on 64; pad size to multiple of 64. + +.. _mju_free: + +mju_free +~~~~~~~~ + +.. mujoco-include:: mju_free + +Free memory, using free() by default. + +.. _mj_warning: + +mj_warning +~~~~~~~~~~ + +.. mujoco-include:: mj_warning + +High-level warning function: count warnings in mjData, print only the first. + +.. _mju_writeLog: + +mju_writeLog +~~~~~~~~~~~~ + +.. mujoco-include:: mju_writeLog + +Write [datetime, type: message] to MUJOCO_LOG.TXT. + +.. _mjs_getError: + +mjs_getError +~~~~~~~~~~~~ + +.. mujoco-include:: mjs_getError + +Get compiler error message from spec. + +.. _mjs_isWarning: + +mjs_isWarning +~~~~~~~~~~~~~ + +.. mujoco-include:: mjs_isWarning + +Return 1 if compiler error is a warning. + +.. _Miscellaneous: + +Miscellaneous +^^^^^^^^^^^^^ + +.. _mju_muscleGain: + +mju_muscleGain +~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_muscleGain + +Muscle active force, prm = (range[2], force, scale, lmin, lmax, vmax, fpmax, fvmax). + +.. _mju_muscleBias: + +mju_muscleBias +~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_muscleBias + +Muscle passive force, prm = (range[2], force, scale, lmin, lmax, vmax, fpmax, fvmax). + +.. _mju_muscleDynamics: + +mju_muscleDynamics +~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_muscleDynamics + +Muscle activation dynamics, prm = (tau_act, tau_deact, smoothing_width). + +.. _mju_encodePyramid: + +mju_encodePyramid +~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_encodePyramid + +Convert contact force to pyramid representation. + +.. _mju_decodePyramid: + +mju_decodePyramid +~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_decodePyramid + +Convert pyramid representation to contact force. + +.. _mju_springDamper: + +mju_springDamper +~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_springDamper + +Integrate spring-damper analytically, return pos(dt). + +.. _mju_min: + +mju_min +~~~~~~~ + +.. mujoco-include:: mju_min + +Return min(a,b) with single evaluation of a and b. + +.. _mju_max: + +mju_max +~~~~~~~ + +.. mujoco-include:: mju_max + +Return max(a,b) with single evaluation of a and b. + +.. _mju_clip: + +mju_clip +~~~~~~~~ + +.. mujoco-include:: mju_clip + +Clip x to the range [min, max]. + +.. _mju_sign: + +mju_sign +~~~~~~~~ + +.. mujoco-include:: mju_sign + +Return sign of x: +1, -1 or 0. + +.. _mju_round: + +mju_round +~~~~~~~~~ + +.. mujoco-include:: mju_round + +Round x to nearest integer. + +.. _mju_type2Str: + +mju_type2Str +~~~~~~~~~~~~ + +.. mujoco-include:: mju_type2Str + +Convert type id (mjtObj) to type name. + +.. _mju_str2Type: + +mju_str2Type +~~~~~~~~~~~~ + +.. mujoco-include:: mju_str2Type + +Convert type name to type id (mjtObj). + +.. _mju_writeNumBytes: + +mju_writeNumBytes +~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_writeNumBytes + +Return human readable number of bytes using standard letter suffix. + +.. _mju_warningText: + +mju_warningText +~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_warningText + +Construct a warning message given the warning type and info. + +.. _mju_isBad: + +mju_isBad +~~~~~~~~~ + +.. mujoco-include:: mju_isBad + +Return 1 if nan or abs(x)>mjMAXVAL, 0 otherwise. Used by check functions. + +.. _mju_isZero: + +mju_isZero +~~~~~~~~~~ + +.. mujoco-include:: mju_isZero + +Return 1 if all elements are 0. + +.. _mju_standardNormal: + +mju_standardNormal +~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_standardNormal + +Standard normal random number generator (optional second number). + +.. _mju_f2n: + +mju_f2n +~~~~~~~ + +.. mujoco-include:: mju_f2n + +Convert from float to mjtNum. + +.. _mju_n2f: + +mju_n2f +~~~~~~~ + +.. mujoco-include:: mju_n2f + +Convert from mjtNum to float. + +.. _mju_d2n: + +mju_d2n +~~~~~~~ + +.. mujoco-include:: mju_d2n + +Convert from double to mjtNum. + +.. _mju_n2d: + +mju_n2d +~~~~~~~ + +.. mujoco-include:: mju_n2d + +Convert from mjtNum to double. + +.. _mju_insertionSort: + +mju_insertionSort +~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_insertionSort + +Insertion sort, resulting list is in increasing order. + +.. _mju_insertionSortInt: + +mju_insertionSortInt +~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_insertionSortInt + +Integer insertion sort, resulting list is in increasing order. + +.. _mju_Halton: + +mju_Halton +~~~~~~~~~~ + +.. mujoco-include:: mju_Halton + +Generate Halton sequence. + +.. _mju_strncpy: + +mju_strncpy +~~~~~~~~~~~ + +.. mujoco-include:: mju_strncpy + +Call strncpy, then set dst[n-1] = 0. + +.. _mju_sigmoid: + +mju_sigmoid +~~~~~~~~~~~ + +.. mujoco-include:: mju_sigmoid + +Sigmoid function over 0<=x<=1 using quintic polynomial. + .. _Interaction: Interaction @@ -2198,127 +2568,283 @@ This function is called in the screen refresh loop. It copies the offscreen Open there are multiple UIs in the application, it should be called once for each UI. Thus ``mjui_render`` is called all the time, while :ref:`mjui_update` is called only when changes in the UI take place. dsffsdg -.. _Errorandmemory: +.. _Derivatives-api: -Error and memory -^^^^^^^^^^^^^^^^ +Derivatives +^^^^^^^^^^^ -.. _mju_error: +The functions below provide useful derivatives of various functions, both analytic and +finite-differenced. The latter have names with the suffix ``FD``. Note that unlike much of the API, +outputs of derivative functions are the trailing rather than leading arguments. -mju_error -~~~~~~~~~ +.. _mjd_transitionFD: -.. mujoco-include:: mju_error +mjd_transitionFD +~~~~~~~~~~~~~~~~ -Main error function; does not return to caller. +.. mujoco-include:: mjd_transitionFD -.. _mju_error_i: +Finite-differenced discrete-time transition matrices. -mju_error_i -~~~~~~~~~~~ +Letting :math:`x, u` denote the current :ref:`state` and :ref:`control` +vector in an mjData instance, and letting :math:`y, s` denote the next state and sensor +values, the top-level :ref:`mj_step` function computes :math:`(x,u) \rightarrow (y,s)` +:ref:`mjd_transitionFD` computes the four associated Jacobians using finite-differencing. +These matrices and their dimensions are: -.. mujoco-include:: mju_error_i +.. csv-table:: + :header: "matrix", "Jacobian", "dimension" + :widths: auto + :align: left -Deprecated: use mju_error. + ``A``, :math:`\partial y / \partial x`, ``2*nv+na x 2*nv+na`` + ``B``, :math:`\partial y / \partial u`, ``2*nv+na x nu`` + ``C``, :math:`\partial s / \partial x`, ``nsensordata x 2*nv+na`` + ``D``, :math:`\partial s / \partial u`, ``nsensordata x nu`` -.. _mju_error_s: +- All outputs are optional (can be NULL). +- ``eps`` is the finite-differencing epsilon. +- ``flg_centered`` denotes whether to use forward (0) or centered (1) differences. +- Accuracy can be somewhat improved if solver :ref:`iterations` are set to a + fixed (small) value and solver :ref:`tolerance` is set to 0. This insures that + all calls to the solver will perform exactly the same number of iterations. -mju_error_s -~~~~~~~~~~~ +.. _mjd_inverseFD: -.. mujoco-include:: mju_error_s - -Deprecated: use mju_error. - -.. _mju_warning: - -mju_warning -~~~~~~~~~~~ - -.. mujoco-include:: mju_warning - -Main warning function; returns to caller. - -.. _mju_warning_i: - -mju_warning_i +mjd_inverseFD ~~~~~~~~~~~~~ -.. mujoco-include:: mju_warning_i +.. mujoco-include:: mjd_inverseFD -Deprecated: use mju_warning. +Finite differenced continuous-time inverse-dynamics Jacobians. -.. _mju_warning_s: +Letting :math:`x, a` denote the current :ref:`state` and acceleration vectors in an mjData instance, and +letting :math:`f, s` denote the forces computed by the inverse dynamics (``qfrc_inverse``), the function +:ref:`mj_inverse` computes :math:`(x,a) \rightarrow (f,s)`. :ref:`mjd_inverseFD` computes seven associated Jacobians +using finite-differencing. These matrices and their dimensions are: -mju_warning_s -~~~~~~~~~~~~~ +.. csv-table:: + :header: "matrix", "Jacobian", "dimension" + :widths: auto + :align: left -.. mujoco-include:: mju_warning_s + ``DfDq``, :math:`\partial f / \partial q`, ``nv x nv`` + ``DfDv``, :math:`\partial f / \partial v`, ``nv x nv`` + ``DfDa``, :math:`\partial f / \partial a`, ``nv x nv`` + ``DsDq``, :math:`\partial s / \partial q`, ``nv x nsensordata`` + ``DsDv``, :math:`\partial s / \partial v`, ``nv x nsensordata`` + ``DsDa``, :math:`\partial s / \partial a`, ``nv x nsensordata`` + ``DmDq``, :math:`\partial M / \partial q`, ``nv x nM`` -Deprecated: use mju_warning. +- All outputs are optional (can be NULL). +- All outputs are transposed relative to Control Theory convention (i.e., column major). +- ``DmDq``, which contains a sparse representation of the ``nv x nv x nv`` tensor :math:`\partial M / \partial q`, is + not strictly an inverse dynamics Jacobian but is useful in related applications. It is provided as a convenience to + the user, since the required values are already computed if either of the other two :math:`\partial / \partial q` + Jacobians are requested. +- ``eps`` is the (forward) finite-differencing epsilon. +- ``flg_actuation`` denotes whether to subtract actuation forces (``qfrc_actuator``) from the output of the inverse + dynamics. If this flag is positive, actuator forces are not considered as external. -.. _mju_clearHandlers: +.. _mjd_subQuat: -mju_clearHandlers +mjd_subQuat +~~~~~~~~~~~ + +.. mujoco-include:: mjd_subQuat + +Derivatives of :ref:`mju_subQuat` (quaternion difference). + +.. _mjd_quatIntegrate: + +mjd_quatIntegrate ~~~~~~~~~~~~~~~~~ -.. mujoco-include:: mju_clearHandlers +.. mujoco-include:: mjd_quatIntegrate -Clear user error and memory handlers. +Derivatives of :ref:`mju_quatIntegrate`. -.. _mju_malloc: +:math:`{\tt \small mju\_quatIntegrate}(q, v, h)` performs the in-place rotation :math:`q \leftarrow q + v h`, +where :math:`q \in \mathbf{S}^3` is a unit quaternion, :math:`v \in \mathbf{R}^3` is a 3D angular velocity and +:math:`h \in \mathbf{R^+}` is a timestep. This is equivalent to :math:`{\tt \small mju\_quatIntegrate}(q, s, 1.0)`, +where :math:`s` is the scaled velocity :math:`s = h v`. -mju_malloc -~~~~~~~~~~ +:math:`{\tt \small mjd\_quatIntegrate}(v, h, D_q, D_v, D_h)` computes the Jacobians of the output :math:`q` with respect +to the inputs. Below, :math:`\bar q` denotes the pre-modified quaternion: -.. mujoco-include:: mju_malloc +.. math:: + \begin{aligned} + D_q &= \partial q / \partial \bar q \\ + D_v &= \partial q / \partial v \\ + D_h &= \partial q / \partial h + \end{aligned} -Allocate memory; byte-align on 64; pad size to multiple of 64. +Note that derivatives depend only on :math:`h` and :math:`v` (in fact, on :math:`s = h v`). +All outputs are optional. -.. _mju_free: -mju_free -~~~~~~~~ +These functions provide high level manipulation for :ref:`mjSpec` structs, which represent an uncompiled :ref:`mjModel`. -.. mujoco-include:: mju_free +.. _Plugins-api: -Free memory, using free() by default. +Plugins +^^^^^^^ +.. _mjp_defaultPlugin: -.. _mj_warning: +mjp_defaultPlugin +~~~~~~~~~~~~~~~~~ -mj_warning -~~~~~~~~~~ +.. mujoco-include:: mjp_defaultPlugin -.. mujoco-include:: mj_warning +Set default plugin definition. -High-level warning function: count warnings in mjData, print only the first. +.. _mjp_registerPlugin: -.. _mju_writeLog: +mjp_registerPlugin +~~~~~~~~~~~~~~~~~~ -mju_writeLog -~~~~~~~~~~~~ +.. mujoco-include:: mjp_registerPlugin -.. mujoco-include:: mju_writeLog +Globally register a plugin. This function is thread-safe. +If an identical mjpPlugin is already registered, this function does nothing. +If a non-identical mjpPlugin with the same name is already registered, an mju_error is raised. +Two mjpPlugins are considered identical if all member function pointers and numbers are equal, +and the name and attribute strings are all identical, however the char pointers to the strings +need not be the same. -Write [datetime, type: message] to MUJOCO_LOG.TXT. +.. _mjp_pluginCount: -.. _mjs_getError: +mjp_pluginCount +~~~~~~~~~~~~~~~ -mjs_getError -~~~~~~~~~~~~ +.. mujoco-include:: mjp_pluginCount -.. mujoco-include:: mjs_getError +Return the number of globally registered plugins. -Get compiler error message from spec. +.. _mjp_getPlugin: -.. _mjs_isWarning: - -mjs_isWarning +mjp_getPlugin ~~~~~~~~~~~~~ -.. mujoco-include:: mjs_isWarning +.. mujoco-include:: mjp_getPlugin -Return 1 if compiler error is a warning. +Look up a plugin by name. If slot is not NULL, also write its registered slot number into it. + +.. _mjp_getPluginAtSlot: + +mjp_getPluginAtSlot +~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjp_getPluginAtSlot + +Look up a plugin by the registered slot number that was returned by mjp_registerPlugin. + +.. _mjp_defaultResourceProvider: + +mjp_defaultResourceProvider +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjp_defaultResourceProvider + +Set default resource provider definition. + +.. _mjp_registerResourceProvider: + +mjp_registerResourceProvider +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjp_registerResourceProvider + +Globally register a resource provider in a thread-safe manner. The provider must have a prefix +that is not a sub-prefix or super-prefix of any current registered providers. This function +returns a slot number > 0 on success. + +.. _mjp_resourceProviderCount: + +mjp_resourceProviderCount +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjp_resourceProviderCount + +Return the number of globally registered resource providers. + +.. _mjp_getResourceProvider: + +mjp_getResourceProvider +~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjp_getResourceProvider + +Return the resource provider with the prefix that matches against the resource name. +If no match, return NULL. + +.. _mjp_getResourceProviderAtSlot: + +mjp_getResourceProviderAtSlot +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjp_getResourceProviderAtSlot + +Look up a resource provider by slot number returned by mjp_registerResourceProvider. +If invalid slot number, return NULL. + +.. _Thread: + +Threads +^^^^^^^ +.. _mju_threadPoolCreate: + +mju_threadPoolCreate +~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_threadPoolCreate + +Create a thread pool with the specified number of threads running. + +.. _mju_bindThreadPool: + +mju_bindThreadPool +~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_bindThreadPool + +Adds a thread pool to mjData and configures it for multi-threaded use. + +.. _mju_threadPoolEnqueue: + +mju_threadPoolEnqueue +~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_threadPoolEnqueue + +Enqueue a task in a thread pool. + +.. _mju_threadPoolDestroy: + +mju_threadPoolDestroy +~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_threadPoolDestroy + +Destroy a thread pool. + +.. _mju_defaultTask: + +mju_defaultTask +~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_defaultTask + +Initialize an mjTask. + +.. _mju_taskJoin: + +mju_taskJoin +~~~~~~~~~~~~ + +.. mujoco-include:: mju_taskJoin + +Wait for a task to complete. .. _Standardmath: @@ -3199,532 +3725,6 @@ Allocate heap memory for box-constrained Quadratic Program. As in :ref:`mju_boxQP`, ``index``, ``lower``, and ``upper`` are optional. Free all pointers with ``mju_free()``. -.. _Miscellaneous: - -Miscellaneous -^^^^^^^^^^^^^ - -.. _mju_muscleGain: - -mju_muscleGain -~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_muscleGain - -Muscle active force, prm = (range[2], force, scale, lmin, lmax, vmax, fpmax, fvmax). - -.. _mju_muscleBias: - -mju_muscleBias -~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_muscleBias - -Muscle passive force, prm = (range[2], force, scale, lmin, lmax, vmax, fpmax, fvmax). - -.. _mju_muscleDynamics: - -mju_muscleDynamics -~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_muscleDynamics - -Muscle activation dynamics, prm = (tau_act, tau_deact, smoothing_width). - -.. _mju_encodePyramid: - -mju_encodePyramid -~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_encodePyramid - -Convert contact force to pyramid representation. - -.. _mju_decodePyramid: - -mju_decodePyramid -~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_decodePyramid - -Convert pyramid representation to contact force. - -.. _mju_springDamper: - -mju_springDamper -~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_springDamper - -Integrate spring-damper analytically, return pos(dt). - -.. _mju_min: - -mju_min -~~~~~~~ - -.. mujoco-include:: mju_min - -Return min(a,b) with single evaluation of a and b. - -.. _mju_max: - -mju_max -~~~~~~~ - -.. mujoco-include:: mju_max - -Return max(a,b) with single evaluation of a and b. - -.. _mju_clip: - -mju_clip -~~~~~~~~ - -.. mujoco-include:: mju_clip - -Clip x to the range [min, max]. - -.. _mju_sign: - -mju_sign -~~~~~~~~ - -.. mujoco-include:: mju_sign - -Return sign of x: +1, -1 or 0. - -.. _mju_round: - -mju_round -~~~~~~~~~ - -.. mujoco-include:: mju_round - -Round x to nearest integer. - -.. _mju_type2Str: - -mju_type2Str -~~~~~~~~~~~~ - -.. mujoco-include:: mju_type2Str - -Convert type id (mjtObj) to type name. - -.. _mju_str2Type: - -mju_str2Type -~~~~~~~~~~~~ - -.. mujoco-include:: mju_str2Type - -Convert type name to type id (mjtObj). - -.. _mju_writeNumBytes: - -mju_writeNumBytes -~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_writeNumBytes - -Return human readable number of bytes using standard letter suffix. - -.. _mju_warningText: - -mju_warningText -~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_warningText - -Construct a warning message given the warning type and info. - -.. _mju_isBad: - -mju_isBad -~~~~~~~~~ - -.. mujoco-include:: mju_isBad - -Return 1 if nan or abs(x)>mjMAXVAL, 0 otherwise. Used by check functions. - -.. _mju_isZero: - -mju_isZero -~~~~~~~~~~ - -.. mujoco-include:: mju_isZero - -Return 1 if all elements are 0. - -.. _mju_standardNormal: - -mju_standardNormal -~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_standardNormal - -Standard normal random number generator (optional second number). - -.. _mju_f2n: - -mju_f2n -~~~~~~~ - -.. mujoco-include:: mju_f2n - -Convert from float to mjtNum. - -.. _mju_n2f: - -mju_n2f -~~~~~~~ - -.. mujoco-include:: mju_n2f - -Convert from mjtNum to float. - -.. _mju_d2n: - -mju_d2n -~~~~~~~ - -.. mujoco-include:: mju_d2n - -Convert from double to mjtNum. - -.. _mju_n2d: - -mju_n2d -~~~~~~~ - -.. mujoco-include:: mju_n2d - -Convert from mjtNum to double. - -.. _mju_insertionSort: - -mju_insertionSort -~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_insertionSort - -Insertion sort, resulting list is in increasing order. - -.. _mju_insertionSortInt: - -mju_insertionSortInt -~~~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_insertionSortInt - -Integer insertion sort, resulting list is in increasing order. - -.. _mju_Halton: - -mju_Halton -~~~~~~~~~~ - -.. mujoco-include:: mju_Halton - -Generate Halton sequence. - -.. _mju_strncpy: - -mju_strncpy -~~~~~~~~~~~ - -.. mujoco-include:: mju_strncpy - -Call strncpy, then set dst[n-1] = 0. - -.. _mju_sigmoid: - -mju_sigmoid -~~~~~~~~~~~ - -.. mujoco-include:: mju_sigmoid - -Sigmoid function over 0<=x<=1 using quintic polynomial. - -.. _Derivatives-api: - -Derivatives -^^^^^^^^^^^ - -The functions below provide useful derivatives of various functions, both analytic and -finite-differenced. The latter have names with the suffix ``FD``. Note that unlike much of the API, -outputs of derivative functions are the trailing rather than leading arguments. - -.. _mjd_transitionFD: - -mjd_transitionFD -~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjd_transitionFD - -Finite-differenced discrete-time transition matrices. - -Letting :math:`x, u` denote the current :ref:`state` and :ref:`control` -vector in an mjData instance, and letting :math:`y, s` denote the next state and sensor -values, the top-level :ref:`mj_step` function computes :math:`(x,u) \rightarrow (y,s)` -:ref:`mjd_transitionFD` computes the four associated Jacobians using finite-differencing. -These matrices and their dimensions are: - -.. csv-table:: - :header: "matrix", "Jacobian", "dimension" - :widths: auto - :align: left - - ``A``, :math:`\partial y / \partial x`, ``2*nv+na x 2*nv+na`` - ``B``, :math:`\partial y / \partial u`, ``2*nv+na x nu`` - ``C``, :math:`\partial s / \partial x`, ``nsensordata x 2*nv+na`` - ``D``, :math:`\partial s / \partial u`, ``nsensordata x nu`` - -- All outputs are optional (can be NULL). -- ``eps`` is the finite-differencing epsilon. -- ``flg_centered`` denotes whether to use forward (0) or centered (1) differences. -- Accuracy can be somewhat improved if solver :ref:`iterations` are set to a - fixed (small) value and solver :ref:`tolerance` is set to 0. This insures that - all calls to the solver will perform exactly the same number of iterations. - -.. _mjd_inverseFD: - -mjd_inverseFD -~~~~~~~~~~~~~ - -.. mujoco-include:: mjd_inverseFD - -Finite differenced continuous-time inverse-dynamics Jacobians. - -Letting :math:`x, a` denote the current :ref:`state` and acceleration vectors in an mjData instance, and -letting :math:`f, s` denote the forces computed by the inverse dynamics (``qfrc_inverse``), the function -:ref:`mj_inverse` computes :math:`(x,a) \rightarrow (f,s)`. :ref:`mjd_inverseFD` computes seven associated Jacobians -using finite-differencing. These matrices and their dimensions are: - -.. csv-table:: - :header: "matrix", "Jacobian", "dimension" - :widths: auto - :align: left - - ``DfDq``, :math:`\partial f / \partial q`, ``nv x nv`` - ``DfDv``, :math:`\partial f / \partial v`, ``nv x nv`` - ``DfDa``, :math:`\partial f / \partial a`, ``nv x nv`` - ``DsDq``, :math:`\partial s / \partial q`, ``nv x nsensordata`` - ``DsDv``, :math:`\partial s / \partial v`, ``nv x nsensordata`` - ``DsDa``, :math:`\partial s / \partial a`, ``nv x nsensordata`` - ``DmDq``, :math:`\partial M / \partial q`, ``nv x nM`` - -- All outputs are optional (can be NULL). -- All outputs are transposed relative to Control Theory convention (i.e., column major). -- ``DmDq``, which contains a sparse representation of the ``nv x nv x nv`` tensor :math:`\partial M / \partial q`, is - not strictly an inverse dynamics Jacobian but is useful in related applications. It is provided as a convenience to - the user, since the required values are already computed if either of the other two :math:`\partial / \partial q` - Jacobians are requested. -- ``eps`` is the (forward) finite-differencing epsilon. -- ``flg_actuation`` denotes whether to subtract actuation forces (``qfrc_actuator``) from the output of the inverse - dynamics. If this flag is positive, actuator forces are not considered as external. - -.. _mjd_subQuat: - -mjd_subQuat -~~~~~~~~~~~ - -.. mujoco-include:: mjd_subQuat - -Derivatives of :ref:`mju_subQuat` (quaternion difference). - -.. _mjd_quatIntegrate: - -mjd_quatIntegrate -~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjd_quatIntegrate - -Derivatives of :ref:`mju_quatIntegrate`. - -:math:`{\tt \small mju\_quatIntegrate}(q, v, h)` performs the in-place rotation :math:`q \leftarrow q + v h`, -where :math:`q \in \mathbf{S}^3` is a unit quaternion, :math:`v \in \mathbf{R}^3` is a 3D angular velocity and -:math:`h \in \mathbf{R^+}` is a timestep. This is equivalent to :math:`{\tt \small mju\_quatIntegrate}(q, s, 1.0)`, -where :math:`s` is the scaled velocity :math:`s = h v`. - -:math:`{\tt \small mjd\_quatIntegrate}(v, h, D_q, D_v, D_h)` computes the Jacobians of the output :math:`q` with respect -to the inputs. Below, :math:`\bar q` denotes the pre-modified quaternion: - -.. math:: - \begin{aligned} - D_q &= \partial q / \partial \bar q \\ - D_v &= \partial q / \partial v \\ - D_h &= \partial q / \partial h - \end{aligned} - -Note that derivatives depend only on :math:`h` and :math:`v` (in fact, on :math:`s = h v`). -All outputs are optional. - - -These functions provide high level manipulation for :ref:`mjSpec` structs, which represent an uncompiled :ref:`mjModel`. - -.. _Plugins-api: - -Plugins -^^^^^^^ -.. _mjp_defaultPlugin: - -mjp_defaultPlugin -~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjp_defaultPlugin - -Set default plugin definition. - -.. _mjp_registerPlugin: - -mjp_registerPlugin -~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjp_registerPlugin - -Globally register a plugin. This function is thread-safe. -If an identical mjpPlugin is already registered, this function does nothing. -If a non-identical mjpPlugin with the same name is already registered, an mju_error is raised. -Two mjpPlugins are considered identical if all member function pointers and numbers are equal, -and the name and attribute strings are all identical, however the char pointers to the strings -need not be the same. - -.. _mjp_pluginCount: - -mjp_pluginCount -~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjp_pluginCount - -Return the number of globally registered plugins. - -.. _mjp_getPlugin: - -mjp_getPlugin -~~~~~~~~~~~~~ - -.. mujoco-include:: mjp_getPlugin - -Look up a plugin by name. If slot is not NULL, also write its registered slot number into it. - -.. _mjp_getPluginAtSlot: - -mjp_getPluginAtSlot -~~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjp_getPluginAtSlot - -Look up a plugin by the registered slot number that was returned by mjp_registerPlugin. - -.. _mjp_defaultResourceProvider: - -mjp_defaultResourceProvider -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjp_defaultResourceProvider - -Set default resource provider definition. - -.. _mjp_registerResourceProvider: - -mjp_registerResourceProvider -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjp_registerResourceProvider - -Globally register a resource provider in a thread-safe manner. The provider must have a prefix -that is not a sub-prefix or super-prefix of any current registered providers. This function -returns a slot number > 0 on success. - -.. _mjp_resourceProviderCount: - -mjp_resourceProviderCount -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjp_resourceProviderCount - -Return the number of globally registered resource providers. - -.. _mjp_getResourceProvider: - -mjp_getResourceProvider -~~~~~~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjp_getResourceProvider - -Return the resource provider with the prefix that matches against the resource name. -If no match, return NULL. - -.. _mjp_getResourceProviderAtSlot: - -mjp_getResourceProviderAtSlot -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjp_getResourceProviderAtSlot - -Look up a resource provider by slot number returned by mjp_registerResourceProvider. -If invalid slot number, return NULL. - -.. _Thread: - -Threads -^^^^^^^ -.. _mju_threadPoolCreate: - -mju_threadPoolCreate -~~~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_threadPoolCreate - -Create a thread pool with the specified number of threads running. - -.. _mju_bindThreadPool: - -mju_bindThreadPool -~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_bindThreadPool - -Adds a thread pool to mjData and configures it for multi-threaded use. - -.. _mju_threadPoolEnqueue: - -mju_threadPoolEnqueue -~~~~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_threadPoolEnqueue - -Enqueue a task in a thread pool. - -.. _mju_threadPoolDestroy: - -mju_threadPoolDestroy -~~~~~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_threadPoolDestroy - -Destroy a thread pool. - -.. _mju_defaultTask: - -mju_defaultTask -~~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_defaultTask - -Initialize an mjTask. - -.. _mju_taskJoin: - -mju_taskJoin -~~~~~~~~~~~~ - -.. mujoco-include:: mju_taskJoin - -Wait for a task to complete. - .. _Attachment: Attachment