Refactors the doc on Schema for Lab 3.0, and adds MuJoCo gravcomp

[vidurv-nvidia]

Description

Adds Newton-native and MuJoCo-specific schema cfg classes to isaaclab_newton.sim.schemas,
following the base/subclass framework from #5275. All new cfgs use the per-declaring-class
MRO routing in _apply_namespaced_schemas — no backend-specific branching in any writer.

Depends on #5275.

New cfgs

MuJoCo (Newton MuJoCo kernel, mjc:* namespace)

Class	Field	USD attribute	Applied schema
MujocoRigidBodyPropertiesCfg	gravcomp	mjc:gravcomp	None (raw attr)
MujocoJointDrivePropertiesCfg	actuatorgravcomp	mjc:actuatorgravcomp	MjcJointAPI

Body-level gravcomp must be set for joint-level actuatorgravcomp to have any effect.
The spawner auto-enables MujocoRigidBodyPropertiesCfg(gravcomp=1.0) when joint-level
actuator gravcomp is requested without body-level gravcomp.

Newton-native (newton:* namespace)

Class	Fields	USD attributes	Applied schema
NewtonCollisionPropertiesCfg	contact_margin, contact_gap	newton:contactMargin, newton:contactGap	NewtonCollisionAPI
NewtonMeshCollisionPropertiesCfg	max_hull_vertices	newton:maxHullVertices	NewtonMeshCollisionAPI
NewtonMaterialPropertiesCfg	torsional_friction, rolling_friction	newton:torsionalFriction, newton:rollingFriction	NewtonMaterialAPI
NewtonArticulationRootPropertiesCfg	self_collision_enabled	newton:selfCollisionEnabled	NewtonArticulationRootAPI

Design constraints

Same single-cfg-per-spawner-slot rule as #5275. Newton cfgs subclass the same base classes
as PhysX cfgs; each declares _usd_namespace/_usd_applied_schema (ClassVar) and fields
that auto-camelCase to their USD attr names. Per-declaring-class MRO routing handles mixed
PhysX+Newton cfg hierarchies correctly.

Field renames (with deprecation aliases through 5.0)

Old	New	Reason
gravity_compensation_scale	gravcomp	Single word identity: gravcomp → mjc:gravcomp
gravity_compensation	actuatorgravcomp	Single word identity: actuatorgravcomp → mjc:actuatorgravcomp

Type of change

• New feature (non-breaking)

Forwarding shims on isaaclab.sim.schemas keep existing imports working.
Deprecation aliases keep old field names working through 5.0.

Test plan

• MuJoCo tests: mjc:gravcomp / mjc:actuatorgravcomp written when set, not written when None
• Newton collision, material, articulation-root: attrs written, schemas applied only when non-None
• Deprecation alias tests for renamed fields
• test_schemas.py 46/46 pass — no regressions
• Pre-commit clean

Supersedes

Together with #5275, supersedes #4847 and #5203.

[greptile-apps]

Greptile Summary

Adds MuJoCo gravity-compensation and Newton-native schema cfg classes (MujocoRigidBodyPropertiesCfg, MujocoJointDrivePropertiesCfg, and four Newton* cfgs) under isaaclab_newton.sim.schemas, with lazy-import forwarding shims from isaaclab.sim.schemas so downstream code continues to work without isaaclab_newton installed. A spawner convenience block in from_files.py tries to auto-enable body-level gravcomp when joint-level actuatorgravcomp is requested.

• New cfg classes in isaaclab_newton: eight classes using ClassVar _usd_namespace/_usd_applied_schema metadata; deprecation aliases for renamed fields included.
• Forwarding shims: __getattr__-based lazy resolution added to isaaclab.sim.schemas, isaaclab.sim.schemas.schemas_cfg, and isaaclab.sim; mirrors the existing PhysX shim pattern cleanly.
• Auto-gravcomp logic in from_files.py: two issues — an unconditional from isaaclab_newton... import that fires for any joint-drive config (breaking non-Newton users), and an isinstance guard that misses MujocoRigidBodyPropertiesCfg(gravcomp=None) cases where body-level compensation is still absent.

Confidence Score: 4/5

The cfg classes and forwarding shims are well-structured and safe. One block in the core spawner unconditionally imports from isaaclab_newton, which will break any non-Newton spawn that sets joint drive properties when isaaclab_newton is not installed.

The cfg definitions, shims, and tests are solid. The spawner change in from_files.py introduces a hard dependency on isaaclab_newton for all joint-drive users: the import fires unconditionally inside the if-block, raising ImportError for PhysX and base configs alike when isaaclab_newton is absent. Additionally, the isinstance guard that decides whether to auto-apply body-level gravcomp does not check whether gravcomp is actually set on an existing MujocoRigidBodyPropertiesCfg, so the auto-apply can be silently skipped even when body-level compensation is absent.

