isaaclab.sim

Sub-package containing simulation-specific functionalities.

These include:

• Ability to spawn different objects and materials into Omniverse

• Define and modify various schemas on USD prims

• Converters to obtain USD file from other file formats (such as URDF, OBJ, STL, FBX)

• Utility class to control the simulator

Note

Currently, only a subset of all possible schemas and prims in Omniverse are supported. We are expanding the these set of functions on a need basis. In case, there are specific prims or schemas that you would like to include, please open an issue on GitHub as a feature request elaborating on the required application.

To make it convenient to use the module, we recommend importing the module as follows:

import isaaclab.sim as sim_utils

Submodules

converters	Sub-module containing converters for converting various file types to USD.
schemas	Sub-module containing utilities for schemas used in Omniverse.
spawners	Sub-module containing utilities for creating prims in Omniverse.
utils	Utilities built around USD operations.

Classes

SimulationContext	Controls simulation lifecycle including physics stepping and rendering.
SimulationCfg	Configuration for simulation physics.

Functions

simulation_context.build_simulation_context([...])

Context manager to build a simulation context with the provided settings.

Simulation Context

class isaaclab.sim.SimulationContext

Bases: object

Controls simulation lifecycle including physics stepping and rendering.

This singleton class manages:

• Physics configuration (time-step, solver parameters via isaaclab.sim.SimulationCfg)

• Simulation state (play, pause, step, stop)

• Rendering and visualization

The singleton instance can be accessed using the instance() class method.

Methods:

__new__(cls[, cfg])	Enforce singleton pattern.
instance()	Get the singleton instance, or None if not created.
__init__([cfg])	Initialize the simulation context.
has_active_visualizers()	Return whether any visualizer path is active for rendering/camera control.
is_headless_or_exist_active_visualizer()	Return whether the simulation should keep stepping without visualizers or with an active visualizer.
require_visual_shapes()	Record that something in this simulation draws the physics model's visual-only shapes.
can_render_rgb_array()	Return whether rgb-array rendering is currently available.
get_physics_dt()	Returns the physics time step.
get_physics_step_count()	Return the monotonic physics step counter (incremented each step()).
resolve_visualizer_types()	Resolve visualizer types from config or CLI settings.
initialize_visualizers()	Initialize visualizers from SimulationCfg.visualizer_cfgs.
register_interactive_scene(scene)	Register the active scene so scene data providers can expose scene-owned sensors.
get_scene_data_requirements()	Return scene-data requirements resolved from visualizers/renderers.
update_scene_data_requirements(requirements)	Update scene-data requirements.
get_clone_plan()	Return the clone plan published by the scene.
set_clone_plan(plan)	Set the cloner's clone plan.
get_rendering_dt()	Return rendering dt, allowing visualizer-specific override.
set_camera_view(eye, target)	Set camera view on all visualizers that support it.
add_render_callback(name, fn[, order])	Register a callback to fire after every render step.
remove_render_callback(name)	Unregister a previously registered render callback.
forward()	Update kinematics without stepping physics.
reset([soft])	Reset the simulation.
step([render])	Step physics and optionally render.
render([mode, skip_app_pumping])	Update visualizers and render the scene.
update_visualizers(dt[, skip_app_pumping])	Update visualizers without triggering renderer/GUI.
play()	Start or resume the simulation.
pause()	Pause the simulation (can be resumed with play).
stop()	Stop the simulation completely.
request_reset()	Request an episode reset from a UI control (e.g. the Kit window button).
consume_reset_request()	Return True if any visualizer or UI control requested an episode reset and clear the flag.
is_playing()	Returns True if simulation is playing (not paused or stopped).
is_stopped()	Returns True if simulation is stopped (not just paused).
set_setting(name, value)	Set a setting value.
get_setting(name)	Get a setting value.
clear_instance()	Clean up resources and clear the singleton instance.
clear_stage()	Clear the current USD stage (preserving /World and PhysicsScene).

Attributes:

physics_sim_view	Returns the physics simulation view.
device	Returns the device on which the simulation is running.
backend	Returns the tensor backend being used ("numpy" or "torch").
has_gui	Returns whether GUI is enabled (cached at init).
has_offscreen_render	Returns whether offscreen rendering is enabled (cached at init).
visual_shapes_required	Whether require_visual_shapes() was called for this simulation.
is_rendering	Returns whether continuous rendering is active (GUI, RTX sensors, visualizers, or XR).
render_context	Shared RenderContext for camera renderers.
render_generation	Returns a monotonic counter for render() executions.
visualizers	Returns the list of active visualizers.
services	Typed service registry for backend-specific singletons.

