Refactor articulation actuator ownership

[AntoineRichard]

Description

This PR gives actuator behavior one backend-neutral runtime owner: ActuatorCollection. It is rebased onto develop after the articulation-ordering work in #6784 merged.

Previously, each backend articulation simultaneously owned simulated state, actuator groups, raw targets, processed targets, telemetry, gain resolution, actuator-model execution, joint-order conversion, and backend submission. That duplicated one control pipeline across PhysX, Newton, and OVPhysX and made the Newton-native actuator path difficult to integrate cleanly.

The refactor separates those responsibilities:

• ActuatorCollection owns actuator groups, input commands, processed joint commands, telemetry, resolved gains, and model lifecycle.
• ActuatorControl defines the narrow backend contract.
• PhysxActuatorControl, NewtonActuatorControl, and OvPhysxActuatorControl handle only backend ordering, staging, native-actuator integration, property writes, and command submission.
• Articulation remains responsible for simulated joint/body state, topology, and lifecycle orchestration.

Public API and terminology

The new API distinguishes the two sides of the actuator model:

# Input received by the actuator model.
robot.actuators.command.position
robot.actuators.command.velocity
robot.actuators.command.effort
robot.actuators.command.set_position_index(value=position_command)

# Processed command produced for the simulated joints.
robot.actuators.joint_command.position
robot.actuators.joint_command.velocity
robot.actuators.joint_command.effort

# Actuator telemetry and resolved properties.
robot.actuators.computed_torque
robot.actuators.applied_torque
robot.actuators.actuator_stiffness
robot.actuators.actuator_damping

All public arrays remain expressed on the simulated joint side and indexed in articulation public joint order. “Actuator command” names the receiving component; it does not imply motor-shaft indexing.

Existing articulation target/gain methods and ArticulationData command/torque properties remain available as deprecated forwarding aliases. This PR does not remove a previously released public API.

Backend behavior

• PhysX: supports the standard Isaac Lab actuator loop and optional Newton-native actuators through PhysxActuatorWrapper. Mixed implicit/explicit groups retain solver-drive commands where required.
• Newton: supports both the standard Lab compute loop and manager-owned native actuators, including ordering-aware global DOF binding, resets, gain updates, and post-actuator telemetry synchronization.
• OVPhysX: preserves eager target writes and partial-write semantics. Processed torque uses separate backend scratch so it cannot corrupt the persistent raw effort command used by later partial writes.
• Ordering: collection buffers stay in public order. Conversion occurs only at backend binding/submission boundaries, with identity-order fast paths and fused reorder kernels.

Neural actuator checkpoints

Newton MLP/LSTM actuator checkpoints are now resolved through Isaac Lab's shared retrieve_file_path() cache before PyTorch loads and re-saves them with Newton metadata. This enables remote HTTP/Nucleus-style checkpoint paths without adding a dependency, while retaining support for local TorchScript and dictionary checkpoints.

Documentation

• Rewrote the actuator concept page around the command pipeline, explicit/implicit ownership, clipping, delay, armature, friction, velocity limits, and the runtime collection API.
• Updated migration guides and tutorials to use actuators.command.
• Added light/dark pipeline and parameter-reference media.
• Moved the procedural actuator comparison utility to tools/actuator_parameters.py.

Dependencies

• Integrate articulation ordering caches and selectors #6784 — articulation ordering caches and selectors (merged; this branch is now rebased onto it).

Type of change

• Bug fix (remote Newton neural checkpoints and backend command-staging edge cases)
• New feature (backend-neutral actuator collection and Newton-native actuator paths)
• Documentation update

Screenshots

The actuator documentation includes generated pipeline diagrams, parameter curves, and comparison clips for stiffness, damping, armature, friction, effort limit, velocity limit, delay, and implicit-versus-explicit behavior.

Validation

Command and backend equivalence

• Focused collection tests cover mapping behavior, public command views, cached selectors, signed int64 index writes, mask writes, processed-command submission, resolved gains, and actuator metadata.
• Cross-backend interface tests exercise deprecated live aliases and backend adapters.
• ANYmal-C Lab-versus-Newton actuator suites compare joint position, joint velocity, computed torque, and applied torque across Ideal PD, DC motor, mixed explicit/implicit groups, feed-forward effort, delay, resets, multiple articulations, public reordering, and neural construction.
• Default numerical tolerances are 2e-3 position, 1e-2 velocity, and 1e-3 computed/applied torque (with the corresponding relative tolerances defined by the suites).

Training evidence

The long-form runs used PhysX physics, 4096 environments, RSL-RL, seed 42, and 500 learning iterations. “PhysX + Newton actuators” changes actuator execution, not the physics backend.

Run	Final reward	Best reward	Final episode length	Mean FPS
Go2, develop, regular PhysX actuators	35.432	35.645	1000.00	212,888
Go2, PR, PhysX + Newton actuators	35.676	35.961	1000.00	208,391
ANYmal-D flat, PhysX + Newton actuators	21.341	21.579	987.90	173,677
Spot flat, PhysX + Newton actuators	234.708	263.764	882.28	88,257
A1 flat (contrib), PhysX + Newton actuators	31.414	31.414	1000.00	219,286
Go1 flat (contrib), PhysX + Newton actuators	36.304	36.351	1000.00	205,034

The controlled Go2 pair reached comparable reward and episode length. Mean throughput was 2.1% lower in that single Newton-actuator run; this is “same ballpark” evidence, not a statistically rigorous performance claim. The other robot runs establish that their explicit actuator configurations complete meaningful training, not matched per-robot performance parity.

Post-rebase checks

• ./isaaclab.sh -p -m pytest source/isaaclab/test/actuators/test_actuator_collection.py source/isaaclab/test/assets/test_articulation_iface.py::TestArticulationDataAliases -k 'cpu or test_actuator_collection' — 32 passed, 24 deselected
• ./isaaclab.sh -d — Sphinx warning-as-error build succeeded
• ./isaaclab.sh -f — all repository-wide hooks passed
• ./isaaclab.sh -p tools/actuator_parameters.py --list_parameters — completed successfully
• Rebase range-diff audited all 20 commits; the only material delta is removal of the newer Integrate articulation ordering caches and selectors #6784 OVPhysX target helper whose ownership moves into OvPhysxActuatorControl

GPU-dependent interface coverage could not be rerun in the final post-rebase environment because CUDA and OVPhysX were unavailable. This is separate from the successful GPU equivalence and training runs collected during development.

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have added a changelog fragment under source/<pkg>/changelog.d/ for every touched package
• My name already exists in CONTRIBUTORS.md