source/isaaclab/isaaclab/sim/spawners/from_files/from_files.py — both the unconditional import and the isinstance guard logic need to be fixed before merging.

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/sim/spawners/from_files/from_files.py	Auto-gravcomp convenience block has two bugs: unconditional isaaclab_newton import breaks non-Newton spawns, and the isinstance guard misses MujocoRigidBodyPropertiesCfg instances where gravcomp is still None.
source/isaaclab_newton/isaaclab_newton/sim/schemas/schemas_cfg.py	New Newton/MuJoCo cfg classes follow the established base/subclass pattern correctly; ClassVar metadata and field declarations look correct.
source/isaaclab/isaaclab/sim/schemas/schemas_cfg.py	Adds lazy-import forwarding shim for Newton cfg names; mirrors the existing PhysX shim pattern correctly.
source/isaaclab/isaaclab/sim/schemas/init.py	Adds _NEWTON_FORWARDS set and getattr branch, consistent with the PhysX forwarding pattern.
source/isaaclab_newton/test/sim/test_newton_schemas.py	Comprehensive tests for written/not-written behaviour of all new cfg classes; covers both set and None cases.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[_spawn_from_usd_file] --> B{joint_drive_props\nis not None?}
    B -- No --> Z[skip gravcomp block]
    B -- Yes --> C["from isaaclab_newton import\nMujocoJointDrivePropertiesCfg\nMujocoRigidBodyPropertiesCfg\n⚠️ UNCONDITIONAL — fails if\nisaaclab_newton not installed"]
    C --> D{isinstance\njoint_drive_props,\nMujocoJointDrivePropertiesCfg?}
    D -- No --> G[modify_joint_drive_properties]
    D -- Yes --> E{actuatorgravcomp\nis truthy?}
    E -- No --> G
    E -- Yes --> F{isinstance\nrigid_props,\nMujocoRigidBodyPropertiesCfg?}
    F -- "Yes, but gravcomp=None" --> H["⚠️ No auto-apply fires\nBody gravcomp not set\nBut no warning logged"]
    F -- "No / different type" --> I["Auto-apply\nMujocoRigidBodyPropertiesCfg\ngravcomp=1.0"]
    I --> G
    H --> G

Loading

_{Reviews (3): Last reviewed commit: "Merge branch 'develop' into vidur/featur..." | Re-trigger Greptile}

[greptile-apps]

cfg arg docstring doesn't mention the new MuJoCo type

The Args section for cfg lists RigidBodyPropertiesCfg and PhysxRigidBodyPropertiesCfg but not MujocoRigidBodyPropertiesCfg. The same omission exists in modify_joint_drive_properties (around line 650). Since users discover supported types from the docstring, both should be updated to include the new classes.

Suggested change

	Args:
	prim_path: The prim path to the rigid body.
	cfg: The configuration for the rigid body.
	cfg: The configuration for the rigid body. Can be
	:class:`~schemas_cfg.RigidBodyPropertiesCfg` for solver-common properties or
	:class:`~schemas_cfg.PhysxRigidBodyPropertiesCfg` for PhysX-specific properties.
	stage: The stage where to find the prim. Defaults to None, in which case the
	cfg: The configuration for the rigid body. Can be
	:class:`~schemas_cfg.RigidBodyPropertiesCfg` for solver-common properties,
	:class:`~schemas_cfg.PhysxRigidBodyPropertiesCfg` for PhysX-specific properties, or
	:class:`~schemas_cfg.MujocoRigidBodyPropertiesCfg` for Newton (MuJoCo)-specific properties.

[greptile-apps]

No range validation for gravity_compensation_scale

MuJoCo's gravcomp is documented as a scale in [0.0, 1.0] where 0 means no compensation and 1 means full compensation. Values outside this range are silently accepted and passed through to USD, which may produce unexpected simulation behaviour. Consider adding a __post_init__ validator or at least a more explicit range annotation in the docstring (e.g. [0.0, 1.0, dimensionless]) to prevent silently misconfigured assets.

[greptile-apps]

Missing guard when namespace is None but cfg_dict is non-empty

If a future subclass of RigidBodyPropertiesCfg adds fields without setting _usd_namespace, the f-string f"{namespace}:{usd_attr_name}" evaluates to "None:someAttr" and silently writes a garbage attribute name. The existing subclasses are safe today, but a guard would be defensive:

