From 534aedd47ddd294aa89d4f459389d7fcf5489509 Mon Sep 17 00:00:00 2001 From: Yuval Tassa Date: Sun, 13 Oct 2024 07:24:09 -0700 Subject: [PATCH] Improve documentation of `joint/armature`. See Drake [discussion](https://github.com/RobotLocomotion/drake/pull/21967) for more context. PiperOrigin-RevId: 685428316 Change-Id: I80e8d4f097697f28529f5891a763979390c59e99 --- doc/XMLreference.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index 7ea1158a..e5f3e92e 100644 --- a/doc/XMLreference.rst +++ b/doc/XMLreference.rst @@ -2200,13 +2200,14 @@ rotations as unit quaternions. .. _body-joint-armature: :at:`armature`: :at-val:`real, "0"` - Armature inertia (or rotor inertia, or reflected inertia) of all degrees of freedom created by this joint. These are - constants added to the diagonal of the inertia matrix in generalized coordinates. They make the simulation more - stable, and often increase physical realism. This is because when a motor is attached to the system with a - transmission that amplifies the motor force by c, the inertia of the rotor (i.e., the moving part of the motor) is - amplified by c*c. The same holds for gears in the early stages of planetary gear boxes. These extra inertias often - dominate the inertias of the robot parts that are represented explicitly in the model, and the armature attribute is - the way to model them. + Additional inertia associated with movement of the joint that is not due to body mass. This added inertia is usually + due to a rotor (a.k.a `armature `__) spinning faster than the + joint itself due to a geared transmission; in this case the added inertia is known as "reflected inertia" and its + value is the rotational inertia of the spinning element multiplied by the square of the gear ratio. The value applies + to all degrees of freedom created by this joint. + + Besides increasing the realism of joints with geared transmission, positive :at:`armature` significantly improves + simulation stability, even for small values, and is a recommended possible fix when encountering stability issues. .. _body-joint-damping: