From f85cfb8ed238e08002578fce547b073cc0be6f5c Mon Sep 17 00:00:00 2001
From: Kevin Zakka <zakka@google.com>
Date: Tue, 4 Oct 2022 07:07:21 -0700
Subject: [PATCH] Fix broken simulate links.

PiperOrigin-RevId: 478775551
Change-Id: I1c4f43c7cbe01f267948f5915a7511744eb0d158
---
 doc/APIreference.rst | 30 ++++++++++++++-------------
 doc/XMLreference.rst | 12 +++++------
 doc/modeling.rst     | 19 +++++++++---------
 doc/overview.rst     |  3 +--
 doc/programming.rst  | 48 +++++++++++++++++++++-----------------------
 simulate/README.md   | 10 +++++++++
 6 files changed, 64 insertions(+), 58 deletions(-)
 create mode 100644 simulate/README.md

diff --git a/doc/APIreference.rst b/doc/APIreference.rst
index 9e689ec0..9b33a285 100644
--- a/doc/APIreference.rst
+++ b/doc/APIreference.rst
@@ -723,7 +723,7 @@ mjtMouse
 | Defined in `mjvisualize.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_
 
 | These are the mouse actions that the abstract visualizer recognizes. It is up to the user to intercept mouse events
-  and translate them into these actions, as illustrated in ``simulate.cc``.
+  and translate them into these actions, as illustrated in :ref:`simulate.cc <saSimulate>`.
 
 .. _mjtPertBit:
 
@@ -2960,9 +2960,9 @@ mjcb_time
    extern mjfTime mjcb_time;
 
 Installing this callback enables the built-in profiler, and keeps timing statistics in ``mjData.timer``. The return type
-is mjtNum, while the time units are up to the user. ``simulate.cc`` assumes the unit is 1 millisecond. In order to be
-useful, the callback should use high-resolution timers with at least microsecond precision. This is because the
-computations being timed are very fast.
+is mjtNum, while the time units are up to the user. :ref:`simulate.cc <saSimulate>` assumes the unit is 1 millisecond.
+In order to be useful, the callback should use high-resolution timers with at least microsecond precision. This is
+because the computations being timed are very fast.
 
 .. _mjcb_act_dyn:
 
@@ -3029,8 +3029,8 @@ String constants
 ^^^^^^^^^^^^^^^^
 
 The string constants described here are provided for user convenience. They correspond to the English names of lists of
-options, and can be displayed in menus or dialogs in a GUI. The code sample :ref:`saSimulate` illustrates how they can
-be used.
+options, and can be displayed in menus or dialogs in a GUI. The code sample :ref:`simulate.cc <saSimulate>` illustrates
+how they can be used.
 
 .. _mjDISABLESTRING:
 
@@ -3104,7 +3104,7 @@ mjVISSTRING
 | [1]: the string "0" or "1" indicating if the flag is on or off by default, as set by
   :ref:`mjv_defaultOption`;
 
-| [2]: one-character string with a suggested keyboard shortcut, used in ``simulate.cc``.
+| [2]: one-character string with a suggested keyboard shortcut, used in :ref:`simulate.cc <saSimulate>`.
 
 .. _mjRNDSTRING:
 
@@ -3239,9 +3239,10 @@ API functions
 
 The main header `mujoco.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mujoco.h>`_ exposes a very large number
 of functions. However the functions that most users are likely to need are a small fraction. For example,
-``simulate.cc`` which is as elaborate as a MuJoCo application is likely to get, calls around 40 of these functions,
-while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for them. This includes us as
-users of MuJoCo -- we do our own work with the public library instead of relying on internal builds.
+:ref:`simulate.cc <saSimulate>` which is as elaborate as a MuJoCo application is likely to get, calls around 40
+of these functions, while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for
+them. This includes us as users of MuJoCo -- we do our own work with the public library instead of relying on
+internal builds.
 
 .. _Activation:
 
@@ -4712,7 +4713,7 @@ Interaction
 ^^^^^^^^^^^
 
 These function implement abstract mouse interactions, allowing control over cameras and perturbations. Their use is well
-illustrated in ``simulate.cc``.
+illustrated in :ref:`simulate.cc <saSimulate>`.
 
 .. _mjv_defaultCamera:
 
@@ -4915,7 +4916,7 @@ This function is used for mouse selection. Previously selection was done via Ope
 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 ``simulate.cc`` for an illustration.
+The 3D coordinates of the clicked point are returned in selpnt. See :ref:`simulate.cc <saSimulate>` for an illustration.
 
 .. _Visualization-api:
 
@@ -4924,7 +4925,7 @@ Visualization
 
 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 ``simulate.cc`` for illustration of how to use these functions.
+Unity or Unreal Engine. See :ref:`simulate.cc <saSimulate>` for illustration of how to use these functions.
 
 .. _mjv_defaultOption:
 
@@ -5069,7 +5070,8 @@ Update skins.
 OpenGL rendering
 ^^^^^^^^^^^^^^^^
 
-These functions expose the OpenGL renderer. See ``simulate.cc`` for illustration of how to use these functions.
+These functions expose the OpenGL renderer. See :ref:`simulate.cc <saSimulate>` for an illustration
+of how to use these functions.
 
 .. _mjr_defaultContext:
 
diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst
index 2dd6cb07..86457ae7 100644
--- a/doc/XMLreference.rst
+++ b/doc/XMLreference.rst
@@ -116,8 +116,7 @@ how to use includes and how to modularize large files if desired.
 The unique top-level element, identifying the XML file as an MJCF model file.
 
 :at:`model`: :at-val:`string, "MuJoCo Model"`
-   The name of the model. This name is shown in the title bar of `simulate.cc
-   <https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_.
+   The name of the model. This name is shown in the title bar of :ref:`simulate.cc <saSimulate>`.
 
 .. _compiler:
 