static __new__(cls, cfg: SimulationCfg | None = None)

Enforce singleton pattern.

classmethod instance() → SimulationContext | None

Get the singleton instance, or None if not created.

__init__(cfg: SimulationCfg | None = None)

Initialize the simulation context.

Parameters:

cfg – Simulation configuration. Defaults to None (uses default config).

property physics_sim_view

Returns the physics simulation view.

property device: str

Returns the device on which the simulation is running.

property backend: str

Returns the tensor backend being used (“numpy” or “torch”).

property has_gui: bool

Returns whether GUI is enabled (cached at init).

property has_offscreen_render: bool

Returns whether offscreen rendering is enabled (cached at init).

has_active_visualizers() → bool

Return whether any visualizer path is active for rendering/camera control.

is_headless_or_exist_active_visualizer() → bool

Return whether the simulation should keep stepping without visualizers or with an active visualizer.

require_visual_shapes() → None

Record that something in this simulation draws the physics model’s visual-only shapes.

Camera sensors call this from their constructor, before cloning runs, so backends that import visual geometry lazily (see isaaclab_newton.physics.NewtonCfg.load_visual_shapes) know the geometry is needed even when no viewer or offscreen capture is active.

property visual_shapes_required: bool

Whether require_visual_shapes() was called for this simulation.

can_render_rgb_array() → bool

Return whether rgb-array rendering is currently available.

property is_rendering: bool

Returns whether continuous rendering is active (GUI, RTX sensors, visualizers, or XR).

This drives the per-step render/Kit-pump loop, so it deliberately excludes headless offscreen rendering (--video / rgb_array). Offscreen frames are produced on demand when a frame is actually requested (via render()), not on every step; see has_offscreen_render() and can_render_rgb_array() for the capability checks.

get_physics_dt() → float

Returns the physics time step.

get_physics_step_count() → int

Return the monotonic physics step counter (incremented each step()).

property render_context: RenderContext

Shared RenderContext for camera renderers.

property render_generation: int

Returns a monotonic counter for render() executions.

resolve_visualizer_types() → list[str]

Resolve visualizer types from config or CLI settings.

initialize_visualizers() → None

Initialize visualizers from SimulationCfg.visualizer_cfgs.

register_interactive_scene(scene) → None

Register the active scene so scene data providers can expose scene-owned sensors.

get_scene_data_requirements() → SceneDataRequirement

Return scene-data requirements resolved from visualizers/renderers.

update_scene_data_requirements(requirements: SceneDataRequirement) → None

Update scene-data requirements.

get_clone_plan() → ClonePlan | None

Return the clone plan published by the scene.

Set after replication. Consumed by scene data providers that build backend models (e.g. Newton visualizer model on a PhysX backend) from the same plan the cloner used. None until the scene replicates.

set_clone_plan(plan: ClonePlan | None) → None

Set the cloner’s clone plan.

property visualizers: list[BaseVisualizer]

Returns the list of active visualizers.

get_rendering_dt() → float

Return rendering dt, allowing visualizer-specific override.

set_camera_view(eye: tuple, target: tuple) → None

Set camera view on all visualizers that support it.

add_render_callback(name: str, fn: Callable[[Any], None], order: int = 0) → None

Register a callback to fire after every render step.

Parameters:

• name – Unique identifier. Silently replaces any existing callback with the same name.

• fn – Callable invoked with a single None argument after each render() call.

• order – Execution order relative to other callbacks. Lower values fire first.

remove_render_callback(name: str) → None

Unregister a previously registered render callback.

Parameters:

name – Identifier passed to add_render_callback(). No-op if not found.

forward() → None

Update kinematics without stepping physics.

reset(soft: bool = False) → None

Reset the simulation.

Parameters:

soft – If True, skip full reinitialization.

step(render: bool = True) → None

Step physics and optionally render.

If the timeline is paused (e.g. via the GUI), this method blocks and keeps the visualizer responsive until the timeline is resumed or stopped.

Parameters:

render – Whether to render the scene after stepping. Defaults to True.

render(mode: int | None = None, skip_app_pumping: bool = False) → None

Update visualizers and render the scene.

Calls update_visualizers() so visualizers run at the render cadence (not at every physics step). Camera sensors drive their configured renderer when fetching data. Physics-backend recording hooks (e.g. Kit/RTX headless video pump) fire through add_render_callback() so they are not hard-coded in this class.

