后端与预设

后端与预设#

环境定义机器人、场景、传感器和任务；后端负责物理仿真或渲染；预设选择一组具名配置，使您无需修改 Python 就能切换后端或任务模式。

要选择物理预设，请将其添加到启动命令中：

uv run isaaclab train --rl_library rsl_rl \
   --task Isaac-Cartpole-Direct physics=newton_mjwarp

任务仍是 Isaac-Cartpole-Direct ，预设改变的是启动任务时使用的配置。

可选配置#

任务可以提供三类选项：

Environment
├── physics=...    Which physics configuration runs the simulation?
├── renderer=...   Which renderer produces camera data?
└── presets=...    Which task-specific mode or config bundle is used?

受支持的各后端共用资产、传感器和场景 API。Isaac Lab 如何选择具体实现，见后端架构。

物理、渲染和可视化可以分别选择。例如，相机环境可以使用 Newton 物理与 Newton Warp 渲染器，再通过 --viz 独立选择可视化器。

查看任务支持的选项#

使用 --help 查看任务支持哪些预设：

uv run isaaclab train --rl_library rsl_rl \
   --task Isaac-Cartpole-Camera-Direct --help

帮助输出按 physics=、renderer= 和 presets= 对名称分组。要列出各个已注册环境能够启动的组合，可运行：

uv run isaaclab list_envs --show_presets

输出的每一行都是一组通过无界面启动配置检查的组合，[default] 表示任务的默认组合。某些组合互不兼容：OvPhysX 和 OVRTX 无法与 Isaac Sim / Kit 在同一进程中运行，任务本身也可能施加其他限制。可用 --keyword 缩小搜索范围；检查一个任务的所有组合需要数秒。

如果任务只列出 (defaults)，表示它使用已注册的默认配置，没有可选变体。传入任务未列出的名称不受支持，会在配置校验时失败。

选用合适的选择器#

选择器	示例	修改内容
`physics=NAME`	`physics=newton_mjwarp`	选择物理配置，包括后端和求解器。
`renderer=NAME`	`renderer=newton_renderer`	为产生相机数据的任务选择渲染器配置。
`visualizer=NAME[,NAME,...]`	`visualizer=newton_gl`	选择交互式查看器；`visualizer=none` 表示禁用查看器。
`presets=NAME[,NAME,...]`	`presets=rgb`	应用任务专用选项，例如观测模式、相机布局或兼容的配置组合。

任务脚本还接受 --physics NAME、--renderer NAME 和 --visualizer NAME （--viz NAME）。这些别名选择的是同一组任务预设，并在运行时启动前被解析；--renderer 不会设置 Kit 的渲染模式。显式的 Kit 设置应通过 --kit_args 传入。显式选择会覆盖脚本默认值，若选择相互冲突则报错。

选择器可以组合使用。以下命令选择使用 MuJoCo-Warp 求解器的 Newton 后端、Newton Warp 渲染器，以及 RGB 观测：

uv run isaaclab train --rl_library rsl_rl \
   --task Isaac-Cartpole-Camera-Direct \
   physics=newton_mjwarp renderer=newton_renderer presets=rgb

请使用任务列出的可选值。物理、渲染器、传感器或观测设置不兼容时，配置校验会失败。

常用后端选项#

具体列表取决于环境，但这些名称遵循共同约定：

物理预设#
名称	含义
`isaacsim_physx`	Isaac Sim PhysX，部分任务以此为默认后端。
`physx`	自动选择 PhysX 系列实现。运行时需要 Kit 时使用 Isaac Sim PhysX；完全不使用 Kit 时，可以选用已配置的 OvPhysX 实现。
`newton_mjwarp`	使用 MuJoCo-Warp 求解器的 Newton 物理后端。
`newton_kamino`	使用 Kamino 求解器的 Newton 物理后端，适用于部分任务和兼容资产。
`ovphysx`	适用于受支持任务的 OvPhysX，无需 Kit。

