diff --git a/doc/conf.py b/doc/conf.py index 16c8c34e..284f4918 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -58,7 +58,7 @@ templates_path = ['templates'] # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ '_build', 'Thumbs.db', '.DS_Store', 'includes/*', 'functions.rst', - 'XMLschema.rst' + 'functions_override.rst', 'XMLschema.rst' ] redirects = { diff --git a/doc/ext/header_reader.py b/doc/ext/header_reader.py index ebc5ca82..42a93a14 100644 --- a/doc/ext/header_reader.py +++ b/doc/ext/header_reader.py @@ -38,7 +38,7 @@ _STRUCT_END_REGEX_2 = re.compile(r'^}\s+(?Pmj\w+);') _ENUM_END_REGEX = re.compile(r'^}\s+(?Pmj\w+);') -@dataclasses.dataclass(frozen=True) +@dataclasses.dataclass class ApiDefinition: """Defines a C reference parsed from a C header file.""" token: str diff --git a/doc/functions.rst b/doc/functions.rst index d7560156..161a676a 100644 --- a/doc/functions.rst +++ b/doc/functions.rst @@ -1,3 +1,7 @@ +.. + AUTOGENERATE: DO NOT EDIT + + .. _Activation: Activation @@ -12,7 +16,7 @@ mj_activate .. mujoco-include:: mj_activate -Does nothing, returns 1. +Return 1 (for backward compatibility). .. _mj_deactivate: @@ -21,7 +25,7 @@ mj_deactivate .. mujoco-include:: mj_deactivate -Does nothing. +Do nothing (for backward compatibility). .. _Virtualfilesystem: @@ -58,7 +62,7 @@ mj_addFileVFS .. mujoco-include:: mj_addFileVFS -Add file to VFS, return 0: success, 1: full, 2: repeated name, -1: not found on disk. +Add file to VFS, return 0: success, 1: full, 2: repeated name, -1: failed to load. .. _mj_makeEmptyFileVFS: @@ -112,8 +116,9 @@ mj_loadXML .. mujoco-include:: mj_loadXML -Parse XML file in MJCF or URDF format, compile it, return low-level model. If vfs is not NULL, look up files in vfs -before reading from disk. If error is not NULL, it must have size error_sz. +Parse XML file in MJCF or URDF format, compile it, return low-level model. +If vfs is not ``NULL``, look up files in vfs before reading from disk. +If error is not ``NULL``, it must have size error_sz. .. _mj_saveLastXML: @@ -122,8 +127,8 @@ mj_saveLastXML .. mujoco-include:: mj_saveLastXML -Update XML data structures with info from low-level model, save as MJCF. If error is not NULL, it must have size -error_sz. +Update XML data structures with info from low-level model, save as MJCF. +If error is not ``NULL``, it must have size error_sz. .. _mj_freeLastXML: @@ -286,7 +291,7 @@ mj_copyModel .. mujoco-include:: mj_copyModel -Copy mjModel, allocate new if dest is NULL. +Copy ``mjModel``, allocate new if dest is ``NULL``. .. _mj_saveModel: @@ -304,7 +309,8 @@ mj_loadModel .. mujoco-include:: mj_loadModel -Load model from binary MJB file. If vfs is not NULL, look up file in vfs before reading from disk. +Load model from binary MJB file. +If vfs is not ``NULL``, look up file in vfs before reading from disk. .. _mj_deleteModel: @@ -331,7 +337,8 @@ mj_makeData .. mujoco-include:: mj_makeData -Allocate mjData corresponding to given model. +Allocate ``mjData`` corresponding to given model. +If the model buffer is unallocated the initial configuration will not be set. .. _mj_copyData: @@ -340,7 +347,8 @@ mj_copyData .. mujoco-include:: mj_copyData -Copy mjData. +Copy ``mjData``. +m is only required to contain the size fields from MJMODEL_INTS. .. _mj_resetData: @@ -376,7 +384,7 @@ mj_stackAlloc .. mujoco-include:: mj_stackAlloc -Allocate array of specified size on mjData stack. Call mju_error on stack overflow. +Allocate array of specified size on ``mjData`` stack. Call mju_error on stack overflow. .. _mj_deleteData: @@ -385,7 +393,7 @@ mj_deleteData .. mujoco-include:: mj_deleteData -Free memory allocation in mjData. +Free memory allocation in ``mjData``. .. _mj_resetCallbacks: @@ -394,7 +402,7 @@ mj_resetCallbacks .. mujoco-include:: mj_resetCallbacks -Reset all callbacks to NULL pointers (NULL is the default). +Reset all callbacks to ``NULL`` pointers (``NULL`` is the default). .. _mj_setConst: @@ -403,7 +411,7 @@ mj_setConst .. mujoco-include:: mj_setConst -Set constant fields of mjModel, corresponding to qpos0 configuration. +Set constant fields of ``mjModel``, corresponding to qpos0 configuration. .. _mj_setLengthRange: @@ -421,7 +429,6 @@ Printing These functions can be used to print various quantities to the screen for debugging purposes. - .. _mj_printFormattedModel: mj_printFormattedModel @@ -429,8 +436,8 @@ mj_printFormattedModel .. mujoco-include:: mj_printFormattedModel -Print ``mjModel`` to text file, specifying format. ``float_format`` must be a valid printf-style format string for a -single float value. +Print ``mjModel`` to text file, specifying format. +float_format must be a valid printf-style format string for a single float value. .. _mj_printModel: @@ -444,12 +451,12 @@ Print model to text file. .. _mj_printFormattedData: mj_printFormattedData -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_printFormattedData -Print ``mjData`` to text file, specifying format. ``float_format`` must be a valid printf-style format string for a -single float value. +Print ``mjData`` to text file, specifying format. +float_format must be a valid printf-style format string for a single float value .. _mj_printData: @@ -683,6 +690,8 @@ mj_comPos Map inertias and motion dofs to global frame centered at CoM. +.. _mj_camlight: + mj_camlight ~~~~~~~~~~~ @@ -690,6 +699,8 @@ mj_camlight Compute camera and light positions and orientations. +.. _mj_tendon: + mj_tendon ~~~~~~~~~ @@ -697,6 +708,8 @@ mj_tendon Compute tendon lengths, velocities and moment arms. +.. _mj_transmission: + mj_transmission ~~~~~~~~~~~~~~~ @@ -704,6 +717,8 @@ mj_transmission Compute actuator transmission lengths and moments. +.. _mj_crb: + mj_crb ~~~~~~ @@ -747,6 +762,8 @@ mj_comVel Compute cvel, cdof_dot. +.. _mj_passive: + mj_passive ~~~~~~~~~~ @@ -763,6 +780,8 @@ mj_subtreeVel subtree linear velocity and angular momentum +.. _mj_rne: + mj_rne ~~~~~~ @@ -815,14 +834,14 @@ mj_referenceConstraint Compute efc_vel, efc_aref. -. _mj_constraintUpdate: +.. _mj_constraintUpdate: mj_constraintUpdate ~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_constraintUpdate -Compute efc_state, efc_force, qfrc_constraint, and (optionally) cone Hessians. If cost is not NULL, set \*cost = s(jar) +Compute efc_state, efc_force, qfrc_constraint, and (optionally) cone Hessians. If cost is not ``NULL``, set \*cost = s(jar) where jar = Jac*qacc-aref. .. _Support: @@ -877,7 +896,7 @@ mj_mulJacVec .. mujoco-include:: mj_mulJacVec -This function multiplies the constraint Jacobian mjData.efc_J by a vector. Note that the Jacobian can be either dense or +This function multiplies the constraint Jacobian ``mjData.efc_J`` by a vector. Note that the Jacobian can be either dense or sparse; the function is aware of this setting. Multiplication by J maps velocities from joint space to constraint space. .. _mj_mulJacTVec: @@ -899,7 +918,7 @@ mj_jac This function computes an "end-effector" Jacobian, which is unrelated to the constraint Jacobian above. Any MuJoCo body can be treated as end-effector, and the point for which the Jacobian is computed can be anywhere in space (it is treated -as attached to the body). The Jacobian has translational (jacp) and rotational (jacr) components. Passing NULL for +as attached to the body). The Jacobian has translational (jacp) and rotational (jacr) components. Passing ``NULL`` for either pointer will skip part of the computation. Each component is a 3-by-nv matrix. Each row of this matrix is the gradient of the corresponding 3D coordinate of the specified point with respect to the degrees of freedom. The ability to compute end-effector Jacobians analytically is one of the advantages of working in minimal coordinates - so use it! @@ -930,7 +949,7 @@ mj_jacSubtreeCom .. mujoco-include:: mj_jacSubtreeCom -Compute subtree center-of-mass end-effector Jacobian. ``jacp`` is 3 x nv. +Compute subtree center-of-mass end-effector Jacobian. .. _mj_jacGeom: @@ -993,7 +1012,7 @@ mj_mulM .. mujoco-include:: mj_mulM -This function multiplies the joint-space inertia matrix stored in mjData.qM by a vector. qM has a custom sparse format +This function multiplies the joint-space inertia matrix stored in ``mjData.qM`` by a vector. qM has a custom sparse format that the user should not attempt to manipulate directly. Alternatively one can convert qM to a dense matrix with mj_fullM and then user regular matrix-vector multiplication, but this is slower because it no longer benefits from sparsity. @@ -1014,7 +1033,8 @@ mj_addM .. mujoco-include:: mj_addM -Add inertia matrix to destination matrix. Destination can be sparse uncompressed, or dense when all int\* are NULL +Add inertia matrix to destination matrix. +Destination can be sparse uncompressed, or dense when all int* are ``NULL`` .. _mj_applyFT: @@ -1024,7 +1044,7 @@ mj_applyFT .. mujoco-include:: mj_applyFT This function can be used to apply a Cartesian force and torque to a point on a body, and add the result to the vector -mjData.qfrc_applied of all applied forces. Note that the function requires a pointer to this vector, because sometimes +``mjData.qfrc_applied`` of all applied forces. Note that the function requires a pointer to this vector, because sometimes we want to add the result to a different vector. .. _mj_objectVelocity: @@ -1113,6 +1133,36 @@ mj_setTotalmass Scale body masses and inertias to achieve specified total mass. +.. _mj_getPluginConfig: + +mj_getPluginConfig +~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mj_getPluginConfig + +Return a config attribute value of a plugin instance; +``NULL``: invalid plugin instance ID or attribute name + +.. _mj_loadPluginLibrary: + +mj_loadPluginLibrary +~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mj_loadPluginLibrary + +Load a dynamic library. The dynamic library is assumed to register one or more plugins. + +.. _mj_loadAllPluginLibraries: + +mj_loadAllPluginLibraries +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mj_loadAllPluginLibraries + +Scan a directory and load all dynamic libraries. Dynamic libraries in the specified directory +are assumed to register one or more plugins. Optionally, if a callback is specified, it is called +for each dynamic library encountered that registers plugins. + .. _mj_version: mj_version @@ -1122,7 +1172,7 @@ mj_version Return version number: 1.0.2 is encoded as 102. -.. mj_versionString: +.. _mj_versionString: mj_versionString ~~~~~~~~~~~~~~~~ @@ -1155,7 +1205,7 @@ mj_ray Intersect ray (pnt+x*vec, x>=0) with visible geoms, except geoms in bodyexclude. Return geomid and distance (x) to nearest surface, or -1 if no intersection. -geomgroup is an array of length mjNGROUP, where 1 means the group should be included. Pass geomgroup=NULL to skip +geomgroup is an array of length mjNGROUP, where 1 means the group should be included. Pass geomgroup=``NULL`` to skip group exclusion. If flg_static is 0, static geoms will be excluded. bodyexclude=-1 can be used to indicate that all bodies are included. @@ -1167,7 +1217,7 @@ mj_rayHfield .. mujoco-include:: mj_rayHfield -Interect ray with hfield, return nearest distance or -1 if no intersection. +Intersect ray with hfield, return nearest distance or -1 if no intersection. .. _mj_rayMesh: @@ -1176,7 +1226,7 @@ mj_rayMesh .. mujoco-include:: mj_rayMesh -Interect ray with mesh, return nearest distance or -1 if no intersection. +Intersect ray with mesh, return nearest distance or -1 if no intersection. .. _mju_rayGeom: @@ -1185,7 +1235,7 @@ mju_rayGeom .. mujoco-include:: mju_rayGeom -Interect ray with pure geom, return nearest distance or -1 if no intersection. +Intersect ray with pure geom, return nearest distance or -1 if no intersection. .. _mju_raySkin: @@ -1194,7 +1244,8 @@ mju_raySkin .. mujoco-include:: mju_raySkin -Interect ray with skin, return nearest vertex id. +Intersect ray with skin, return nearest distance or -1 if no intersection, +and also output nearest vertex id. .. _Interaction: @@ -1328,8 +1379,8 @@ mjv_applyPerturbPose .. mujoco-include:: mjv_applyPerturbPose -Set perturb pos,quat in d->mocap when selected body is mocap, and in d->qpos otherwise. Write d->qpos only if flg_paused -and subtree root for selected body has free joint. +Set perturb pos,quat in d->mocap when selected body is mocap, and in d->qpos otherwise. +Write d->qpos only if flg_paused and subtree root for selected body has free joint. .. _mjv_applyPerturbForce: @@ -1396,7 +1447,7 @@ mjv_initGeom .. mujoco-include:: mjv_initGeom -Initialize given geom fields when not NULL, set the rest to their default values. +Initialize given geom fields when not ``NULL``, set the rest to their default values. .. _mjv_makeConnector: @@ -1405,8 +1456,8 @@ mjv_makeConnector .. mujoco-include:: mjv_makeConnector -Set (type, size, pos, mat) for connector-type geom between given points. Assume that mjv_initGeom was already called to -set all other properties. +Set (type, size, pos, mat) for connector-type geom between given points. +Assume that mjv_initGeom was already called to set all other properties. .. _mjv_defaultScene: @@ -1576,8 +1627,8 @@ mjr_setBuffer .. mujoco-include:: mjr_setBuffer -Set OpenGL framebuffer for rendering: mjFB_WINDOW or mjFB_OFFSCREEN. If only one buffer is available, set that buffer -and ignore framebuffer argument. +Set OpenGL framebuffer for rendering: mjFB_WINDOW or mjFB_OFFSCREEN. +If only one buffer is available, set that buffer and ignore framebuffer argument. .. _mjr_readPixels: @@ -1586,8 +1637,8 @@ mjr_readPixels .. mujoco-include:: mjr_readPixels -Read pixels from current OpenGL framebuffer to client buffer. Viewport is in OpenGL framebuffer; client buffer starts at -(0,0). +Read pixels from current OpenGL framebuffer to client buffer. +Viewport is in OpenGL framebuffer; client buffer starts at (0,0). .. _mjr_drawPixels: @@ -1596,8 +1647,8 @@ mjr_drawPixels .. mujoco-include:: mjr_drawPixels -Draw pixels from client buffer to current OpenGL framebuffer. Viewport is in OpenGL framebuffer; client buffer starts at -(0,0). +Draw pixels from client buffer to current OpenGL framebuffer. +Viewport is in OpenGL framebuffer; client buffer starts at (0,0). .. _mjr_blitBuffer: @@ -1606,8 +1657,8 @@ mjr_blitBuffer .. mujoco-include:: mjr_blitBuffer -Blit from src viewpoint in current framebuffer to dst viewport in other framebuffer. If src, dst have different size and -flg_depth==0, color is interpolated with GL_LINEAR. +Blit from src viewpoint in current framebuffer to dst viewport in other framebuffer. +If src, dst have different size and flg_depth==0, color is interpolated with GL_LINEAR. .. _mjr_setAux: @@ -1666,7 +1717,7 @@ Draw rectangle. .. _mjr_label: mjr_label -~~~~~~~~~~~~~ +~~~~~~~~~ .. mujoco-include:: mjr_label @@ -1740,6 +1791,8 @@ mjui_themeColor Get builtin UI theme color (ind: 0-3). +.. _mjui_add: + mjui_add ~~~~~~~~ @@ -1747,6 +1800,8 @@ mjui_add Add definitions to UI. +.. _mjui_addToSection: + mjui_addToSection ~~~~~~~~~~~~~~~~~ @@ -1754,6 +1809,8 @@ mjui_addToSection Add definitions to UI section. +.. _mjui_resize: + mjui_resize ~~~~~~~~~~~ @@ -1770,12 +1827,16 @@ mjui_update Update specific section/item; -1: update all. +.. _mjui_event: + mjui_event ~~~~~~~~~~ .. mujoco-include:: mjui_event -Handle UI event, return pointer to changed item, NULL if no change. +Handle UI event, return pointer to changed item, ``NULL`` if no change. + +.. _mjui_render: mjui_render ~~~~~~~~~~~ @@ -1825,6 +1886,8 @@ mju_warning Main warning function; returns to caller. +.. _mju_warning_i: + mju_warning_i ~~~~~~~~~~~~~ @@ -1832,6 +1895,8 @@ mju_warning_i Warning function with int argument. +.. _mju_warning_s: + mju_warning_s ~~~~~~~~~~~~~ @@ -1873,7 +1938,7 @@ mj_warning .. mujoco-include:: mj_warning -High-level warning function: count warnings in mjData, print only the first. +High-level warning function: count warnings in ``mjData``, print only the first. .. _mju_writeLog: @@ -2006,6 +2071,8 @@ mju_ceil Vector math ^^^^^^^^^^^ +.. _mju_zero3: + mju_zero3 ~~~~~~~~~ @@ -2013,6 +2080,8 @@ mju_zero3 Set res = 0. +.. _mju_copy3: + mju_copy3 ~~~~~~~~~ @@ -2020,6 +2089,8 @@ mju_copy3 Set res = vec. +.. _mju_scl3: + mju_scl3 ~~~~~~~~ @@ -2027,6 +2098,8 @@ mju_scl3 Set res = vec*scl. +.. _mju_add3: + mju_add3 ~~~~~~~~ @@ -2034,6 +2107,8 @@ mju_add3 Set res = vec1 + vec2. +.. _mju_sub3: + mju_sub3 ~~~~~~~~ @@ -2077,6 +2152,8 @@ mju_addScl3 Set res = vec1 + vec2*scl. +.. _mju_normalize3: + mju_normalize3 ~~~~~~~~~~~~~~ @@ -2084,6 +2161,8 @@ mju_normalize3 Normalize vector, return length before normalization. +.. _mju_norm3: + mju_norm3 ~~~~~~~~~ @@ -2091,6 +2170,8 @@ mju_norm3 Return vector length (without normalizing the vector). +.. _mju_dot3: + mju_dot3 ~~~~~~~~ @@ -2098,6 +2179,8 @@ mju_dot3 Return dot-product of vec1 and vec2. +.. _mju_dist3: + mju_dist3 ~~~~~~~~~ @@ -2112,7 +2195,7 @@ mju_rotVecMat .. mujoco-include:: mju_rotVecMat -Multiply vector by 3D rotation matrix: res = mat \* vec. +Multiply vector by 3D rotation matrix: res = mat * vec. .. _mju_rotVecMatT: @@ -2121,7 +2204,9 @@ mju_rotVecMatT .. mujoco-include:: mju_rotVecMatT -Multiply vector by transposed 3D rotation matrix: res = mat' \* vec. +Multiply vector by transposed 3D rotation matrix: res = mat' * vec. + +.. _mju_cross: mju_cross ~~~~~~~~~ @@ -2130,6 +2215,8 @@ mju_cross Compute cross-product: res = cross(a, b). +.. _mju_zero4: + mju_zero4 ~~~~~~~~~ @@ -2137,6 +2224,8 @@ mju_zero4 Set res = 0. +.. _mju_unit4: + mju_unit4 ~~~~~~~~~ @@ -2144,6 +2233,8 @@ mju_unit4 Set res = (1,0,0,0). +.. _mju_copy4: + mju_copy4 ~~~~~~~~~ @@ -2151,6 +2242,8 @@ mju_copy4 Set res = vec. +.. _mju_normalize4: + mju_normalize4 ~~~~~~~~~~~~~~ @@ -2158,6 +2251,8 @@ mju_normalize4 Normalize vector, return length before normalization. +.. _mju_zero: + mju_zero ~~~~~~~~ @@ -2174,6 +2269,8 @@ mju_fill Set res = val. +.. _mju_copy: + mju_copy ~~~~~~~~ @@ -2181,6 +2278,8 @@ mju_copy Set res = vec. +.. _mju_sum: + mju_sum ~~~~~~~ @@ -2206,6 +2305,8 @@ mju_scl Set res = vec*scl. +.. _mju_add: + mju_add ~~~~~~~ @@ -2213,6 +2314,8 @@ mju_add Set res = vec1 + vec2. +.. _mju_sub: + mju_sub ~~~~~~~ @@ -2256,6 +2359,8 @@ mju_addScl Set res = vec1 + vec2*scl. +.. _mju_normalize: + mju_normalize ~~~~~~~~~~~~~ @@ -2263,6 +2368,8 @@ mju_normalize Normalize vector, return length before normalization. +.. _mju_norm: + mju_norm ~~~~~~~~ @@ -2270,6 +2377,8 @@ mju_norm Return vector length (without normalizing vector). +.. _mju_dot: + mju_dot ~~~~~~~ @@ -2284,7 +2393,7 @@ mju_mulMatVec .. mujoco-include:: mju_mulMatVec -Multiply matrix and vector: res = mat \* vec. +Multiply matrix and vector: res = mat * vec. .. _mju_mulMatTVec: @@ -2293,7 +2402,7 @@ mju_mulMatTVec .. mujoco-include:: mju_mulMatTVec -Multiply transposed matrix and vector: res = mat' \* vec. +Multiply transposed matrix and vector: res = mat' * vec. .. _mju_mulVecMatVec: @@ -2302,7 +2411,9 @@ mju_mulVecMatVec .. mujoco-include:: mju_mulVecMatVec -Multiply square matrix with vectors on both sides: return vec1' \* mat \* vec2. +Multiply square matrix with vectors on both sides: returns vec1' * mat * vec2. + +.. _mju_transpose: mju_transpose ~~~~~~~~~~~~~ @@ -2336,7 +2447,7 @@ mju_mulMatMat .. mujoco-include:: mju_mulMatMat -Multiply matrices: res = mat1 \* mat2. +Multiply matrices: res = mat1 * mat2. .. _mju_mulMatMatT: @@ -2345,7 +2456,7 @@ mju_mulMatMatT .. mujoco-include:: mju_mulMatMatT -Multiply matrices, second argument transposed: res = mat1 \* mat2'. +Multiply matrices, second argument transposed: res = mat1 * mat2'. .. _mju_mulMatTMat: @@ -2354,7 +2465,7 @@ mju_mulMatTMat .. mujoco-include:: mju_mulMatTMat -Multiply matrices, first argument transposed: res = mat1' \* mat2. +Multiply matrices, first argument transposed: res = mat1' * mat2. .. _mju_sqrMatTD: @@ -2363,7 +2474,7 @@ mju_sqrMatTD .. mujoco-include:: mju_sqrMatTD -Set res = mat' \* diag \* mat if diag is not NULL, and res = mat' \* mat otherwise. +Set res = mat' * diag * mat if diag is not ``NULL``, and res = mat' * mat otherwise. .. _mju_transformSpatial: @@ -2372,8 +2483,8 @@ mju_transformSpatial .. mujoco-include:: mju_transformSpatial -Coordinate transform of 6D motion or force vector in rotation:translation format. rotnew2old is 3-by-3, NULL means no -rotation; flg_force specifies force or motion type. +Coordinate transform of 6D motion or force vector in rotation:translation format. +rotnew2old is 3-by-3, ``NULL`` means no rotation; flg_force specifies force or motion type. .. _Quaternions: @@ -2396,7 +2507,7 @@ mju_negQuat .. mujoco-include:: mju_negQuat -Negate quaternion. +Conjugate quaternion, corresponding to opposite rotation. .. _mju_mulQuat: @@ -2509,7 +2620,7 @@ mju_negPose .. mujoco-include:: mju_negPose -Negate pose. +Conjugate pose, corresponding to the opposite spatial transformation. .. _mju_trnVecPose: @@ -2522,8 +2633,8 @@ Transform vector by pose. .. _Decompositions: -Decompositions -^^^^^^^^^^^^^^ +Decompositions / Solvers +^^^^^^^^^^^^^^^^^^^^^^^^ .. _mju_cholFactor: @@ -2541,7 +2652,7 @@ mju_cholSolve .. mujoco-include:: mju_cholSolve -Solve mat \* res = vec, where mat is Cholesky-factorized +Solve mat * res = vec, where mat is Cholesky-factorized .. _mju_cholUpdate: @@ -2552,6 +2663,8 @@ mju_cholUpdate Cholesky rank-one update: L*L' +/- x*x'; return rank. +.. _mju_eig3: + mju_eig3 ~~~~~~~~ @@ -2687,6 +2800,17 @@ 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 ~~~~~~~~ @@ -2694,6 +2818,8 @@ mju_sign Return sign of x: +1, -1 or 0. +.. _mju_round: + mju_round ~~~~~~~~~ @@ -2726,7 +2852,7 @@ mju_writeNumBytes .. mujoco-include:: mju_writeNumBytes -Construct a human readable number of bytes using standard letter suffix. +Return human readable number of bytes using standard letter suffix. .. _mju_warningText: @@ -2764,6 +2890,8 @@ mju_standardNormal Standard normal random number generator (optional second number). +.. _mju_f2n: + mju_f2n ~~~~~~~ @@ -2771,6 +2899,8 @@ mju_f2n Convert from float to mjtNum. +.. _mju_n2f: + mju_n2f ~~~~~~~ @@ -2778,6 +2908,8 @@ mju_n2f Convert from mjtNum to float. +.. _mju_d2n: + mju_d2n ~~~~~~~ @@ -2785,6 +2917,8 @@ mju_d2n Convert from double to mjtNum. +.. _mju_n2d: + mju_n2d ~~~~~~~ @@ -2819,6 +2953,8 @@ mju_Halton Generate Halton sequence. +.. _mju_strncpy: + mju_strncpy ~~~~~~~~~~~ @@ -2826,6 +2962,8 @@ mju_strncpy Call strncpy, then set dst[n-1] = 0. +.. _mju_sigmoid: + mju_sigmoid ~~~~~~~~~~~ @@ -2833,6 +2971,11 @@ mju_sigmoid Sigmoid function over 0<=x<=1 constructed from half-quadratics. +.. _Derivatives-api: + +Derivatives +^^^^^^^^^^^ + .. _mjd_transitionFD: mjd_transitionFD @@ -2842,3 +2985,4 @@ mjd_transitionFD Finite differenced state-transition and control-transition matrices dx(t+h) = A*dx(t) + B*du(t). Required output matrix dimensions: A: (2*nv+na x 2*nv+na), B: (2*nv+na x nu). + diff --git a/doc/functions_override.rst b/doc/functions_override.rst new file mode 100644 index 00000000..6880aee3 --- /dev/null +++ b/doc/functions_override.rst @@ -0,0 +1,372 @@ +.. + This file contains each section text along with function doc overrides. By default the docs use the function doc + pulled from the header files. + +.. _Activation: + +The functions in this section are maintained for backward compatibility with the now-removed activation mechanism. + +.. _Virtualfilesystem: + +Virtual file system (VFS) functionality was introduced in MuJoCo 1.50. It enables the user to load all necessary files +in memory, including MJB binary model files, XML files (MJCF, URDF and included files), STL meshes, PNGs for textures +and height fields, and HF files in our custom height field format. Model and resource files in the VFS can also be +constructed programmatically (say using a Python library that writes to memory). Once all desired files are in the VFS, +the user can call :ref:`mj_loadModel` or :ref:`mj_loadXML` with a pointer to the VFS. When this pointer is not NULL, the +loaders will first check the VFS for any file they are about to load, and only access the disk if the file is not found +in the VFS. The file names stored in the VFS have their name and extension but the path information is stripped; this +can be bypassed however by using a custom path symbol in the file names, say "mydir_myfile.xml". + +The entire VFS is contained in the data structure :ref:`mjVFS`. All utility functions for maintaining the VFS operate on +this data structure. The common usage pattern is to first clear it with mj_defaultVFS, then add disk files to it with +mj_addFileVFS (which allocates memory buffers and loads the file content in memory), then call mj_loadXML or +mj_loadModel, and then clear everything with mj_deleteVFS. + +.. _Parseandcompile: + +The key function here is mj_loadXML. It invokes the built-in parser and compiler, and either returns a pointer to a +valid mjModel, or NULL - in which case the user should check the error information in the user-provided string. The +model and all files referenced in it can be loaded from disk or from a VFS when provided. + +.. _Mainsimulation: + +These are the main entry points to the simulator. Most users will only need to call ``mj_step``, which computes +everything and advanced the simulation state by one time step. Controls and applied forces must either be set in advance +(in mjData.ctrl, qfrc_applied and xfrc_applied), or a control callback mjcb_control must be installed which will be +called just before the controls and applied forces are needed. Alternatively, one can use ``mj_step1`` and ``mj_step2`` +which break down the simulation pipeline into computations that are executed before and after the controls are needed; +in this way one can set controls that depend on the results from ``mj_step1``. Keep in mind though that the RK4 solver +does not work with mj_step1/2. + +mj_forward performs the same computations as ``mj_step`` but without the integration. It is useful after loading or +resetting a model (to put the entire mjData in a valid state), and also for out-of-order computations that involve +sampling or finite-difference approximations. + +mj_inverse runs the inverse dynamics, and writes its output in mjData.qfrc_inverse. Note that mjData.qacc must be set +before calling this function. Given the state (qpos, qvel, act), mj_forward maps from force to acceleration, while +mj_inverse maps from acceleration to force. Mathematically these functions are inverse of each other, but numerically +this may not always be the case because the forward dynamics rely on a constraint optimization algorithm which is +usually terminated early. The difference between the results of forward and inverse dynamics can be computed with the +function :ref:`mj_compareFwdInv`, which can be though of as another solver accuracy check (as well as a general sanity +check). + +The skip version of mj_forward and mj_inverse are useful for example when qpos was unchanged but qvel was changed +(usually in the context of finite differencing). Then there is no point repeating the computations that only depend on +qpos. Calling the dynamics with skipstage = mjSTAGE_POS will achieve these savings. + +.. _Initialization: + +This section contains functions that load/initialize the model or other data structures. Their use is well illustrated +in the code samples. + +.. _Printing: + +These functions can be used to print various quantities to the screen for debugging purposes. + +.. _Components: + +These are components of the simulation pipeline, called internally from mj_step, mj_forward and mj_inverse. It is +unlikely that the user will need to call them. + +.. _Subcomponents: + +These are sub-components of the simulation pipeline, called internally from the components above. It is very unlikely +that the user will need to call them. + +.. _mj_factorM: + +Compute sparse :math:`L^T D L` factorizaton of inertia matrix. + +.. _mj_solveM: + +Solve linear system :math:`M x = y` using factorization: :math:`x = (L^T D L)^{-1} y` + +.. _mj_solveM2: + +Half of linear solve: :math:`x = \sqrt{D^{-1}} (L^T)^{-1} y` + +.. _mj_constraintUpdate: + +Compute efc_state, efc_force, qfrc_constraint, and (optionally) cone Hessians. If cost is not NULL, set \*cost = s(jar) +where jar = Jac*qacc-aref. + +.. _Support: + +These are support functions that need access to mjModel and mjData, unlike the utility functions which do not need such +access. Support functions are called within the simulator but some of them can also be useful for custom computations, +and are documented in more detail below. + +.. _mj_mulJacVec: + +This function multiplies the constraint Jacobian mjData.efc_J by a vector. Note that the Jacobian can be either dense or +sparse; the function is aware of this setting. Multiplication by J maps velocities from joint space to constraint space. + +.. _mj_mulJacTVec: + +Same as mj_mulJacVec but multiplies by the transpose of the Jacobian. This maps forces from constraint space to joint +space. + +.. _mj_jac: + +This function computes an "end-effector" Jacobian, which is unrelated to the constraint Jacobian above. Any MuJoCo body +can be treated as end-effector, and the point for which the Jacobian is computed can be anywhere in space (it is treated +as attached to the body). The Jacobian has translational (jacp) and rotational (jacr) components. Passing NULL for +either pointer will skip part of the computation. Each component is a 3-by-nv matrix. Each row of this matrix is the +gradient of the corresponding 3D coordinate of the specified point with respect to the degrees of freedom. The ability +to compute end-effector Jacobians analytically is one of the advantages of working in minimal coordinates - so use it! + +.. _mj_jacBody: + +This and the remaining variants of the Jacobian function call mj_jac internally, with the center of the body, geom or +site. They are just shortcuts; the same can be achieved by calling mj_jac directly. + +.. _mj_mulM: + +This function multiplies the joint-space inertia matrix stored in mjData.qM by a vector. qM has a custom sparse format +that the user should not attempt to manipulate directly. Alternatively one can convert qM to a dense matrix with +mj_fullM and then user regular matrix-vector multiplication, but this is slower because it no longer benefits from +sparsity. + +.. _mj_applyFT: + +This function can be used to apply a Cartesian force and torque to a point on a body, and add the result to the vector +mjData.qfrc_applied of all applied forces. Note that the function requires a pointer to this vector, because sometimes +we want to add the result to a different vector. + +.. _mj_differentiatePos: + +This function subtracts two vectors in the format of qpos (and divides the result by dt), while respecting the +properties of quaternions. Recall that unit quaternions represent spatial orientations. They are points on the unit +sphere in 4D. The tangent to that sphere is a 3D plane of rotational velocities. Thus when we subtract two quaternions +in the right way, the result is a 3D vector and not a 4D vector. This the output qvel has dimensionality nv while the +inputs have dimensionality nq. + +.. _mj_integratePos: + +This is the opposite of mj_differentiatePos. It adds a vector in the format of qvel (scaled by dt) to a vector in the +format of qpos. + +.. _Raycollisions: + +Ray collision functionality was added in MuJoCo 1.50. This is a new collision detection module that uses analytical +formulas to intersect a ray (p + x*v, x>=0) with a geom, where p is the origin of the ray and v is the vector specifying +the direction. All functions in this family return the distance to the nearest geom surface, or -1 if there is no +intersection. Note that if p is inside a geom, the ray will intersect the surface from the inside which still counts as +an intersection. + +All ray collision functions rely on quantities computed by :ref:`mj_kinematics` (see :ref:`mjData`), so must be called +after :ref:`mj_kinematics`, or functions that call it (e.g. :ref:`mj_fwdPosition`). + +.. _mj_ray: + +Intersect ray (pnt+x*vec, x>=0) with visible geoms, except geoms in bodyexclude. Return geomid and distance (x) to +nearest surface, or -1 if no intersection. + +geomgroup is an array of length mjNGROUP, where 1 means the group should be included. Pass geomgroup=NULL to skip +group exclusion. +If flg_static is 0, static geoms will be excluded. +bodyexclude=-1 can be used to indicate that all bodies are included. + +.. _Interaction: + +These function implement abstract mouse interactions, allowing control over cameras and perturbations. Their use is well +illustrated in :ref:`simulate.cc `. + +.. _mjv_select: + +This function is used for mouse selection. Previously selection was done via OpenGL, but as of MuJoCo 1.50 it relies on +ray intersections which are much more efficient. aspectratio is the viewport width/height. relx and rely are the +relative coordinates of the 2D point of interest in the viewport (usually mouse cursor). The function returns the id of +the geom under the specified 2D point, or -1 if there is no geom (note that they skybox if present is not a model geom). +The 3D coordinates of the clicked point are returned in selpnt. See :ref:`simulate.cc ` for an illustration. + +.. _Visualization-api: + +The functions in this section implement abstract visualization. The results are used by the OpenGL rendered, and can +also be used by users wishing to implement their own rendered, or hook up MuJoCo to advanced rendering tools such as +Unity or Unreal Engine. See :ref:`simulate.cc ` for illustration of how to use these functions. + +.. _OpenGLrendering: + +These functions expose the OpenGL renderer. See :ref:`simulate.cc ` for an illustration +of how to use these functions. + +.. _UIframework: + +.. _Errorandmemory: + +.. _Standardmath: + +The "functions" in this section are preprocessor macros replaced with the corresponding C standard library math +functions. When MuJoCo is compiled with single precision (which is not currently available to the public, but we +sometimes use it internally) these macros are replaced with the corresponding single-precision functions (not shown +here). So one can think of them as having inputs and outputs of type mjtNum, where mjtNum is defined as double or float +depending on how MuJoCo is compiled. We will not document these functions here; see the C standard library +specification. + +mju_sqrt +~~~~~~~~ + +.. code-block:: C + + #define mju_sqrt sqrt + +mju_exp +~~~~~~~ + +.. code-block:: C + + #define mju_exp exp + +mju_sin +~~~~~~~ + +.. code-block:: C + + #define mju_sin sin + +mju_cos +~~~~~~~ + +.. code-block:: C + + #define mju_cos cos + +mju_tan +~~~~~~~ + +.. code-block:: C + + #define mju_tan tan + +mju_asin +~~~~~~~~ + +.. code-block:: C + + #define mju_asin asin + +mju_acos +~~~~~~~~ + +.. code-block:: C + + #define mju_acos acos + +mju_atan2 +~~~~~~~~~ + +.. code-block:: C + + #define mju_atan2 atan2 + +mju_tanh +~~~~~~~~ + +.. code-block:: C + + #define mju_tanh tanh + +mju_pow +~~~~~~~ + +.. code-block:: C + + #define mju_pow pow + +mju_abs +~~~~~~~ + +.. code-block:: C + + #define mju_abs fabs + +mju_log +~~~~~~~ + +.. code-block:: C + + #define mju_log log + +mju_log10 +~~~~~~~~~ + +.. code-block:: C + + #define mju_log10 log10 + +mju_floor +~~~~~~~~~ + +.. code-block:: C + + #define mju_floor floor + +mju_ceil +~~~~~~~~ + +.. code-block:: C + + #define mju_ceil ceil + +.. _Vectormath: + +.. _Quaternions: + +.. _Poses: + +.. _Decompositions: + +.. _mju_boxQP: + +Minimize :math:`\tfrac{1}{2} x^T H x + x^T g \quad \text{s.t.} \quad l \le x \le u`, return rank or -1 if failed. + +inputs: + ``n`` - problem dimension + + ``H`` - SPD matrix ``n*n`` + + ``g`` - bias vector ``n`` + + ``lower`` - lower bounds ``n`` + + ``upper`` - upper bounds ``n`` + + ``res`` - solution warmstart ``n`` + +return value: + ``nfree <= n`` - rank of unconstrained subspace, -1 if failure + +outputs (required): + ``res`` - solution ``n`` + + ``R`` - subspace Cholesky factor ``nfree*nfree``, allocated: ``n*(n+7)`` + +outputs (optional): + ``index`` - set of free dimensions ``nfree``, allocated: ``n`` + +notes: + The initial value of ``res`` is used to warmstart the solver. + ``R`` must have allocatd size ``n*(n+7)``, but only ``nfree*nfree`` values are used in output. + ``index`` (if given) must have allocated size ``n``, but only ``nfree`` values are used in output. + The convenience function :ref:`mju_boxQPmalloc` allocates the required data structures. + Only the lower triangles of H and R and are read from and written to, respectively. + +.. _mju_boxQPmalloc: + +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()``. + +.. _mju_symmetrize: + +Symmetrize square matrix :math:`R = \frac{1}{2}(M + M^T)`. + +.. _Miscellaneous: + +.. _Derivatives-api: + +.. _mjd_transitionFD: + +Finite differenced state-transition and control-transition matrices dx(t+h) = A*dx(t) + B*du(t). Required output matrix +dimensions: A: (2*nv+na x 2*nv+na), B: (2*nv+na x nu).