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/XMLreference.rst

@@ -301,8 +301,8 @@ adjust it properly through the XML.
    setting of solimp determines a single impedance value for all contact dimensions, which is then modulated by this
    attribute. Settings larger than 1 cause friction forces to be "harder" than normal forces, having the general effect
    of preventing slip, without increasing the actual friction coefficient. For pyramidal friction cones the situation is
-   more complex because the pyramidal approximation mixes normal and frictional dimensions within each basis vector; but
-   the overall effect of this attribute is qualitatively similar.
+   more complex because the pyramidal approximation mixes normal and frictional dimensions within each basis vector; it
+   is not recommended to use high impratio values with pyramidal cones.
 
 .. _option-gravity:
 
@@ -2274,7 +2274,8 @@ helps clarify the role of bodies and geoms in MuJoCo.
    along both axes of the tangent plane. The second number is the torsional friction, acting around the contact normal.
    The third number is the rolling friction, acting around both axes of the tangent plane. The friction parameters for
    the contact pair are combined depending on the solmix and priority attributes, as explained in :ref:`Contact
-   parameters <CContact>`.
+   parameters <CContact>`. See the general :ref:`Contact<coContact>` section for descriptions of the semantics of this
+   attribute.
 
 .. _body-geom-mass:
 

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.

doc/modeling.rst

@@ -31,7 +31,7 @@ Loading models
 
 As explained in :ref:`Model instances <Instance>` in the Overview chapter, MuJoCo models can be loaded from plain-text
 XML files in the MJCF or URDF formats, and then compiled into a low-level mjModel. Alternatively a previously saved
-mjModel can be loaded directly from a binary MJB file - whose format is not documented but is essentially a copy of the
+mjModel can be loaded directly from a binary MJB file -- whose format is not documented but is essentially a copy of the
 mjModel memory buffer. MJCF and URDF files are loaded with :ref:`mj_loadXML` while MJB files are loaded with
 :ref:`mj_loadModel`.
 
@@ -45,8 +45,8 @@ XML file has a unique top-level element. This element must be :el:`mujoco` for M
 Compiling models
 ~~~~~~~~~~~~~~~~
 
-Once a high-level mjCModel is created - by loading an MJCF file or a URDF file, or programmatically when such
-functionality becomes available - it is compiled into mjModel. Even though loading and compilation are presently
+Once a high-level mjCModel is created---by loading an MJCF file or a URDF file, or programmatically when such
+functionality becomes available---it is compiled into mjModel. Even though loading and compilation are presently
 combined in one step, compilation is independent of loading, meaning that the compiler works in the same way
 regardless of how mjCModel was created. Both the parser and the compiler perform extensive error checking, and abort
 when the first error is encountered. The resulting error messages contain the row and column number in the XML file,
@@ -56,7 +56,7 @@ simulation step of the compiled model is performed and any runtime errors are in
 (temporarily) setting :ref:`mju_user_error` to point to a function that throws C++
 exceptions; the user can implement similar error-interception functionality at runtime if desired.
 
-The entire process of parsing and compilation is very fast - less than a second if the model does not contain large
+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 :ref:`simulate.cc <saSimulate>` code
 sample has a keyboard shortcut for re-loading the current model (Ctrl+L).
@@ -166,7 +166,7 @@ which overrides the default settings. The cylinder specifies defaults class "mai
 "sub", even though the latter was specified in the childclass attribute of the body containing the geom.
 
 Now we describe the general rules. MuJoCo supports unlimited number of defaults classes, created by possibly nested
-:ref:`default <default>` elements in the XML. Each class has a unique name - which is a required
+:ref:`default <default>` elements in the XML. Each class has a unique name -- which is a required
 attribute except for the top-level class whose name is "main" if left undefined. Each class also has a complete
 collection of dummy model elements, with their attributes set as follows. When a defaults class is defined within
 another defaults class, the child automatically inherits all attribute values from the parent. It can then override
@@ -248,7 +248,7 @@ specified by the user, the frame is not rotated.
 :at:`zaxis`: :at-val:`real(3), optional`
    The Z axis of the frame. The compiler finds the minimal rotation that maps the vector :math:`(0, 0, 1)` into the
    vector specified here. This determines the X and Y axes of the frame implicitly. This is useful for geoms with
-   rotational symmetry around the Z axis, as well as lights - which are oriented along the Z axis of their frame.
+   rotational symmetry around the Z axis, as well as lights -- which are oriented along the Z axis of their frame.
 
 .. _CSolver:
 
@@ -448,33 +448,36 @@ there is nothing to do, but what if their parameters are different? In that case
 :at:`solmix` and :at:`priority` to decide how to combine them. The combination rules for each contact parameter
 are as follows:
 
-condim
+**condim**
    If one of the two geoms has higher priority, its condim is used. If both geoms have the same priority, the maximum of
    the two condims is used. In this way a frictionless geom and a frictional geom form a frictional contact, unless the
    frictionless geom has higher priority. The latter is desirable in particle systems for example, where we may not want
    the particles to stick to any objects.
-friction
+**friction**
    Recall that contacts can have up to 5 friction coefficients: two tangential, one torsional, two rolling. Each contact
    in mjData.contact actually has all 5 of them, even if condim is less than 6 and not all coefficients are used. In
    contrast, geoms have only 3 friction coefficients: tangential (same for both axes), torsional, rolling (same for both
    axes). Each of these 3D vectors of friction coefficients is expanded into a 5D vector of friction coefficients by
-   replicating the tangetial and rolling components. The contact friction coefficients are then computed according to
-   the following rule: if one of the two geoms has higher priority, its friction coefficients are used. Otherwise the
-   element-wise maximum of each friction coefficient over the two geoms is used. The rationale is similar to taking the
-   maximum over condim: we want the more frictional geom to win.
+   replicating the tangetial and rolling components. See the :ref:`Contact<coContact>` section in the Computation
+   chapter for an intuitive description of the semantics of tangential, torsional and rolling coefficients.
+
+   The contact friction coefficients are then computed according to the following rule: if one of the two geoms has
+   higher priority, its friction coefficients are used. Otherwise the **element-wise maximum** of each friction
+   coefficient over the two geoms is used.
+
    The reason for having 5 coefficients per contact and only 3 per geom is as follows. For a contact pair, we want to
    allow the most flexible model our solver can handle. As mentioned earlier, anisotropic friction can be exploited to
    model effects such as skating. This however requires knowing how the two axes of the contact tangent plane are
    oriented. For a predefined contact pair we know the two geom types in advance, and the corresponding collision
-   function always generates contact frames oriented in the same way - which we do not describe here but it can be seen
+   function always generates contact frames oriented in the same way -- which we do not describe here but it can be seen
    in the visualizer. For individual geoms however, we do not know which other geoms they might collide with and what
    their geom types might be, so there is no way to know how the contact tangent plane will be oriented when specifying
    an individual geom. This is why MuJoCo does not allow anisotropic friction in the individual geom specifications, but
    only in the explicit contact pair specifications.
-margin, gap
+**margin**, **gap**
    The maximum of the two geom margins (or gaps respectively) is used. The geom priority is ignored here, because the
    margin and gap are distance properties and a one-sided specification makes little sense.
-solref, solimp
+**solref**, **solimp**
    If one of the two geoms has higher priority, its solref and solimp parameters are used. If both geoms have the same
    priority, the weighted average is used. The weights are proportional to the solmix attributes, i.e., weight1 =
    solmix1 / (solmix1 + solmix2) and similarly for weight2. There is one important exception to this weighted averaging
@@ -493,7 +496,7 @@ facilitate this process, we provide a mechanism to override some of the solver p
 the actual model. Once the override is disabled, the simulation reverts to the parameters specified in the model. This
 mechanism can also be used to implement continuation methods in the context of numerical optimization (such as optimal
 control or state estimation). This is done by allowing contacts to act from a distance in the early phases of
-optimization - so as to help the optimizer find a gradient and get close to a good solution - and reducing this effect
+optimization---so as to help the optimizer find a gradient and get close to a good solution---and reducing this effect
 later to make the final solution physically realistic.
 
 The relevant settings here are the :at:`override` attribute of :ref:`flag <option-flag>` which
@@ -556,12 +559,12 @@ general guidelines and observations:
    threshold is better defined in terms of number of active constraints, which is model and behavior dependent.
 -  The choice between pyramidal and elliptic friction cones is a modeling choice rather than an algorithmic choice,
    i.e., it leads to a different optimization problem solved with the same algorithms. Elliptic cones correspond more
-   closely to physical reality. However pyramidal cones can improve the performance of the algorithms - but not
+   closely to physical reality. However pyramidal cones can improve the performance of the algorithms -- but not
    necessarily. While the default is pyramidal, we recommend trying the elliptic cones. When contact slip is a problem,
    the best way to suppress it is to use elliptic cones, large impratio, and the Newton algorithm with very small
    tolerance. If that is not sufficient, enable the Noslip solver.
 -  The Newton algorithm is the best choice for most models. It has quadratic convergence near the global minimum and
-   gets there in surprisingly few iterations - usually around 5, and rarely more than 20. It should be used with
+   gets there in surprisingly few iterations -- usually around 5, and rarely more than 20. It should be used with
    aggressive tolerance values, say 1e-10, because it is capable of achieving high accuracy without added delay (due to
    quadratic convergence at the end). The only situation where we have seen it slow down are large models with elliptic
    cones and many slipping contacts. In that regime the Hessian factorization needs a lot of updates. It may also slow
@@ -1314,7 +1317,7 @@ probe away (which is possible because the probe is a mocap body which can move i
 we can see the indentation made by the probe, and the resulting deformation in the rest of the body. By changing the
 solref and solimp attributes of the equality constraints that hold the soft object together, one can adjust the behavior
 of the system making it softer or harder, damped or springy, etc. Note that box, cylinder and ellipsoid objects do not
-involve long kinematic chains, and can be simulated at large timesteps - similar to particle and grid, and unlike rope
+involve long kinematic chains, and can be simulated at large timesteps -- similar to particle and grid, and unlike rope
 and cloth.
 
 .. _CDeformable:
@@ -1403,7 +1406,7 @@ self-collisions; see XML reference.
 In case of 3D flexes made of tetrahedra, it may be useful to examine how the flex is "triangulated" internally. We have
 a special visualization mode that peels off the outer layers. Below is an example with the Stanford Bunny. Note how it
 has smaller tetrahedra on the outside and larger ones on the inside. This mesh design makes sense, because we want the
-collision surface to be accurate, but on the inside we just need soft material properties - which require less spatial
+collision surface to be accurate, but on the inside we just need soft material properties -- which require less spatial
 resolution. In order to convert a surface mesh to a tetrahedral mesh, we recommend open tools like the
 `fTetWild library <https://github.com/wildmeshing/fTetWild>`__.
 