渲染器预设#
名称	含义
`isaacsim_rtx`	Isaac Sim RTX 渲染器。
`rtx`	自动选择 RTX 系列实现。物理、可视化、直播流或其他运行时选项需要 Kit 时，使用 Isaac Sim RTX；否则使用 OVRTX，实现完全不依赖 Kit 的运行。
`newton_renderer`	Newton Warp 渲染器。对于采用多后端渲染器预设的任务，它是默认渲染器。
`ovrtx`	用于不依赖 Kit 的运行方式的 OVRTX 渲染器。

physics=physx 和 renderer=rtx 等自动选择器需显式启用。默认值均明确指定具体实现，保证不传选择器时的任务行为可预测。求解器不等于独立后端： newton_mjwarp 和 newton_kamino 都使用 Newton，只是配置了不同的求解器。

默认值、预设与微调#

预设会替换所在位置的整个配置部分，而不会合并两个备选配置的字段。Isaac Lab 按以下顺序解析配置：

应用各预设配置中的 default 选项。
应用 presets=... 指定的全局选项。
应用针对特定路径的预设，例如 env.sim.physics=newton_mjwarp 。
应用 Hydra 标量覆盖项，例如 env.sim.dt=0.002 。

选择预设后，如需更改某个值：

uv run isaaclab train --rl_library rsl_rl \
   --task Isaac-Cartpole-Direct \
   physics=newton_mjwarp env.sim.dt=0.002

使用 physics= 和 renderer= 选择后端；使用 presets= 选择任务模式，或同时更新多个匹配的配置部分。路径选择器只替换指定的部分。

重要

加载检查点时，应保持会影响行为的预设与训练时一致。观测预设可能改变张量形状，使用一种观测模式训练的策略，未必能在另一种模式下加载。

任务开发者如何提供选项#

任务开发者通过 PresetCfg 定义备选配置，并选定一个默认值。对于多后端任务，预设包装器应放在 SimulationCfg 中：

from isaaclab.physics import PhysxAutoCfg
from isaaclab.sim import SimulationCfg
from isaaclab.utils import configclass
from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg
from isaaclab_ov.physics import OvPhysxCfg
from isaaclab_physx.physics import PhysxCfg
from isaaclab_tasks.utils import PresetCfg


@configclass
class PhysicsCfg(PresetCfg):
    isaacsim_physx = PhysxCfg()
    ovphysx = OvPhysxCfg()
    physx = PhysxAutoCfg(
        isaacsim_physx=isaacsim_physx,
        ovphysx=ovphysx,
    )
    default = isaacsim_physx
    newton_mjwarp = NewtonCfg(solver_cfg=MJWarpSolverCfg())


@configclass
class MyEnvCfg:
    sim: SimulationCfg = SimulationCfg(physics=PhysicsCfg())

尽可能将后端专用值放在具名配置中。这样可以共享任务逻辑，并让命令行显示所有受支持的选项。

如果后端选择还必须改变时间步长等仿真全局设置，物理预设也可以包含完整的 SimulationCfg 备选配置。 physics= 选择器会通过其中的 physics 字段识别这些组合，并应用完整的匹配仿真配置。

后端架构#

工厂在对象构造时将其分派给当前后端的具体实现，因此上层代码可以使用统一的公共 API，无需直接导入各后端的专用模块。

工厂分派#

所有工厂均继承自 FactoryBase，先选择后端键，再通过模块路径定位实现：

FactoryBase._get_backend() 返回 SimulationContext.backend_manager 实例的 backend_name。添加新的物理后端时，需要在其管理器上设置这一类属性。
工厂模块路径决定后端模块路径。例如， isaaclab.assets.articulation 映射到 isaaclab_physx.assets.articulation 、 isaaclab_newton.assets.articulation 或 isaaclab_ov.assets.articulation 。OvPhysX 后端键使用共享的 isaaclab_ov 集成软件包。
工厂按需导入后端模块，并将实现类缓存到注册表中。

User code: Articulation(cfg)
    │
    ▼
