Actuator model: rotor inertia, gear ratio and joint friction

[Onwcan]

What is missing

RigidBody describes a rigid link and nothing else.

There is currently no model for:

• motor rotor inertia
• gear ratio
• viscous joint friction
• Coulomb joint friction

As a result, the torque returned by inverseDynamics is the torque demanded by the linkage, not necessarily the torque a motor must produce.

Why it matters

On a real machine, rotor inertia reflected through a high gear ratio can be comparable to the inertia of the link itself.

A user who interprets the current result as motor torque can therefore undersize a drive.

The error is largest exactly where that becomes expensive: fast, small-amplitude moves where reflected rotor inertia dominates.

Coulomb and viscous friction create a similar discrepancy during slower motion.

ADR-0010 already documents the omission, so the current behaviour is not misleading by design. This is nevertheless the main change required to move the dynamics module from "kinematically correct" toward "usable for drive sizing".

Proposed shape

Per joint, add:

• rotor_inertia — kg m^2, motor side
• gear_ratio — dimensionless, with n = theta_motor / theta_joint
• viscous — N m s / rad
• coulomb — N m

Reflected rotor inertia contributes n^2 * rotor_inertia to the diagonal of the mass matrix.

It does not introduce coupling.

Joint friction contributes viscous * qd + coulomb * sign(qd) to torque.

The discontinuity at qd == 0 must be handled explicitly rather than depending on floating-point signed-zero behaviour.

Where

• include/motionkit/core/dynamics.hpp — RigidBody, DynamicChain
• src/core/dynamics.cpp — RNEA and CRBA

Acceptance criteria

• Extend RigidBody, or introduce a sibling JointActuator, carrying the four actuator terms.
• A default-constructed actuator model must reproduce today's numbers exactly.
• Add a regression test proving existing measurements remain unchanged under default parameters.
• Reflected inertia must appear in both massMatrix and inverseDynamics.
• The existing CRBA-vs-RNEA cross-check must continue to agree to approximately one ULP. The current reference is 8.882e-16 kg m^2.
• Friction must not appear in the gravity torque.
• Friction must not appear in massMatrix.
• Add tests pinning both properties.
• Validate non-negative rotor inertia.
• Validate non-zero gear ratio.
• Validate non-negative friction coefficients.
• Add a qd == 0 test proving the Coulomb term does not flip sign depending on floating-point signed zero.
• Re-run benchmarks.
• If performance moves materially, update the README from the current reference figures: inverse dynamics approximately 416 ns and mass matrix approximately 400 ns.
• Amend the ADR-0010 consequence section that currently records actuator effects as not implemented.

Not in scope

Link flexibility.

That changes the state vector rather than simply adding actuator parameters and belongs to a different class of model.

References

docs/adr/0010-dynamics-in-the-base-frame.md, Consequences.