if namespace is not None:
    for attr_name, value in cfg_dict.items():
        usd_attr_name = attr_name_map.get(attr_name, to_camel_case(attr_name, "cC"))
        safe_set_attribute_on_usd_prim(rigid_body_prim, f"{namespace}:{usd_attr_name}", value, camel_case=False)

[AntoineRichard]

My main concern here is usability. Users will have to call the right schema for the right backend which will mean backend specific assets? @vidurv-nvidia
It's the same concern as in #5275. If it only touches the assets, then fine, but I wouldn't be for injecting more auto-magic in the code.

[greptile-apps]

Unconditional isaaclab_newton import breaks non-MuJoCo spawning without the extension

The import on this line is placed unconditionally inside if cfg.joint_drive_props is not None:, so it executes for every call that sets any joint_drive_props — including plain PhysxJointDrivePropertiesCfg. If isaaclab_newton is not installed, every such spawn will raise an ImportError, silently regressing the core PhysX path for anyone who doesn't have the Newton extension.

The rest of the PR goes to great lengths to keep all Newton imports lazy; this one location undoes that guarantee. Wrapping the import in try/except ImportError (or moving it inside the inner if isinstance(...) condition) restores the intended isolation.

[greptile-apps]

Unconditional isaaclab_newton import breaks non-Newton joint-drive users

The import on this line executes unconditionally whenever cfg.joint_drive_props is not None, regardless of whether the cfg is a MuJoCo type. Any user of isaaclab (without isaaclab_newton) who sets joint_drive_props to a PhysX or base config will receive an ImportError at spawn time — a regression from the pre-PR behaviour. The import must be guarded with try/except ImportError so it's a no-op when isaaclab_newton is absent.

[greptile-apps]

Auto-enable guard misses MujocoRigidBodyPropertiesCfg with gravcomp=None

The condition not isinstance(cfg.rigid_props, MujocoRigidBodyPropertiesCfg) evaluates to False (skipping the auto-apply) even when cfg.rigid_props = MujocoRigidBodyPropertiesCfg() — i.e. gravcomp is still None. Body-level compensation won't be active, but no warning is logged and no auto-apply fires. The check should be not (isinstance(cfg.rigid_props, MujocoRigidBodyPropertiesCfg) and cfg.rigid_props.gravcomp is not None) to match the intent stated in the inline comment.

[ooctipus]

is the rhs of as aliasing exactly the same as lhs?

[ooctipus]

hmmmm maybe only override to 1.0 if the default is None?, what if I want gravcomp=0.5?

[ooctipus]

 body_gravcomp_not_exist_in_rigid_object = (
      not isinstance(cfg.rigid_props, MujocoRigidBodyPropertiesCfg)
      or cfg.rigid_props.gravcomp is None
  )

  if (
      isinstance(cfg.joint_drive_props, MujocoJointDrivePropertiesCfg)
      and cfg.joint_drive_props.actuatorgravcomp
      and body_gravcomp_not_exist_in_rigid_object
  ):
      schemas.modify_rigid_body_properties(
          prim_path,
          MujocoRigidBodyPropertiesCfg(gravcomp=1.0),
      )

[ooctipus]

Base schema cfg already has drive properties, but some are missing:
Covered:

  JointDriveBaseCfg(
      drive_type="force",
      max_force=100.0,
      stiffness=100.0,
      damping=10.0,
      max_joint_velocity=5.0,
  )

Missing

  # Joint-level, missing
  newton:linear:limitStiffness
  newton:angular:limitStiffness
  newton:rotX:limitStiffness
  newton:rotY:limitStiffness
  newton:rotZ:limitStiffness

  newton:linear:limitDamping
  newton:angular:limitDamping
  newton:rotX:limitDamping
  newton:rotY:limitDamping
  newton:rotZ:limitDamping

  # Shape-level, partially represented
  newton:maxHullVertices       # covered
  newton:contactMargin         # covered
  newton:contactGap            # covered
  newton:contact_ke            # missing
  newton:contact_kd            # missing

  # Articulation/material covered
  newton:selfCollisionEnabled  # covered
  newton:torsionalFriction     # covered
  newton:rollingFriction       # covered

MuJoCo also provides more. From newton/newton/_src/usd/schemas.py:284, MuJoCo resolver has:

  # Joint-level, missing
  mjc:armature
  mjc:frictionloss
  mjc:solreflimit

  # Shape-level, missing
  mjc:maxhullvert
  mjc:margin
  mjc:gap
  mjc:solref

  # Material-level, missing
  mjc:torsionalfriction
  mjc:rollingfriction
  mjc:priority
  mjc:solmix
  mjc:solref

  # Actuator-level, missing
  mjc:ctrlRange:min
  mjc:ctrlRange:max
  mjc:forceRange:min
  mjc:forceRange:max
  mjc:actRange:min
  mjc:actRange:max
  mjc:lengthRange:min
  mjc:lengthRange:max
  mjc:gainPrm
  mjc:gainType
  mjc:biasPrm
  mjc:biasType
  mjc:dynPrm
  mjc:dynType
  mjc:gear

