[multibody] Implement kinematic results for fused links (pos & vel).

[sherm1]

Separates per-mobod kinematics from per-link kinematics so that we get correct link kinematics when fusing welded-together links onto a single mobod.

Changes here:

• position and velocity cache entries gain some new fields, and methods that were incorrectly implemented in the header are moved to the cc file
• position and velocity kinematics calculations fill in the new fields (see body_node_impl.cc)
• new unit tests in fused_welds_test.cc
• cassie bench gets a --fuse flag to support timing comparisons between fused/unfused.
• RigidBody class gets some terminology cleanup to support wider use of "link" internally, and methods that were incorrectly implemented in the header are moved to the cc file
• Two test tolerances that were too tight for Mac are reduced

There are no user-visible changes here unless fusing is enabled (which is "internal only" for now). Also, there are likely to be several independent kinematics-dependent computations that are written in terms of mobods that need to be in terms of links instead, and possibly vice versa. Those will be addressed in their own PRs.

---

This change is 

[sherm1]

+a:@mitiguy for feature review, please

@sherm1 made 1 comment.
Reviewable status: LGTM missing from assignee mitiguy, needs platform reviewer assigned, needs at least two assigned reviewers (waiting on mitiguy).

[Copilot]

Pull request overview

This PR extends MultibodyTree kinematics to correctly report per-link poses and spatial velocities when multiple welded-together links are fused onto a single mobilized body (mobod). It updates the position/velocity cache structures and fills the new link-indexed results during kinematics recursion, adds tests to validate fused vs explicit-weld equivalence, and adds a benchmarking toggle for timing comparisons.

Changes:

• Refactors kinematics caches to separate mobod vs link results (e.g., V_WL, X_WL, and new p_BoLo_W).
• Updates kinematics computations to populate link kinematics for fused mobods (position + velocity).
• Adds fused-weld kinematics unit tests and a Cassie benchmark --fuse flag; includes terminology cleanup (Link vs RigidBody) and minor tolerance updates.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
multibody/tree/velocity_kinematics_cache.h	Refactors cache API (ctor + SetToZero) and updates documentation for link-aware velocity results.
multibody/tree/velocity_kinematics_cache.cc	Implements moved-out ctor / allocation / zeroing logic; initializes world and world-fixed link velocities.
multibody/tree/test/tree_from_mobilizers_test.cc	Updates to new velocity-cache API (SetToZero).
multibody/tree/rigid_body.h	Introduces Link synonym, renames attorney, updates link-vs-mobod wording, and moves inline methods to .cc.
multibody/tree/rigid_body.cc	Adds out-of-line implementations for Lock/Unlock, topology setup, parameter plumbing, and finalize checks.
multibody/tree/position_kinematics_cache.h	Adds p_BoLo_W storage/accessors for link origins relative to mobod origins.
multibody/tree/position_kinematics_cache.cc	Allocates/initializes p_BoLo_W and fills world-composite precomputations.
multibody/tree/multibody_tree.cc	Uses LinkAttorney, updates velocity zeroing, and adjusts frame-body pose / inertia bookkeeping for link ordinals.
multibody/tree/joint.h	Makes mobilizer clone lookup robust to mobilizer_ == nullptr.
multibody/tree/frame_body_pose_cache.h	Documents world-composite precalculation expectations.
multibody/tree/body_node_impl.cc	Populates per-link X_WL and p_BoLo_W for fused mobods; computes per-link V_WL via shifts.
multibody/plant/test/fused_welds_test.cc	Adds unit tests comparing link poses and spatial velocities for fused vs explicit welds.
multibody/optimization/test/toppra_test.cc	Relaxes an overly-tight numeric tolerance (Mac stability).
multibody/benchmarking/cassie.cc	Adds --fuse flag and updates Jacobian benchmark loop to iterate mobods / active links.
multibody/benchmarking/BUILD.bazel	Adds direct @gflags dependency for new flag include.
bindings/generated_docstrings/multibody_tree.h	Updates generated docstrings to reflect terminology and doc changes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mitiguy]

Just starting. Consider changing "explicit" to "unfused" -- some examples below.

@mitiguy partially reviewed 3 files and made 4 comments.
Reviewable status: 5 unresolved discussions, LGTM missing from assignee mitiguy, needs platform reviewer assigned, needs at least two assigned reviewers (waiting on sherm1).

---

multibody/benchmarking/cassie.cc line 139 at r2 (raw file):

        // The active link's link frame is also the Mobod's frame.
        const Frame<double>& active_link_frame =
            plant_->get_body(active_link_index).link_frame();

nit Hmmm. One line of code was replaced by many. If this pattern (or one like it for getting the body) repeats often, perhaps there should be a shortcut?

---

multibody/plant/test/fused_welds_test.cc line 167 at r2 (raw file):

GTEST_TEST(CompositeTest, LinkKinematicsMatchExplicitWelds) {
  const TestModel explicit_model = MakeModel(false /* unfused */);
  const TestModel fused_model = MakeModel(true /* fuse welds */);

nit Consider using "unfused" rather than "explicit". It is shorter, and then the comment after false is redundant.

Suggestion:

  const TestModel unfused_model = MakeModel(false);
  const TestModel fused_model = MakeModel(true);

---

multibody/plant/test/fused_welds_test.cc line 186 at r2 (raw file):

             {"Link3", explicit_model.link3, fused_model.link3},
             {"Link4", explicit_model.link4, fused_model.link4},
         }) {

nit Consider unfused -- which is what is used in later tests.

Suggestion:

    for (const auto& [link_name, unfused_link, fused_link] :
         std::vector<std::tuple<const char*, const RigidBody<double>*,
                                const RigidBody<double>*>>{
             {"Link1", unfused_model.link1, fused_model.link1},
             {"Link2", unfused_model.link2, fused_model.link2},
             {"Link3", unfused_model.link3, fused_model.link3},
             {"Link4", unfused_model.link4, fused_model.link4},
         }) {

[sherm1]

Resolved all the feature review comments so far.

@sherm1 made 6 comments and resolved 5 discussions.
Reviewable status: LGTM missing from assignee mitiguy, needs platform reviewer assigned, needs at least two assigned reviewers (waiting on mitiguy).

---

multibody/benchmarking/cassie.cc line 139 at r2 (raw file):

Previously, mitiguy (Mitiguy) wrote…

nit Hmmm. One line of code was replaced by many. If this pattern (or one like it for getting the body) repeats often, perhaps there should be a shortcut?

Done. I added an internal helper function to MultibodyTree.

---

multibody/plant/test/fused_welds_test.cc line 167 at r2 (raw file):

Previously, mitiguy (Mitiguy) wrote…

nit Consider using "unfused" rather than "explicit". It is shorter, and then the comment after false is redundant.

Done

---

multibody/plant/test/fused_welds_test.cc line 186 at r2 (raw file):

Previously, mitiguy (Mitiguy) wrote…

nit Consider unfused -- which is what is used in later tests.

Done

[sherm1]

@sherm1 made 1 comment.
Reviewable status: LGTM missing from assignee mitiguy, needs platform reviewer assigned, needs at least two assigned reviewers (waiting on mitiguy).