Documentation updates:

- Added a section on preventing slip in the modeling chapter.
- Added more intuitive descriptions of friction coefficients in the Computation chapter.
- Fixed some en-dashes and em-dashes.

PiperOrigin-RevId: 630856003
Change-Id: I8e767e6c5a95affdeb72ef9bc424bdd18f58e4df

doc/computation/index.rst

@@ -29,7 +29,7 @@ Robots as well as humans interact with their environment primarily through physi
 importance of physics modeling in robotics, machine learning, animation, virtual reality, biomechanics and other fields,
 there is need for simulation models of contact dynamics that are both physically accurate and computationally efficient.
 One application of simulation models is to assess candidate estimation and control strategies before deploying them on
-physical systems. Another application is to automate the design of those strategies - usually through numerical
+physical systems. Another application is to automate the design of those strategies -- usually through numerical
 optimization that uses simulation in an inner loop. The latter application imposes an additional constraint: the
 objective function defined with respect to the contact dynamics should be amenable to numerical optimization. The
 contact model underlying MuJoCo has benefits along these and other relevant dimensions. In the following sections we
@@ -50,7 +50,7 @@ for frictional contacts there are differences.
 If one sees convex models as approximations to LCP, the logical question to ask is how good that approximation is.
 However we do not see it that way. Instead, we see both LCP models and convex models as different approximations to
 physical reality, each with its strengths and weaknesses. The immediate consequence of dropping strict complementarity
-and replacing it with a cost is that complementarity can be violated - meaning that force and velocity in the contact
+and replacing it with a cost is that complementarity can be violated -- meaning that force and velocity in the contact
 normal direction can be simultaneously positive, and frictional forces may not be maximally dissipative. A related
 phenomenon is that the only way to initiate slip is to generate some motion in the normal direction. These effects are
 numerically small yet undesirable. This shortcoming however has little practical relevance, because it is premised on
@@ -117,7 +117,7 @@ Inverse dynamics and optimization
 The objective of inverse dynamics is to recover the applied force and contact force given the position, velocity and
 acceleration of the multi-joint system. With hard contacts this computation is impossible. Consider pushing against a
 wall without moving. The contact force cannot be recovered from the kinematics, unless of course we consider the
-material deformations - in which case we need a soft contact model. Inverse dynamics are trivial to compute with
+material deformations -- in which case we need a soft contact model. Inverse dynamics are trivial to compute with
 spring-damper models of contact, because in that case the contact force is only a function of position and velocity and
 does not depend on applied force. But this is also the reason why spring-damper models are undesirable: ignoring the
 applied force means that an error is introduced at each time step, and so the simulator is perpetually in
@@ -125,7 +125,7 @@ error-correction mode, in turn causing instabilities. In contrast, modern contac
 well as all internal forces) into account when computing the contact force/impulse. But this complicates inversion. The
 present contact model has a uniquely-defined inverse. The inverse dynamics are in fact easier to compute than the
 forward dynamics, because the optimization problem becomes diagonal and decomposes into independent optimization
-problems over individual contacts - which can be solved analytically.
+problems over individual contacts -- which can be solved analytically.
 
 Inverse dynamics play a key role in optimization algorithms arising in system identification, estimation and control.
 They make it possible to treat the sequence of positions (or a parametric representation thereof) as the object being
@@ -269,7 +269,7 @@ activation state :math:`w_i` with its own dynamics. The control inputs for all a
 the force outputs are stored in ``mjData.actuator_force``, and the activation states (if any) are stored in
 ``mjData.act``.
 
-These three components of an actuator - transmission, activation dynamics, and force generation - determine how the
+These three components of an actuator -- transmission, activation dynamics, and force generation -- determine how the
 actuator works. The user can set them independently for maximum flexibility, or use :ref:`Actuator shortcuts
 <CActShortcuts>` which instantiate common actuator types.
 
@@ -736,8 +736,8 @@ properties of quaternions, differentiation with respect to :math:`q` produces ve
 
 Among other applications, equality constraints can be used to create "loop joints", i.e., joints that cannot be modeled
 via the kinematic tree. Gaming engines represent all joints in this way. The same can be done in MuJoCo but is not
-recommended - because it leads to both slower and less accurate simulation, effectively turning MuJoCo into a gaming
-engine. The only reason to represent joints with equality constraints would be to model soft joints - which can be done
+recommended -- because it leads to both slower and less accurate simulation, effectively turning MuJoCo into a gaming
+engine. The only reason to represent joints with equality constraints would be to model soft joints -- which can be done
 via the constraint solver but not via the kinematic tree.
 
 There are five types of equality constraints described next. The numbers in the headings correspond to the
@@ -846,7 +846,7 @@ at the limit, and negative if the limit is violated. The constraint becomes acti
 constraint force depends on distance through the solver :ref:`parameters <soParameters>` described later.
 
 It is possible that both the lower and the upper limits for a given joint or tendon become active. In that case they are
-both included in the list of scalar constraints, however this situation should be avoided - by increasing the range or
+both included in the list of scalar constraints, however this situation should be avoided -- by increasing the range or
 decreasing the margin. In particular, avoid using narrow ranges to approximate an equality constraint. Instead use an
 explicit equality constraint, and if some slack is desired make the constraint soft by adjusting the solver parameters.
 This is more efficient computationally, not only because it involves one scalar constraint instead of two, but also
