Make model editing API public, fixes #364

Still missing:

- Detailed documentation.
- Python bindings.

PiperOrigin-RevId: 641445626
Change-Id: I20e67b707cf1bebae7e0cc94d17f7b76a89171f0

doc/programming/index.rst

@@ -18,7 +18,7 @@ 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.
+   C++ object which is exposed to the user via mjSpec.
 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.
@@ -108,10 +108,10 @@ Building 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.
+#. 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.
@@ -123,8 +123,8 @@ 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>``
- #. After building, install with ``cmake --install .``
+5. Select the directory: ``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).
@@ -160,6 +160,8 @@ links below, to make this documentation self-contained.
    Defines the primitive types and structures needed by the UI framework.
 `mjtnum.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjtnum.h>`__
    Defines MuJoCo's ``mjtNum`` floating-point type to be either ``double`` or ``float``. See :ref:`mjtNum`.
+`mjspec.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjspec.h>`__
+   Defines enums and structs used for :doc:`procedural model editing <modeledit>`.
 `mjmacro.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmacro.h>`__
    Defines C macros that are useful in user code.
 `mjxmacro.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjxmacro.h>`__
@@ -226,6 +228,8 @@ to which the symbol belongs. First we list the prefixes corresponding to type de
    Data structure related to OpenGL rendering, for example :ref:`mjrContext`.
 ``mjui``
    Data structure related to UI framework, for example :ref:`mjuiSection`.
+``mjs``
+   Data structure related :doc:`procedural model editing <modeledit>`, for example :ref:`mjsJoint`.
 
 Next we list the prefixes corresponding to function definitions. Note that function prefixes always end with underscore.
 
@@ -247,6 +251,8 @@ Next we list the prefixes corresponding to function definitions. Note that funct
    custom callbacks by setting these global pointers to user-defined functions.
 ``mjd_``
    Functions for computing derivatives, for example :ref:`mjd_transitionFD`.
+``mjs_``
+   Functions for :doc:`procedural model editing <modeledit>`, for example :ref:`mjs_addJoint`.
 
 .. _inOpenGL:
 
@@ -276,5 +282,6 @@ now lazily resolved at runtime after the switch to GLAD, the "nogl" libraries ar
     simulation
     visualization
     ui
+    modeledit
     samples
     extension

doc/programming/modeledit.rst

@@ -0,0 +1,44 @@
+Model Editing
+-------------
+
+.. admonition:: Unstable API
+   :class: attention
+
+   The API described below is new and unstable. There may be latent bugs and function signatures may change. Early
+   adopters are welcome (indeed, encouraged) to try it out and report any issues on GitHub.
+
+As of MuJoCo 3.2, it is possible to create and modify models using the :ref:`mjSpec` struct and related API.
+This datastructure is in one-to-one correspondence with MJCF and indeed, MuJoCo's own XML parsers (both MJCF and URDF)
+use this API when loading a model.
+
+
+.. _meOverview:
+
+Overview
+~~~~~~~~
+
+As summarized in the the :ref:`Overview chapter<Instance>`, the traditional workflow to create compiled :ref:`mjModel`
+instances 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.
+
+The new workflow looks like:
+
+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.
+
+
+.. _meUsage:
+
+Usage
+~~~~~
+
+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.
+

doc/programming/simulation.rst

@@ -585,8 +585,8 @@ corresponding to precomputed quantities when the model is in the reference confi
 
 Finally, if changes are made to mjModel at runtime, it may be desirable to save them back to the XML. The function
 :ref:`mj_saveLastXML` does that in a limited sense: it copies all real-valued parameters from mjModel back to the
-internal mjCModel, and then saves it as XML. This does not cover all possible changes that the user could have made.
-The only way to guarantee that all changes are saved is to save the model as a binary MJB file with the function
+internal :ref:`mjSpec`, and then saves it as XML. This does not cover all possible changes that the user could have
+made. The only way to guarantee that all changes are saved is to save the model as a binary MJB file with the function
 :ref:`mj_saveModel`, or even better, make the changes directly in the XML. Unfortunately there are situations where
 changes need to be made programmatically, as in system identification for example, and this can only be done with the
 compiled model. So in summary, we have reasonable but not perfect mechanisms for saving model changes. The reason for