Rename Python mujoco.simulate to mujoco.viewer.

PiperOrigin-RevId: 492701386
Change-Id: I059c572e2a63bd5529e863a9404720973df8ea46

doc/changelog.rst

@@ -9,8 +9,8 @@ Upcoming version (not yet released)
 Python bindings
 ^^^^^^^^^^^^^^^
 
-- The ``simulate`` GUI is now available through the ``mujoco`` Python package. See :ref:`documentation<PyGUI>` for
+- The ``simulate`` GUI is now available through the ``mujoco`` Python package as ``mujoco.viewer``.
-  details. (Contribution by `Levi Burner <https://github.com/aftersomemath>`_.)
+  See :ref:`documentation<PyViewer>` for details. (Contribution by `Levi Burner <https://github.com/aftersomemath>`_.)
 
 General
 ^^^^^^^

doc/python.rst

@@ -102,8 +102,41 @@ The Python bindings should now be installed! To check that they've been
 successfully installed, ``cd`` outside of the ``mujoco`` directory and run
 ``python -c "import mujoco"``.
 
+.. _PyViewer:
+
+Interactive viewer
+==================
+
+An interactive GUI viewer is available as part of the Python package. (This is the same viewer as the ``simulate``
+application that ships with the MuJoCo binary releases.)
+
+Three distinct use cases are supported:
+
+#. Launching as a standalone application:
+
+   - ``python -m mujoco.viewer`` launches an empty visualization session, where a model can be loaded by drag-and-drop.
+   - ``python -m mujoco.viewer --mjcf=/path/to/some/mjcf.xml`` launches a visualization session for the specified
+     model file.
+
+#. Launching from a Python program/script -- import the module via ``from mujoco import viewer`` and launch the GUI
+   using one of the following invocations:
+
+   - ``viewer.launch()`` launches an empty visualization session, where a model can be loaded by drag-and-drop.
+   - ``viewer.launch(model)`` launches a visualzation session for the given ``mjModel`` where the visualizer
+     internally creates its own instance of ``mjData``
+   - ``viewer.launch(model, data)`` is the same as above, except that the visualizer operates directly on the given
+     ``mjData`` instance -- upon exit the ``data`` object will have been modified.
+
+#. Launching from an interactive Python session (aka REPL): when working interactively either in a ``python`` or
+   ``ipython`` shell, the visualizer can be launched in a "passive" mode via ``viewer.launch_repl(model, data)``, where
+   the user remains in full control of modifying or stepping the physics. In this mode, the user can interact with the
+   visualizer using the mouse and keyboard as usual, however the physics will be frozen unless the user explicitly calls
+   ``mj_step`` (or perform any other modification of the ``mjData`` or ``mjModel``) in the REPL terminal. Note that since
+   the visualizer does not modify ``mjData`` in this mode, mouse-drag perturbations will not work unless the user
+   explicitly handles incoming GUI perturbation events in the REPL session.
+
 Basic usage
------------
+===========
 
 Once installed, the package can be imported via ``import mujoco``. Structs, functions, constants, and enums are
 available directly from the top-level ``mujoco`` module.
@@ -111,7 +144,7 @@ available directly from the top-level ``mujoco`` module.
 .. _PyStructs:
 
 Structs
-=======
+-------
 
 MuJoCo data structures are exposed as Python classes. In order to conform to
 `PEP 8 <https://peps.python.org/pep-0008/>`__ naming guidelines, struct names begin with a capital letter, for example
@@ -135,7 +168,7 @@ Structs
 dictionary which is converted into a MuJoCo :ref:`Virtualfilesystem` for use during model compilation.
 
 Functions
-=========
+---------
 
 MuJoCo functions are exposed as Python functions of the same name. Unlike with structs, we do not attempt to make
 the function names `PEP 8 <https://peps.python.org/pep-0008/>`__-compliant, as MuJoCo uses both underscores and
