Name changes & infrastructure in support of composites to come (#24443)

Also miscellaneous opportunistic comment cleanups.

Author: sherm1

bindings/generated_docstrings/multibody_math.h

@@ -1005,6 +1005,13 @@ Parameter ``translational_tolerance``:
     elements of ``this`` and ``other`` are equal within
     translational_tolerance.)""";
         } IsNearlyEqualWithinAbsoluteTolerance;
+        // Symbol: drake::multibody::SpatialVector::NaN
+        struct /* NaN */ {
+          // Source: drake/multibody/math/spatial_vector.h
+          const char* doc =
+R"""(Factory to create a *NaN* spatial vector, i.e., a SpatialVector whose
+rotational and translational components are all NaN.)""";
+        } NaN;
         // Symbol: drake::multibody::SpatialVector::SetNaN
         struct /* SetNaN */ {
           // Source: drake/multibody/math/spatial_vector.h

bindings/generated_docstrings/multibody_plant.h

@@ -186,32 +186,6 @@ This method must be called pre-Finalize.
 Raises:
     RuntimeError if ``plant`` is finalized or if time_step is changed.)""";
       } ApplyMultibodyPlantConfig;
-      // Symbol: drake::multibody::BaseBodyJointType
-      struct /* BaseBodyJointType */ {
-        // Source: drake/multibody/plant/multibody_plant.h
-        const char* doc =
-R"""(The kind of joint to be used to connect base bodies to world at
-Finalize(). See mbp_working_with_free_bodies "Working with free
-bodies" for definitions and discussion.
-
-See also:
-    SetBaseBodyJointType() for details.)""";
-        // Symbol: drake::multibody::BaseBodyJointType::kQuaternionFloatingJoint
-        struct /* kQuaternionFloatingJoint */ {
-          // Source: drake/multibody/plant/multibody_plant.h
-          const char* doc = R"""(6 dofs, unrestricted orientation.)""";
-        } kQuaternionFloatingJoint;
-        // Symbol: drake::multibody::BaseBodyJointType::kRpyFloatingJoint
-        struct /* kRpyFloatingJoint */ {
-          // Source: drake/multibody/plant/multibody_plant.h
-          const char* doc = R"""(6 dofs using 3 angles; has singularity.)""";
-        } kRpyFloatingJoint;
-        // Symbol: drake::multibody::BaseBodyJointType::kWeldJoint
-        struct /* kWeldJoint */ {
-          // Source: drake/multibody/plant/multibody_plant.h
-          const char* doc = R"""(0 dofs, fixed to World.)""";
-        } kWeldJoint;
-      } BaseBodyJointType;
       // Symbol: drake::multibody::CalcContactFrictionFromSurfaceProperties
       struct /* CalcContactFrictionFromSurfaceProperties */ {
         // Source: drake/multibody/plant/coulomb_friction.h
@@ -4968,7 +4942,7 @@ be used by Finalize(); post-finalize it returns the joint type that
 *was* used if there were any base bodies in need of a joint.
 
 See also:
-    SetBaseBodyJointType())""";
+    SetBaseBodyJointType(), Finalize())""";
         } GetBaseBodyJointType;
         // Symbol: drake::multibody::MultibodyPlant::GetBodiesKinematicallyAffectedBy
         struct /* GetBodiesKinematicallyAffectedBy */ {
@@ -6625,7 +6599,10 @@ Parameter ``model_instance``:
     is to be applied.
 
 Raises:
-    RuntimeError if called after Finalize().)""";
+    RuntimeError if called after Finalize().
+
+See also:
+    GetBaseBodyJointType(), Finalize())""";
         } SetBaseBodyJointType;
         // Symbol: drake::multibody::MultibodyPlant::SetConstraintActiveStatus
         struct /* SetConstraintActiveStatus */ {

bindings/generated_docstrings/multibody_tree.h

@@ -156,6 +156,7 @@ drake_pybind_library(
     name = "plant_py",
     cc_deps = [
         "//bindings/generated_docstrings:multibody_plant",
+        "//bindings/generated_docstrings:multibody_tree",
         "//bindings/pydrake/common:cpp_template_pybind",
         "//bindings/pydrake/common:default_scalars_pybind",
         "//bindings/pydrake/common:deprecation_pybind",

bindings/pydrake/multibody/BUILD.bazel

@@ -5,6 +5,7 @@
 #include <vector>
 
 #include "drake/bindings/generated_docstrings/multibody_plant.h"
+#include "drake/bindings/generated_docstrings/multibody_tree.h"
 #include "drake/bindings/pydrake/common/cpp_template_pybind.h"
 #include "drake/bindings/pydrake/common/default_scalars_pybind.h"
 #include "drake/bindings/pydrake/common/deprecation_pybind.h"
@@ -1776,8 +1777,11 @@ PYBIND11_MODULE(plant, m) {
   }
 
   {
+    // This enum comes from a MultibodyTree header but for historical
+    // reasons we've bound it in plant.
     using Class = BaseBodyJointType;
-    constexpr auto& cls_doc = doc.BaseBodyJointType;
+    constexpr auto& tree_doc = pydrake_doc_multibody_tree.drake.multibody;
+    constexpr auto& cls_doc = tree_doc.BaseBodyJointType;
     py::enum_<Class> cls(m, "BaseBodyJointType", cls_doc.doc);
     cls.value("kQuaternionFloatingJoint", Class::kQuaternionFloatingJoint,
            cls_doc.kQuaternionFloatingJoint.doc)

bindings/pydrake/multibody/plant_py.cc

@@ -85,16 +85,16 @@ class DrakeKukaIIwaRobot {
         MakeKukaIiwaModel<T>(false /* finalized model */,
                              gravity /* acceleration of gravity */));
 
-    linkN_ = &tree().world_body();
+    linkN_ = &tree().world_link();
 
     // Get this robot's seven links.
-    linkA_ = &tree().GetRigidBodyByName("iiwa_link_1");
-    linkB_ = &tree().GetRigidBodyByName("iiwa_link_2");
-    linkC_ = &tree().GetRigidBodyByName("iiwa_link_3");
-    linkD_ = &tree().GetRigidBodyByName("iiwa_link_4");
-    linkE_ = &tree().GetRigidBodyByName("iiwa_link_5");
-    linkF_ = &tree().GetRigidBodyByName("iiwa_link_6");
-    linkG_ = &tree().GetRigidBodyByName("iiwa_link_7");
+    linkA_ = &tree().GetLinkByName("iiwa_link_1");
+    linkB_ = &tree().GetLinkByName("iiwa_link_2");
+    linkC_ = &tree().GetLinkByName("iiwa_link_3");
+    linkD_ = &tree().GetLinkByName("iiwa_link_4");
+    linkE_ = &tree().GetLinkByName("iiwa_link_5");
+    linkF_ = &tree().GetLinkByName("iiwa_link_6");
+    linkG_ = &tree().GetLinkByName("iiwa_link_7");
 
     // Get this robot's seven joints.
     NA_joint_ = &tree().template GetJointByName<RevoluteJoint>("iiwa_joint_1");
@@ -111,7 +111,7 @@ class DrakeKukaIIwaRobot {
 
   /// This method gets the number of rigid bodies in this robot.
   /// @returns the number of rigid bodies in this robot.
-  int get_number_of_rigid_bodies() const { return tree().num_bodies(); }
+  int get_number_of_rigid_bodies() const { return tree().num_links(); }
 
   /// This method calculates kinematic properties of the end-effector (herein
   /// denoted as rigid body G) of a 7-DOF KUKA LBR iiwa robot (14 kg payload).
@@ -145,7 +145,7 @@ class DrakeKukaIIwaRobot {
     const SpatialVelocity<T>& V_NG_N = vc.get_V_WB(linkG_->mobod_index());
 
     // Retrieve end-effector spatial acceleration from acceleration cache.
-    std::vector<SpatialAcceleration<T>> A_WB(tree().num_bodies());
+    std::vector<SpatialAcceleration<T>> A_WB(tree().num_links());
     // TODO(eric.cousineau): For this model, the end effector's BodyIndex
     // matches its MobodIndex, thus we're not really checking the difference
     // between MultibodyPlant and MultibodyTree's ordering.

multibody/benchmarks/kuka_iiwa_robot/drake_kuka_iiwa_robot.h

@@ -75,13 +75,13 @@ KukaIiwaModelBuilder<T>::Build() const {
                                                      I_GGcm_G_);
 
   // Add this robot's seven links.
-  const RigidBody<T>& linkA = model->AddRigidBody("iiwa_link_1", M_AAo_A);
-  const RigidBody<T>& linkB = model->AddRigidBody("iiwa_link_2", M_BBo_B);
-  const RigidBody<T>& linkC = model->AddRigidBody("iiwa_link_3", M_CCo_C);
-  const RigidBody<T>& linkD = model->AddRigidBody("iiwa_link_4", M_DDo_D);
-  const RigidBody<T>& linkE = model->AddRigidBody("iiwa_link_5", M_EEo_E);
-  const RigidBody<T>& linkF = model->AddRigidBody("iiwa_link_6", M_FFo_F);
-  const RigidBody<T>& linkG = model->AddRigidBody("iiwa_link_7", M_GGo_G);
+  const Link<T>& linkA = model->AddLink("iiwa_link_1", M_AAo_A);
+  const Link<T>& linkB = model->AddLink("iiwa_link_2", M_BBo_B);
+  const Link<T>& linkC = model->AddLink("iiwa_link_3", M_CCo_C);
+  const Link<T>& linkD = model->AddLink("iiwa_link_4", M_DDo_D);
+  const Link<T>& linkE = model->AddLink("iiwa_link_5", M_EEo_E);
+  const Link<T>& linkF = model->AddLink("iiwa_link_6", M_FFo_F);
+  const Link<T>& linkG = model->AddLink("iiwa_link_7", M_GGo_G);
 
   // Create a revolute joint between linkN (Newtonian frame/world) and linkA
   // using two joint-frames, namely "Na" and "An".  The "inboard frame" Na is
@@ -91,7 +91,7 @@ KukaIiwaModelBuilder<T>::Build() const {
   // angles and a position vector. Alternately, frame An is regarded as
   // coincident with linkA.
   const Joint<T>* joint{nullptr};
-  const RigidBody<T>& linkN = model->world_body();
+  const Link<T>& linkN = model->world_link();
   joint = &AddRevoluteJointFromSpaceXYZAnglesAndXYZ(
       "iiwa_joint_1", linkN, joint_1_rpy_, joint_1_xyz_, linkA,
       Eigen::Vector3d::UnitZ(), model.get());
@@ -109,7 +109,7 @@ KukaIiwaModelBuilder<T>::Build() const {
       Eigen::Vector3d::UnitZ(), model.get());
   model->AddJointActuator("iiwa_actuator_3", *joint);
 
-  // Create a revolute joint between linkB and linkC.
+  // Create a revolute joint between linkC and linkD.
   joint = &AddRevoluteJointFromSpaceXYZAnglesAndXYZ(
       "iiwa_joint_4", linkC, joint_4_rpy_, joint_4_xyz_, linkD,
       Eigen::Vector3d::UnitZ(), model.get());

multibody/benchmarks/kuka_iiwa_robot/make_kuka_iiwa_model.cc

@@ -291,6 +291,14 @@ class SpatialVector {
   /// rotational and translational components are both zero.
   static SpatialQuantity Zero() { return SpatialQuantity{}.SetZero(); }
 
+  /// Factory to create a _NaN_ spatial vector, i.e., a %SpatialVector whose
+  /// rotational and translational components are all NaN.
+  static SpatialQuantity NaN() {
+    SpatialQuantity quantity;
+    quantity.SetNaN();
+    return quantity;
+  }
+
  private:
   // Helper method to return a mutable reference to the derived spatial
   // quantity.

multibody/math/spatial_vector.h

@@ -110,6 +110,27 @@ TYPED_TEST(SpatialQuantityTest, ZeroFactory) {
   EXPECT_TRUE(V.translational() == Vector3<T>::Zero());
 }
 
+// Construction of a "NaN" spatial vector.
+TYPED_TEST(SpatialQuantityTest, NaNFactory) {
+  typedef typename TestFixture::SpatialQuantityType SpatialQuantity;
+  typedef typename TestFixture::ScalarType T;
+  SpatialQuantity V = SpatialQuantity::NaN();
+  auto is_nan = [](const T& x) -> bool {
+    if constexpr (std::is_same_v<T, Expression>) {
+      return symbolic::is_nan(x);
+    }
+    if constexpr (std::is_same_v<T, AutoDiffXd>) {
+      return std::isnan(x.value());
+    }
+    if constexpr (std::is_same_v<T, double>) {
+      return std::isnan(x);
+    }
+  };
+  for (int i = 0; i < V.size(); ++i) {
+    EXPECT_TRUE(is_nan(V[i]));
+  }
+}
+
 // Tests:
 // - Construction from a Eigen expressions.
 // - SetZero() method.

multibody/math/test/spatial_algebra_test.cc

@@ -333,7 +333,7 @@ template <typename T>
 void DeformableModel<T>::SetParallelism(Parallelism parallelism) {
   parallelism_ = parallelism;
   const std::vector<DeformableBodyIndex>& body_indices =
-      deformable_bodies_.indices();
+      deformable_bodies_.valid_indices();
   for (const DeformableBodyIndex& index : body_indices) {
     deformable_bodies_.get_mutable_element(index).set_parallelism(parallelism);
   }
@@ -346,7 +346,8 @@ void DeformableModel<T>::SetDefaultState(const systems::Context<T>& context,
     DRAKE_DEMAND(is_empty());
     return;
   } else {
-    for (const DeformableBodyIndex& index : deformable_bodies_.indices()) {
+    for (const DeformableBodyIndex& index :
+         deformable_bodies_.valid_indices()) {
       const DeformableBody<T>& body = deformable_bodies_.get_element(index);
       body.SetDefaultState(context, state);
     }
@@ -372,7 +373,8 @@ std::unique_ptr<PhysicalModel<double>> DeformableModel<T>::CloneToDouble(
 
     /* Copy over deformable_bodies_. */
     result->deformable_bodies_.ResizeToMatch(deformable_bodies_);
-    for (const DeformableBodyIndex& index : deformable_bodies_.indices()) {
+    for (const DeformableBodyIndex& index :
+         deformable_bodies_.valid_indices()) {
       const DeformableBody<T>& body = deformable_bodies_.get_element(index);
       result->deformable_bodies_.Add(body.CloneToDouble());
     }
@@ -430,7 +432,7 @@ void DeformableModel<T>::DoDeclareSystemResources() {
 
     /* Declare discrete states and parameters. */
     const std::vector<DeformableBodyIndex>& body_indices =
-        deformable_bodies_.indices();
+        deformable_bodies_.valid_indices();
     for (const DeformableBodyIndex& index : body_indices) {
       DeformableBody<T>& body = deformable_bodies_.get_mutable_element(index);
       body.DeclareDiscreteState(static_cast<internal::MultibodyTreeSystem<T>*>(
@@ -482,7 +484,7 @@ void DeformableModel<T>::CopyVertexPositions(const systems::Context<T>& context,
       output->get_mutable_value<geometry::GeometryConfigurationVector<T>>();
   output_value.clear();
   const std::vector<DeformableBodyIndex>& body_indices =
-      deformable_bodies_.indices();
+      deformable_bodies_.valid_indices();
   for (const DeformableBodyIndex& index : body_indices) {
     const DeformableBody<T>& body = deformable_bodies_.get_element(index);
     const GeometryId geometry_id = body.geometry_id();