@@ -1436,7 +1439,7 @@ The flexibility of repeated MCJF sections comes at a price: global settings that
 the :at:`angle` attribute of :ref:`compiler <compiler>` for example, can be defined multiple times.
 MuJoCo allows this, and uses the last definition encountered in the composite model, after all include elements have
 been processed. So if model A is defined in degrees and model B is defined in radians, and A is included in B after
-the :el:`compiler` element in B, the entire composite model will be treated as if it was defined in degrees - leading
+the :el:`compiler` element in B, the entire composite model will be treated as if it was defined in degrees -- leading
 to undesirable consequences in this case. The user has to make sure that models included in each other are compatible
 in this sense; local vs. global coordinates is another compatibility requirement.
 
@@ -1469,7 +1472,7 @@ unless there is a specific reason to define it. There can be several such reason
    is useful for custom computations involving a model element that is identified by its name in the XML (as opposed to
    relying on a fixed index which can change when the model is edited).
 -  The model file could in principle become more readable by naming certain elements. Keep in mind however that XML
-   itself has a commenting mechanism, and that mechanism is more suitable for achieving readability - especially since
+   itself has a commenting mechanism, and that mechanism is more suitable for achieving readability -- especially since
    most text editors provide syntax highlighting which detects XML comments.
 
 .. _CURDF:
@@ -1620,8 +1623,8 @@ is not always obvious, so it may be useful to have it spelled out.
 Performance tuning
 ~~~~~~~~~~~~~~~~~~
 
-Here is a list of steps one can take in order to maximize simulation throughput. All of the recommendations below
-involve some tweaking. It is recommended that these be carried out in interactive fashion while looking at the
+Below is a list of steps one can take in order to maximize simulation throughput. All of the recommendations
+involve parameter tweaking. It is recommended that these be carried out in interactive fashion while looking at the
 :ref:`simulate<saSimulate>` utility's built-in profiler. A detailed and sometimes more useful profile is also reported
 by the :ref:`testspeed<saTestspeed>` utility. When embarking on the more elaborate steps below, target the most
 expensive pipeline component reported by the profiler. Note that some of these are subtly different for MJX, see
@@ -1663,6 +1666,61 @@ dedicated section :ref:`therein<MjxPerformance>`.
    - If replacing collision meshes with primitives is not feasible, decimate the meshes as much as possible. Open source
      tools like trimesh, Blender, MeshLab and CoACD are very useful in this regard.
 
+.. _CSlippage:
+
+Preventing slip
+~~~~~~~~~~~~~~~
+
+Below is a list of steps one can take in order to diagnose and solve contact slippage, which is especially problematic
+in manipulation tasks. In order to diagnose slippage, it is recommended to use the :ref:`simulate<saSimulate>` utility's
+built in visualization options to inspect contacts and contact forces. It is often helpful to tweak the visual size of
+contacts and forces (using the global :ref:`meansize<statistic-meansize>` or the specific
+:ref:`contactwidth<visual-scale-contactwidth>`, :ref:`contactheight<visual-scale-contactheight>` and
+:ref:`forcewidth<visual-scale-forcewidth>` attributes) and the :ref:`force scaling<visual-map-force>` attribute, to
+better visualize and understand the contact configuration and resulting forces.
+
+**Slip-preventing contact forces are outside the friction cone**
+  This implies that the physics cannot prevent slip, even in principle. This occurs when:
+
+  a. *The normal force is too small.* Ensure that the maximum force that can be applied by the gripper mutiplied by
+     the sliding friction coefficient is significantly greater than the weight of the object.
+  b. *The sliding friction coefficient is too low.* Increase the sliding :ref:`friction<body-geom-friction>`
+     coefficient.
+  c. *Torsional friction is insufficient to apply the required torques.* Increase :ref:`condim<body-geom-condim>` to
+     4 or 6 and choose appropriate friction coefficients.
+     **condim 4** enables torsional friction, preventing rotation around the normal.
+     **condim 6** also enables rolling friction, preventing rotation around the tangential directions.
+     See the :ref:`Contact<coContact>` section for details and the specifc semantics of these coefficients.
+
+**The geometry does not support the required forces or torques**
+  This is a common real-world problem, solved by improved design of grippers and handles.
+
+  a. Improve the geometry of the contacting geoms in order to add more contact points, possibly with non-flat
+     geometry (e.g., bumps), so slippage is prevented by the normal force and not only frictional components.
+  b. If contacts are between flat surfaces, try enabling the :ref:`multiccd<option-flag-multiccd>` flag, which allows
+     the detector to find more contacts than the single contact returned by the convex-convex collider.
+
+**High-frequency vibration**
+  High-frequency, low-amplitude vibrations are also a real-world problem in many industrial settings, but unlike in
+  simulation, in the real world they are audible. Such vibration is often caused by controllers with very
+  high gains and sometimes by stick-slip feedback from contacts or joints, resonating with the eigen-modes of the
+  mechanism. The easist way to diagnose such vibration is to visualize contact forces in
+  :ref:`simulate<saSimulate>`. The solution is usually to reduce the :ref:`timestep<option-timestep>` and/or add
+  some :ref:`armature<body-joint-armature>` to the relevant joints. Another reason for vibration is feedback from
+  explicit damping. Use the implicit or implicitfast integrators, as documented in the
+  :ref:`Numerical Integration<geIntegration>` section.
+
+**Slow slippage**
+  Unlike the above problems which lead to fast slippage, slow, gradual slippage is a property of MuJoCo's contact
+  model by design, since without it the inverse dynamics are not defined. This is discussed in detail in the
+  :ref:`softness and slip<Soft>` clarification. This type of slippage can be addressed in two ways.
+
+  a. Increase the :ref:`impration<option-impratio>` parameter. This will reduce (but not entirely prevent) slow
+     slippage. Note that high impratio values work well only with :ref:`elliptic cones<option-cone>`.
+  b. Enable the noslip solver by increasing :ref:`noslip_iterations<option-noslip_iterations>` to a positive integer.
+     A small number (1, 2 or 3) is usually sufficient. The noslip post-processing solver will entirely prevent slip,
+     at the cost of making inverse dynamics ill-defined and additional computational cost.
+
 .. _CBacklash:
 
 Backlash
@@ -1710,7 +1768,7 @@ destabilize the system because of integration errors. This was already discussed
 
 The standard approach to reducing integration errors is to reduce the timestep or use the Runge-Kutta integrator, both
 of which are effective but slow down the simulation. An alternative approach is to put all damping in the joints and
-use the Euler integrator. In that case damping forces are integrated implicitly - meaning that the inertia matrix is
+use the Euler integrator. In that case damping forces are integrated implicitly -- meaning that the inertia matrix is
 adjusted and re-factorized internally as part of the velocity update, in a way transparent to the user. Implicit
 integration is much more stable than explicit integration, allowing substantially larger time steps. Note that the
 Runge-Kutta integrator is explicit, and so is Euler except for the way it treats damping forces. Ideally we would have

doc/overview.rst

@@ -56,7 +56,7 @@ Soft, convex and analytically-invertible contact dynamics
    equality constraints.
 
 Tendon geometry
-   MuJoCo can model the 3D geometry of tendons - which are minimum-path-length strings obeying wrapping and via-point
+   MuJoCo can model the 3D geometry of tendons -- which are minimum-path-length strings obeying wrapping and via-point
    constraints. The mechanism is similar to the one in OpenSim but implements a more restricted, closed-form set of
    wrapping options to speed up computation. It also offers robotics-specific structures such as pulleys and coupled
    degrees of freedom. Tendons can be used for actuation as well as to impose inequality or equality constraints on the
