Name changes in support of composites to come

Author: sherm1

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

@@ -589,6 +589,32 @@ representation.)""";
           const char* doc = R"""()""";
         } type_name;
       } BallRpyJoint;
+      // Symbol: drake::multibody::BaseBodyJointType
+      struct /* BaseBodyJointType */ {
+        // Source: drake/multibody/tree/multibody_tree.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/tree/multibody_tree.h
+          const char* doc = R"""(6 dofs, unrestricted orientation.)""";
+        } kQuaternionFloatingJoint;
+        // Symbol: drake::multibody::BaseBodyJointType::kRpyFloatingJoint
+        struct /* kRpyFloatingJoint */ {
+          // Source: drake/multibody/tree/multibody_tree.h
+          const char* doc = R"""(6 dofs using 3 angles; has singularity.)""";
+        } kRpyFloatingJoint;
+        // Symbol: drake::multibody::BaseBodyJointType::kWeldJoint
+        struct /* kWeldJoint */ {
+          // Source: drake/multibody/tree/multibody_tree.h
+          const char* doc = R"""(0 dofs, fixed to World.)""";
+        } kWeldJoint;
+      } BaseBodyJointType;
       // Symbol: drake::multibody::BodyIndex
       struct /* BodyIndex */ {
         // Source: drake/multibody/tree/multibody_tree_indexes.h
@@ -2778,7 +2804,7 @@ extract X_BF for this Frame from it.
     since the last parameter change; we can't check here.
 
 Returns ``X_BF``:
-    pose of this frame in its body's frame)""";
+    pose of this frame in its Mobod's frame)""";
         } get_X_BF;
         // Symbol: drake::multibody::Frame::get_X_FB
         struct /* get_X_FB */ {
@@ -5115,6 +5141,17 @@ body frame B.)""";
           const char* doc = R"""()""";
         } stiffness;
       } LinearSpringDamper;
+      // Symbol: drake::multibody::LinkIndex
+      struct /* LinkIndex */ {
+        // Source: drake/multibody/tree/multibody_tree_indexes.h
+        const char* doc = R"""(This is a synonym for BodyIndex.)""";
+      } LinkIndex;
+      // Symbol: drake::multibody::LinkOrdinal
+      struct /* LinkOrdinal */ {
+        // Source: drake/multibody/tree/multibody_tree_indexes.h
+        const char* doc =
+R"""(Type used to identify links by ordinal within a multibody plant.)""";
+      } LinkOrdinal;
       // Symbol: drake::multibody::ModelInstanceIndex
       struct /* ModelInstanceIndex */ {
         // Source: drake/multibody/tree/multibody_tree_indexes.h
@@ -7676,6 +7713,14 @@ the index into all associated quantities.)""";
 R"""(Gets the ``name`` associated with this rigid body. The name will never
 be empty.)""";
         } name;
