Improve documentation regarding choice of integrator. Fixes #1085
PiperOrigin-RevId: 576546484 Change-Id: I7192a0c32e1aed8e201d1db953b657e605cd74f0
This commit is contained in:
Yuval Tassa
committed by
Copybara-Service
Copybara-Service
parent
a89412bb4a
commit
5231a335bf
Vendored
+22
@@ -0,0 +1,22 @@
|
||||
<mujoco>
|
||||
<asset>
|
||||
<texture type="skybox" builtin="gradient" rgb1=".3 .5 .7" rgb2="0 0 0" width="32" height="512"/>
|
||||
<texture name="grid" type="2d" builtin="checker" width="512" height="512" rgb1=".1 .2 .3" rgb2=".2 .3 .4"/>
|
||||
<material name="grid" texture="grid" texrepeat="1 1" texuniform="true" reflectance=".2"/>
|
||||
</asset>
|
||||
|
||||
<statistic extent="1"/>
|
||||
|
||||
<!-- switch the integrator to "implicit" for better gyroscopic stabillity -->
|
||||
<option timestep="0.01" integrator="implicitfast"/>
|
||||
|
||||
<worldbody>
|
||||
<geom pos="0 0 -.5" type="plane" size="100 100 .1" zaxis=".5 0 1" material="grid"/>
|
||||
<body pos="0 0 .3">
|
||||
<freejoint/>
|
||||
<geom type="ellipsoid" size="0.15 0.1 0.07" euler="20 40 60"/>
|
||||
<light pos="0 0 1.5" mode="track"/>
|
||||
<camera pos="0 -1.498 0.1" xyaxes="1 0 0 0 0 1" mode="track"/>
|
||||
</body>
|
||||
</worldbody>
|
||||
</mujoco>
|
||||
Vendored
+27
@@ -0,0 +1,27 @@
|
||||
<mujoco model="energy conserving pendulum">
|
||||
<option integrator="RK4">
|
||||
<flag constraint="disable" energy="enable"/>
|
||||
</option>
|
||||
|
||||
<worldbody>
|
||||
<light pos="0 0 2"/>
|
||||
<geom pos="0 0 -.5" type="plane" size="1 1 .01"/>
|
||||
<body pos="0 0 0">
|
||||
<joint type="hinge" axis="0 1 0"/>
|
||||
<geom type="cylinder" size="0.02" fromto="0 -.02 0 0 .02 0"/>
|
||||
<geom type="capsule" size="0.02" fromto="0 0 0 .1 0 0"/>
|
||||
<body pos="0.1 0 0">
|
||||
<joint type="slide" axis="1 0 0" stiffness="200"/>
|
||||
<geom type="capsule" size="0.015" fromto="-.1 0 0 .1 0 0"/>
|
||||
<body pos=".1 0 0">
|
||||
<joint type="ball"/>
|
||||
<geom type="box" size=".02" fromto="0 0 0 0 .1 0"/>
|
||||
<body pos="0 .1 0">
|
||||
<joint axis="1 0 0"/>
|
||||
<geom type="capsule" size="0.02" fromto="0 0 0 0 .1 0"/>
|
||||
</body>
|
||||
</body>
|
||||
</body>
|
||||
</body>
|
||||
</worldbody>
|
||||
</mujoco>
|
||||
+37
-18
@@ -526,29 +526,48 @@ Fast implicit-in-velocity (``implicitfast``)
|
||||
derivatives are also the main source of asymmetry of :math:`D`, by dropping them and symmetrizing, we can use the
|
||||
faster Cholesky rather than LU decomposition.
|
||||
|
||||
.. tip::
|
||||
The implicitfast integrator has similar computational cost to Euler, yet provides increased stability, and is
|
||||
therefore a strict improvement. It is the recommended integrator and will become the default in a future version.
|
||||
|
||||
4th-order Runge-Kutta (``RK4``)
|
||||
One advantage of our continuous-time formulation is that we can use higher order integrators such as Runge-Kutta or
|
||||
multistep methods. The only such integrator currently implemented is the fixed-step `4th-order Runge-Kutta method
|
||||
<https://en.wikipedia.org/wiki/Runge–Kutta_methods#Derivation_of_the_Runge–Kutta_fourth-order_method>`_, though users
|
||||
can easily implement other integrators by calling :ref:`mj_forward` and integrating accelerations themselves. We have
|
||||
observed that for energy-conserving systems (`example
|
||||
<https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/derivative/energy_conserving_pendulum.xml>`_) RK4
|
||||
is qualitatively better than the single-step methods, both in terms of stability and accuracy, even when the timestep
|
||||
is decreased by a factor of 4 (so the computational effort is identical). In the presence of large velocity-
|
||||
dependent forces, if the chosen single-step method integrates those forces implicitly, single-step methods can be
|
||||
significantly more stable than RK4.
|
||||
<https://en.wikipedia.org/wiki/Runge–Kutta_methods#Derivation_of_the_Runge–Kutta_fourth-order_method>`__, though
|
||||
users can easily implement other integrators by calling :ref:`mj_forward` and integrating accelerations themselves.
|
||||
We have observed that for energy-conserving systems (`example <../_static/pendulum.xml>`__), RK4 is qualitatively
|
||||
better than the single-step methods, both in terms of stability and accuracy, even when the timestep is decreased by
|
||||
a factor of 4 (so the computational effort is identical). In the presence of large velocity- dependent forces, if the
|
||||
chosen single-step method integrates those forces implicitly, single-step methods can be significantly more stable
|
||||
than RK4.
|
||||
|
||||
.. note::
|
||||
The accuracy and stability of all integrators can be improved by reducing the time step :math:`h` which is stored in
|
||||
``mjModel.opt.timestep``. Of course this also slows down the simulation. The time step is perhaps the most important
|
||||
parameter that the user can adjust. If it is too large, the simulation will become unstable. If it is too small, CPU
|
||||
time will be wasted without meaningful improvement in accuracy. There is always a comfortable range where the time
|
||||
step is "just right", but that range is model-dependent.
|
||||
.. admonition:: Choosing timestep and integrator
|
||||
:class: tip
|
||||
|
||||
:ref:`timestep<option-timestep>`
|
||||
The accuracy and stability of all integrators can be improved by reducing the time step :math:`h`.
|
||||
Of course a smaller time step also slows down the simulation. The time step is perhaps the single most important
|
||||
parameter that the user can adjust. If it is too large, the simulation will become unstable. If it is too small, CPU
|
||||
time will be wasted without meaningful improvement in accuracy. There is always a comfortable range where the time
|
||||
step is "just right", but that range is model-dependent.
|
||||
|
||||
:ref:`integrator<option-integrator>`
|
||||
Summary: The recommended integrator is ``implicitfast`` which usually has the best tradeoff of stabillity and
|
||||
performance.
|
||||
|
||||
**Euler**:
|
||||
Use ``Euler`` for compatibillity with older models and :ref:`MJX<Mjx>`. Specifically for MJX,
|
||||
setting the :ref:`eulerdamp<option-flag-eulerdamp>` disable flag can :ref:`improve performance<MjxPerformance>`.
|
||||
**implicitfast**:
|
||||
The ``implicitfast`` integrator has similar computational cost to ``Euler``, yet provides
|
||||
increased stability, and is therefore a strict improvement. It is the recommended integrator for most models.
|
||||
**implicit**:
|
||||
The benefit over ``implicitfast`` is the implicit integration of Coriolis and centripetal forces, including
|
||||
gyroscopic forces. The most common case where integrating such forces implicitly leads to noticable improvement is
|
||||
when free objects with assymetric inertia are spinning quickly. `gyroscopic.xml <../_static/gyroscopic.xml>`__
|
||||
shows an ellipsoid rolling on an inclined plane which quickly diverges with ``implicitfast`` but is stable with
|
||||
``implicit``.
|
||||
**RK4**:
|
||||
This integrator is best for systems which are energy conserving, or almost energy-conserving. `pendulum.xml
|
||||
<../_static/pendulum.xml>`__ shows a complicated pendulum mechanism which diverges quickly using ``Euler`` or
|
||||
``implicitfast`` yet conserves energy well under ``RK4``. Note that under ``implicit``, this model doesn't diverge
|
||||
but rather loses energy.
|
||||
|
||||
.. _geState:
|
||||
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
.. _Mjx:
|
||||
|
||||
================
|
||||
MuJoCo XLA (MJX)
|
||||
================
|
||||
|
||||
Reference in New Issue
Block a user