Are you planning to include them ? if yes is it in follow up pr?

[isaaclab-review-bot]

Review Summary

Excellent addition that fills an important gap in the multi-backend schema story. The per-declaring-class MRO routing design from #5275 pays off here — each Newton/MuJoCo cfg cleanly declares its namespace and schema without any backend branching in the writer code.

Strengths

• Clean class hierarchy: MujocoRigidBodyPropertiesCfg → NewtonRigidBodyPropertiesCfg → RigidBodyBaseCfg is exactly right for the solver-within-backend relationship
• Lazy forwarding shims: isaaclab.sim.schemas doesn't hard-depend on isaaclab_newton — great for users who only have PhysX installed
• Auto-enable gravcomp: The spawner auto-enabling body-level gravcomp when joint-level actuatorgravcomp is set prevents a footgun (joint-level alone is a no-op)
• Documentation: The schema_cfgs.rst concept page is outstanding — clear hierarchy diagram, when-to-use-which guidance, mixed-namespace explanation, and the gravity compensation section anticipates exactly the question users will have
• Test coverage: Every cfg tested for both "written when set" and "not written when None" — correct approach for optional schema authoring
• Migration guide: Comprehensive tables in migrating_to_isaaclab_3-0.rst with before/after code examples

Concerns

See inline comments.

[isaaclab-review-bot]

🔴 Hard import of isaaclab_newton inside core isaaclab: This imports MujocoJointDrivePropertiesCfg and MujocoRigidBodyPropertiesCfg directly from isaaclab_newton inside a spawner function in core isaaclab. This creates a runtime dependency of isaaclab on isaaclab_newton — if someone uses a MuJoCo joint drive cfg, this code path will fail if isaaclab_newton isn't installed.

The lazy __getattr__ shims in __init__.py were specifically designed to avoid this. This should use the same pattern or guard with a try/except:

Suggested change

	# auto-enable body-level gravcomp if joint-level actuator gravcomp is requested
	# auto-enable body-level gravcomp if joint-level actuator gravcomp is requested
	# without it — actuatorgravcomp has no effect since there are no forces to route
	try:
	from isaaclab_newton.sim.schemas.schemas_cfg import MujocoJointDrivePropertiesCfg, MujocoRigidBodyPropertiesCfg
	except ImportError:
	MujocoJointDrivePropertiesCfg = type(None) # type: ignore[misc,assignment]
	MujocoRigidBodyPropertiesCfg = type(None) # type: ignore[misc,assignment]

Alternatively, this logic could use duck-typing: check for hasattr(cfg.joint_drive_props, 'actuatorgravcomp') and hasattr(cfg.rigid_props, 'gravcomp') instead of isinstance checks.

[isaaclab-review-bot]

🟡 modify_rigid_body_properties called before the cfg's own rigid_props: The auto-enable calls modify_rigid_body_properties(prim_path, MujocoRigidBodyPropertiesCfg(gravcomp=1.0)) here, but the existing rigid_props from the cfg was already applied earlier in the function (around line 342). This means:

1. If the user passed rigid_props=RigidBodyBaseCfg(disable_gravity=True), those properties are already on the prim.
2. The auto-enable then calls modify_rigid_body_properties again with a fresh MujocoRigidBodyPropertiesCfg(gravcomp=1.0) — this will write mjc:gravcomp but might also re-apply base-class fields with their defaults (all None, so probably fine since the writer skips None values).

Is this ordering intentional? The auto-enable won't clobber existing base fields (since they're None on the auto-generated cfg), but it's worth adding a comment confirming this expectation.

[isaaclab-review-bot]

🟡 NewtonMeshCollisionPropertiesCfg multiple inheritance: This class inherits from both NewtonCollisionPropertiesCfg and MeshCollisionBaseCfg. While the MRO routing handles field-to-namespace mapping correctly, Python's dataclass (and configclass) MRO can be tricky with diamond inheritance if both parents share a common grandparent.

Does NewtonCollisionPropertiesCfg → CollisionBaseCfg share any fields with MeshCollisionBaseCfg? If MeshCollisionBaseCfg doesn't inherit from CollisionBaseCfg, this is fine. But if it does (even transitionally), configclass field resolution order could produce surprising behavior.