Kit vs. standalone visualizers: The Kit app loop (app.update()) is the only way to drive camera/RTX sensor rendering and viewport GUI updates; it cannot be split into “cameras only” and “GUI only”. Standalone visualizers (Newton, Rerun, Viser) have self-contained step() methods that never call app.update(), so they can run independently of camera rendering. The skip_app_pumping flag exploits this distinction: when True, Kit is skipped while standalone visualizers continue to update.

Parameters:

• mode – Unused. Kept for backward compatibility.

• skip_app_pumping – When True, skip visualizers whose pumps_app_update() returns True (e.g. KitVisualizer). This disables the Kit app loop and camera updates while still stepping standalone visualizers (Newton, Rerun, Viser). Used by environment step() when render_enabled is False.

update_visualizers(dt: float, skip_app_pumping: bool = False) → None

Update visualizers without triggering renderer/GUI.

Parameters:

• dt – Simulation time-step in seconds.

• skip_app_pumping – When True, skip visualizers whose pumps_app_update() returns True (e.g. KitVisualizer). This is used when the environment’s render_enabled flag is False — cameras and the Kit app loop are skipped, but standalone visualizers (Newton, Rerun, Viser) still receive updates.

play() → None

Start or resume the simulation.

pause() → None

Pause the simulation (can be resumed with play).

stop() → None

Stop the simulation completely.

request_reset() → None

Request an episode reset from a UI control (e.g. the Kit window button).

The request is consumed on the next call to consume_reset_request().

consume_reset_request() → bool

Return True if any visualizer or UI control requested an episode reset and clear the flag.

Checks both the simulation-context-level flag (set by request_reset()) and each visualizer’s own flag. All flags are cleared atomically so a single reset is triggered even when multiple sources fire in the same step.

Returns:

True once when a reset was requested, then False until the next request.

is_playing() → bool

Returns True if simulation is playing (not paused or stopped).

is_stopped() → bool

Returns True if simulation is stopped (not just paused).

set_setting(name: str, value: Any) → None

Set a setting value.

get_setting(name: str) → Any

Get a setting value.

property services: ServiceLocator

Typed service registry for backend-specific singletons.

Usage:

sim_context.services[FabricStageCache] = cache
cache = sim_context.services[FabricStageCache]
del sim_context.services[FabricStageCache]  # closes and removes

classmethod clear_instance() → None

Clean up resources and clear the singleton instance.

classmethod clear_stage() → None

Clear the current USD stage (preserving /World and PhysicsScene).

Uses a predicate that preserves /World and PhysicsScene while also respecting the default deletability checks (ancestral prims, etc.).

Simulation Configuration

class isaaclab.sim.SimulationCfg

Bases: object

Configuration for simulation physics.

This class contains the main simulation parameters including physics time-step, gravity, device settings, and physics backend configuration.

Attributes:

device	The device to run the simulation on.
dt	The physics simulation time-step (in seconds).
gravity	The gravity vector (in m/s^2).
physics_prim_path	The prim path where the USD PhysicsScene is created.
physics_material	Default physics material settings for rigid bodies.
use_fabric	Enable/disable reading of physics buffers directly.
render_interval	The number of physics simulation steps per rendering step.
enable_scene_query_support	Enable/disable scene query support for collision shapes.
use_newton_actuators	Use Newton-native actuators instead of IsaacLab explicit actuator models.
physics	Physics manager configuration.
create_stage_in_memory	If stage is first created in memory.
logging_level	The logging level.
save_logs_to_file	Save logs to a file.
log_dir	The directory to save the logs to.
visualizer_cfgs	The visualizer configuration(s).
default_visualizer_cfg	Default visualizer camera hint applied to any visualizer that is selected at runtime.

device: str

The device to run the simulation on. Default is "cuda:0".

Valid options are:

• "cpu": Use CPU.

• "cuda": Use GPU, where the device ID is inferred from AppLauncher’s config.

• "cuda:N": Use GPU, where N is the device ID. For example, “cuda:0”.

dt: float

The physics simulation time-step (in seconds). Default is 0.0167 seconds.

gravity: tuple[float, float, float]

The gravity vector (in m/s^2). Default is (0.0, 0.0, -9.81).

physics_prim_path: str

The prim path where the USD PhysicsScene is created. Default is “/physicsScene”.

physics_material: RigidBodyMaterialBaseCfg

Default physics material settings for rigid bodies. Default is RigidBodyMaterialBaseCfg.

