添加物理后端

添加物理后端#

本指南介绍如何为 Isaac Lab 扩展新的物理后端。请先阅读 后端架构 ，了解此扩展所实现的工厂分发和通用接口设计。

先决条件#

开始前，先明确引擎的生命周期、原生数据归属，以及可支持的资产和传感器。后端必须提供 PhysicsManager 实现，并遵循 FactoryBase 要求的模块布局。

创建后端包#

创建扩展包，在包路径中使用后端名称。例如，名为 mybackend 的后端使用以下布局：

source/isaaclab_mybackend/
└── isaaclab_mybackend/
    ├── __init__.py
    ├── physics/
    │   ├── __init__.py           # lazy_export()
    │   ├── __init__.pyi          # public exports
    │   ├── mybackend_manager.py
    │   └── mybackend_manager_cfg.py
    ├── assets/
    │   ├── articulation/
    │   │   ├── __init__.py
    │   │   ├── __init__.pyi
    │   │   ├── articulation.py
    │   │   └── articulation_data.py
    │   ├── rigid_object/
    │   │   └── ...
    │   ├── deformable_object/
    │   │   └── ...
    │   └── rigid_object_collection/
    │       └── ...
    ├── sensors/
    │   ├── contact_sensor/
    │   └── ...
    ├── renderers/
    │   └── ...
    └── cloner/
        └── ...

实现物理管理器#

管理器必须提供 SceneDataBackend ，使 SceneDataProvider 能以渲染器和可视化器使用的 Warp 原生格式，读取后端的刚体变换。

# isaaclab_mybackend/physics/mybackend_manager.py
from typing import ClassVar

from isaaclab.physics import PhysicsEvent, PhysicsManager
from isaaclab.scene_data import SceneDataBackend, SceneDataFormat


class MyBackendSceneDataBackend(SceneDataBackend):
    def __init__(self):
        self._scene_data = SceneDataFormat.Transform()

    @property
    def transforms(self) -> SceneDataFormat.Transform:
        # Return current world-space body transforms as a Warp transformf array.
        self._scene_data.transforms = ...  # backend-native tensor view
        return self._scene_data

    @property
    def transform_count(self) -> int:
        ...

    @property
    def transform_paths(self) -> list[str]:
        # One prim path per transform; used by SceneDataProvider.create_mapping.
        ...


class MyBackendManager(PhysicsManager):
    _scene_data_backend: ClassVar[MyBackendSceneDataBackend | None] = None

    @classmethod
    def initialize(cls, sim_context):
        super().initialize(sim_context)
        cls._scene_data_backend = MyBackendSceneDataBackend()
        # Initialize the physics engine.

    @classmethod
    def get_scene_data_backend(cls) -> SceneDataBackend:
        return cls._scene_data_backend

    @classmethod
    def step(cls):
        # Advance simulation by one timestep.
        ...

    @classmethod
    def forward(cls):
        # Update kinematics without stepping.
        ...

    @classmethod
    def reset(cls, soft=False):
        if not soft:
            cls.dispatch_event(PhysicsEvent.PHYSICS_READY)
        # Reset simulation state.

    @classmethod
    def close(cls):
        super().close()
        # Clean up resources.

定义物理配置#

定义 PhysicsCfg 子类，指定管理器类并保存后端特有设置：

# isaaclab_mybackend/physics/mybackend_manager_cfg.py
from isaaclab.physics import PhysicsCfg
from isaaclab.utils import configclass


@configclass
class MyBackendCfg(PhysicsCfg):
    class_type = "{DIR}.mybackend_manager:MyBackendManager"
    # Backend-specific settings here.

注册后端键#

FactoryBase 不会根据任意物理管理器类名自动推导新的后端键。在工厂能够解析该后端的资产和传感器前，需将管理器前缀添加到 isaaclab.utils.backend_utils 中的核心选择器：

# source/isaaclab/isaaclab/utils/backend_utils.py
@classmethod
def _get_backend(cls, *args, **kwargs) -> str:
    from isaaclab.sim.simulation_context import SimulationContext

    manager_name = SimulationContext.instance().physics_manager.__name__.lower()
    if manager_name.startswith("mybackend"):
        return "mybackend"
    # Keep the existing newton, ovphysx, and physx cases below.

现有 _get_package_name() 约定会将 mybackend 键映射到上述 isaaclab_mybackend 包。如果集成使用其他包名，还需在 _get_package_name() 中添加显式分支。只有键与包映射选定并导入后端模块后， FactoryBase.register() 才会缓存具体类；单独调用它不会注册新的物理管理器前缀。

实现资产和传感器#

每个受支持的资产或传感器都继承 isaaclab 中对应的基类。实现类名必须与工厂期望的名称一致。在包的 __init__.py 中使用 lazy_export() 。核心后端键映射配置好后，工厂会按包名和模块路径约定导入模块，并缓存实现类。

# isaaclab_mybackend/assets/articulation/articulation.py
from isaaclab.assets.articulation import BaseArticulation


class Articulation(BaseArticulation):
    def __init__(self, cfg):
        super().__init__(cfg)
        # Set up backend-specific simulation structures.

验证后端发现机制#

从当前物理管理器选择已注册的 mybackend 键后， FactoryBase 会将 isaaclab.assets.articulation 映射到 isaaclab_mybackend.assets.articulation 。请按以下步骤验证配置的发现路径：

  • 构造后端配置。

  • 使用该配置初始化最小仿真。

  • 实例化一个后端支持的资产。

  • 推进一个仿真步。

  • 正常关闭仿真。

目录