A quick MujocoJointDrivePropertiesCfg.__mro__ printout in tests would be a good sanity check to document the resolution order.

[isaaclab-review-bot]

💡 Empty base classes as namespace reservations: NewtonRigidBodyPropertiesCfg and NewtonJointDrivePropertiesCfg are currently empty — they exist to reserve the newton: namespace and provide a type for isinstance checks. This is a good pattern, but it means users who isinstance(cfg, NewtonRigidBodyPropertiesCfg) are testing "this cfg targets Newton" rather than "this cfg has Newton-specific fields".

Consider adding a brief class-level note about this intended usage:

# Use isinstance(cfg, NewtonRigidBodyPropertiesCfg) to check whether a cfg
# targets the Newton backend (including MuJoCo solver cfgs).

[isaaclab-review-bot]

💡 DRY: _NEWTON_FORWARDS defined in three places: The same frozenset of Newton class names appears in isaaclab.sim.__init__.py, isaaclab.sim.schemas.__init__.py, and isaaclab.sim.schemas.schemas_cfg.py. If a new Newton cfg is added, all three must be updated.

Consider defining it once (e.g., in isaaclab.sim.schemas.schemas_cfg) and importing from there:

# In isaaclab.sim.schemas.__init__.py:
from .schemas_cfg import _NEWTON_FORWARDS

This would centralize the vocabulary. Minor suggestion — the pattern is already established by the PhysX forwards, so consistency with existing code is also valid.

[isaaclab-review-bot]

💡 Outstanding documentation: This concept page is one of the best-structured docs in the project. The hierarchy diagram, when-to-use decision matrix, mixed-namespace explanation, and gravity compensation deep-dive are all exactly what a user needs. The tables mapping fields → USD attributes → namespaces are particularly valuable for debugging.

One small addition that would help: a "Quick Reference" at the top showing which import to use for the most common scenarios:

.. code-block:: python

   # Backend-portable (any solver):
   from isaaclab.sim.schemas import RigidBodyBaseCfg

   # PhysX-targeted:
   from isaaclab_physx.sim.schemas import PhysxRigidBodyPropertiesCfg

   # Newton MuJoCo-targeted:
   from isaaclab_newton.sim.schemas import MujocoRigidBodyPropertiesCfg

[AntoineRichard]

In general I think it's pretty good considering our timeline I would be in favor of getting this in in its current state with a couple of small changes. (see the imports) But we'd need to severly rework the doc to avoid maintenance issues in the future.

[AntoineRichard]

Shouldn't that be in a separate PR?

[AntoineRichard]

Same here, could be in another PR?

[AntoineRichard]

Could be in another PR?

[AntoineRichard]

Could be in another PR?

[AntoineRichard]

I think what's ambiguous, and that's not on you @vidurv-nvidia, is that PhysX TGS iterations, is really not in the same class as MuJoCo grav comp. PhysX TGS iterations should very likely live inside a solver CFG similar to the newton solvers.

[AntoineRichard]

Could you not mention PhysX TGS iterations here?

[AntoineRichard]

What's the difference?

[AntoineRichard]

So we need this here? Can this be in the code and directly collected using auto-doc?

[AntoineRichard]

4.0

[AntoineRichard]

4.0

[AntoineRichard]

YEah that weird why not do:

Suggested change

	from .schemas_cfg import (
	MujocoJointDrivePropertiesCfg as MujocoJointDrivePropertiesCfg,
	MujocoRigidBodyPropertiesCfg as MujocoRigidBodyPropertiesCfg,
	NewtonArticulationRootPropertiesCfg as NewtonArticulationRootPropertiesCfg,
	NewtonCollisionPropertiesCfg as NewtonCollisionPropertiesCfg,
	NewtonJointDrivePropertiesCfg as NewtonJointDrivePropertiesCfg,
	NewtonMaterialPropertiesCfg as NewtonMaterialPropertiesCfg,
	NewtonMeshCollisionPropertiesCfg as NewtonMeshCollisionPropertiesCfg,
	NewtonRigidBodyPropertiesCfg as NewtonRigidBodyPropertiesCfg,
	from .schemas_cfg import (
	MujocoJointDrivePropertiesCfg,
	MujocoRigidBodyPropertiesCfg,
	NewtonArticulationRootPropertiesCfg,
	NewtonCollisionPropertiesCfg,
	NewtonJointDrivePropertiesCfg,
	NewtonMaterialPropertiesCfg,
	NewtonMeshCollisionPropertiesCfg,
	NewtonRigidBodyPropertiesCfg,