FactoryBase.__new__()
    │
    ├─ _get_backend()       → "physx", "newton", or "ovphysx"
    │    (reads SimulationContext.backend_manager)
    │
    ├─ _get_module_name()   → "isaaclab_physx.assets.articulation"
    │    (OvPhysX maps to the shared isaaclab_ov package)
    │
    ├─ importlib.import_module()
    │    (lazy load — only on first use)
    │
    └─ Return backend-specific instance

渲染器和可视化器则通过配置中的 class_type 选择实现。它们的选择独立于物理后端；渲染器实例通过下文介绍的仿真注册表共享。

物理管理器生命周期#

各后端均实现 PhysicsManager 。这一抽象基类负责管理仿真生命周期。具体实现根据 SimulationContext 初始化引擎，通过 forward() 更新运动学、 step() 推进仿真、 reset() 重置状态，并通过 close() 释放资源。

管理器通过 PhysicsEvent 回调处理跨后端的生命周期操作。 MODEL_INIT 在场景构建期间触发， PHYSICS_READY 在物理初始化完成后触发， STOP 在原生资源被替换或关闭之前触发。具体的 close() 实现负责派发 STOP 事件。

SimulationContext 在同一个注册表中管理原生资源和渲染器。若配置及其具体类型均匹配，get_or_create_backend(backend_cfg) 会复用已有资源，否则调用 instantiate(backend_cfg)。可选的关键字参数用于在缓存未命中时提供构造依赖，不影响资源共享的匹配键。BackendCfg 定义资源设置及标识规则，RendererCfg 在此基础上扩展渲染器配置，PhysicsCfg 则选择物理管理器。

注册前应完成配置，之后将配置及其嵌套值视为只读。需要不同设置时，请创建新配置。

使用者释放绑定后，close_backend(backend) 会关闭注册表中与传入对象完全相同的资源，不进行配置比较。由 BackendCfg 描述的资源必须实现 close()；仅用于构造的普通配置保存的是 Python 管理的数据，无需提供释放方法。关闭失败时，注册项会保留以便重试。仿真销毁时，物理后端先使相机数据失效，然后依次关闭材质写入器、渲染器、可视化器和剩余原生资源，最后关闭舞台。

图像视图也使用同一注册表。ImageViewCfg 按声明的对象身份比较，因此初始设置相同的两个透视相机仍相互独立；窗口和录制器则通过显式共用同一声明来复用图像。

管理器和原生渲染器通过 backend 暴露其借用的资源。例如，sim.backend_manager.backend.model 可访问 Newton 仿真中已完成初始化的原生模型。关闭渲染器时，只释放其绑定，不关闭共享的原生资源。暴露原生句柄并不替代 SDP 数据传输。

克隆准备阶段会在原生初始化前解析各使用者配置所需的上下文。上下文派生自 ReplicateContext，其默认的 prepare(sim, routing) 保留已声明的路由。重写此方法可合并路由以共享同一种表示，并通过仿真注册表获取资源。例如，OV 包可将原生 OVPhysX 和 OVRTX 路由替换为单个 OVStage 路由。渲染器构造函数负责声明自身需求，不应决定其他使用者的克隆路径。对于场景构建后注册的独立使用者，准备阶段也会在重置前执行；物理后端就绪后注册的使用者，则在自身初始化前执行相同的准备步骤。

生成的克隆上下文会在计划分发前单独注册为 sim.clone_contexts[Context] = Context(...)。上下文负责应用计划，不拥有原生运行时资源。舞台填充、克隆执行及物理/渲染附加方式均遵循准备阶段的决定。

Newton 有两类生命周期不同的资源，它们并非两个可互换的后端：

ModelBuilder 持有可修改的构建数据。克隆时填充这些数据，传感器在模型最终构建完成之前声明需求；之后构建器仍保留，用于硬重置。 NewtonBuilderCfg 是普通构造配置，而不是 BackendCfg ，构建器无需原生 close() 操作。
NewtonBackend 持有最终构建完成的模型和原生缓冲区，物理与渲染使用方借用这些句柄。关闭它会释放运行时分配的资源，但不会关闭构建器。