@@ -171,9 +204,8 @@ Functions
       for _ in range(20):
         mj_step(model, data)
 
-
 Enums and constants
-===================
+-------------------
 
 MuJoCo enums are available as ``mujoco.mjtEnumType.ENUM_VALUE``, for example ``mujoco.mjtObj.mjOBJ_SITE``. MuJoCo
 constants are available with the same name directly under the ``mujoco`` module, for example ``mujoco.mjVISSTRING``.
@@ -209,38 +241,6 @@ Minimal example
      mujoco.mj_step(model, data)
      print(data.geom_xpos)
 
-.. _PyGUI:
-
-Interactive visualizer
-----------------------
-
-MuJoCo's interactive GUI (also known as the ``simulate`` application) is available as part of the Python package.
-Three distinct use cases are supported:
-
-- Launching as a standalone application:
-
-   * ``python -m mujoco.simulate`` launches an empty visualization session, where a model can be loaded by drag-and-drop.
-   * ``python -m mujoco.simulate --mjcf=/path/to/some/mjcf.xml`` launches a visualization session for the specified
-     model file.
-
-- Launching from a Python program/script -- import the module via ``from mujoco import simulate`` and launch the GUI
-  using one of the following invocations:
-
-   * ``simulate.launch()`` launches an empty visualization session, where a model can be loaded by drag-and-drop.
-   * ``simulate.launch(model)`` launches a visualzation session for the given ``mjModel`` where the visualizer
-     internally creates its own instance of ``mjData``
-   * ``simulate.launch(model, data)`` is the same as above, except that the visualizer operates directly on the given
-     ``mjData`` instance -- upon exit the ``data`` object will have been modified.
-
-- Launching from an interactive Python session (aka REPL): when working interactively either in a ``python`` or
-  ``ipython`` shell, the visualizer can be launched in a "passive" mode via ``simulate.launch_repl(model, data)``, where
-  the user remains in full control of modifying or stepping the physics. In this mode, the user can interact with the
-  visualizer using the mouse and keyboard as usual, however the physics will be frozen unless the user explicitly calls
-  ``mj_step`` (or perform any other modification of the ``mjData`` or ``mjModel``) in the REPL terminal. Note that since
-  the visualizer does not modify ``mjData`` in this mode, mouse-drag perturbations will not work unless the user
-  explicitly handles incoming GUI perturbation events in the REPL session.
-
-
 .. _PyNamed:
 
 Named access
@@ -356,69 +356,8 @@ Alternatively, if a callback is implemented in a native dynamic library, users c
 it to ``mujoco.set_mjcb_foo``. The bindings will then retrieve the underlying function pointer and assign it directly to
 the raw callback pointer, and the GIL will **not** be acquired each time the callback is entered.
 
