Unambiguously identify ephemeral elements.

Author: sherm1

bindings/pydrake/multibody/test/plant_test.py

@@ -580,6 +580,7 @@ def _test_multibody_tree_element_mixin(self, T, element):
         cls = type(element)
         self.assertIsInstance(element.index(), get_index_class(cls, T))
         self.assertIsInstance(element.model_instance(), ModelInstanceIndex)
+        self.assertFalse(element.is_ephemeral())
         element.GetParentPlant()
 
     def _test_frame_api(self, T, frame):

bindings/pydrake/multibody/tree_py.cc

@@ -76,6 +76,7 @@ void BindMultibodyElementMixin(PyClass* pcls) {
   cls  // BR
       .def("index", &Class::index)
       .def("model_instance", &Class::model_instance)
+      .def("is_ephemeral", &Class::is_ephemeral)
       .def("GetParentPlant",
           [](const Class& self) -> const multibody::MultibodyPlant<T>& {
             return self.GetParentPlant();

multibody/plant/test/multibody_plant_test.cc

@@ -4030,8 +4030,11 @@ GTEST_TEST(StateSelection, FreeBodiesVsFloatingBaseBodies) {
     const ModelInstanceIndex table_model =
         parser.AddModelsFromUrl(table_sdf_url).at(0);
     const RigidBody<double>& table = plant.GetBodyByName("link", table_model);
-    plant.AddJoint(std::make_unique<PrismaticJoint<double>>(
-        "table", plant.world_frame(), table.body_frame(), Vector3d(1, 1, 1)));
+    const auto& prismatic_joint =
+        plant.AddJoint(std::make_unique<PrismaticJoint<double>>(
+            "table", plant.world_frame(), table.body_frame(),
+            Vector3d(1, 1, 1)));
+    EXPECT_FALSE(prismatic_joint.is_ephemeral());
 
     // Add a mug with no joint. This will become a floating base body at
     // finalization unless we add a joint.
@@ -4040,7 +4043,10 @@ GTEST_TEST(StateSelection, FreeBodiesVsFloatingBaseBodies) {
     if (!mug_in_world) {
       // Explicitly put a 6-dof joint between mug and table, making this a
       // "free" body, but _not_ a floating base body.
-      plant.AddJoint<QuaternionFloatingJoint>("sixdof", table, {}, mug, {});
+      const auto& joint =
+          plant.AddJoint<QuaternionFloatingJoint>("sixdof", table, {}, mug, {});
+      // An explicitly added joint is not ephemeral.
+      EXPECT_FALSE(joint.is_ephemeral());
     }
 
     plant.Finalize();
@@ -4280,6 +4286,7 @@ GTEST_TEST(StateSelection, FloatingBodies) {
 // Verify that we can control what kind of joint is used to connect an
 // unconnected body to World, globally or per-model instance. The default
 // should be QuaternionFloatingJoint, with RpyFloating and Weld as options.
+// These should all be marked "ephemeral" since they aren't user-added.
 //
 // We'll also verify that we can set state (q & v), pose, and velocity using the
 // generic Joint API applied to the floating joints. We'll also check that we
@@ -4321,9 +4328,10 @@ GTEST_TEST(MultibodyPlantTest, BaseBodyJointChoice) {
     EXPECT_EQ(plant->num_positions(), 14);
     EXPECT_EQ(plant->num_velocities(), 12);
 
-    // When base joints are added they are named after the base body.
+    // When ephemeral base joints are added they are named after the base body.
     const Joint<double>& quaternion_joint =
         plant->GetJointByName("InstanceBody");
+    EXPECT_TRUE(quaternion_joint.is_ephemeral());
     auto context = plant->CreateDefaultContext();
     Eigen::Vector<double, 7> set_q;
     set_q << 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7;
@@ -4380,6 +4388,7 @@ GTEST_TEST(MultibodyPlantTest, BaseBodyJointChoice) {
 
     // When base joints are added they are named after the base body.
     const Joint<double>& instance_joint = plant->GetJointByName("InstanceBody");
+    EXPECT_TRUE(instance_joint.is_ephemeral());
     auto context = plant->CreateDefaultContext();
     Vector6d set_q;
     set_q << 0.1, 0.2, 0.3, 0.4, 0.5, 0.6;
@@ -4445,6 +4454,7 @@ GTEST_TEST(MultibodyPlantTest, BaseBodyJointChoice) {
     // We'll use the weld joint to generate some Joint API errors.
     const Joint<double>& weld_joint = plant->GetJointByName("DefaultBody");
     EXPECT_EQ(weld_joint.type_name(), "weld");
+    EXPECT_TRUE(weld_joint.is_ephemeral());
     auto context = plant->CreateDefaultContext();
 
     // SetPositions() and SetVelocities() should work for every joint as

multibody/tree/body_node.h

@@ -100,6 +100,7 @@ class BodyNode : public MultibodyElement<T> {
         body_(body),
         mobilizer_(mobilizer) {
     DRAKE_DEMAND(!(parent_node == nullptr && body->index() != world_index()));
+    this->set_is_ephemeral(true);  // BodyNodes are never added by users.
   }
 
   ~BodyNode() override;

multibody/tree/fixed_offset_frame.cc

@@ -53,8 +53,10 @@ std::unique_ptr<Frame<ToScalar>> FixedOffsetFrame<T>::TemplatedDoCloneToScalar(
     const internal::MultibodyTree<ToScalar>& tree_clone) const {
   const Frame<ToScalar>& parent_frame_clone =
       tree_clone.get_variant(parent_frame_);
-  return std::make_unique<FixedOffsetFrame<ToScalar>>(
+  auto new_frame = std::make_unique<FixedOffsetFrame<ToScalar>>(
       this->name(), parent_frame_clone, X_PF_, this->model_instance());
+  new_frame->set_is_ephemeral(this->is_ephemeral());
+  return new_frame;
 }
 
 template <typename T>
@@ -78,8 +80,10 @@ FixedOffsetFrame<T>::DoCloneToScalar(
 
 template <typename T>
 std::unique_ptr<Frame<T>> FixedOffsetFrame<T>::DoShallowClone() const {
-  return std::make_unique<FixedOffsetFrame<T>>(this->name(), parent_frame_,
-                                               X_PF_, this->model_instance());
+  auto new_frame = std::make_unique<FixedOffsetFrame<T>>(
+      this->name(), parent_frame_, X_PF_, this->model_instance());
+  new_frame->set_is_ephemeral(this->is_ephemeral());
+  return new_frame;
 }
 
 template <typename T>

multibody/tree/fixed_offset_frame.h

@@ -7,7 +7,6 @@
 #include "drake/common/default_scalars.h"
 #include "drake/common/eigen_types.h"
 #include "drake/multibody/tree/frame.h"
-#include "drake/multibody/tree/multibody_tree_topology.h"
 
 namespace drake {
 namespace multibody {

multibody/tree/mobilizer.h

@@ -264,6 +264,7 @@ class Mobilizer : public MultibodyElement<T> {
       throw std::runtime_error(
           "The provided inboard and outboard frames reference the same object");
     }
+    this->set_is_ephemeral(true);  // Mobilizers are never added by users.
   }
 
   ~Mobilizer() override;

multibody/tree/multibody_element.h

@@ -26,6 +26,14 @@ class MultibodyPlant;
 /// BodyIndex index() const { return this->template index_impl<BodyIndex>(); }
 /// @endcode
 ///
+/// Some multibody elements are added during Finalize() and are not part of
+/// the user-specified model. These are called "ephemeral" elements and can
+/// be identified using the `is_ephemeral()` function here. Examples include
+///   - free joints added to connect lone bodies or free-floating trees
+///     to World
+///   - fixed offset frames added when joints are modeled by mobilizers
+///   - all mobilizers.
+///
 /// @tparam_default_scalar
 template <typename T>
 class MultibodyElement {
@@ -64,6 +72,15 @@ class MultibodyElement {
   /// @pre parameters != nullptr
   void SetDefaultParameters(systems::Parameters<T>* parameters) const;
 
+  /// Returns `true` if this %MultibodyElement was added during Finalize()
+  /// rather than something a user added. (See class comments.)
+  bool is_ephemeral() const { return is_ephemeral_; }
+
+  /// (Internal use only) Sets the `is_ephemeral` flag to the indicated value.
+  /// The default if this is never called is `false`. Any element that is added
+  /// during Finalize() should set this flag to `true`.
+  void set_is_ephemeral(bool is_ephemeral) { is_ephemeral_ = is_ephemeral; }
+
  protected:
   /// Default constructor made protected so that sub-classes can still declare
   /// their default constructors if they need to.
@@ -186,6 +203,8 @@ class MultibodyElement {
   // The default model instance id is *invalid*. This must be set to a
   // valid index value before the element is released to the wild.
   ModelInstanceIndex model_instance_;
+
+  bool is_ephemeral_{false};
 };
 
 }  // namespace multibody

multibody/tree/multibody_tree-inl.h

@@ -72,6 +72,14 @@ const FrameType<T>& MultibodyTree<T>::AddFrame(
   return *result;
 }
 
+template <typename T>
+template <template <typename Scalar> class FrameType>
+const FrameType<T>& MultibodyTree<T>::AddEphemeralFrame(
+    std::unique_ptr<FrameType<T>> frame) {
+  frame->set_is_ephemeral(true);
+  return AddFrame(std::move(frame));
+}
+
 template <typename T>
 template <template <typename Scalar> class FrameType, typename... Args>
 const FrameType<T>& MultibodyTree<T>::AddFrame(Args&&... args) {
@@ -80,6 +88,15 @@ const FrameType<T>& MultibodyTree<T>::AddFrame(Args&&... args) {
   return AddFrame(std::make_unique<FrameType<T>>(std::forward<Args>(args)...));
 }
 
+template <typename T>
+template <template <typename Scalar> class FrameType, typename... Args>
+const FrameType<T>& MultibodyTree<T>::AddEphemeralFrame(Args&&... args) {
+  static_assert(std::is_convertible_v<FrameType<T>*, Frame<T>*>,
+                "FrameType must be a sub-class of Frame<T>.");
+  return AddEphemeralFrame(
+      std::make_unique<FrameType<T>>(std::forward<Args>(args)...));
+}
+
 template <typename T>
 template <template <typename Scalar> class MobilizerType>
 const MobilizerType<T>& MultibodyTree<T>::AddMobilizer(
@@ -228,6 +245,7 @@ const JointType<T>& MultibodyTree<T>::AddJoint(
   // during modeling are already in the graph.
   if (!is_ephemeral_joint) RegisterJointAndMaybeJointTypeInGraph(*joint.get());
 
+  joint->set_is_ephemeral(is_ephemeral_joint);
   joint->set_parent_tree(this, joints_.next_index());
   joint->set_ordinal(joints_.num_elements());
   JointType<T>* raw_joint_ptr = joint.get();

multibody/tree/multibody_tree.cc

@@ -927,7 +927,10 @@ void MultibodyTree<T>::Finalize() {
   elements" to provide a uniform interface to the additional elements that were
   required to build the model. Below, we will augment the MultibodyPlant
   elements to match, so that advanced users can use the familiar Plant API to
-  access and control these ephemeral elements. */
+  access and control these ephemeral elements. The process of modeling Joints
+  with available Mobilizers may introduce ephemeral Frames as well. All
+  ephemeral elements must be marked as such in the base MultibodyElement class;
+  public API element.is_ephemeral() is available to check. */
   link_joint_graph_.BuildForest();
   const LinkJointGraph& graph = link_joint_graph_;
 

multibody/tree/multibody_tree.h

@@ -205,6 +205,10 @@ class MultibodyTree {
   template <template <typename Scalar> class FrameType>
   const FrameType<T>& AddFrame(std::unique_ptr<FrameType<T>> frame);
 
+  // Same as above but sets the `is_ephemeral` bit.
+  template <template <typename Scalar> class FrameType>
+  const FrameType<T>& AddEphemeralFrame(std::unique_ptr<FrameType<T>> frame);
+
   // Constructs a new frame with type `FrameType` with the given `args`, and
   // adds it to `this` %MultibodyTree, which retains ownership. The `FrameType`
   // will be specialized on the scalar type T of this %MultibodyTree.
@@ -243,6 +247,10 @@ class MultibodyTree {
   template <template <typename Scalar> class FrameType, typename... Args>
   const FrameType<T>& AddFrame(Args&&... args);
 
+  // Same as above but sets the `is_ephemeral` bit.
+  template <template <typename Scalar> class FrameType, typename... Args>
+  const FrameType<T>& AddEphemeralFrame(Args&&... args);
+
   // Takes ownership of `mobilizer` and adds it to `this` %MultibodyTree.
   // Returns a constant reference to the mobilizer just added, which will
   // remain valid for the lifetime of `this` %MultibodyTree.
@@ -977,14 +985,18 @@ class MultibodyTree {
     return forest().mobods(index);
   }
 
-  // This method must be called after all elements in the plant (joints, bodies,
-  // force elements, constraints) were added and before any computations are
-  // performed. It compiles all the necessary "topological information", i.e.
-  // how bodies, mobilizers, and any other elements connect with each other, and
-  // performs all the required pre-processing to permit efficient computations
-  // at a later stage.
+  // Finalize() must be called after all user-defined elements in the plant
+  // (joints, bodies, force elements, constraints, etc.) have been added and
+  // before any computations are performed. It compiles all the necessary
+  // topological information, i.e. how bodies, mobilizers, and any other
+  // elements connect with each other, and performs all the required
+  // pre-processing to permit efficient computations at a later stage. During
+  // this process, we may add additional elements (e.g. joints, frames,
+  // and constraints) to facilitate computation; we call those "ephemeral"
+  // elements and mark them as such in the base MultibodyElement class to
+  // distinguish them from user-defined elements.
   //
-  // If the finalize stage is successful, the topology of this MultibodyTree
+  // If the Finalize operation is successful, the topology of this MultibodyTree
   // is validated, meaning that the topology is up-to-date after this call.
   // No more multibody plant elements can be added after a call to Finalize().
   //

multibody/tree/test/frames_test.cc

@@ -70,16 +70,19 @@ class FrameTests : public ::testing::Test {
     // Frame Q is rigidly attached to P with pose X_PQ.
     frameQ_ = &model->AddFrame<FixedOffsetFrame>("Q", *frameP_, X_PQ_);
 
-    // Frame R is arbitrary, but named.
+    // Frame R is arbitrary, but named and not ephemeral.
     frameR_ = &model->AddFrame<FixedOffsetFrame>(
         "R", *frameP_, math::RigidTransformd::Identity());
+    EXPECT_FALSE(frameR_->is_ephemeral());
 
-    // Frame S is arbitrary, but named and with a specific model instance.
+    // Frame S is arbitrary, but named, with a specific model instance, and
+    // ephemeral.
     X_WS_ = X_BP_;  // Any non-identity pose will do.
     extra_instance_ = model->AddModelInstance("extra_instance");
-    frameS_ = &model->AddFrame<FixedOffsetFrame>("S", model->world_frame(),
-                                                 X_WS_, extra_instance_);
+    frameS_ = &model->AddEphemeralFrame<FixedOffsetFrame>(
+        "S", model->world_frame(), X_WS_, extra_instance_);
     EXPECT_EQ(frameS_->scoped_name().get_full(), "extra_instance::S");
+    EXPECT_TRUE(frameS_->is_ephemeral());
 
     // Ensure that the model instance propagates implicitly.
     frameSChild_ = &model->AddFrame<FixedOffsetFrame>(
@@ -351,13 +354,15 @@ TEST_F(FrameTests, ShallowCloneTests) {
   EXPECT_NE(dynamic_cast<const RigidBodyFrame<double>*>(frameB_), nullptr);
   EXPECT_EQ(clone_of_frameB->name(), frameB_->name());
   EXPECT_EQ(clone_of_frameB->model_instance(), frameB_->model_instance());
+  EXPECT_FALSE(clone_of_frameB->is_ephemeral());
 
   // Make sure ShallowClone() preserves FixedOffsetFrame frameS's properties.
   const std::unique_ptr<Frame<double>> clone_of_frameS =
       frameS_->ShallowClone();
   EXPECT_NE(clone_of_frameS.get(), frameS_);
   EXPECT_EQ(clone_of_frameS->name(), frameS_->name());
   EXPECT_EQ(clone_of_frameS->model_instance(), frameS_->model_instance());
+  EXPECT_TRUE(clone_of_frameS->is_ephemeral());
   const auto& downcast_clone =
       dynamic_cast<const FixedOffsetFrame<double>&>(*clone_of_frameS);
   EXPECT_TRUE(downcast_clone.GetFixedPoseInBodyFrame().IsExactlyEqualTo(X_WS_));
@@ -373,12 +378,14 @@ TEST_F(FrameTests, DeepCloneTests) {
             nullptr);
   EXPECT_EQ(clone_of_frameB.name(), frameB_->name());
   EXPECT_EQ(clone_of_frameB.model_instance(), frameB_->model_instance());
+  EXPECT_FALSE(clone_of_frameB.is_ephemeral());
 
   // Make sure CloneToScalar() preserves FixedOffsetFrame frameS's properties.
   const Frame<AutoDiffXd>& clone_of_frameS =
       cloned_tree->get_frame(frameS_->index());
   EXPECT_EQ(clone_of_frameS.name(), frameS_->name());
   EXPECT_EQ(clone_of_frameS.model_instance(), frameS_->model_instance());
+  EXPECT_TRUE(clone_of_frameS.is_ephemeral());
   const auto& downcast_clone =
       dynamic_cast<const FixedOffsetFrame<AutoDiffXd>&>(clone_of_frameS);
   EXPECT_TRUE(downcast_clone.GetFixedPoseInBodyFrame().IsExactlyEqualTo(

multibody/tree/test/revolute_mobilizer_test.cc

@@ -34,6 +34,8 @@ class RevoluteMobilizerTest : public MobilizerTester {
         std::make_unique<RevoluteJoint<double>>(
             "joint0", tree().world_body().body_frame(), body_->body_frame(),
             axis_F_));
+    // Mobilizers are always ephemeral (i.e. not added by user).
+    EXPECT_TRUE(mobilizer_->is_ephemeral());
     mutable_mobilizer_ = const_cast<RevoluteMobilizer<double>*>(mobilizer_);
   }