@@ -900,7 +900,8 @@ model definition.
    * - ``condim``
      - Dimensionality of the contact force/torque in the contact frame. |br| It can be 1, 3, 4 or 6.
    * - ``friction``
-     - Vector of friction coefficients with dimensionality ``condim-1``.
+     - Vector of friction coefficients with dimensionality ``condim-1``. See below for semantics of the specific
+       coefficients.
    * - ``margin``
      - The distance margin used to determine if the contact should be included in the global contact array
        ``mjData.contact``.
@@ -921,19 +922,23 @@ as defined later. The ``condim`` parameter determines the contact type, and has
    similar to a joint or tendon limit, but is applied to the distance between two geoms.
 
 ``condim = 3`` : 3 for elliptic, 4 for pyramidal
-   This is a regular frictional contact, which can generate normal force as well as tangential friction force opposing
-   slip.
+   This is a regular frictional contact, which can generate normal force as well as a tangential friction force opposing
+   slip. An interpertation of this number is the slope of a surface above which a flat object will begin to slip
+   under gravity.
 
 ``condim = 4`` : 4 for elliptic, 6 for pyramidal
    In addition to normal and tangential force, this contact can generate torsional friction torque opposing rotation
-   around the contact normal. This is useful for modeling soft fingers, and can substantially improve the stability of
-   simulated grasping. Keep in mind that the torsional (as well as rolling) friction coefficients have different units
-   from the tangential friction coefficients.
+   around the contact normal, corresponding to a torque generated by a contacting surface patch. This is useful for
+   modeling soft fingers, and can substantially improve the stability of simulated grasping. Torsional friction
+   coefficients have **units of length** which can be interperted as the diameter of the surface contact patch.
 
 ``condim = 6`` : 6 for elliptic, 10 for pyramidal
    This contact can oppose motion in all relative degrees of freedom between the two geoms. In particular it adds
-   rolling friction, which can be used for example to stop a ball from rolling indefinitely on a plane. It can also be
-   used to model rolling friction between tires and a road, and in general to stabilize contacts.
+   rolling friction, which can be used for example to stop a ball from rolling indefinitely on a plane. Rolling friction
+   in the real world results from energy dissipated by local deformations near the contact point. It can be
+   used to model rolling friction between tires and a road, and in general to stabilize contacts. Rolling friction
+   coefficients also have **units of length** which can be interperted as the depth of the local deformation within
+   which energy is dissipated.
 
 Note that condim cannot be 2 or 5. This is because the two tangential directions and the two rolling directions are
 treated as pairs. The friction coefficients within a pair can be different though, which can be used to model skating
@@ -1109,7 +1114,7 @@ and the dual of the dual of a cone is the cone itself. The pyramidal friction co
 self-dual, but the elliptic one is not.
 
 The Huber "norm" is based on the Huber function from robust statistics: it is a quadratic around zero, and transitions
-smoothly to a linear function when the absolute value of the argument crosses a threshold - in this case given by the
+smoothly to a linear function when the absolute value of the argument crosses a threshold -- in this case given by the
 friction loss parameters. Setting :math:`\eta = \infty` recovers the quadratic norm; we use this convention for all
 constraint forces that are not due to friction loss. This is another instance of reverse engineering: we want to obtain
 interval constraints on the friction loss forces, which is non-trivial because Lagrange duality usually yields
@@ -1190,7 +1195,7 @@ the constraints. We are then left with an unconstrained optimization problem ove
 more efficient algorithms.
 
 The reduction is based on the fact that minimization over :math:`y` in :eq:`eq:primal` comes down to finding the nearest
-point on the constraint set - which is either a plane or a cone, and can be done analytically. Substituting the result,
+point on the constraint set -- which is either a plane or a cone, and can be done analytically. Substituting the result,
 we obtain the unconstrained problem
 
 .. math::
@@ -1296,7 +1301,7 @@ because the forward dynamics need all the quantities that enter into the inverse
 the analytical formula. This makes it possible to implement an automatic correctness check in MuJoCo. When the flag
 ``fwdinv`` in ``mjModel.opt.enableflags`` is on, the forward and inverse dynamics are automatically compared at the end
 of each time step, and the difference is recorded in ``mjData.solver_fwdinv``. Discrepancies indicate that the forward
-solver - which is numerical and is usually terminated early - is not converging well. Of course the inverse dynamics are
+solver---which is numerical and is usually terminated early---is not converging well. Of course the inverse dynamics are
 also useful on their own, without computing the forward dynamics first.
 
 .. _soAlgorithms:
@@ -1348,7 +1353,7 @@ representations of the constraint Jacobian and related matrices.
    can be up to 5-dimensional given our contact model. Now we optimize the quadratic cost within this ellipsoid. This is
    an instance of quadratically constrained quadratic programming (QCQP). Since there is only one scalar constraint
    (however nonlinear it may be), the dual is a scalar optimization problem over the unknown Lagrange multiplier. We
-   solve this problem with Newton's method applied until convergence - which in practice takes less than 10 iterations,
+   solve this problem with Newton's method applied until convergence -- which in practice takes less than 10 iterations,
    and involves small matrices. Overall this algorithm has similar behavior to PGS for pyramidal cones, but it can
    handle elliptic cones without approximating them. It does more work per contact, however the contact dimensionality
    is smaller, and these two factors roughly balance each other.