两类资源使用相同的注册表：

builder_cfg = NewtonBuilderCfg(physics_cfg=sim.cfg.physics)
builder = sim.get_or_create_backend(builder_cfg)
# Clone/import populates this builder before model allocation.
model_cfg = NewtonBackendCfg(physics_cfg=sim.cfg.physics, device=sim.device)
backend = sim.get_or_create_backend(model_cfg)

两种配置均使用选定的物理配置；物理后端不是 Newton 时，则选用仅用于渲染的表示。 SimulationContext 没有特定后端专用的配置字段，使用方也不访问克隆上下文，而是直接通过 SDP 请求刚体变换和可视点。查询共享原生资源的 BVH，但各使用方捕获的计算工作相互独立。

可跨后端使用的资源与传感器接口#

资源和传感器采用与工厂相同的分层方式：

isaaclab 中的基类定义公共接口约定，例如 BaseArticulation 或 BaseContactSensor 。
工厂类同时继承 FactoryBase 和相应基类。
后端软件包提供受支持的具体实现。

传感器数据类也采用相同模式，例如 ContactSensorData(FactoryBase, BaseContactSensorData)。各实现通过公共资产和传感器数据属性提供 ProxyArray 值。每个代理封装底层 wp.array，通过 .warp 显式访问该数组，并通过 .torch 访问缓存的零拷贝 torch.Tensor 视图。API 明确要求某种表示形式时，请使用对应的访问器。将 ProxyArray 传给 wp.to_torch() 仅由已弃用的兼容层支持，新代码应使用 proxy_array.torch。后端原生接口和内部存储仍可能使用原始 Warp 数组。用法和缓冲区生命周期见使用 ProxyArray 。

可跨后端使用的渲染器与场景数据接口#

渲染器的选择独立于物理后端。通过 sim.get_or_create_backend(renderer_cfg) 获取符合 BaseRenderer 接口约定的实现。 RenderContext 通过注册表的过滤视图协调渲染生命周期，不另设渲染器缓存，也不持有渲染器所有权。它验证全局设置和注册时机，在物理就绪后初始化渲染器，并协调 USD 舞台准备、场景更新和材质写入器。渲染器选择与用法见渲染器。

物理管理器通过 SceneDataBackend 暴露实时仿真数据。仿真上下文持有的 SceneDataProvider 负责转换和重新映射数据，供不依赖具体后端的使用方消费：

physics manager -> SceneDataBackend -> SceneDataProvider -> renderer or visualizer

这一边界使渲染器和可视化器能够共用基于 Warp 的原生数据通路，而不必关心状态由哪个物理引擎持有。完整的数据流模型见场景数据提供器。

原生引擎访问边界#

可移植接口构成了稳定的 API 边界。高级代码也可使用各引擎的原生底层数据 API，但这些 API 保留各自的所有权和同步语义。相关说明见 PhysX 类型化视图、Newton 模型与状态数组和 OvPhysX 张量绑定后端指南。

设计原则#

按需加载： 后端模块仅在首次实例化时导入，既加快启动，也避免依赖未使用的后端。
已识别的后端键与路径约定： 核心选择器识别后端键后，模块路径遵循 isaaclab.X.Y 的结构。OvPhysX 映射为 isaaclab_ov.X.Y ；其他已识别后端默认使用 isaaclab_<backend>.X.Y 。
独立选择： 物理后端、渲染器和可视化器分别选择。
显式数据互操作： 公共资源和传感器数据属性返回 ProxyArray ；通过 .warp 和 .torch 访问所需的数组表示，无需复制。
无运行时额外开销： 实现在实例化时选定，不会在仿真频繁执行的路径中增加分派逻辑。

进一步阅读#

环境列出了环境及其支持的预设。
Hydra 配置系统介绍标量覆盖、预设编写、冲突处理和高级配置行为。
物理后端比较了物理后端的运行要求、求解器类型和适用场景。
渲染器介绍渲染器的选择与实现细节。