doc multibody: Call out nuances on spatial inertia monogram; add explicit "expressed-in" monogram column

[EricCousineau-TRI]

Summary from f2f with @amcastro-tri:

I was implementing a quick, but generalized, ComputeCompositeInertia algorithm in Anzu to replace the hacky specific version copied from ManipulationStation to compute the gripper inertia when creating the IIWA controller. (Will upstream it, but not immediately.)

To validate the computation, I wanted to compute the kinetic energy of two floating models (w/ non-trivial pose and spatial velocity): (a) an articulated model and (b) a composite non-articulated version of the same model.

When doing the kinetic energy via spatial velocities, I accidentally computed the energy incorrectly as:

const double ke_B = 0.5 * (M_BWo_W * V_WB).dot(V_WB);

rather than the correct version:

const double ke_B = 0.5 * (M_BBo_W * V_WB).dot(V_WB);

The reason is that I looked at the documentation in spatial_momentum.h, used that formula, but hadn't fully sorted through what the inertia's "about" point should be, and pattern-matched correctly.

It would have been helpful to me if, in the Multibody Quantities table:

• There was a big WARNING section that mentioned the semantic difference in frame ordering between spatial inertias and other quantities; e.g.
  • p_BQ is position of Q w.r.t. B
  • M_BQ is the spatial inertia of B expressed about Q about point Q.
• Add a column after "Code" to add in "Expressed-In Version" to expand on the monogram to make the expressed-in frame explicit (e.g. p_BQ -> p_BQ_B, M_BQ -> M_BQ_B).

(NOTE: In the end, I just checked the kinetic energy w/ the mass matrix, 0.5 * v.dot(M(q) * v).)

\cc @sherm1 @siyuanfeng-tri

[sherm1]

Thanks, @EricCousineau-TRI! @mitiguy, can you take a look at this please to see if we can improve the notation & doc to avoid future trouble?

[EricCousineau-TRI]

Per discussion on Slack: https://drakedevelopers.slack.com/archives/C2WBPQDB7/p1559770286041200?thread_ts=1559682534.013300&cid=C2WBPQDB7

It would be nice if we also call out that transforms/poses shouldn't have explicitly expressed-in notation, as it's generally dubious.

Example: X_AB_C could imply (R_BC, p_AB_C), but that just looks confusing.

[sherm1]

Worse -- X_AB_C would mean (R_CB, p_AB_C) which is really useless! That's because a rotation matrix R_AB is composed of the three axes of B, expressed in A, like this:

R_AB = [ Bx_A By_A Bz_A]

Re-expressing those three vectors in C produces

R_AB_C = [ Bx_C By_C Bz_C] = R_CB

We don't allow the "expressed-in" frame suffix in our notation for rotations or transforms since the result would be meaningless, or at best confusing.

[EricCousineau-TRI]

Unassigning myself; multiple owners on an issue muddles responsibility IMO.

[EricCousineau-TRI]

FTR I'm not sure if this issue would have helped this Slack discussion at all: https://drakedevelopers.slack.com/archives/C2WBPQDB7/p1587738147097000?thread_ts=1587678529.092200&cid=C2WBPQDB7

[amcastro-tri]

copy/pasting my thoughts from that thread:

I feel like lil code snippets like the one above would be useful to have somewhere more discoverable. Probably a python tutorial on spatial algebra?

That is, a nice example with use cases probably in tutorial form would be much better than updating a table with operations out of context.

[EricCousineau-TRI]

Aye, that would make more sense. Perhaps make an issue for it, then?

FYI @IanTheEngineer This may relate #12912, #13084 However, you may want to explicitly recruit someone else's help in writing the tutorial (not just reviewing it) - e.g. from Dynamics, maybe @amcastro-tri or @mitiguy? :)

[mitiguy]

I am moving this up my priority list now.