-.. _PyMjpy_migration:
-
-Migration Notes for mujoco-py
------------------------------
-
-In mujoco-py, the main entry point is the `MjSim <https://github.com/openai/mujoco-py/blob/master/mujoco_py/mjsim.pyx>`_
-class.  Users construct a stateful ``MjSim`` instance from an MJCF model (similar to ``dm_control.Physics``), and this
-instance holds references to an ``mjModel`` instance and its associated ``mjData``.  In contrast, the MuJoCo Python
-bindings (``mujoco``) take a more low-level approach, as explained above: following the design principle of the C
-library, the ``mujoco`` module itself is stateless, and merely wraps the underlying native structs and functions.
-
-While a complete survey of mujoco-py is beyond the scope of this document, we offer below implementation notes for a
-non-exhaustive list of specific mujoco-py features:
-
-``mujoco_py.load_model_from_xml(bstring)``
-===========================================
-
-This factory function constructs a stateful ``MjSim`` instance.  When using ``mujoco``, the user should call the factory
-function ``mujoco.MjModel.from_xml_*`` as described :ref:`above <PyStructs>`. The user is then responsible for holding
-the resulting ``MjModel`` struct instance and explicitly generating the corresponding ``MjData`` by calling
-``mujoco.MjData(model)``.
-
-``sim.reset()``, ``sim.forward()``, ``sim.step()``
-==================================================
-
-Here as above, ``mujoco`` users needs to call the underlying library functions, passing instances of ``MjModel`` and
-``MjData``: :ref:`mujoco.mj_resetData(model, data) <mj_resetData>`, :ref:`mujoco.mj_forward(model, data) <mj_forward>`,
-and :ref:`mujoco.mj_step(model, data) <mj_step>`.
-
-``sim.get_state()``, ``sim.set_state(state)``, ``sim.get_flattened_state()``, ``sim.set_state_from_flattened(state)``
-=====================================================================================================================
-
-The MuJoCo library’s computation is deterministic given a specific input, as explained in the :ref:`Programming section
-<Simulation>`.  mujoco-py implements methods for getting and setting some of the relevant fields (and similarly
-``dm_control.Physics`` offers methods that correspond to the flattened case).  ``mujoco`` do not offer such abstraction,
-and the user is expected to get/set the values of the relevant fields explicitly.
-
-``sim.model.get_joint_qvel_addr(joint_name)``
-=============================================
-
-This is a convenience method in mujoco-py that returns a list of contiguous indices corresponding to this joint. The
-list starts from ``model.jnt_qposadr[joint_index]``, and its length depends on the joint type.  ``mujoco`` doesn't offer
-this functionality, but this list can be easily constructed using ``model.jnt_qposadr[joint_index]`` and ``xrange``.
-
-``sim.model.*_name2id(name)``
-=============================
-
-mujoco-py creates dicts in ``MjSim`` that allow for efficient lookup of indices for objects of different types:
-``site_name2id``, ``body_name2id`` etc.  These functions replace the function :ref:`mujoco.mj_name2id(model, type_enum,
-name) <mj_name2id>` whose current implementation is inefficient.  ``mujoco`` offers a different
-approach for using entity names – :ref:`named access <PyNamed>`, as well as access to the native :ref:`mj_name2id`.
-
-``sim.save(fstream, format_name)``
-==================================
-
-This is the one context in which the MuJoCo library (and therefore also ``mujoco``) is stateful: it holds a copy in
-memory of the last XML that was compiled, which is used in :ref:`mujoco.mj_saveLastXML(fname) <mj_saveLastXML>`. Note
-that mujoco-py’s implementation has a convenient extra feature, whereby the pose (as determined by ``sim.data``’s
-state) is transformed to a keyframe that’s added to the model before saving.  This extra feature is not currently
-available in ``mujoco``.
-
 Code Sample: open-loop rollout
-------------------------------
+==============================
 
 We include a code sample showing how to add additional C/C++ functionality, exposed as a Python module via pybind11. The
 sample, implemented in ``rollout.cc`` and wrapped in ``rollout.py``, implements a common use case where tight loops
@@ -441,3 +380,64 @@ all inputs including ``time`` and ``qacc_warmstart`` are set to default values,
 
 Since the Global Interpreter Lock can be released, this function can be efficiently threaded using Python threads. See
 the ``test_threading`` function in ``rollout_test.py`` for an example of threaded operation.