@@ -606,9 +605,9 @@ is effectively a miscellaneous subsection.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This element specifies settings that affect the quality of the rendering. Larger values result in higher quality but
-possibly slower speed. Note that `simulate.cc <https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_
-displays the frames per second (FPS). The target FPS is 60 Hz; if the number shown in the visualizer is substantially
-lower, this means that the GPU is over-loaded and the visualization should somehow be simplified.
+possibly slower speed. Note that :ref:`simulate.cc <saSimulate>` displays the frames per second (FPS). The target FPS is 60 Hz; if the
+number shown in the visualizer is substantially lower, this means that the GPU is over-loaded and the visualization
+should somehow be simplified.
 
 :at:`shadowsize`: :at-val:`int, "4096"`
    This attribute specifies the size of the square texture used for shadow mapping. Higher values result is smoother
@@ -3908,8 +3907,7 @@ the nkey attribute of :ref:`size <size>`, and the number of elements defined her
 defined here, the undefined keyframes have all their data set to 0, except for the qpos attribute which is set to
 mjModel.qpos0.
 The user can also set keyframe data in mjModel at runtime; this data will then appear in the saved MJCF model. Note that
-in `simulate.cc <https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_ the simulation state can be copied
-into a selected keyframe and vice versa.
+in :ref:`simulate.cc <saSimulate>` the simulation state can be copied into a selected keyframe and vice versa.
 
 .. _key:
 
diff --git a/doc/modeling.rst b/doc/modeling.rst
index 2612cf81..44ae8625 100644
--- a/doc/modeling.rst
+++ b/doc/modeling.rst
@@ -58,8 +58,8 @@ exceptions; the user can implement similar error-interception functionality at r
 
 The entire process of parsing and compilation is very fast - less than a second if the model does not contain large
 meshes or actuator lengthranges that need to be computed via simulation. This makes it possible to design models
-interactively, by re-loading often and visualizing the changes. Note that the `simulate.cc`_ code sample has a
-keyboard shortcut for re-loading the current model (Ctrl+L).
+interactively, by re-loading often and visualizing the changes. Note that the :ref:`simulate.cc <saSimulate>` code
+sample has a keyboard shortcut for re-loading the current model (Ctrl+L).
 
 .. _Save:
 
@@ -493,8 +493,8 @@ There is also a second Noslip solver, which is a post-processing step enabled by
 noslip iterations. All these algorithm settings can be specified in the :ref:`option <option>` element.
 
 The default settings work well for most models, but in some cases it is necessary to tune the algorithm. The best way to
-do this is to experiment with the relevant settings and use the visual profiler in `simulate.cc`_, which shows the
-timing of different computations as well as solver statistics per iteration. We can offer the following general
+do this is to experiment with the relevant settings and use the visual profiler in :ref:`simulate.cc <saSimulate>`, which
+shows the timing of different computations as well as solver statistics per iteration. We can offer the following general
 guidelines and observations:
 
 -  The constraint Jacobian should be dense for small models and sparse for large models. The default setting is 'auto';
@@ -903,7 +903,7 @@ Here we describe the XML attributes common to all sensor types, so as to avoid r
    quaternions and unit vectors remain normalized, non-negative quantities remain non-negative.
 :at:`cutoff`: :at-val:`real, "0"`
    When this value is positive, it limits the absolute value of the sensor output. It is also used to normalize the
-   sensor output in the sensor data plots in `simulate.cc`_.
+   sensor output in the sensor data plots in :ref:`simulate.cc <saSimulate>`.
 :at:`user`: :at-val:`real(nuser_sensor), "0 0 ..."`
    See :ref:`User parameters <CUser>`.
 