+        // Symbol: drake::multibody::RigidBody::ordinal
+        struct /* ordinal */ {
+          // Source: drake/multibody/tree/rigid_body.h
+          const char* doc =
+R"""((Internal use only) Returns this Link's (RigidBody's) unique ordinal.
+Currently identical to the index but will differ when we permit
+removal of Links as we do for Joints.)""";
+        } ordinal;
         // Symbol: drake::multibody::RigidBody::scoped_name
         struct /* scoped_name */ {
           // Source: drake/multibody/tree/rigid_body.h

bindings/pydrake/multibody/plant_py.cc

@@ -1775,17 +1775,6 @@ PYBIND11_MODULE(plant, m) {
         .value("kLagged", Class::kLagged, cls_doc.kLagged.doc);
   }
 
-  {
-    using Class = BaseBodyJointType;
-    constexpr auto& cls_doc = doc.BaseBodyJointType;
-    py::enum_<Class> cls(m, "BaseBodyJointType", cls_doc.doc);
-    cls.value("kQuaternionFloatingJoint", Class::kQuaternionFloatingJoint,
-           cls_doc.kQuaternionFloatingJoint.doc)
-        .value("kRpyFloatingJoint", Class::kRpyFloatingJoint,
-            cls_doc.kRpyFloatingJoint.doc)
-        .value("kWeldJoint", Class::kWeldJoint, cls_doc.kWeldJoint.doc);
-  }
-
   {
     using Class = MultibodyPlantConfig;
     constexpr auto& cls_doc = doc.MultibodyPlantConfig;

bindings/pydrake/multibody/test/plant_test.py

@@ -59,7 +59,6 @@
     AddMultibodyPlant,
     AddMultibodyPlantSceneGraph,
     ApplyMultibodyPlantConfig,
-    BaseBodyJointType,
     CalcContactFrictionFromSurfaceProperties,
     ConnectContactResultsToDrakeVisualizer,
     ContactModel,
@@ -81,6 +80,7 @@
 )
 from pydrake.multibody.tree import (
     BallRpyJoint_,
+    BaseBodyJointType,
     Body_,  # dispreferred alias for RigidBody_
     BodyIndex,
     CalcSpatialInertia,

bindings/pydrake/multibody/tree_py.cc

@@ -148,6 +148,17 @@ void DoScalarIndependentDefinitions(py::module m) {
         .value("kV", Enum::kV, enum_doc.kV.doc);
   }
 
+  {
+    using Enum = BaseBodyJointType;
+    constexpr auto& cls_doc = doc.BaseBodyJointType;
+    py::enum_<Enum> cls(m, "BaseBodyJointType", cls_doc.doc);
+    cls.value("kQuaternionFloatingJoint", Enum::kQuaternionFloatingJoint,
+           cls_doc.kQuaternionFloatingJoint.doc)
+        .value("kRpyFloatingJoint", Enum::kRpyFloatingJoint,
+            cls_doc.kRpyFloatingJoint.doc)
+        .value("kWeldJoint", Enum::kWeldJoint, cls_doc.kWeldJoint.doc);
+  }
+
   {
     using Class = ScopedName;
     constexpr auto& cls_doc = doc.ScopedName;

multibody/benchmarks/kuka_iiwa_robot/drake_kuka_iiwa_robot.h

@@ -85,7 +85,7 @@ 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");
@@ -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/make_kuka_iiwa_model.cc

@@ -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 RigidBody<T>& linkN = model->world_link();
   joint = &AddRevoluteJointFromSpaceXYZAnglesAndXYZ(
       "iiwa_joint_1", linkN, joint_1_rpy_, joint_1_xyz_, linkA,
       Eigen::Vector3d::UnitZ(), model.get());

multibody/optimization/test/toppra_test.cc

@@ -210,7 +210,7 @@ TEST_F(IiwaToppraTest, JointTorqueLimit) {
   auto s_path = result.value();
 
   // This tolerance was tuned to work with the given gridpoints.
-  const double tol = 1e-14;
+  const double tol = 1e-13;
   Eigen::MatrixXd M(7, 7);
   Eigen::VectorXd Cv(7);
   Eigen::VectorXd G(7);

multibody/plant/multibody_plant.cc

@@ -1350,7 +1350,7 @@ void MultibodyPlant<T>::CalcSpatialAccelerationsFromVdot(
     // Make sure there aren't any inactives for now.
     DRAKE_DEMAND(ssize(mobod.follower_link_ordinals()) == 1);
     const BodyIndex active_link_index =
-        forest.links(mobod.link_ordinal()).index();
+        forest.links(mobod.active_link_ordinal()).index();
     (*A_WB_array)[active_link_index] = A_WB_array_mobod[mobod.index()];
   }
 }
@@ -1418,43 +1418,13 @@ template <typename T>
 void MultibodyPlant<T>::SetBaseBodyJointType(
     BaseBodyJointType joint_type,
     std::optional<ModelInstanceIndex> model_instance) {
-  std::optional<internal::ForestBuildingOptions> options;
-  switch (joint_type) {
-    case BaseBodyJointType::kQuaternionFloatingJoint:
-      options = internal::ForestBuildingOptions::kDefault;
-      break;
-    case BaseBodyJointType::kRpyFloatingJoint:
-      options = internal::ForestBuildingOptions::kUseRpyFloatingJoints;
-      break;
-    case BaseBodyJointType::kWeldJoint:
-      options = internal::ForestBuildingOptions::kUseFixedBase;
-      break;
-  }
-  DRAKE_DEMAND(options.has_value());
-  DRAKE_THROW_UNLESS(!is_finalized());
-  internal::LinkJointGraph& graph = mutable_tree().mutable_graph();
-  if (model_instance.has_value()) {
-    graph.SetForestBuildingOptions(*model_instance, *options);
-  } else {
-    graph.SetGlobalForestBuildingOptions(*options);
-  }
+  mutable_tree().SetBaseBodyJointType(joint_type, model_instance);
 }
 
 template <typename T>
 BaseBodyJointType MultibodyPlant<T>::GetBaseBodyJointType(
     std::optional<ModelInstanceIndex> model_instance) const {
-  const internal::LinkJointGraph& graph = internal_tree().graph();
-  const internal::ForestBuildingOptions options =
-      model_instance.has_value()
-          ? graph.get_forest_building_options_in_use(*model_instance)
-          : graph.get_global_forest_building_options();
-  if (static_cast<bool>(options &
-                        internal::ForestBuildingOptions::kUseRpyFloatingJoints))
-    return BaseBodyJointType::kRpyFloatingJoint;
-  if (static_cast<bool>(options &
-                        internal::ForestBuildingOptions::kUseFixedBase))
-    return BaseBodyJointType::kWeldJoint;
-  return BaseBodyJointType::kQuaternionFloatingJoint;
+  return internal_tree().GetBaseBodyJointType(model_instance);
 }
 
 template <typename T>

multibody/plant/multibody_plant.h

@@ -245,16 +245,6 @@ enum class DiscreteContactApproximation {
   kLagged,
 };
 
-/// The kind of joint to be used to connect base bodies to world at Finalize().
-/// See @ref mbp_working_with_free_bodies "Working with free bodies"
-/// for definitions and discussion.
-/// @see SetBaseBodyJointType() for details.
-enum class BaseBodyJointType {
-  kQuaternionFloatingJoint,  ///< 6 dofs, unrestricted orientation.
-  kRpyFloatingJoint,         ///< 6 dofs using 3 angles; has singularity.
-  kWeldJoint,                ///< 0 dofs, fixed to World.
-};
-
 /// @cond
 // Helper macro to throw an exception within methods that should not be called
 // post-finalize.
@@ -1267,6 +1257,10 @@ class MultibodyPlant final : public internal::MultibodyTreeSystem<T> {
   const systems::OutputPort<T>& get_generalized_contact_forces_output_port(
       ModelInstanceIndex model_instance) const;
 
+  // TODO(sherm1) Modify the next comment to explain that unmodeled joints will
+  //  have NaN reaction force entries here. (Joints can be unmodeled because
+  //  they were removed or because they are internal to a composite body.)
+
   /// Reports joint reaction forces as an @ref AbstractValue "abstract-valued"
   /// output port containing an `std::vector<SpatialForce<T>>` of size
   /// num_joints().
@@ -1766,6 +1760,7 @@ class MultibodyPlant final : public internal::MultibodyTreeSystem<T> {
   /// @param[in] model_instance (optional) the index of the model instance to
   ///   which `joint_type` is to be applied.
   /// @throws std::exception if called after Finalize().
+  /// @see GetBaseBodyJointType(), Finalize()
   void SetBaseBodyJointType(
       BaseBodyJointType joint_type,
       std::optional<ModelInstanceIndex> model_instance = {});
@@ -1778,7 +1773,7 @@ class MultibodyPlant final : public internal::MultibodyTreeSystem<T> {
   /// This can be called any time -- pre-finalize it returns the joint type
   /// that will 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 SetBaseBodyJointType()
+  /// @see SetBaseBodyJointType(), Finalize()
   BaseBodyJointType GetBaseBodyJointType(
       std::optional<ModelInstanceIndex> model_instance = {}) const;
 
@@ -5195,7 +5190,7 @@ class MultibodyPlant final : public internal::MultibodyTreeSystem<T> {
 
   /// Returns a constant reference to the *world* body.
   const RigidBody<T>& world_body() const {
-    return internal_tree().world_body();
+    return internal_tree().world_link();
   }
 
   /// Returns a constant reference to the *world* frame.
@@ -5206,7 +5201,7 @@ class MultibodyPlant final : public internal::MultibodyTreeSystem<T> {
   /// Returns the number of RigidBody elements in the model, including the
   /// "world" RigidBody, which is always part of the model.
   /// @see AddRigidBody().
-  int num_bodies() const { return internal_tree().num_bodies(); }
+  int num_bodies() const { return internal_tree().num_links(); }
 
   /// Returns `true` if plant has a rigid body with unique index `body_index`.
   bool has_body(BodyIndex body_index) const {