The physics engine defaults to this physics material for all the rigid body prims that do not have any physics material specified on them.

The material is created at the path: {physics_prim_path}/defaultMaterial.

use_fabric: bool

Enable/disable reading of physics buffers directly. Default is True.

When running the simulation, updates in the states in the scene is normally synchronized with USD. This leads to an overhead in reading the data and does not scale well with massive parallelization. This flag allows disabling the synchronization and reading the data directly from the physics buffers.

It is recommended to set this flag to True when running the simulation with a large number of primitives in the scene.

render_interval: int

The number of physics simulation steps per rendering step. Default is 1.

enable_scene_query_support: bool

Enable/disable scene query support for collision shapes. Default is False.

This flag allows performing collision queries (raycasts, sweeps, and overlaps) on actors and attached shapes in the scene. This is useful for implementing custom collision detection logic outside of the physics engine.

If set to False, the physics engine does not create the scene query manager and the scene query functionality will not be available. However, this provides some performance speed-up.

Note

This flag is overridden to True inside the SimulationContext class when running the simulation with the GUI enabled. This is to allow certain GUI features to work properly.

use_newton_actuators: bool

Use Newton-native actuators instead of IsaacLab explicit actuator models.

When True, explicit actuator configs (e.g. IdealPDActuatorCfg, DCMotorCfg) are translated into NewtonActuator USD prims and stepped by the physics engine. The Lab config values (stiffness, damping, effort_limit, etc.) take precedence: for every joint covered by a Lab actuator config, any existing NewtonActuator prim targeting that joint is replaced by one synthesised from the config. Joints that are not covered by a Lab config keep their USD-authored actuators (if any).

ImplicitActuatorCfg entries are still instantiated normally and their gains are written to the simulation, so joints that use implicit actuation continue to work as expected.

physics: PhysicsCfg | None

Physics manager configuration. Default is None (uses PhysxCfg()).

This configuration determines which physics manager to use. Override with a different config (e.g., NewtonManagerCfg) to use a different physics backend.

create_stage_in_memory: bool

If stage is first created in memory. Default is False.

Creating the stage in memory can reduce start-up time.

logging_level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']

The logging level. Default is “WARNING”.

save_logs_to_file: bool

Save logs to a file. Default is True.

log_dir: str | None

The directory to save the logs to. Default is None.

If save_logs_to_file is True, the logs will be saved to the directory specified by log_dir. If None, the logs will be saved to the temp directory.

visualizer_cfgs: list[VisualizerCfg] | VisualizerCfg

The visualizer configuration(s). Default is an empty list.

default_visualizer_cfg: VisualizerCfg | None

Default visualizer camera hint applied to any visualizer that is selected at runtime.

This is a hint only — it does not add a visualizer to visualizer_cfgs. Fields such as eye and lookat are forwarded to each resolved visualizer unless that visualizer already has an explicitly customised value.

Simulation Context Builder

simulation_context.build_simulation_context(gravity_enabled: bool = True, device: str | None = None, dt: float = 0.01, sim_cfg: SimulationCfg | None = None, add_ground_plane: bool = False, add_lighting: bool = False, auto_add_lighting: bool = False, visualizers: list[str] | None = None) → Iterator[SimulationContext]

Context manager to build a simulation context with the provided settings.

Parameters:

• create_new_stage – Whether to create a new stage. Defaults to True.

• gravity_enabled – Whether to enable gravity. Defaults to True.

• device – Device to run the simulation on. When given alongside sim_cfg, overrides sim_cfg.device so the caller’s explicit choice wins (most test callers pass both, expecting this behavior). Defaults to None, meaning sim_cfg.device is left untouched and a freshly built sim_cfg uses SimulationCfg’s default device.

• dt – Time step for the simulation. Defaults to 0.01.

• sim_cfg – SimulationCfg to use. Defaults to None.

• add_ground_plane – Whether to add a ground plane. Defaults to False.

• add_lighting – Whether to add a dome light. Defaults to False.

• auto_add_lighting – Whether to auto-add lighting if GUI present. Defaults to False.

• visualizers – List of visualizer backend keys to enable (e.g. ["kit", "newton_gl", "rerun"]). Valid types: "kit", "newton_gl", "newton_rtx", "rerun", "viser". "newton" is a deprecated alias for "newton_gl". When provided, sets the /isaaclab/visualizer/types setting so the existing visualizer resolution machinery picks them up. Defaults to None.

Yields:

The simulation context to use for the simulation.