@@ -1248,8 +1248,8 @@ this?
 
 The first step is to define a mocap body in the MJCF model, and implement code that reads the data stream at runtime and
 sets mjModel.mocap_pos and mjModel.mocap_quat to the position and orientation received from the motion capture system.
-The `simulate.cc <https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_ code sample uses the mouse as a
-motion capture device, allowing the user to move mocap bodies around:
+The :ref:`simulate.cc <saSimulate>` code sample uses the mouse as a motion capture device, allowing the user to move mocap
+bodies around:
 
 |particle|
 
@@ -1395,8 +1395,8 @@ memory, or cache performance could be adversely affected. And even if nothing ba
 memory than needed is just poor style.
 
 So how do we know how much memory to allocate? mjData has fields maxuse_stack, maxuse_con and maxuse_efc which keep
-track of the maximum memory utilization in each category since the last reset. The code sample `simulate.cc`_ shows
-this data as a fraction of the maximum allocation (in the info window in the lower-left corner). So one can start with
+track of the maximum memory utilization in each category since the last reset. The code sample :ref:`simulate.cc <saSimulate>`
+shows this data as a fraction of the maximum allocation (in the info window in the lower-left corner). So one can start with
 the defaults, simulate for a while, and if the fractions are too small go back to the XML and set the allocation sizes
 explicitly. Keep in mind though that memory utilization can change dramatically in the course of the simulation,
 depending on how many constraints are active and also which constraint solver is used.
@@ -1446,4 +1446,3 @@ model. If you only intend to use the CG solver, you can get away with significan
    :height: 250px
 .. |particle| image:: images/models/particle.gif
    :width: 270px
-.. _simulate.cc: https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc
diff --git a/doc/overview.rst b/doc/overview.rst
index 4b185527..2c41b6bb 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -529,8 +529,7 @@ Sensor
    are copied from the corresponding fields of ``mjData``. There is also a user sensor, allowing user code to insert any
    other quantity of interest in the sensor data array. MuJoCo also has off-screen rendering capabilities, making it
    straightforward to simulate both color and depth camera sensors. This is not included in the standard sensor model
-   and instead has to be done programmatically, as illustrated in the code sample `simulate.cc
-   <https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_.
+   and instead has to be done programmatically, as illustrated in the code sample :ref:`simulate.cc <saSimulate>`.
 
 Equality
    Equality constraints can impose additional constraints beyond those already imposed by the kinematic tree structure
diff --git a/doc/programming.rst b/doc/programming.rst
index 192642af..61425b74 100644
--- a/doc/programming.rst
+++ b/doc/programming.rst
@@ -330,10 +330,10 @@ illustration of the concepts in that guide.
 
 .. _saSimulate:
 
-`simulate.cc <https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`simulate.cc <https://github.com/deepmind/mujoco/blob/main/simulate>`_
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This code sample is a full-featured interactive simulator. It opens an OpenGL window using the platform-independent
+This code sample is a fully-featured interactive simulator. It opens an OpenGL window using the platform-independent
 GLFW library, and renders the simulation state in it. There is built-in help, simulation statistics, profiler, sensor
 data plots. The model file can be specified as a command-line argument, or loaded at runtime using drag-and-drop
 functionality. As of MuJoCo 2.0, this code sample uses the native UI to render various controls, and provides an
@@ -342,7 +342,7 @@ illustration of how the new UI framework is intended to be used. Below is a scre
 ..  youtube:: 0ORsj_E17B0
     :align: center
 
-Interaction is done with the mouse; built-in help with a summary of available commands is available by pressing the 'F1'
+Interaction is done with the mouse; built-in help with a summary of available commands is available by pressing the ``F1``
 key. Briefly, an object is selected by left-double-click. The user can then apply forces and torques on the selected
 object by holding Ctrl and dragging the mouse. Dragging the mouse alone (without Ctrl) moves the camera. There are
 keyboard shortcuts for pausing the simulation, resetting, and re-loading the model file. The latter functionality is
@@ -364,10 +364,9 @@ is extracted from the diagnostic fields of mjData. It is a very useful tool for
 constraint solver algorithms. The outputs of the sensors defined in the model are visualized as a bar graph.
 
 Note that the profiler shows timing information collected with high-resolution timers. On Windows, depending on the
