Add per-DoF mimic actuator mode (#2222)

Author: jslee02

.github/workflows/ci_gz_physics.yml

@@ -78,5 +78,7 @@ jobs:
           mkdir -p "${RUNNER_TEMP}/ccache"
 
       - name: Test gz-physics
+        env:
+          DART_PARALLEL_JOBS: 8
         run: |
           pixi r -e gazebo test-gz

.github/workflows/ci_macos.yml

@@ -52,7 +52,8 @@ jobs:
       - name: Setup pixi
         uses: prefix-dev/setup-pixi@v0.9.3
         with:
-          cache: true
+          # Avoid cache key generation failures on macOS self-hosted runners
+          cache: false
 
       - name: Add pixi to PATH (prepend to override system pixi)
         run: echo "${HOME}/.pixi/bin" >> $GITHUB_PATH
@@ -102,7 +103,8 @@ jobs:
       - name: Setup pixi
         uses: prefix-dev/setup-pixi@v0.9.3
         with:
-          cache: true
+          # Avoid cache key generation failures on macOS self-hosted runners
+          cache: false
 
       - name: Add pixi to PATH (prepend to override system pixi)
         run: echo "${HOME}/.pixi/bin" >> $GITHUB_PATH

.github/workflows/ci_ubuntu.yml

@@ -51,7 +51,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v5
 
-      - name: Remove preinstalled pixi (if any)
+      - name: Remove stale pixi binary
         run: rm -f "$HOME/.pixi/bin/pixi"
 
       - name: Setup pixi

CHANGELOG.md

@@ -38,6 +38,7 @@
   - Removed all APIs deprecated in DART 6.0 (legacy BodyNode collision flags, Skeleton self-collision aliases, Joint `getLocal*`/`updateLocal*` accessors, `World::checkCollision(bool)`, `ConstraintSolver::setCollisionDetector(raw*)`, Marker `getBodyNode()`, `SdfParser::readSdfFile`, and deprecated XML helpers).
   - Removed all APIs deprecated in DART 6.7 (legacy math random helpers, `Skeleton::clone()` overloads, and `ConstraintSolver::set/getLCPSolver()`).
   - Removed all APIs deprecated in DART 6.2 (legacy Entity/BodyNode/JacobianNode/Joints/Skeleton notifiers, `Shape::notify*Update`, `EllipsoidShape::getSize`/`setSize`, `MultiSphereShape` alias, and `Eigen::make_aligned_shared` alias).
+  - Allow configuring mimic actuator mode per DoF so multi-axis joints can mimic a single axis without forcing the rest of the joint into mimic mode; added `Joint::setActuatorType(std::size_t, ...)`, `Joint::getActuatorType(std::size_t)`, `Joint::getActuatorTypes()`, and `Joint::hasActuatorType(...)` plus the corresponding dartpy bindings and regression tests. ([#1684](https://github.com/dartsim/dart/issues/1684))
   - Deprecated `ResourceRetriever::getFilePath()` and the overriding implementations across retrievers. The method now emits compiler deprecation warnings and will be removed in DART 8.0; use the new resource-materialization helpers (e.g., the SDF/OSG utilities) instead.
   - Removed the final compatibility headers that only re-included their replacements (`dart/collision/Option.hpp`, `dart/collision/Result.hpp`, and `dart/dynamics/MultiSphereShape.hpp`) and scrubbed the remaining deprecated documentation strings.
   - Removed `CollisionFilter::needCollision()` (deprecated in DART 6.3).

dart/constraint/ConstraintSolver.cpp

@@ -516,19 +516,47 @@ void ConstraintSolver::updateConstraints()
       }
 
       if (joint->areLimitsEnforced()
-          || joint->getActuatorType() == dynamics::Joint::SERVO) {
+          || joint->hasActuatorType(dynamics::Joint::SERVO)) {
         mJointConstraints.push_back(std::make_shared<JointConstraint>(joint));
       }
 
-      if (joint->getActuatorType() == dynamics::Joint::MIMIC
-          && joint->getMimicJoint()) {
-        if (joint->isUsingCouplerConstraint()) {
-          mCouplerConstraints.push_back(std::make_shared<CouplerConstraint>(
-              joint, joint->getMimicDofProperties()));
-        } else {
-          mMimicMotorConstraints.push_back(
-              std::make_shared<MimicMotorConstraint>(
-                  joint, joint->getMimicDofProperties()));
+      if (joint->hasActuatorType(dynamics::Joint::MIMIC)) {
+        auto mimicProps = joint->getMimicDofProperties();
+        mimicProps.resize(joint->getNumDofs());
+        const auto dofCount = joint->getNumDofs();
+        bool hasValidMimicDof = false;
+        bool useCouplerConstraint = false;
+        bool allMimicWithReference = true;
+        for (std::size_t dofIndex = 0; dofIndex < dofCount; ++dofIndex) {
+          if (joint->getActuatorType(dofIndex) == dynamics::Joint::MIMIC) {
+            if (mimicProps[dofIndex].mReferenceJoint != nullptr) {
+              hasValidMimicDof = true;
+              if (mimicProps[dofIndex].mConstraintType
+                  == dynamics::MimicConstraintType::Coupler) {
+                useCouplerConstraint = true;
+              }
+            } else {
+              allMimicWithReference = false;
+              DART_WARN(
+                  "Joint '{}' DoF {} is set to MIMIC without a reference; "
+                  "mimic constraint will be skipped.",
+                  joint->getName(),
+                  dofIndex);
+            }
+          } else {
+            allMimicWithReference = false;
+          }
+        }
+
+        if (hasValidMimicDof) {
+          if (useCouplerConstraint && allMimicWithReference) {
+            mCouplerConstraints.push_back(std::make_shared<CouplerConstraint>(
+                joint, joint->getMimicDofProperties()));
+          } else {
+            mMimicMotorConstraints.push_back(
+                std::make_shared<MimicMotorConstraint>(
+                    joint, joint->getMimicDofProperties()));
+          }
         }
       }
     }

dart/constraint/CouplerConstraint.cpp

@@ -38,6 +38,8 @@
 #include "dart/dynamics/Joint.hpp"
 #include "dart/dynamics/Skeleton.hpp"
 
+#include <algorithm>
+
 #include <cmath>
 
 namespace {
@@ -122,6 +124,12 @@ void CouplerConstraint::update()
   for (std::size_t i = 0; i < dof; ++i) {
     const auto& mimicProp = mMimicProps[i];
 
+    if (mJoint->getActuatorType(i) != dynamics::Joint::MIMIC
+        || mimicProp.mReferenceJoint == nullptr) {
+      mActive[i] = false;
+      continue;
+    }
+
     double timeStep = mJoint->getSkeleton()->getTimeStep();
     double velLower = mJoint->getVelocityLowerLimit(i);
     double velUpper = mJoint->getVelocityUpperLimit(i);
@@ -339,8 +347,14 @@ void CouplerConstraint::uniteSkeletons()
 
   auto dependentRoot = ConstraintBase::compressPath(dependentSkeleton);
 
-  for (const auto& mimicProp : mMimicProps) {
-    if (mimicProp.mReferenceJoint == nullptr)
+  for (std::size_t i = 0; i < mJoint->getNumDofs(); ++i) {
+    if (i >= mMimicProps.size())
+      break;
+
+    const auto& mimicProp = mMimicProps[i];
+
+    if (mJoint->getActuatorType(i) != dynamics::Joint::MIMIC
+        || mimicProp.mReferenceJoint == nullptr)
       continue;
 
     auto referenceBody = mimicProp.mReferenceJoint->getChildBodyNode();
@@ -380,8 +394,13 @@ void CouplerConstraint::uniteSkeletons()
 //==============================================================================
 bool CouplerConstraint::isActive() const
 {
-  if (mJoint->getActuatorType() == dynamics::Joint::MIMIC)
-    return true;
+  const auto dof = std::min(mJoint->getNumDofs(), mMimicProps.size());
+  for (std::size_t i = 0; i < dof; ++i) {
+    if (mJoint->getActuatorType(i) == dynamics::Joint::MIMIC
+        && mMimicProps[i].mReferenceJoint != nullptr) {
+      return true;
+    }
+  }
 
   return false;
 }

dart/constraint/JointConstraint.cpp

@@ -298,7 +298,8 @@ void JointConstraint::update()
         continue;
       }
 
-      const bool isServo = mJoint->getActuatorType() == dynamics::Joint::SERVO;
+      const bool isServo = mJoint->getActuatorType(static_cast<std::size_t>(i))
+                           == dynamics::Joint::SERVO;
       const double servoCommand
           = isServo ? mJoint->getCommand(static_cast<std::size_t>(i)) : 0.0;
       const bool atLowerLimit
@@ -367,7 +368,8 @@ void JointConstraint::update()
     }
 
     // Servo motor constraint check
-    if (mJoint->getActuatorType() == dynamics::Joint::SERVO) {
+    if (mJoint->getActuatorType(static_cast<std::size_t>(i))
+        == dynamics::Joint::SERVO) {
       // The desired velocity shouldn't be out of the velocity limits
       double desired_velocity = math::clip(
           mJoint->getCommand(static_cast<std::size_t>(i)),

dart/constraint/MimicMotorConstraint.cpp

@@ -162,6 +162,12 @@ void MimicMotorConstraint::update()
   for (std::size_t i = 0; i < dof; ++i) {
     const auto& mimicProp = mMimicProps[i];
 
+    if (mJoint->getActuatorType(i) != dynamics::Joint::MIMIC
+        || mimicProp.mReferenceJoint == nullptr) {
+      mActive[i] = false;
+      continue;
+    }
+
     double timeStep = mJoint->getSkeleton()->getTimeStep();
     double velLower = mJoint->getVelocityLowerLimit(i);
     double velUpper = mJoint->getVelocityUpperLimit(i);
@@ -327,11 +333,14 @@ dynamics::SkeletonPtr MimicMotorConstraint::getRootSkeleton() const
 //==============================================================================
 bool MimicMotorConstraint::isActive() const
 {
-  // Since we are not allowed to set the joint actuator type per each
-  // DegreeOfFreedom, we just check if the whole joint is SERVO actuator.
-  if (mJoint->getActuatorType() == dynamics::Joint::MIMIC)
-    return true;
-
+  const std::size_t dof = mJoint->getNumDofs();
+  for (std::size_t i = 0; i < dof; ++i) {
+    if (mJoint->getActuatorType(i) == dynamics::Joint::MIMIC
+        && i < mMimicProps.size()
+        && mMimicProps[i].mReferenceJoint != nullptr) {
+      return true;
+    }
+  }
   return false;
 }