Add coupler constraint support and example

[jslee02]

• add CouplerConstraint so mimic joints can optionally be enforced bilaterally and ensure the constraint solver instantiates it only when Joint::setUseCouplerConstraint(true) is set
• expose the flag through dartpy, add integration coverage, and ship a GUI example so downstream code (e.g., gz-sim mimic joints) can exercise the new constraint
• resolves Add Coupler Constraint (similar to a gearbox constaint from Gazebo) #1756 and supersedes the exploratory work in Added coupler constraint #1835 by documenting the intended gearbox use case and providing a pixi-friendly example

Testing

• pixi run test-all
• pixi run ex coupler_constraint

---

Before creating a pull request

• Run pixi run test-all to lint, build, and test your changes
• Add unit tests for new functionality
• Document new methods and classes
• Add Python bindings (dartpy) if applicable

[codecov]

Codecov Report

❌ Patch coverage is 79.03226% with 39 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.88%. Comparing base (4f0c56c) to head (56246e7).
⚠️ Report is 65 commits behind head on main.

Files with missing lines	Patch %	Lines
dart/constraint/CouplerConstraint.cpp	77.05%	39 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2115      +/-   ##
==========================================
+ Coverage   61.78%   61.88%   +0.09%     
==========================================
  Files         393      394       +1     
  Lines       33331    33515     +184     
  Branches     4126     4151      +25     
==========================================
+ Hits        20594    20740     +146     
- Misses      12737    12775      +38     

Flag	Coverage Δ
unittests	61.88% <79.03%> (+0.09%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
dart/constraint/ConstraintSolver.cpp	72.93% <100.00%> (+0.73%)	⬆️
dart/constraint/ConstraintSolver.hpp	100.00% <ø> (ø)
dart/dynamics/Joint.cpp	67.88% <100.00%> (+1.46%)	⬆️
dart/dynamics/Joint.hpp	100.00% <ø> (ø)
dart/dynamics/detail/JointAspect.hpp	100.00% <ø> (ø)
dart/constraint/CouplerConstraint.cpp	77.05% <77.05%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[azeey]

cc @scpeters

[scpeters]

thanks for making progress here @jslee02! I'll test it shortly; these are just some comments from reading through the changes and comparing the new constraint files to the Mimic constraint

[scpeters]

I started testing with gz-physics (see gazebosim/gz-physics#517 (comment)), but don't have it working yet

[jslee02]

@scpeters Thanks for reviewing and testing this! This PR isn’t ready yet. I’ll mark it as “Ready for review” once it is. Sorry for the confusion!

[jslee02]

@scpeters, quick update now that everything’s in place. thanks again for the detailed review and testing!

I’ve pushed changes that address each of your comments: both skeletons now have their constraint impulses cleared before unit impulses, the const_cast usage is centralized via local pointers, every assert is upgraded to DART_ASSERT, and there’s a new COUPLER_CONSTRAINT_APPLY_IMPULSE test so the bilateral bookkeeping stays covered.

I also refreshed the GUI example (pixi run ex coupler_constraint) so it compares the CouplerConstraint on the left rig against the MimicMotorConstraint on the right rig both primaries track the same command while their followers share the same plus or minus twenty degree limit and when the follower saturates you can see only the Coupler rig’s primary joint get pulled back exactly like the gearbox behavior.

Screencast.from.2025-11-18.06-16-25.mp4

[jslee02]

This seems to work functionally, but adding a constraint-type-specific flag directly onto JointAspect feels clunky. Let me spend some time refactoring so we have a more scalable way to plug in future joint constraints without touching the shared aspect.

[jslee02]

Let's continue in #2212