fix(dynamics): paycap returns the capacity, a scalar, as the MATLAB method does

[petercorke]

Summary

paycap and pay came from the MATLAB Robotics Toolbox, where Bryan Moutrie contributed them (pHRIWARE). Following #731 I read the original to see what the function was meant to return.

MATLAB's paycap ends with [wM, j] = min(WM, [], 2): the largest multiple of the unit payload wrench that no joint torque limit forbids, and the joint that limits it. The Python port kept the argmin but dropped the min, so it returned one value per joint, labelled "maximum permissible payload wrench (6)". That is why it only worked for six joint robots (#728) and why its old test's expected values were six numbers, one of them 6e15.

(The MATLAB docstring also says WMAX (1x6), which the code does not do either; the docstring was wrong from the start.)

Changes

• paycap returns the scalar capacity and the limiting joint (vectors over poses for a trajectory)
• a joint that the wrench does not load, to within rounding error, is unbounded; before, a torque of ~1e-17 gave a capacity of ~1e17
• documented: the capacity is negative if gravity alone is beyond a limit; w is the wrench the payload applies to the end-effector
• pay() docstring said tau = J'W; the code (and MATLAB's) is -J'W, the holding torque, which adds to gravload. Docstring fixed, with a worked sign example
• Bryan Moutrie credited in both docstrings
• tests on a planar two link arm with hand-worked values, covering both signs of the wrench, the minimum limits, a negative capacity, an unloaded joint, base and end-effector frames and a trajectory; the commented-out test is removed

Compatibility

For a six joint robot, paycap used to return a (6,) array of per-joint values; it now returns a scalar. Nothing in this repository, its docs or RVC3 calls paycap, and it has had no working test since 2020. A versionchanged:: 1.4.5 note says so. This is a bug fix of the port, so it is committed as a fix.

Builds on the shape handling in #731, whose author is credited in the commit.

Test plan

• tests/test_paycap_capacity.py (18 tests) and tests/test_DHRobot.py
• hand values: tip at (2, 0), joint 1 limit (30 - 2g)/2, joint 2 limit (10 - g/2); second pose elbow up: 30 - 1.5g, in either frame

🤖 Generated with Claude Code

[codacy-production]

Not up to standards ⛔

🔴 Issues 5 high

Alerts:
⚠ 5 issues (≤ 0 issues of at least minor severity)

Results:
5 new issues

Category	Results
Security	5 high

View in Codacy

🟢 Metrics 10 complexity · 0 duplication

Metric	Results
Complexity	10
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[codecov]

Codecov Report

❌ Patch coverage is 0% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 0.00%. Comparing base (6a45f73) to head (7edf028).

Files with missing lines	Patch %	Lines
src/roboticstoolbox/robot/Dynamics.py	0.00%	6 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff          @@
##            main    #759   +/-   ##
=====================================
  Coverage   0.00%   0.00%           
=====================================
  Files        143     143           
  Lines      14367   14367           
=====================================
  Misses     14367   14367           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[petercorke]

Closing for now, this is on hold. The branch bug/paycap-return-min is kept as it is and the PR can be reopened.