Add Newton inverse kinematics action

[maxkra15]

Description

Add Newton-backed inverse kinematics support to Isaac Lab.

This PR introduces a NewtonIKManager wrapper around Newton's objective-list IK solver API. The manager builds Newton pose objectives, optional joint-limit regularization, sampler settings, and custom objective passthrough into a batched Isaac Lab interface. Targets are updated from Torch tensors and converted to Warp arrays before calling Newton's IKSolver.

The PR also adds a manager-based NewtonInverseKinematicsAction that plugs this solver into Isaac Lab MDP action terms. Because Newton IK needs a single-articulation model while Isaac Lab runs replicated scenes, the Newton cloner now registers prototype builders during replication. NewtonManager.get_prototype_model() lazily finalizes the matching prototype on the active device, and the action resolves Isaac Lab joint/body names into Newton prototype joint-coordinate and link indices before solving.

Finally, this adds a Franka reach task variant using the new Newton IK action:

• Isaac-Reach-Franka-Newton-IK-Rel-v0
• Isaac-Reach-Franka-Newton-IK-Rel-Play-v0

The implementation includes tests for prototype-model lookup and cached prototype finalization behavior.

Fixes # (no issue filed)

Type of change

• New feature (non-breaking change which adds functionality)

Screenshots

Not applicable.

Test plan

• Added source/isaaclab_newton/test/physics/test_newton_prototype_models.py.
• Manually launched the Franka Newton IK task and verified environment setup:

  ./isaaclab.sh -p scripts/environments/random_agent.py \
    --task Isaac-Reach-Franka-Newton-IK-Rel-Play-v0 \
    --num_envs 1 \
    --visualizer newton

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot - PR #5756

Summary

This PR adds Newton-backed inverse kinematics support to Isaac Lab, including a NewtonIKManager, NewtonInverseKinematicsAction, and Franka reach task variants. Overall, this is a well-structured feature with clean separation of concerns.

---

🏗️ Architecture & API Design

Strengths:

• ✅ Clean separation between NewtonIKManager (solver wrapper) and NewtonInverseKinematicsAction (MDP action term)
• ✅ Follows established Isaac Lab patterns for action terms (process_actions/apply_actions lifecycle)
• ✅ Good use of configclass for configuration with sensible defaults
• ✅ Prototype model registration integrates well with the existing cloner infrastructure
• ✅ Named pose objectives design allows flexible multi-target IK scenarios

Suggestions:

1. Document fixed-base limitation prominently - The fixed-base check is in the action init, but users should see this constraint in the class/config docstrings before they hit the runtime error
2. Consider adding get_cost() method - Currently costs returns raw Warp array; a convenience method returning per-env convergence status would aid debugging

---

🔍 Potential Silent Failure Modes

1. No convergence validation (newton_ik_manager.py:161-167)

   • solve() returns joint positions without checking if the IK actually converged
   • Consider adding an optional warn_on_high_cost parameter or returning a (joint_pos, converged_mask) tuple

2. Unreachable target handling (newton_ik_actions.py:213-218)

   • When targets lie outside the robot's workspace, Newton may return the last iteration's result with high residual cost
   • Silent failures here could cause unexpected robot behavior in RL training

3. Device state caching (newton_manager.py:792-795)

   if info.model is None or info.model_device != device:
       info.model = info.builder.finalize(device=device)

   • If the Newton model device changes mid-session, older cached prototype models could become stale
   • Consider invalidating all cached models when NewtonManager._model.device changes

4. Jacobian singularities - No explicit handling or damping adjustments when the manipulator approaches singular configurations. The lambda_initial parameter helps, but consider documenting expected behavior near singularities.

---

🧪 Test Coverage Assessment

Current tests (test_newton_prototype_models.py):

• ✅ Prototype model lookup with env regex paths
• ✅ Cached model reuse on same device

Missing test coverage:

• ❌ NewtonIKManager.solve() with various target poses and seeds
• ❌ NewtonInverseKinematicsAction integration with mock environment
• ❌ Edge cases: unreachable targets, near-singularity configurations
• ❌ Error conditions: invalid joint names, shape mismatches
• ❌ Multi-objective IK scenarios (multiple pose objectives)
• ❌ Device migration scenarios

Recommendation: Add at least basic unit tests for NewtonIKManager.set_target_pose() and solve() to ensure the Torch↔Warp conversion is correct.

---

📝 Minor Issues

1. CI Status: The "Check for Broken Links" check is failing - may need to add API docs links for the new classes

2. Docstring completeness (newton_ik_manager.py):

   • NewtonIKPoseObjective fields could use docstrings explaining units (radians vs degrees, etc.)

3. Magic numbers (newton_ik_manager_cfg.py):

   • Default iterations=24 and lambda_initial=0.1 work well for typical cases but the rationale for these defaults would be helpful in comments

4. Unused import (newton_ik_actions.py:12):

   • Sequence is imported from collections.abc but the reset method uses slice(None) pattern instead

---

✅ What Looks Good

• Changelog fragments present for both isaaclab_newton and isaaclab_tasks
• Type hints throughout
• Proper lazy export pattern for new subpackages
• The Franka task variant configuration is minimal and delegates properly to base configs
• Good logging in the action init for debugging joint/body resolution

---

This review was generated by the Isaac Lab Review Bot using ensemble analysis.

---

📝 Update (2ce0a4b)

New changes reviewed: This commit addresses several suggestions from the original review and adds significant new functionality.

✅ Improvements Made

1. Persistent IK seeds - New use_persistent_seed config option and set_joint_seed() / step() methods allow the solver to warm-start from previous solutions. This should improve convergence in continuous control scenarios.

2. Body transform helpers - set_target_pose_from_body_q() and set_pose_targets_from_body_q() make it easy to initialize pose objectives from live Newton body transforms, with proper handling of env_origins.

3. Test coverage added - New test_newton_ik_manager.py with tests for:

   • Persistent seed reuse between solves ✅
   • Pose target initialization from body transforms ✅
   • This addresses the "missing test coverage" concern from the original review 🎉

4. Improved reset() API - Now accepts optional env_ids and joint_pos parameters for selective reset with seed initialization.

🔍 New Code Review Notes

1. Type hints - Good use of Sequence[int] | torch.Tensor | slice | None for flexible env_ids handling

2. Helper functions - _as_torch() and _env_ids_to_tensor() are clean utility functions. Consider whether these should be module-private or potentially reusable elsewhere.

3. Changelog updated - Properly documents the new persistent seed and body transform helpers

📋 Remaining Suggestions (from original review)

• Convergence validation still not addressed (returning cost threshold / converged mask)
• Docstring for default hyperparameters rationale

Overall: Solid iteration that improves usability and addresses test coverage gaps. The persistent seed feature is particularly useful for RL training loops. 👍