-power settings, the OS may reduce the CPU frequency; this is because `simulate.cc
-<https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_ sleeps most of the time in order to slow down to
-realtime. This results in inaccurate timings. To avoid this problem, change the Windows power plan so that the minimum
-processor state is 100%.
+power settings, the OS may reduce the CPU frequency; this is because :ref:`simulate.cc <saSimulate>` sleeps most of
+the time in order to slow down to realtime. This results in inaccurate timings. To avoid this problem, change the
+Windows power plan so that the minimum processor state is 100%.
 
 .. _saRecord:
 
@@ -376,12 +375,11 @@ processor state is 100%.
 
 This code sample simulates the passive dynamics of a given model, renders it offscreen, reads the color and depth pixel
 values, and saves them into a raw data file that can then be converted into a movie file with tools such as ffmpeg. The
-rendering is simplified compared to `simulate.cc <https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_
-because there is no user interaction, visualization options or timing; instead we simply render with the default
-settings as fast as possible. The dimensions and number of multi-samples for the offscreen buffer are specified in the
-MuJoCo model, while the simulation duration, frames-per-second to be rendered (usually much less than the physics
-simulation rate), and output file name are specified as command-line arguments. For example, a 5 second animation at 60
-frames per second is created with:
+rendering is simplified compared to :ref:`simulate.cc <saSimulate>` because there is no user interaction, visualization
+options or timing; instead we simply render with the default settings as fast as possible. The dimensions and number of
+multi-samples for the offscreen buffer are specified in the MuJoCo model, while the simulation duration, frames-per-second
+to be rendered (usually much less than the physics simulation rate), and output file name are specified as command-line
+arguments. For example, a 5 second animation at 60 frames per second is created with:
 
 .. code-block:: Shell
 
@@ -479,12 +477,11 @@ model, i.e., a model that is softer than desired, so as to obtain more accurate
 uitools
 ~~~~~~~
 
-`(uitools.h) <https://github.com/deepmind/mujoco/blob/main/sample/uitools.h>`_ `(uitools.c)
-<https://github.com/deepmind/mujoco/blob/main/sample/uitools.c>`_ This is not a stand-alone code sample, but rather a
-small utility used to hook up the new UI to GLFW. It is used in `simulate.cc
-<https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_ and can also be used in user projects that involve
-the new UI. If GLFW is replaced with a different window library, this is the only file that would have to be changed in
-order to access the UI functionality.
+`(uitools.h) <https://github.com/deepmind/mujoco/blob/main/simulate/uitools.h>`_ `(uitools.cc)
+<https://github.com/deepmind/mujoco/blob/main/simulate/uitools.cc>`_ This is not a stand-alone code sample, but rather
+a small utility used to hook up the new UI to GLFW. It is used in :ref:`simulate.cc <saSimulate>` and can also be used
+in user projects that involve the new UI. If GLFW is replaced with a different window library, this is the only file
+that would have to be changed in order to access the UI functionality.
 
 .. _Simulation:
 
@@ -1922,11 +1919,12 @@ can be the entire active buffer, or part of it for custom effects. A viewport co
 be obtained with the function :ref:`mjr_maxViewport`. Note that while the offscreen buffer size does not change, the
 window buffer size changes whenever the user resizes or maximizes the window. Therefore user code should not assume
 fixed viewport size. In the code sample :ref:`simulate.cc <saSimulate>` we use a callback which is triggered whenever
-the window size changes, while in :ref:`basic.cc <saBasic>` we simply check the window size every time we render. On certain scaled
-displays (only on OSX it seems) the window size and framebuffer size can be different. So if you are getting the size
-with GLFW functions, use glfwGetFramebuferSize rather than glfwGetWindowSize. On the other hand, mouse coordinates are
-returned by the operating system in window rather than framebuffer units; thus the mouse interaction functions discussed
-earlier should use glfwGetWindowSize to obtain the window height needed to normalize the mouse displacement data.
+the window size changes, while in :ref:`basic.cc <saBasic>` we simply check the window size every time we render. On
+certain scaled displays (only on OSX it seems) the window size and framebuffer size can be different. So if you are
+getting the size with GLFW functions, use glfwGetFramebuferSize rather than glfwGetWindowSize. On the other hand,
+mouse coordinates are returned by the operating system in window rather than framebuffer units; thus the mouse
+interaction functions discussed earlier should use glfwGetWindowSize to obtain the window height needed to normalize
+the mouse displacement data.
 
 mjr_render renders all mjvGeoms from the list mjvScene.geom. The abstract visualization options mjvOption are no
 longer relevant here; they are used by mjv_updateScene to determine which geoms to add, and as far as mjr_render is
diff --git a/simulate/README.md b/simulate/README.md
new file mode 100644
index 00000000..6a1bde3f
--- /dev/null
+++ b/simulate/README.md
@@ -0,0 +1,10 @@
+# Simulate App
+
+`simulate` is a fully-featured interactive application for MuJoCo. It opens an
+OpenGL window using the platform-independent GLFW library, and renders the
+simulation state in it. There is built-in help, simulation statistics, profiler,
+sensor data plots. The model file can be specified as a command-line argument,
+or loaded at runtime using drag-and-drop functionality. Below is a
+screen-capture of simulate in action:
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/0ORsj_E17B0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>