Initial Support for Multiple Simulation Backends

[AntoineRichard]

Description

This PR introduces a multi-backend architecture for Isaac Lab asset classes, separating simulation backend-specific code from the core API. This enables future support for different physics backends while maintaining a consistent user-facing API.

Key Changes:

New isaaclab_physx Extension

A new extension containing PhysX-specific implementations of asset classes:

• Articulation and ArticulationData
• RigidObject and RigidObjectData
• RigidObjectCollection and RigidObjectCollectionData
• DeformableObject, DeformableObjectCfg, and DeformableObjectData (moved from isaaclab)
• SurfaceGripper and SurfaceGripperCfg (moved from isaaclab)

Abstract Base Classes in isaaclab

• Added backend-agnostic base classes that define the interface:
• BaseArticulation and BaseArticulationData
• BaseRigidObject and BaseRigidObjectData
• BaseRigidObjectCollection and BaseRigidObjectCollectionData

Deprecations

• root_physx_view → root_view on all asset classes (Articulation, RigidObject, RigidObjectCollection, DeformableObject)
• object_* → body_* naming convention in RigidObjectCollection (e.g., write_object_state_to_sim() → write_body_state_to_sim())

Migration Guide

Added comprehensive migration guide at docs/source/migration/migrating_to_isaaclab_3-0.rst with:

• Import changes for moved classes
• Complete deprecation tables
• Code examples

Type of change

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

Screenshots

Please attach before and after screenshots of the change if applicable.

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 updated the changelog and the corresponding version in the extension's config/extension.toml file
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[greptile-apps]

Greptile Overview

Greptile Summary

This PR introduces a multi-backend architecture to Isaac Lab 3.0, separating simulation backend-specific code (PhysX) from the core API. This is a foundational refactoring that enables future support for different physics backends.

Key Changes

• Factory Pattern Implementation: New FactoryBase class in backend_utils.py dynamically loads backend implementations (currently hardcoded to PhysX)
• Asset Class Refactoring: Split into base classes (BaseArticulation, BaseRigidObject, BaseRigidObjectCollection) and backend-specific implementations
• New isaaclab_physx Extension: PhysX-specific implementations moved to separate extension (DeformableObject, SurfaceGripper, and PhysX versions of core assets)
• API Deprecations:
  • root_physx_view → root_view (with deprecation warnings)
  • object_* → body_* naming in RigidObjectCollection (backward compatible)
• Comprehensive Migration Guide: Detailed documentation covering all breaking changes

Architecture Quality

The refactoring follows solid software engineering principles with clear separation of concerns. The factory pattern implementation is clean, though the backend selection is currently hardcoded to "physx" (line 40 in backend_utils.py). The base classes provide well-defined interfaces for backend implementations.

Backward Compatibility

Good backward compatibility support through:

• Deprecation warnings for old APIs
• Factory pattern returns backend implementations transparently
• Migration guide with clear examples

Testing & Documentation

• Tests updated to import from isaaclab_physx where appropriate
• Comprehensive migration guide added
• All major code paths appear to be covered

Confidence Score: 4/5

• This PR is safe to merge with minor considerations - the refactoring is well-structured with proper deprecation warnings and migration documentation
• Score of 4 reflects a massive but well-executed refactoring with comprehensive migration support. The architecture is sound and backward compatibility is maintained. The only concern is the hardcoded backend selection which should be configurable before final release, and the PR is marked as DRAFT suggesting the author is aware of remaining work.
• Pay attention to backend_utils.py (hardcoded backend selection) and verify that all deprecated API paths have proper warnings implemented

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/utils/backend_utils.py	New factory pattern implementation for backend abstraction - hardcoded backend selection needs configuration mechanism
source/isaaclab/isaaclab/assets/articulation/base_articulation.py	New base class for backend-agnostic articulation interface - clean abstraction layer
source/isaaclab/isaaclab/assets/articulation/articulation.py	Refactored to thin factory wrapper delegating to backend implementations
source/isaaclab_physx/isaaclab_physx/assets/articulation/articulation.py	PhysX-specific articulation moved from core - maintains existing functionality
source/isaaclab/isaaclab/envs/mdp/events.py	Updated to use root_view instead of root_physx_view and added local caching of default values
docs/source/migration/migrating_to_isaaclab_3-0.rst	Comprehensive migration guide documenting API changes and deprecations

Sequence Diagram

sequenceDiagram
    participant User
    participant Articulation as Articulation(Factory)
    participant FactoryBase
    participant Module as isaaclab_physx.assets.articulation
    participant PhysXArticulation as PhysXArticulation
    participant BaseArticulation

    User->>Articulation: Articulation(cfg)
    Articulation->>FactoryBase: __new__(cls, cfg)
    FactoryBase->>FactoryBase: backend = "physx" (hardcoded)
    
    alt Backend not in registry
        FactoryBase->>Module: importlib.import_module("isaaclab_physx.assets.articulation")
        Module->>FactoryBase: Return module
        FactoryBase->>Module: getattr(module, "Articulation")
        Module->>FactoryBase: Return PhysXArticulation class
        FactoryBase->>FactoryBase: register("physx", PhysXArticulation)
    end
    
    FactoryBase->>PhysXArticulation: __init__(cfg)
    PhysXArticulation->>BaseArticulation: super().__init__(cfg)
    BaseArticulation-->>PhysXArticulation: Initialized
    PhysXArticulation-->>User: PhysXArticulation instance
    
    Note over User,PhysXArticulation: User code sees Articulation but gets PhysXArticulation
    Note over FactoryBase: Backend selection currently hardcoded to "physx"

Loading

[greptile-apps]

_{6 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Backend selection is hardcoded to "physx". Consider adding a configuration mechanism (e.g., environment variable, config file, or function parameter) to make the backend selectable before the 3.0 release.

Suggested change

	# TODO: Make the backend configurable.
	backend = "physx"
	# TODO: Make the backend configurable via environment variable or config
	backend = os.environ.get("ISAACLAB_BACKEND", "physx")

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}