Documents JointDrivePropertiesCfg.ensure_drives_exist (#5723)

# Description

Documents the `JointDrivePropertiesCfg.ensure_drives_exist` flag
introduced in #5251. Adds a troubleshooting entry and a how-to section
so users hitting *"my joints actuate in PhysX but do nothing in Newton
with `ImplicitActuatorCfg`"* can find the fix without having to read the
schemas source.

## Background

Newton's USD importer only materialises a solver actuator for a joint
when the authored `PhysicsDriveAPI` reports a non-zero stiffness or
damping. Many existing assets ship with both at `0`, expecting an
`ImplicitActuatorCfg` (or `IdealPDActuatorCfg`) to supply the gains at
runtime. PhysX creates the actuator regardless and lets the runtime
writes take effect; Newton drops the joint from the actuator set before
the runtime writes can attach.

`ensure_drives_exist=True` on the spawn config writes a minimal
placeholder stiffness (`1e-3`) to any drive whose authored stiffness
*and* damping are both zero, so Newton creates the actuator. The actual
gains still come from the actuator model at runtime.

## Changes

- `docs/source/refs/troubleshooting.rst` — new "Joints actuate in PhysX
but not in a Newton-based backend" section, slotted with the other
physics-stability entries. Includes symptom, cause, and a working code
snippet.
- `docs/source/how-to/import_new_asset.rst` — new "Ensuring joint drives
exist on every joint" section with the labelled anchor
`import-new-asset-ensure-drives-exist` so other pages can
cross-reference the full explanation. Sits between the MJCF importer and
Mesh importer sections since it applies to URDF- and MJCF-imported
assets but not to mesh assets.
- `docs/source/how-to/write_articulation_cfg.rst` — short
cross-reference admonition next to the `ImplicitActuatorCfg` example,
pointing readers to the anchor above.
- `source/isaaclab/changelog.d/antoiner-docs-ensure-drives-exist.skip` —
docs-only, no version bump.

## Type of change

- Documentation update

## Checklist

- [x] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [x] I have run the `pre-commit` checks with `./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works (docs-only)
- [x] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file (`.skip` fragment, docs-only)
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

Author: AntoineRichard

docs/source/how-to/import_new_asset.rst

@@ -343,6 +343,61 @@ Executing the above script will create the USD file inside the
     :alt: result of convert_mjcf.py
 
 
+.. _import-new-asset-ensure-drives-exist:
+
+Ensuring joint drives exist on every joint
+------------------------------------------
+
+A common pitfall when porting a freshly-imported asset across physics backends
+is that joints which actuate fine in PhysX silently do nothing in a
+Newton-based backend (MuJoCo Warp, XPBD, Featherstone, Semi-implicit).
+
+The URDF and MJCF importers both write a ``PhysicsDriveAPI`` to every
+articulated joint, but the stiffness and damping on that drive are often left
+at ``0`` — the assumption being that the actuator gains are authored at runtime
+by an :class:`~isaaclab.actuators.ImplicitActuatorCfg` or
+:class:`~isaaclab.actuators.IdealPDActuatorCfg`. This is the recommended way to
+keep gains tunable per task without re-importing the USD.
+
+PhysX creates a solver actuator for every joint regardless of the authored
+gains, so the runtime writes from ``ImplicitActuatorCfg.stiffness`` /
+``damping`` always take effect. Newton's USD importer, by contrast, only
+materialises a solver actuator when the authored drive reports a non-zero
+stiffness or damping — a joint whose authored gains are both zero is treated
+as passive and is dropped from the actuator set, so subsequent runtime writes
+have nothing to attach to.
+
+The recommended fix is to opt the spawn config into the cross-backend bridge by
+setting :attr:`~isaaclab.sim.schemas.JointDrivePropertiesCfg.ensure_drives_exist`
+to ``True``:
+
+.. code:: python
+
+   spawn=sim_utils.UsdFileCfg(
+       usd_path=f"{ISAACLAB_NUCLEUS_DIR}/Robots/Agility/Cassie/cassie.usd",
+       joint_drive_props=sim_utils.JointDrivePropertiesCfg(ensure_drives_exist=True),
+       ...
+   )
+
+When ``ensure_drives_exist=True``, every drive whose authored stiffness *and*
+damping are both zero is updated with a minimal placeholder stiffness
+(``1e-3``) before the simulation starts. This is enough for Newton's importer
+to create the actuator; the actual gains are then overwritten by the actuator
+model at runtime, so the placeholder has no effect on the simulated dynamics.
+Drives whose authored gains are non-zero are left untouched.
+
+This is how ``isaaclab_assets.CASSIE_CFG`` keeps Cassie working across both
+PhysX and Newton — the asset ships with zero-gain drives because it relies on
+``ImplicitActuatorCfg`` for the legs, and the spawn config enables
+:attr:`~isaaclab.sim.schemas.JointDrivePropertiesCfg.ensure_drives_exist` so
+that both backends see the same actuator set.
+
+You can leave the flag at its default ``False`` for assets that author non-zero
+drive gains in the USD itself, or for assets driven by an
+:class:`~isaaclab.actuators.IdealPDActuatorCfg` that explicitly zeroes the
+solver drive and applies torque externally.
+
+
 Using Mesh Importer
 -------------------
 

docs/source/how-to/write_articulation_cfg.rst

@@ -116,6 +116,15 @@ to combine them into a single actuator model.
          ),
       },
 
+.. note::
+   If your asset's USD authored drives ship with zero stiffness *and* zero damping
+   — a common pattern for assets that expect ``ImplicitActuatorCfg`` to supply the
+   gains at runtime — the joints will actuate under PhysX but appear unactuated
+   under Newton-based backends (MuJoCo Warp, XPBD, Featherstone, Semi-implicit).
+   Set :attr:`~isaaclab.sim.schemas.JointDrivePropertiesCfg.ensure_drives_exist`
+   to ``True`` on the spawn config to keep both backends in sync. See
+   :ref:`import-new-asset-ensure-drives-exist` for the full explanation.
+
 
 ActuatorCfg velocity/effort limits considerations
 -------------------------------------------------

docs/source/refs/troubleshooting.rst

@@ -107,6 +107,57 @@ To enable OmniPVD capture in Isaac Lab, add the relevant kit arguments to the co
     ./isaaclab.sh -p scripts/demos/bipeds.py --kit_args "--/persistent/physics/omniPvdOvdRecordingDirectory=/tmp/ --/physics/omniPvdOutputEnabled=true" --headless
 
 
+Joints actuate in PhysX but not in a Newton-based backend
+---------------------------------------------------------
+
+If your robot's joints move under PhysX but appear unactuated under one of the
+Newton-based backends (MuJoCo Warp, XPBD, Featherstone, Semi-implicit) — even
+though you have authored an :class:`~isaaclab.actuators.ImplicitActuatorCfg`
+with non-zero ``stiffness`` and ``damping`` — the cause is almost always that
+the USD asset ships with zero authored drive gains.
+
+Newton's USD importer only materialises a solver actuator when the authored
+``PhysicsDriveAPI`` reports a non-zero stiffness *or* damping. Many existing
+assets leave both at ``0`` on purpose, expecting the actuator gains to come from
+an :class:`~isaaclab.actuators.ImplicitActuatorCfg` at runtime. PhysX creates
+the actuator regardless and lets the runtime gain writes take effect, so the
+asset works there; Newton drops the actuator before the runtime writes can
+attach to it.
+
+The fix is to set
+:attr:`~isaaclab.sim.schemas.JointDrivePropertiesCfg.ensure_drives_exist` to
+``True`` on the spawn config. This writes a minimal placeholder stiffness
+(``1e-3``) to any drive whose authored stiffness *and* damping are both zero,
+which is enough for Newton's importer to create the actuator. The actual gains
+are then overwritten by the actuator model at runtime, so the placeholder has
+no effect on the simulated dynamics.
+
+.. code:: python
+
+   from isaaclab.actuators import ImplicitActuatorCfg
+   from isaaclab.assets import ArticulationCfg
+   import isaaclab.sim as sim_utils
+
+   ROBOT_CFG = ArticulationCfg(
+       spawn=sim_utils.UsdFileCfg(
+           usd_path="...",
+           joint_drive_props=sim_utils.JointDrivePropertiesCfg(ensure_drives_exist=True),
+       ),
+       actuators={
+           "legs": ImplicitActuatorCfg(
+               joint_names_expr=[".*HAA", ".*HFE", ".*KFE"],
+               effort_limit_sim=120.0,
+               velocity_limit_sim=7.5,
+               stiffness={".*": 40.0},
+               damping={".*": 5.0},
+           ),
+       },
+   )
+
+See :ref:`import-new-asset-ensure-drives-exist` for the underlying USD-import
+details and the equivalent fix when authoring a new asset.
+
+
 Checking the internal logs from the simulator
 ---------------------------------------------
 

source/isaaclab/changelog.d/antoiner-docs-ensure-drives-exist.skip

@@ -0,0 +1 @@
+Docs-only: add FAQ and how-to coverage for the ensure_drives_exist flag.