+
+.. _PyMjpy_migration:
+
+Migration Notes for mujoco-py
+=============================
+
+In mujoco-py, the main entry point is the `MjSim <https://github.com/openai/mujoco-py/blob/master/mujoco_py/mjsim.pyx>`_
+class.  Users construct a stateful ``MjSim`` instance from an MJCF model (similar to ``dm_control.Physics``), and this
+instance holds references to an ``mjModel`` instance and its associated ``mjData``.  In contrast, the MuJoCo Python
+bindings (``mujoco``) take a more low-level approach, as explained above: following the design principle of the C
+library, the ``mujoco`` module itself is stateless, and merely wraps the underlying native structs and functions.
+
+While a complete survey of mujoco-py is beyond the scope of this document, we offer below implementation notes for a
+non-exhaustive list of specific mujoco-py features:
+
+``mujoco_py.load_model_from_xml(bstring)``
+------------------------------------------
+
+This factory function constructs a stateful ``MjSim`` instance.  When using ``mujoco``, the user should call the factory
+function ``mujoco.MjModel.from_xml_*`` as described :ref:`above <PyStructs>`. The user is then responsible for holding
+the resulting ``MjModel`` struct instance and explicitly generating the corresponding ``MjData`` by calling
+``mujoco.MjData(model)``.
+
+``sim.reset()``, ``sim.forward()``, ``sim.step()``
+--------------------------------------------------
+
+Here as above, ``mujoco`` users needs to call the underlying library functions, passing instances of ``MjModel`` and
+``MjData``: :ref:`mujoco.mj_resetData(model, data) <mj_resetData>`, :ref:`mujoco.mj_forward(model, data) <mj_forward>`,
+and :ref:`mujoco.mj_step(model, data) <mj_step>`.
+
+``sim.get_state()``, ``sim.set_state(state)``, ``sim.get_flattened_state()``, ``sim.set_state_from_flattened(state)``
+---------------------------------------------------------------------------------------------------------------------
+
+The MuJoCo library’s computation is deterministic given a specific input, as explained in the :ref:`Programming section
+<Simulation>`.  mujoco-py implements methods for getting and setting some of the relevant fields (and similarly
+``dm_control.Physics`` offers methods that correspond to the flattened case).  ``mujoco`` do not offer such abstraction,
+and the user is expected to get/set the values of the relevant fields explicitly.
+
+``sim.model.get_joint_qvel_addr(joint_name)``
+---------------------------------------------
+
+This is a convenience method in mujoco-py that returns a list of contiguous indices corresponding to this joint. The
+list starts from ``model.jnt_qposadr[joint_index]``, and its length depends on the joint type.  ``mujoco`` doesn't offer
+this functionality, but this list can be easily constructed using ``model.jnt_qposadr[joint_index]`` and ``xrange``.
+
+``sim.model.*_name2id(name)``
+-----------------------------
+
+mujoco-py creates dicts in ``MjSim`` that allow for efficient lookup of indices for objects of different types:
+``site_name2id``, ``body_name2id`` etc.  These functions replace the function :ref:`mujoco.mj_name2id(model, type_enum,
+name) <mj_name2id>` whose current implementation is inefficient.  ``mujoco`` offers a different
+approach for using entity names – :ref:`named access <PyNamed>`, as well as access to the native :ref:`mj_name2id`.
+
+``sim.save(fstream, format_name)``
+----------------------------------
+
+This is the one context in which the MuJoCo library (and therefore also ``mujoco``) is stateful: it holds a copy in
+memory of the last XML that was compiled, which is used in :ref:`mujoco.mj_saveLastXML(fname) <mj_saveLastXML>`. Note
+that mujoco-py’s implementation has a convenient extra feature, whereby the pose (as determined by ``sim.data``’s
+state) is transformed to a keyframe that’s added to the model before saving.  This extra feature is not currently
+available in ``mujoco``.

python/mujoco/viewer.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Python bindings for the Simulate GUI."""
+"""Interactive GUI viewer for MuJoCo."""
 
 import atexit
 import code
@@ -69,7 +69,7 @@ def _file_loader(path: str) -> _LoaderWithPathType:
 
 
 def _physics_loop(simulate: Simulate, loader: Optional[_InternalLoaderType]):
-  """Physics loop for the Simulate GUI, to be run in a separate thread."""
+  """Physics loop for the GUI, to be run in a separate thread."""
   m: mujoco.MjModel = None
   d: mujoco.MjData = None
   ctrlnoise = np.array([])