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

Improve compiler-related documentation.

Browse Source 
PiperOrigin-RevId: 651827545
Change-Id: I85c12dc12967e49087c342445dbfa049c5cdbcdf
This commit is contained in:
Yuval Tassa
2024-07-12 11:04:20 -07:00
committed by Copybara-Service
parent 5d51b4cd5f
commit e13ddfa2ab
8 changed files with 213 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/programming/index.rst
+4 -4
View File
@@ -110,7 +110,7 @@ To build MuJoCo from source, you will need CMake and a working C++17 compiler in
#. 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 :shell:`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
@@ -123,11 +123,11 @@ 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.
5. Select the directory: ``cmake $PATH_TO_CLONED_REPO -DCMAKE_INSTALL_PREFIX=<my_install_dir>``
5. Select the directory: :shell:`cmake $PATH_TO_CLONED_REPO -DCMAKE_INSTALL_PREFIX=<my_install_dir>`
#. After building, install with ``cmake --install .``
When building on Windows, use Visual Studio 2019 or later and make sure Windows SDK version 10.0.22000 or later is
installed (see `here <https://github.com/google-deepmind/mujoco/issues/862>`__ for more details).
installed (see :github:issue:`862` for more details).
.. tip::
As a reference, a working build configuration can be found in MuJoCo's
@@ -198,7 +198,7 @@ the symbol :ref:`mjVERSION_HEADER <glNumeric>` and the library provides the func
.. code-block:: C
// recommended version check
if( mjVERSION_HEADER!=mj_version() )
if (mjVERSION_HEADER!=mj_version())
complain();
Note that only the main header defines this symbol. We assume that the collection of headers released with each software
doc/programming/modeledit.rst
+85 -14
View File
@@ -17,28 +17,99 @@ use this API when loading a model.
Overview
~~~~~~~~
As summarized in the the :ref:`Overview chapter<Instance>`, the traditional workflow to create compiled :ref:`mjModel`
instances is:
The new API augments the traditional workflow of creating and editing models using XML files, breaking up the *parse* and
*compile* steps. As summarized in the the :ref:`Overview chapter<Instance>`, the traditional workflow is:
1. Create an XML model description file (MJCF or URDF).
2. Call :ref:`mj_loadXML` passing in the XML (and associated assets), obtain an :ref:`mjModel` instance.
1. Create an XML model description file (MJCF or URDF) and ascociated assets. |br|
2. Call :ref:`mj_loadXML`, obtain an :ref:`mjModel` instance.
The new workflow looks like:
The new workflow is:
1. Create an :ref:`mjSpec`, either an empty one corresponding to the XML ``<mujoco/>``, or by loading an existing XML
file.
2. Modify the :ref:`mjSpec` as desired, adding, editing and removing elements.
3. Compile the :ref:`mjSpec` at any point, obtaining an updated :ref:`mjModel` instance. After compilation, the
:ref:`mjSpec` remains editable, so steps 2 and 3 are interchangable.
1. :ref:`Create<mj_makeSpec>` an empty :ref:`mjSpec` or :ref:`parse<mj_parseXML>` an existing XML file to an
:ref:`mjSpec`.
2. Edit the mutable :ref:`mjSpec` datastructure adding, changing and removing elements.
3. Compile the :ref:`mjSpec` at any point, obtaining an updated :ref:`mjModel` instance. After compilation, the
:ref:`mjSpec` remains editable, so steps 2 and 3 are interchangable.
.. _meUsage:
Usage
~~~~~
Here we describe the C API for procedural model editing, but it is also exposed in the
:ref:`Python bindings<PyModelEdit>`.
After creating a new :ref:`mjSpec` or parsing an existing XML file to an :ref:`mjSpec`, procedural editing corresponds
to setting attributes. For example, in order to change the timestep, one can do:
Detailed documentation is still missing. In the meantime, advanced users can refer to
`user_api_test.cc <https://github.com/google-deepmind/mujoco/blob/main/test/user/user_api_test.cc>`__ and the MJCF
parser in `xml_native_reader.cc <https://github.com/google-deepmind/mujoco/blob/main/src/xml/xml_native_reader.cc>`__,
which is already using this API.
.. code-block:: C
mjSpec* spec = mj_makeSpec();
spec->opt.timestep = 0.01;
...
mjModel* model = mj_compile(spec);
Attributes which have variable length are C++ vectors and strings, :ref:`exposed to C as opaque types<ArrayHandles>`.
In C one uses the provided :ref:`getters<AttributeGetters>` and :ref:`setters<AttributeSetters>`:
.. code-block:: C
mjs_setString(model->modelname, "my_model");
In C++ one can use these directly:
.. code-block:: C++
std::string modelname = "my_model";
*spec->modelname = modelname;
.. _meMjsElements:
Model elements
^^^^^^^^^^^^^^
Model elements corresponding to MJCF are added to the spec using the corresponding functions. For example, to add a box
geom to the world body, one would do
.. code-block:: C
mjSpec* spec = mj_makeSpec();
mjsBody* world = mjs_findBody(spec, "world");
mjsGeom* my_geom = mjs_addGeom(world, NULL);
my_geom->type = mjGEOM_BOX;
my_geom->size[0] = my_geom->size[1] = my_geom->size[2] = 0.5;
mjModel* model = mj_compile(spec);
The ``NULL`` second argument to :ref:`mjs_addGeom` is the optional default class pointer. When using defaults
procedurally, default classes are passed in explicitly to element constructors. The global defaults of all elements
(used when no default class is passed in) can be inspected in
`user_init.c <https://github.com/google-deepmind/mujoco/blob/main/src/user/user_init.c>`__.
.. _meAttachment:
Attachment
^^^^^^^^^^
The new framework introduces a powerful new feature: attaching and detaching model subtrees. Attachment allows the user
copy a subtree from one model into another, while also copying related referenced assets and referencing elements from
outside the kinematic tree (e.g., actuators and sensors). Similarly, detaching a subtree will remove all associated
elements from the model.
This feature is incomplete and will be described in detail once it is fully implemented, but it is already used to power
the :ref:`attach<body-attach>` and :ref:`replicate<replicate>` meta-elements in MJCF.
.. _meKnownIssues:
Known issues
~~~~~~~~~~~~
- Better documentation is still missing and will be added in the future. In the meantime, advanced users can refer
to `user_api_test.cc <https://github.com/google-deepmind/mujoco/blob/main/test/user/user_api_test.cc>`__ and the MJCF
parser in `xml_native_reader.cc <https://github.com/google-deepmind/mujoco/blob/main/src/xml/xml_native_reader.cc>`__,
which is already using this API.
- One of the central design consideration of the new API is incremental compilation, meaning that after making small
changes to a spec that has already been compiled, subsequent re-compilation will be very fast. While the code is
written to support inceremntal compilation, this functionality is not fully implemented and will be added in the
future, resulting in faster re-compilation times.
- Since the main test for the new API is the MJCF parser, which always constructs a model from scratch, there
might be latent bugs related to model editing. Please report such bugs if you encounter them.