@@ -635,7 +635,7 @@ store results from custom computations there; recall that everything that change
 Custom text
 ^^^^^^^^^^^
 
-Custom text fields can be saved in the model. They can be used in custom computations - either to specify keyword
+Custom text fields can be saved in the model. They can be used in custom computations -- either to specify keyword
 commands, or to provide some other textual information. Do not use them for comments though; there is no benefit to
 saving comments in a compiled model. XML has its own commenting mechanism (ignored by MuJoCo's parser and compiler)
 which is more suitable.
@@ -788,7 +788,8 @@ For situations where it is desirable to suppress slip completely, there is a sec
 the main solver. It updates the contact forces in friction dimensions by disregarding constraint softness. When this
 option is used however, MuJoCo is no longer solving the convex optimization problem it was designed to solve, and the
 simulation may become less robust. Thus using the Newton solver with elliptic friction cones and large value of
-``impratio`` is the recommended way of reducing slip.
+``impratio`` is the recommended way of reducing slip. For more detailed recommendations, see
+:ref:`preventing slip<CSlippage>` in the Modeling chapter.
 
 .. _TypeNameId:
 
@@ -847,7 +848,7 @@ Now the differences. Bodies are used to construct the kinematic tree and are con
 geoms and sites. Bodies have a spatial frame, inertial properties, but no properties related to appearance or collision
 geometry. This is because such properties do not affect the physics (except for contacts of course, but these are
 handled separately). If you have seen diagrams of kinematic trees in robotics textbooks, the bodies are usually drawn as
-amorphous shapes - to make the point that their actual shape is irrelevant to the physics.
+amorphous shapes -- to make the point that their actual shape is irrelevant to the physics.
 
 Geoms (short for geometric primitive) are used to specify appearance and collision geometry. Each geom belongs to a body
 and is rigidly attached to that body. Multiple geoms can be attached to the same body. This is particularly useful in