embodichain.lab.sim.sim_manager

Overview

SimulationManager is the central handle around the DexSim scene. It owns the physics world and the object/sensor registry, drives the simulation step, owns its profiler, and exposes capture hooks and visualization configuration. Downstream components (environments, planners, IK solvers, the visualization runtime) look up the active manager through its class-level instance registry instead of passing it around explicitly.

Native entity interaction defaults on when the first native window opens. Set SimulationManagerCfg(enable_entity_gizmo=False) to opt out, or call sim.disable_entity_gizmo() at runtime. Explicit enable/disable calls and custom DexSim controller settings survive window close/reopen. Pure headless and Viser runs do not automatically create native gizmos.

SimulationManagerCfg.robot_ik_gizmo defaults to GizmoCfg() and registers robot control parts with configured IK-chain/TCP metadata during normal updates. Native IK activates on the first I press by default; Viser constructs its solver on the first drag and requires visualization.allow_commands. Registration does not write drive targets. Set this field to None to opt out or select GizmoCfg(ik_solver="embodichain") to reuse configured solvers. Explicit enable_gizmo() settings override automatic defaults, and disable_gizmo() prevents automatic recreation. GizmoCfg(ik_start_enabled=True) activates native IK on the first update with an open window, as used by the robot tutorial.

Physics and visual consumption

State-only headless stepping does not publish Newton state to the renderer. An open native window, camera groups, due recording and due Viser captures request publication when they consume state. render_frame() shares that publication within one read-only consumption phase. Gym arranges this phase after physics and interval events automatically. Standalone callers combining camera observations with recording or Viser can use:

sim.update(physics_dt, step=1, render_final_step=False)
# Complete direct state edits before entering the read-only frame.
with sim.render_frame():
    sim.render_camera_group(camera_group_ids)
    # Due recording and Viser captures run on context exit.

The phase never advances physics and never caches publication across frames. Independent camera/capture calls request fresh publication. If state changes inside a frame, call sync_render_state() explicitly before further reads. Opening a window and rendering while paused also request publication. Native render-thread recording consumes already-published state without invoking the blocking physics-to-render bridge from that thread.

Classes

SimulationManager	Global Embodied AI simulation manager.
SimulationManagerCfg	Global robot simulation configuration.
get_physics_scene([instance_id])	Return the active physics scene from a SimulationManager instance.

class embodichain.lab.sim.sim_manager.SimulationManager

Bases: object

Global Embodied AI simulation manager.

This class is used to manage the global simulation environment and simulated assets.

• assets loading, creation, modification and deletion.

  • assets include rigid objects, soft objects, articulations, robots, sensors and lights.

• manager the scenes and the simulation environment.

  • parallel scenes simulation on both CPU and GPU.

  • create and setup the rendering related settings, eg. environment map, lighting, materials, etc.

  • physics simulation management, including time steps and explicit stepping.

  • interactive control via gizmo and window callbacks events.

Parameters:

• sim_config (SimulationManagerCfg, optional) – simulation configuration. Defaults to SimulationManagerCfg().

• defer_startup_summary (bool) – Let an owning environment emit one combined table after task and manager initialization. Standalone callers keep False.

• requires_native_renderer (bool | None) – Predeclared native render demand. False permits auto to select NoRender; None preserves standalone GPU selection. Windows, Viser, forced synchronization and renderer overrides retain precedence. The renderer is fixed before the World is constructed.

Attributes:

SUPPORTED_SENSOR_TYPES
arena_offsets	Get the arena offsets for all arenas.
asset_uids	Get all assets uid in the simulation.
differentiable_runtime	Return the differentiable facade over the Spawn-owned Newton runtime.
has_native_renderer	Whether the World owns a native renderer and visual resources.
is_default_backend	Whether the Default physics backend is active.
is_newton_backend	Whether the Newton physics backend is active.
is_physics_manually_update
is_use_gpu_physics	Whether the active physics backend is running on GPU.
newton_manager	Compatibility accessor for the removed NewtonManager API.
num_envs	Get the number of arenas in the simulation.
physics_backend	Return the active physics backend name.
spawn_result	Return the finalized Scene, or None before first prepare.
visualization_health	Return current visualization service and client health.
visualization_overlays	Return the overlays included in every Viser scene frame.
visualization_runtime	Return the active visualization runtime, if one has been started.
visualization_stats	Return visualization telemetry, or None before startup.

Methods:

__init__([sim_config, render_cfg, dlss, ...])	Construct the simulation World with a fixed renderer selection.
__new__(cls[, sim_config, render_cfg, dlss, ...])	Create or return the instance based on instance_id.
add_articulation(cfg)	Add an articulation to the scene.
add_custom_window_control(controls)	Add one or more custom window input controls.
add_deformable_object(cfg)	Declare a volume or surface deformable in the scene.
add_light(cfg)	Create a light in the scene.
add_rigid_object(cfg)	Add a rigid object to the scene.
add_rigid_object_group(cfg)	Add a rigid object group to the scene.
add_robot(cfg)	Add a Robot to the scene.
add_sensor(sensor_cfg)	Create a sensor on the pre-created simulation Arenas.
add_usd(name, file_path, *[, pose, robot_cfgs])	Declare the supported entities in a USD scene.
add_visual_object(cfg)	Declare a render-only mesh or primitive, without physics or colliders.
can_open_native_window()	Return whether the native DexSim window may be opened.
capture_visualization([force, ...])	Capture current scene data for the configured visualizer.
capture_visualization_safely([force, ...])	Update visualization without allowing failures to stop simulation.
clean_materials()	Clear runtime wrappers and ask the native owner to release unused materials.
close_window()	Close the simulation window.
create_rigid_constraint(cfg[, env_ids])	Create a fixed constraint between two rigid objects.
create_visual_material(cfg)	Create a visual material with given configuration.
destroy([exit_process])	No longer destructs C++ objects in place due to lingering deep local variables; instead, packages itself into a destruction task, submits to the cleanup queue, and waits for top-level delayed consumption.
disable_entity_gizmo()	Disable native object interaction, including future window opens.
disable_gizmo(uid[, control_part])	Disable a Gizmo and prevent its automatic recreation.
draw_marker(cfg)	Draw visual markers in the simulation scene for debugging and visualization.
enable_entity_gizmo([config])	Enable DexSim entity control and exclude the EmbodiChain ground.
enable_gizmo(uid[, control_part, gizmo_cfg])	Register Gizmo control for a simulation target.
enable_physics(enable)	Enable or disable physics simulation.
enable_window_camera_pose_hotkey([...])	Register p to print the current viewer camera pose.
enable_window_record_hotkey([save_path, ...])	Register the r key to start/stop viewer recording.
export_usd(fpath)	Export the current simulation scene to a USD file.
finalize_newton_physics()	Prepare the Spawn-owned physics runtime.
flush_cleanup_queue()	Run pending destruction tasks and wait for their scenes to disappear.
get_articulation(uid)	Get an articulation by its unique ID.
get_articulation_uid_list()	Get current articulation uid list
get_asset(uid)	Get an asset by its UID.
get_axis_marker_items()	Return active axes for backend-neutral visualization.
get_deformable_object(uid)	Get a deformable object by its unique ID.
get_deformable_object_uid_list()	Return all deformable object UIDs in declaration order.
get_env([arena_index])	Get the arena or env by index.
get_gizmo(uid[, control_part])	Return an active Gizmo.
get_gizmo_items()	Return a stable snapshot of active Gizmo IDs and controllers.
get_instance([instance_id])	Get the instance of SimulationManager by id.
get_instance_num()	Get the number of instantiated SimulationManager instances.
get_light(uid)	Get a light by its UID.
get_light_uid_list()	Get current light uid list
get_physics_scene()	Return the Default backend's compatibility scene after Spawn preparation.
get_rigid_constraint(name)	Get a rigid constraint by its base name.
get_rigid_constraint_uid_list()	Get the list of registered constraint base names.
get_rigid_object(uid)	Get a rigid object by its unique ID.
get_rigid_object_group(uid)	Get a rigid object group by its unique ID.
get_rigid_object_group_uid_list()	Get current rigid body group uid list
get_rigid_object_uid_list()	Get current rigid body uid list
get_robot(uid)	Get a Robot by its unique ID.
get_robot_uid_list()	Retrieves a list of unique identifiers (UIDs) for all robots in the simulation system.
get_sensor(uid)	Get a sensor by its UID.
get_sensor_uid_list()	Get current sensor uid list
get_texture_cache([key])	Get the texture from the global texture cache.
get_visual_material(uid)	Get visual material by UID.
get_visual_object(uid)	Find a registered render-only object.
get_visual_object_uid_list()	Return the registered render-only object identifiers.
get_world()
has_gizmo(uid[, control_part])	Check if a gizmo exists for the given UID and control part.
has_non_static_rigid_object()	Check if there is any non-static rigid object in the simulation.
init_gpu_physics()	Prepare the Spawn-owned physics runtime.
is_instantiated([instance_id])	Check if the instance has been created.
is_window_recording()	Check whether the viewer window is currently recording.
list_gizmos()	List active Gizmo IDs and availability.
notify_visualization_topology_changed()	Mark scene topology dirty and return its new local revision.
open_window()	Open the native DexSim simulation window when allowed.
prepare()	Materialize declarations, bind state, and restore camera parents.
print_window_camera_pose([convert_to_look_at])	Print the current viewer camera pose as reusable Python code.
process_pick_commands()	Apply queued Viser click-pick commands on the simulation thread.
process_visualization_commands()	Apply queued Viser Gizmo commands on the simulation thread.
refresh_visualization()	Publish current scene topology when Viser is active.
remove_asset(uid)	Remove an asset by its UID.
remove_marker(name)	Remove markers (including axis) with the given name.
remove_rigid_constraint(name[, env_ids])	Remove a rigid constraint by name.
render_camera_group(group_ids)	Synchronize physics state and render camera groups.
render_frame(*[, force_visualization, ...])	Share one state publication across the frame's visual consumers.
replace_rigid_object(cfg)	Replace a rigid object with the same UID in one preparation.
replace_rigid_objects(cfgs)	Replace multiple existing rigid objects in one preparation.
reset([instance_id])	Reset the instance.
reset_objects_state([env_ids, ...])	Reset the state of the simulated assets given the environment IDs and excluded UIDs.
set_default_background()	Set default background.
set_default_global_lighting()	Set default global lighting for the scene.
set_default_renderer([renderer, gpu_id])	Set the global default renderer used by new simulations.
set_emission_light([color, intensity])	Set environment emission light.
set_gizmo_visibility(uid, visible[, ...])	Set Gizmo visibility by target UID and optional control part.
set_ground_plane_visibility(visible)	Set native ground rendering visibility while preserving collisions.
set_indirect_lighting(name)	Set indirect lighting.
set_texture_cache(key, texture)	Set the texture to the global texture cache.
set_visualization_overlays(overlays)	Set persistent overlays for automatic Viser captures.
start_visualization()	Start the configured live visualizer and publish the current scene.
start_window_record([save_path, fps, ...])	Start asynchronously recording the simulation to a video buffer.
stop_visualization()	Stop the visualization server and release its worker thread.
stop_window_record([save_path])	Stop the active viewer recording and save frames in the background.
sync_render_state()	Publish current physics state to render resources without stepping.
toggle_gizmo_visibility(uid[, control_part])	Toggle Gizmo visibility and return the new state, if it exists.
toggle_window_record([save_path, fps, ...])	Toggle viewer recording on or off.
update([physics_dt, step, after_substep, ...])	Advance physics explicitly and publish the resulting simulation state.
update_gizmos()	Register robot controls, process interaction, and update active Gizmos.
wait_scene_destruction([timeout_ms])	A public helper to wait for the underlying C++ scenes (dexsim.World) to destruct completely.
wait_window_record_saves()	Wait for all background video export threads to finish.

SUPPORTED_SENSOR_TYPES = {'Camera': <class 'embodichain.lab.sim.sensors.camera.Camera'>, 'ContactSensor': <class 'embodichain.lab.sim.sensors.contact_sensor.ContactSensor'>, 'StereoCamera': <class 'embodichain.lab.sim.sensors.stereo.StereoCamera'>}

__init__(sim_config=SimulationManagerCfg(width=1920, startup_summary='compact', dexsim_startup_info=False, scene_node_capacity=None, height=1080, headless=False, enable_entity_gizmo=True, robot_ik_gizmo=GizmoCfg(axis_length_x=0.2, axis_length_y=0.2, axis_length_z=0.2, axis_size=0.01, rings_radius=0.15, rings_size=0.01, ik_solver='dexsim', ik_root_link_name=None, ik_end_link_name=None, ik_tcp_pose=None, ik_iterations=24, ik_device=None, ik_gizmo_scale=1.5, ik_toggle_key=<InputKey.SCANCODE_I: 12>, ik_start_enabled=False), render_cfg=RenderCfg(renderer='auto', spp=1, denoising=DenoisingCfg(window='dlss', offscreen='dlss'), dlss=DLSSCfg(dlss_quality=2, upsample_ratio=None, render_width=0, render_height=0, target_width=0, target_height=0, tiled_enabled=True, exposure_compensation=1.0), nrd=NRDCfg(max_indirect_bounces=1, denoising_range=500000.0, disocclusion_threshold=0.01, disocclusion_threshold_alternate=0.05, disocclusion_threshold_mix_enabled=True, history_confidence_enabled=True, history_confidence_probe_stride=5, history_confidence_sigma_scale=2.0, history_confidence_sensitivity=1.0, max_accumulated_frame_num=30, max_fast_accumulated_frame_num=6, history_fix_frame_num=3, diffuse_prepass_blur_radius=30.0, specular_prepass_blur_radius=50.0, anti_firefly_enabled=False, sh_mode_enabled=False, validation_enabled=False, max_stabilized_frame_num=63, min_blur_radius=1.0, max_blur_radius=30.0, antilag_luminance_sigma_scale=2.0, antilag_luminance_sensitivity=3.0, taa_min_current_weight=0.0625, taa_sigma_scale=2.0, taa_depth_rejection_enabled=True, taa_tone_mapping_enabled=False), tone_mapping_enabled=False, tone_mapping_exposure=1.0, min_bounces=4, max_bounces=8), gpu_id=0, thread_mode=<ThreadMode.RENDER_SHARE_ENGINE: 0>, cpu_num=1, num_envs=1, arena_space=5.0, physics_cfg=DefaultPhysicsCfg(physics_dt=0.01, device='cpu', gravity=array([ 0.  ,  0.  , -9.81]), cache_material=False, bounce_threshold=2.0, enable_ccd=False, length_tolerance=0.05, speed_tolerance=0.25, gpu_memory=GPUMemoryCfg(temp_buffer_capacity=16777216, max_rigid_contact_count=524288, max_rigid_patch_count=262144, heap_capacity=67108864, found_lost_pairs_capacity=33554432, found_lost_aggregate_pairs_capacity=1024, total_aggregate_pairs_capacity=1024)), profiler=None, window_record=WindowRecordCfg(enable_hotkey=True, save_path=None, fps=20, max_memory=1024, video_prefix='viewer_record'), window_camera_pose=WindowCameraPoseCfg(enable_hotkey=True, convert_to_look_at=True), visualization=VisualizationCfg(backend='none', scene_fps=15.0, env_ids=[0], max_visible_envs=None, point_cloud_max_points=100000, sensor_image_fps=2.0, soft_body_fps=5.0, allow_commands=False, viser_server=ViserServerCfg(host='127.0.0.1', port=8080, label='EmbodiChain', verbose=False))), *, defer_startup_summary=False, requires_native_renderer=None)

Construct the simulation World with a fixed renderer selection.

Failed construction queues cleanup for its owned World without exiting the process. Flush the cleanup queue after constructor frames unwind. Failures before World creation remove only their own registry entry.

Parameters:

• sim_config (SimulationManagerCfg) – Simulation, physics and rendering configuration.

• defer_startup_summary (bool) – Let the owning environment emit the summary.

• requires_native_renderer (bool | None) – Predeclared render demand. False allows auto to select NoRender when there are no window, browser or forced-sync consumers. None preserves standalone GPU-based selection. Explicit and global renderer overrides take precedence.

static __new__(cls, sim_config=SimulationManagerCfg(width=1920, startup_summary='compact', dexsim_startup_info=False, scene_node_capacity=None, height=1080, headless=False, enable_entity_gizmo=True, robot_ik_gizmo=GizmoCfg(axis_length_x=0.2, axis_length_y=0.2, axis_length_z=0.2, axis_size=0.01, rings_radius=0.15, rings_size=0.01, ik_solver='dexsim', ik_root_link_name=None, ik_end_link_name=None, ik_tcp_pose=None, ik_iterations=24, ik_device=None, ik_gizmo_scale=1.5, ik_toggle_key=<InputKey.SCANCODE_I: 12>, ik_start_enabled=False), render_cfg=RenderCfg(renderer='auto', spp=1, denoising=DenoisingCfg(window='dlss', offscreen='dlss'), dlss=DLSSCfg(dlss_quality=2, upsample_ratio=None, render_width=0, render_height=0, target_width=0, target_height=0, tiled_enabled=True, exposure_compensation=1.0), nrd=NRDCfg(max_indirect_bounces=1, denoising_range=500000.0, disocclusion_threshold=0.01, disocclusion_threshold_alternate=0.05, disocclusion_threshold_mix_enabled=True, history_confidence_enabled=True, history_confidence_probe_stride=5, history_confidence_sigma_scale=2.0, history_confidence_sensitivity=1.0, max_accumulated_frame_num=30, max_fast_accumulated_frame_num=6, history_fix_frame_num=3, diffuse_prepass_blur_radius=30.0, specular_prepass_blur_radius=50.0, anti_firefly_enabled=False, sh_mode_enabled=False, validation_enabled=False, max_stabilized_frame_num=63, min_blur_radius=1.0, max_blur_radius=30.0, antilag_luminance_sigma_scale=2.0, antilag_luminance_sensitivity=3.0, taa_min_current_weight=0.0625, taa_sigma_scale=2.0, taa_depth_rejection_enabled=True, taa_tone_mapping_enabled=False), tone_mapping_enabled=False, tone_mapping_exposure=1.0, min_bounces=4, max_bounces=8), gpu_id=0, thread_mode=<ThreadMode.RENDER_SHARE_ENGINE: 0>, cpu_num=1, num_envs=1, arena_space=5.0, physics_cfg=DefaultPhysicsCfg(physics_dt=0.01, device='cpu', gravity=array([ 0.  ,  0.  , -9.81]), cache_material=False, bounce_threshold=2.0, enable_ccd=False, length_tolerance=0.05, speed_tolerance=0.25, gpu_memory=GPUMemoryCfg(temp_buffer_capacity=16777216, max_rigid_contact_count=524288, max_rigid_patch_count=262144, heap_capacity=67108864, found_lost_pairs_capacity=33554432, found_lost_aggregate_pairs_capacity=1024, total_aggregate_pairs_capacity=1024)), profiler=None, window_record=WindowRecordCfg(enable_hotkey=True, save_path=None, fps=20, max_memory=1024, video_prefix='viewer_record'), window_camera_pose=WindowCameraPoseCfg(enable_hotkey=True, convert_to_look_at=True), visualization=VisualizationCfg(backend='none', scene_fps=15.0, env_ids=[0], max_visible_envs=None, point_cloud_max_points=100000, sensor_image_fps=2.0, soft_body_fps=5.0, allow_commands=False, viser_server=ViserServerCfg(host='127.0.0.1', port=8080, label='EmbodiChain', verbose=False))), *, defer_startup_summary=False, requires_native_renderer=None)

Create or return the instance based on instance_id.

add_articulation(cfg)

Add an articulation to the scene.

Parameters:

cfg (ArticulationCfg) – Configuration for the articulation.

Returns:

The added articulation instance handle.

Return type:

Articulation

add_custom_window_control(controls)

Add one or more custom window input controls.

This method registers additional ObjectManipulator instances with the simulation window so they can handle input events alongside any default controls.

Parameters:

controls (list[ObjectManipulator]) – A list of initialized ObjectManipulator instances to add to the current window. Each control will be registered via window.add_input_control. If no window is available, the controls are not added and a warning is logged.

Return type:

None

add_deformable_object(cfg)

Declare a volume or surface deformable in the scene.

Deformables are DexSim 0.5 typed particle sets owned by the Newton Spawn scene. The Default backend is intentionally unsupported.

Parameters:

cfg (DeformableObjectCfg) – Volume- or surface-deformable configuration.

Return type:

DeformableObject

Returns:

The declared deformable facade.

Raises:

• NotImplementedError – If the active backend or device cannot host the requested deformable type.

• ValueError – If the discriminator or UID is invalid.

add_light(cfg)

Create a light in the scene.

Supports six light types: "point", "sun", "direction", "spot", "rect", and "mesh". See LightCfg for type-specific configuration fields.

Attention

"sun" and "direction" lights are global scene lights (infinite-distance directional light sources). They are created as a single instance on the root environment, not batched per environment. All other types are created as per-environment batched lights.

Parameters:

cfg (LightCfg) – Configuration for the light, including type, color, intensity, and type-specific properties.

Returns:

The created light instance.

Return type:

Light

Raises:

ValueError – If cfg.light_type is not supported.

add_rigid_object(cfg)

Add a rigid object to the scene.

Parameters:

cfg (RigidObjectCfg) – Configuration for the rigid object.

Returns:

The added rigid object instance handle.

Return type:

RigidObject

add_rigid_object_group(cfg)

Add a rigid object group to the scene.

Parameters:

cfg (RigidObjectGroupCfg) – Configuration for the rigid object group.

Return type:

RigidObjectGroup

Returns:

The stable Group facade. During initial scene construction it is bound to Spawn handles by prepare().

add_robot(cfg)

Add a Robot to the scene.

Parameters:

cfg (RobotCfg | RobotPresetCfg) – A concrete robot configuration or a replace-only backend preset. Presets are resolved from physics_cfg before the robot is declared. Mounted cameras are created only when cfg.enable_sensor is True and attach during preparation.

Returns:

The added robot instance handle, or None if failed.

Return type:

Robot | None

add_sensor(sensor_cfg)

Create a sensor on the pre-created simulation Arenas.

Cameras keep EmbodiChain’s native CameraGroup implementation. A camera attached to an articulation link is created immediately and attached after the physical Spawn scene is prepared. Contact sensors are created after preparation and query contacts through the backend-neutral Spawn Scene API.

Parameters:

sensor_cfg (SensorCfg) – configuration for the sensor.

Returns:

The added sensor instance handle.

Return type:

BaseSensor

add_usd(name, file_path, *, pose=None, robot_cfgs=None)

Declare the supported entities in a USD scene.

The returned facades are keyed by their USD prim paths. They remain in declared state until prepare() finalizes the shared Spawn scene, then bind in place to the resulting DexSim handles.

Objects without physics or collision geometry become VisualObjects. Conflicting render-only names receive a name_ prefix; dictionary keys retain their original USD prim paths. Other UID conflicts fail before native declarations.

USD does not identify which articulations should expose EmbodiChain’s robot interface. Pass those explicitly through robot_cfgs; all other articulation descriptions become Articulation objects.

Parameters:

• name (str) – Name passed to DexSim’s USD scene parser.

• file_path (str) – USD, USDA, USDC, or USDZ file path.

• pose (ndarray | None) – Optional scene-root transform.

• robot_cfgs (dict[str, RobotCfg] | None) – Robot configurations keyed by USD prim path. These provide robot-side metadata while physics remains authored by the USD scene.

Return type:

dict[str, VisualObject | RigidObject | Articulation | Robot]

Returns:

Supported EmbodiChain facades keyed by USD prim path.

Raises:

RuntimeError – If called after the Spawn scene was finalized.

add_visual_object(cfg)

Declare a render-only mesh or primitive, without physics or colliders.

Parameters:

cfg (VisualObjectCfg) – Appearance and initial state. source=UsdSourceCfg(...) selects a source USD object; only its appearance is imported.

Return type:

VisualObject

Returns:

The declared facade, bound after prepare().

property arena_offsets: Tensor

Get the arena offsets for all arenas.

Returns:

The arena offsets of shape (num_arenas, 3).

Return type:

torch.Tensor

property asset_uids: List[str]

Get all assets uid in the simulation.

The assets include lights, sensors, visual objects, robots, rigid objects and articulations.

Returns:

list of all assets uid.

Return type:

List[str]

can_open_native_window()

Return whether the native DexSim window may be opened.

The Viser backend owns visualization while it is configured or running, so a native window must not be opened for the same simulation.

Return type:

bool

Returns:

True unless the Viser backend is configured or running.

capture_visualization(force=False, *, capture_camera_images=True)

Capture current scene data for the configured visualizer.

Parameters:

• force (bool) – Whether to bypass visualization frame-rate limiting.

• capture_camera_images (bool) – Whether camera images may be captured.

Return type:

bool

Returns:

Whether scene or camera data was captured.

capture_visualization_safely(force=False, *, capture_camera_images=True)

Update visualization without allowing failures to stop simulation.

The first visualization failure is logged and subsequent captures are skipped until the runtime is restarted.

Parameters:

• force (bool) – Whether to bypass visualization frame-rate limiting.

• capture_camera_images (bool) – Whether camera images may be captured.

Return type:

None

clean_materials()

Clear runtime wrappers and ask the native owner to release unused materials.

Explicit material definitions remain reserved in the Scene for the World lifetime. Cleaning does not permit a conflicting definition to replace a UID that declarations or live native handles may still reference.

Return type:

None

close_window()

Close the simulation window.

Return type:

None

create_rigid_constraint(cfg, env_ids=None)

Create a fixed constraint between two rigid objects.

Constraints are native Default-backend resources owned by each Arena. Spawn owns the two actors; this method only borrows their native actor handles while creating the constraint.

Parameters:

• cfg (RigidConstraintCfg) – The constraint configuration.

• env_ids (Union[Sequence[int], Tensor, None]) – Target environment indices. Accepts a tensor (as passed by the EventManager) or a sequence of ints. None -> all arenas.

Return type:

RigidConstraint

Returns:

The created constraint batch.

create_visual_material(cfg)

Create a visual material with given configuration.

Parameters:

cfg (VisualMaterialCfg) – configuration for the visual material.

Returns:

the created visual material instance handle.

Return type:

VisualMaterial

destroy(exit_process=None)

No longer destructs C++ objects in place due to lingering deep local variables; instead, packages itself into a destruction task, submits to the cleanup queue, and waits for top-level delayed consumption.

Parameters:

exit_process (bool | None) – Whether to call os._exit(0) after queuing the destruction task. If None, reads EMBODICHAIN_SIM_EXIT_PROCESS.

Return type:

None

property differentiable_runtime

Return the differentiable facade over the Spawn-owned Newton runtime.

disable_entity_gizmo()

Disable native object interaction, including future window opens.

Call enable_entity_gizmo() to explicitly re-enable interaction. Robot IK controllers and Viser command permissions are independent.

Return type:

None

disable_gizmo(uid, control_part=None)

Disable a Gizmo and prevent its automatic recreation.

Parameters:

• uid (str) – Target asset UID.

• control_part (str | None) – Robot control part. Omit to disable every part of a robot.

Return type:

None

draw_marker(cfg)

Draw visual markers in the simulation scene for debugging and visualization.

Drawing markers does not advance physics. Call capture_visualization() to publish them to Viser without stepping.

Parameters:

cfg (MarkerCfg) –

Marker configuration with the following key parameters: - name (str): Unique identifier for the marker group - marker_type (str): Type of marker (“axis” currently supported) - axis_xpos (np.ndarray | List[np.ndarray]): 4x4 transformation matrices

for marker positions and orientations

• axis_size (float): Thickness of axis arrows

• axis_len (float): Length of axis arrows

• arena_index (int): Arena index for placement (-1 for global)

Returns:

List of created marker handles, False if invalid input, None if no poses provided.

Return type:

List[MeshObject]

Example

`python cfg = MarkerCfg(name="test_axis", marker_type="axis", axis_xpos=np.eye(4)) markers = sim.draw_marker(cfg) `

enable_entity_gizmo(config=None)

Enable DexSim entity control and exclude the EmbodiChain ground.

Called automatically on the first native window unless disabled in SimulationManagerCfg. Explicit calls also work headlessly. DexSim retains this controller and its configuration across window close/reopen; reopening does not reapply the default configuration.

Parameters:

config (EntityGizmoConfig | None) – Native DexSim entity-Gizmo configuration.

Return type:

EntityGizmoManipulator

Returns:

The active world-owned entity Gizmo manipulator.

enable_gizmo(uid, control_part=None, gizmo_cfg=None)

Register Gizmo control for a simulation target.

Robot controls support native windows and Viser; native IK activates on the configured toggle key. Explicit configuration takes precedence over automatically registered controls.

Parameters:

• uid (str) – UID of the robot, rigid object, or camera sensor.

• control_part (str | None) – Robot control part used for IK/FK.

• gizmo_cfg (GizmoCfg | None) – Gizmo appearance and robot IK configuration.

Return type:

Gizmo | None

Returns:

The created Gizmo, or None if setup failed.

enable_physics(enable)

Enable or disable physics simulation.

Parameters:

enable (bool) – whether to enable physics simulation.

Return type:

None

enable_window_camera_pose_hotkey(convert_to_look_at=True)

Register p to print the current viewer camera pose.

Parameters:

convert_to_look_at (bool) – Print a window.set_look_at(...) call when true, which is the default. Set false to print the raw matrix.

Return type:

bool

Returns:

Whether the control is registered on an available window.

enable_window_record_hotkey(save_path=None, fps=20, max_memory=1024, video_prefix='viewer_record')

Register the r key to start/stop viewer recording.

Return type:

bool

export_usd(fpath)

Export the current simulation scene to a USD file.

Parameters:

fpath (str) – The file path to save the USD file.

Returns:

True if export is successful, False otherwise.

Return type:

bool

finalize_newton_physics()

Prepare the Spawn-owned physics runtime.

This backwards-compatible alias now has the same backend-neutral behavior as prepare().

Return type:

None

static flush_cleanup_queue()

Run pending destruction tasks and wait for their scenes to disappear.

An empty queue means that no manager requested destruction. In that case, returning immediately is important: other managers may still own live worlds, and waiting for the global world count to reach zero would block until the timeout even though there is nothing to clean up.

Return type:

None

get_articulation(uid)

Get an articulation by its unique ID.

Parameters:

uid (str) – The unique ID of the articulation.

Returns:

The articulation instance if found, otherwise None.

Return type:

Articulation | None

get_articulation_uid_list()

Get current articulation uid list

Returns:

list of articulation uid.

Return type:

List[str]

get_asset(uid)

Get an asset by its UID.

The asset can be a light, sensor, robot, visual object, rigid object, deformable, or articulation.

Parameters:

uid (str) – The UID of the asset.

Return type:

Light | BaseSensor | Robot | RigidObject | VisualObject | RigidObjectGroup | DeformableObject | Articulation | None

Returns:

The asset instance if found, otherwise None.

get_axis_marker_items()

Return active axes for backend-neutral visualization.

Return type:

tuple[tuple[str, tuple[MeshObject, ...], float, float], ...]

Returns:

Tuples containing the marker name, native handles, axis length, and axis radius for each active marker group.

get_deformable_object(uid)

Get a deformable object by its unique ID.

Return type:

DeformableObject | None

get_deformable_object_uid_list()

Return all deformable object UIDs in declaration order.

Return type:

List[str]

get_env(arena_index=-1)

Get the arena or env by index.

If arena_index is -1, return the global env. If arena_index is valid, return the corresponding arena.

Parameters:

arena_index (int, optional) – the index of arena to get, -1 for global env. Defaults to -1.

Returns:

The arena or global env.

Return type:

dexsim.environment.Arena

get_gizmo(uid, control_part=None)

Return an active Gizmo.

Parameters:

• uid (str) – Target asset UID.

• control_part (str | None) – Robot control part, if applicable.

Return type:

Gizmo | None

Returns:

Gizmo instance if found, otherwise None.

get_gizmo_items()

Return a stable snapshot of active Gizmo IDs and controllers.

Return type:

tuple[tuple[str, Gizmo], ...]

classmethod get_instance(instance_id=0)

Get the instance of SimulationManager by id.

Parameters:

instance_id (int) – The instance id. Defaults to 0.

Returns:

The instance.

Return type:

SimulationManager

Raises:

RuntimeError – If the instance has not been created yet.

classmethod get_instance_num()

Get the number of instantiated SimulationManager instances.

Returns:

The number of instances.

Return type:

int

get_light(uid)

Get a light by its UID.

Parameters:

uid (str) – The UID of the light.

Returns:

The light instance if found, otherwise None.

Return type:

Light | None

get_light_uid_list()

Get current light uid list

Returns:

list of light uid.

Return type:

List[str]

get_physics_scene()

Return the Default backend’s compatibility scene after Spawn preparation.

Newton has no PhysicsScene facade and raises with guidance to use spawn_result instead.

Return type:

PhysicsScene

get_rigid_constraint(name)

Get a rigid constraint by its base name.

Parameters:

name (str) – The base constraint name.

Return type:

RigidConstraint | None

Returns:

The constraint, or None if not found.

get_rigid_constraint_uid_list()

Get the list of registered constraint base names.

Returns:

list of constraint names.

Return type:

List[str]

get_rigid_object(uid)

Get a rigid object by its unique ID.

Parameters:

uid (str) – The unique ID of the rigid object.

Returns:

The rigid object instance if found, otherwise None.

Return type:

RigidObject | None

get_rigid_object_group(uid)

Get a rigid object group by its unique ID.

Parameters:

uid (str) – The unique ID of the rigid object group.

Returns:

The rigid object group instance if found, otherwise None.

Return type:

RigidObjectGroup | None

get_rigid_object_group_uid_list()

Get current rigid body group uid list

Returns:

list of rigid body group uid.

Return type:

List[str]

get_rigid_object_uid_list()

Get current rigid body uid list

Returns:

list of rigid body uid.

Return type:

List[str]

get_robot(uid)

Get a Robot by its unique ID.

Parameters:

uid (str) – The unique ID of the robot.

Returns:

The robot instance if found, otherwise None.

Return type:

Robot | None

get_robot_uid_list()

Retrieves a list of unique identifiers (UIDs) for all robots in the simulation system.

Returns:

A list containing the UIDs of the robots.

Return type:

list

get_sensor(uid)

Get a sensor by its UID.

Parameters:

uid (str) – The UID of the sensor.

Returns:

The sensor instance if found, otherwise None.

Return type:

BaseSensor | None

get_sensor_uid_list()

Get current sensor uid list

Returns:

list of sensor uid.

Return type:

List[str]

get_texture_cache(key=None)

Get the texture from the global texture cache.

Parameters:

key (str | None, optional) – The key of the texture. If None, return None. Defaults to None.

Returns:

The texture if found, otherwise None.

Return type:

torch.Tensor | list[torch.Tensor] | None

get_visual_material(uid)

Get visual material by UID.

Parameters:

uid (str) – uid of visual material.

Return type:

VisualMaterial | None

get_visual_object(uid)

Find a registered render-only object.

Parameters:

uid (str) – Logical asset identifier.

Return type:

VisualObject | None

Returns:

The visual object, or None if absent.

get_visual_object_uid_list()

Return the registered render-only object identifiers.

Return type:

list[str]

Returns:

Identifiers in declaration order.

get_world()

Return type:

World

has_gizmo(uid, control_part=None)

Check if a gizmo exists for the given UID and control part.

Parameters:

• uid (str) – Object UID to check

• control_part (str | None, optional) – Control part name for robots. Defaults to None.

Returns:

True if gizmo exists, False otherwise.

Return type:

bool

property has_native_renderer: bool

Whether the World owns a native renderer and visual resources.

has_non_static_rigid_object()

Check if there is any non-static rigid object in the simulation.

Returns:

True if there is at least one non-static rigid object, False otherwise.

Return type:

bool

init_gpu_physics()

Prepare the Spawn-owned physics runtime.

This backwards-compatible alias now has the same backend-neutral behavior as prepare().

Return type:

None

property is_default_backend: bool

Whether the Default physics backend is active.

classmethod is_instantiated(instance_id=0)

Check if the instance has been created.

Returns:

True if the instance exists, False otherwise.

Return type:

bool

property is_newton_backend: bool

Whether the Newton physics backend is active.

property is_physics_manually_update: bool

property is_use_gpu_physics: bool

Whether the active physics backend is running on GPU.

is_window_recording()

Check whether the viewer window is currently recording.

Return type:

bool

list_gizmos()

List active Gizmo IDs and availability.

Return type:

dict[str, bool]

Returns:

Mapping from uid[:control_part] to availability.

property newton_manager

Compatibility accessor for the removed NewtonManager API.

A non-Newton backend still returns None. The Newton backend raises an actionable error because Spawn owns its World-level runtime and no independent NewtonManager exists.

notify_visualization_topology_changed()

Mark scene topology dirty and return its new local revision.

Return type:

int

property num_envs: int

Get the number of arenas in the simulation.

Returns:

number of arenas.

Return type:

int

open_window()

Open the native DexSim simulation window when allowed.

Viser owns visualization while it is configured or running. In that case this method safely skips the native window so launchers do not need a separate Viser condition.

Return type:

bool

Returns:

True when the native window is open, otherwise False.

property physics_backend: str

Return the active physics backend name.

prepare()

Materialize declarations, bind state, and restore camera parents.

Return type:

None

print_window_camera_pose(convert_to_look_at=True)

Print the current viewer camera pose as reusable Python code.

Parameters:

convert_to_look_at (bool) – Print window.set_look_at(...) by default. Set false to print the raw 4x4 pose matrix instead.

Return type:

str | None

Returns:

The printed snippet, or None when no viewer window is open.

process_pick_commands()

Apply queued Viser click-pick commands on the simulation thread.

A non-empty pick attaches a picker-owned Gizmo to the clicked node; an empty pick (clicking empty space) clears it. Only one picker-owned Gizmo is kept at a time and user-created Gizmos are never touched.

Return type:

int

Returns:

Number of pick commands drained from the visualization runtime.

process_visualization_commands()

Apply queued Viser Gizmo commands on the simulation thread.

Return type:

int

Returns:

Number of commands accepted for active Gizmos.

refresh_visualization()

Publish current scene topology when Viser is active.

Return type:

SceneManifest | None

remove_asset(uid)

Remove an asset by its UID.

Native render lights are not removed by this method. Sensors and Spawn-owned physical assets are supported. Removing a robot also destroys its automatically initialized mounted cameras.

Parameters:

uid (str) – The UID of the asset.

Returns:

True if the asset is removed successfully, otherwise False.

Return type:

bool

remove_marker(name)

Remove markers (including axis) with the given name.

Parameters:

name (str) – The name of the marker to remove.

Returns:

True if the marker was removed successfully, False otherwise.

Return type:

bool

remove_rigid_constraint(name, env_ids=None)

Remove a rigid constraint by name.

With env_ids=None the constraint is removed from every arena and dropped from the registry. With a subset, only those arenas are cleared; the registry entry is kept until all handles become None.

Parameters:

• name (str) – The base constraint name.

• env_ids (Union[Sequence[int], Tensor, None]) – Subset of arenas to clear. Accepts a tensor (as passed by the EventManager) or a sequence of ints. None -> all.

Return type:

bool

Returns:

True if the constraint was found (and removed or partially removed), False if the name is unknown.

render_camera_group(group_ids)

Synchronize physics state and render camera groups.

An empty group list skips camera rendering. An open native window still consumes current state. Use render_frame() to share publication with recording and browser visualization.

Parameters:

group_ids (list[int]) – The list of camera group ids to render.

Return type:

None

Note: This interface is only valid when Ray Tracing rendering backend is enabled.

render_frame(*, force_visualization=False, capture_camera_images=True)

Share one state publication across the frame’s visual consumers.

Render camera observations inside this context. On exit, due recording and Viser frames consume the same state. An open native window is a consumer even when automatic Newton synchronization is disabled.

Attention

Complete physics steps, resets and direct state writes before entering. If state must change inside the context, explicitly call sync_render_state() afterwards. Publication is never cached across contexts or independent camera/visualization calls.

Parameters:

• force_visualization (bool) – Bypass the Viser frame-rate limiter.

• capture_camera_images (bool) – Allow Viser to capture camera images.

Yields:

Control to the caller rendering this frame’s camera observations.

Return type:

Iterator[None]

replace_rigid_object(cfg)

Replace a rigid object with the same UID in one preparation.

The replacement uses its configured initial state and physical properties. Previously returned handles for this object must not be reused. Other scene objects retain their runtime state.

Parameters:

cfg (RigidObjectCfg) – New configuration whose UID identifies an existing rigid object.

Return type:

RigidObject

Returns:

The replacement object, ready for state access if the scene was already materialized.

Raises:

KeyError – If the UID does not identify an existing rigid object.

Note

Replacement applies to all instances of the logical object. A backend preparation failure is propagated; this operation does not provide rollback of native resources.

replace_rigid_objects(cfgs)

Replace multiple existing rigid objects in one preparation.

All UIDs and descriptors are checked before scene mutation. Returned facades follow input order and are ready after the single preparation when the scene was materialized. Run events needing the new objects after this call. Old replaced handles must be discarded; other objects retain their state. Native preparation failures do not roll back.

Parameters:

cfgs (Sequence[RigidObjectCfg]) – Replacement configurations with distinct, existing UIDs.

Return type:

list[RigidObject]

Returns:

Replacement objects in input order, or an empty list for no input.

Raises:

• ValueError – A UID is missing or duplicated, or translation fails.

• KeyError – A UID does not identify an existing rigid object.

classmethod reset(instance_id=0)

Reset the instance.

This allows creating a new instance with different configuration.

Return type:

None

reset_objects_state(env_ids=None, excluded_uids=None, *, excluded_sensor_uids=None)

Reset the state of the simulated assets given the environment IDs and excluded UIDs.

Parameters:

• env_ids (Sequence[int] | None) – The environment IDs to reset. If None, reset all environments.

• excluded_uids (Sequence[str] | None) – List of asset UIDs to exclude from resetting. If None, reset all assets.

• excluded_sensor_uids (Optional[Sequence[str]]) – Sensor UIDs to exclude without excluding physical assets with the same UID.

Return type:

None

set_default_background()

Set default background.

Return type:

None

set_default_global_lighting()

Set default global lighting for the scene.

Initialize environment emission without creating direct lights or changing existing scene lights. Add direct lights explicitly through add_light() or the task’s lighting configuration.

Return type:

None

classmethod set_default_renderer(renderer='auto', gpu_id=0)

Set the global default renderer used by new simulations.

This updates embodichain.lab.sim.cfg.DEFAULT_RENDERER, which is consulted by embodichain.lab.sim.utility.render_utils.select_default_renderer() when render_cfg.renderer="auto" is resolved during SimulationManager construction.

Parameters:

• renderer (str) – The renderer to set. One of "auto", "hybrid", "fast-rt", or "rt". When "auto", the renderer is resolved immediately from the detected GPU via embodichain.lab.sim.utility.render_utils.select_default_renderer().

• gpu_id (int) – The CUDA device index to query when renderer="auto".

Return type:

str

Returns:

The resolved renderer name that was set as the default.

set_emission_light(color=None, intensity=None)

Set environment emission light.

Parameters:

• color (Sequence[float] | None) – color of the light.

• intensity (float | None) – intensity of the light.

Return type:

None

set_gizmo_visibility(uid, visible, control_part=None)

Set Gizmo visibility by target UID and optional control part.

Return type:

None

set_ground_plane_visibility(visible)

Set native ground rendering visibility while preserving collisions.

Applies to native windows and cameras. The setting is retained until the ground is materialized, and does not control the Viser grid. NoRender stores the setting without accessing native visual resources.

Parameters:

visible (bool) – Whether the default ground plane is rendered.

Return type:

None

set_indirect_lighting(name)

Set indirect lighting.

Parameters:

name (str) – name of path of the indirect lighting.

Return type:

None

set_texture_cache(key, texture)

Set the texture to the global texture cache.

Parameters:

• key (str) – The key of the texture.

• texture (Union[torch.Tensor, List[torch.Tensor]]) – The texture data.

Return type:

None

set_visualization_overlays(overlays)

Set persistent overlays for automatic Viser captures.

The overlays remain active across update() calls until replaced or cleared with None. When Viser is running, the new overlays are published immediately.

Parameters:

overlays (SceneOverlays | None) – Backend-neutral overlays to publish with every frame, or None to clear all persistent overlays.

Return type:

None

property spawn_result: Scene | None

Return the finalized Scene, or None before first prepare.

start_visualization()

Start the configured live visualizer and publish the current scene.

Return type:

VisualizationRuntime | None

start_window_record(save_path=None, fps=20, max_memory=1024, video_prefix='viewer_record', pose_provider=None, fixed_pose=None, look_at=None, use_sim_time=None)

Start asynchronously recording the simulation to a video buffer.

The recorder can either follow the live viewer camera or run without a window by using a fixed pose or a pose callback supplied by the caller.

Parameters:

• save_path (str | None) – Optional output path for the recorded video.

• fps (int) – Target output frames per second. Must be positive.

• max_memory (int) – Maximum buffered frame memory in MB. Must be positive.

• video_prefix (str) – File name prefix used when save_path is not provided.

• pose_provider (Optional[Callable[[], ndarray]]) – Optional callback that returns the current camera pose.

• fixed_pose (ndarray | None) – Optional fixed 4x4 camera pose matrix.

• look_at (tuple[Sequence[float], Sequence[float], Sequence[float]] | None) – Optional (eye, target, up) tuple used to derive a fixed pose.

• use_sim_time (bool | None) – Whether to capture frames from simulation time instead of wall time. Defaults to headless mode when no viewer window exists.

Returns:

True if recording starts successfully, otherwise False.

Return type:

bool

stop_visualization()

Stop the visualization server and release its worker thread.

Return type:

None

stop_window_record(save_path=None)

Stop the active viewer recording and save frames in the background.

Return type:

bool

sync_render_state()

Publish current physics state to render resources without stepping.

Use this after direct state writes, such as an environment reset, and before reading cameras or publishing a visualization frame.

Raises:

RuntimeError – If the Spawn scene has not been prepared.

Return type:

None

toggle_gizmo_visibility(uid, control_part=None)

Toggle Gizmo visibility and return the new state, if it exists.

Return type:

bool | None

toggle_window_record(save_path=None, fps=20, max_memory=1024, video_prefix='viewer_record')

Toggle viewer recording on or off.

Return type:

bool

update(physics_dt=None, step=10, *, after_substep=None, render_final_step=True)

Advance physics explicitly and publish the resulting simulation state.

Each substep applies pending Gizmo controls before advancing the world, then updates simulation time, recording, and browser visualization. Physics does not advance in the background while the caller is idle.

Parameters:

• physics_dt (float | None, optional) – the time step for physics simulation. Defaults to None.

• step (int, optional) – the number of World.update() calls per invocation. Defaults to 10.

• after_substep (Optional[Callable[[float], None]]) – Observer called with the elapsed physics time after each world update, before recording and visualization. It runs inside this update call and is not retained by the manager.

• render_final_step (bool) – Render the final substep immediately. Gym defers it until after interval events, then enters render_frame() around observations to share publication with other consumers.

Return type:

None

update_gizmos()

Register robot controls, process interaction, and update active Gizmos.

Return type:

None

property visualization_health: RuntimeHealth

Return current visualization service and client health.

property visualization_overlays: SceneOverlays | None

Return the overlays included in every Viser scene frame.

property visualization_runtime: VisualizationRuntime | None

Return the active visualization runtime, if one has been started.

property visualization_stats: RuntimeStats | None

Return visualization telemetry, or None before startup.

static wait_scene_destruction(timeout_ms=10000)

A public helper to wait for the underlying C++ scenes (dexsim.World) to destruct completely.

Return type:

None

wait_window_record_saves()

Wait for all background video export threads to finish.

Return type:

None

Newton runtime controls

Runtime controls must be registered after declaring their target assets and before SimulationManager.prepare(). The manager expands logical UIDs to the concrete paths of every Arena, so callers do not need access to the private Spawn scene. The particle-material schedule is host-side and disables CUDA Graph replay; the other controls are graph-compatible.

SimulationManager.register_kinematic_joint_trajectory(uid, joint_positions, *, fps=None, root_poses=None)

Register a Newton kinematic joint trajectory for every arena.

The leading trajectory dimension follows EmbodiChain’s batched arena layout. Each arena row is lowered to one DexSim runtime control with the corresponding concrete Spawn articulation path. Row zero is the initial sample; when fps is omitted, each call to update() advances to the next sample.

Attention

Declare the target robot or articulation first, then call this method before prepare(). Runtime controls are part of the finalized Newton simulation pipeline and cannot be added later.

Parameters:

• uid (str) – UID of a robot or articulation declared on this manager.

• joint_positions (Tensor | ndarray) – Batched positions in the articulation’s public qpos order with shape (num_envs, frames, dof).

• fps (float | None) – Optional trajectory sample rate. When omitted, samples advance once per EmbodiChain physics frame.

• root_poses (Tensor | ndarray | None) – Optional batched world-space root transforms with shape (num_envs, frames, 4, 4).

Raises:

• RuntimeError – If the active backend is not Newton, the Spawn scene is already finalized, or its arena count is inconsistent.

• KeyError – If uid is not a declared robot or articulation.

• ValueError – If an input has an invalid batch shape or non-finite values.

Return type:

None

SimulationManager.register_kinematic_nodal_trajectory(uid, node_indices, position_offsets, *, fps=None, rebuild_self_contact_bvh=False)

Register a Newton trajectory for selected deformable nodes.

Each selected node is fixed during Newton model construction and then moved relative to the world position captured when the runtime control initializes. The manager expands the batched offsets to one control per Arena without exposing the private Spawn scene.

When fps is provided, samples are linearly interpolated at Newton substep times. Otherwise one sample is consumed per substep. The final sample is held after the trajectory ends.

Attention

Declare the deformable first and clear the Newton ACTIVE bit in its particle_flags for every selected node. Then register this control before prepare(). This host-side control makes Newton use direct substep launches instead of CUDA Graph replay. Surface node indices can follow an array-backed mesh directly; volume node indices refer to the generated tetrahedral simulation particles, not source-mesh vertices.

Parameters:

• uid (str) – UID of a deformable declared on this manager.

• node_indices (Union[Tensor, ndarray, Sequence[int]]) – Shared one-dimensional simulation-particle indices.

• position_offsets (Tensor | ndarray) – Batched world-frame position offsets with shape (num_envs, samples, selected_nodes, 3).

• fps (float | None) – Optional trajectory sample rate in samples per second.

• rebuild_self_contact_bvh (bool) – Whether to request a full solver BVH rebuild at the start of every physics frame when supported.

Raises:

• RuntimeError – If the active backend is not Newton, the Spawn scene is already finalized, or its Arena count is inconsistent.

• KeyError – If uid is not a declared deformable.

• TypeError – If node indices, fps, or the BVH option have invalid types.

• ValueError – If an input has an invalid shape or value, or selected nodes were not configured as inactive particles.

Return type:

None

SimulationManager.register_contact_material_schedule(uid, keyframes, *, link_names=None)

Register time-varying Newton contact properties for an asset.

The manager expands the declared UID to the concrete Spawn path in every Arena. Supported keyframe tracks are dynamic_friction, stiffness, and damping; each track contains (time, value) pairs and is sampled piecewise-constantly in simulation time.

Attention

Declare the rigid object, robot, or articulation first and call this method before prepare(). Runtime controls are part of the finalized Newton pipeline and cannot be added later.

Parameters:

• uid (str) – UID of a declared rigid object, robot, or articulation.

• keyframes (Mapping[str, Sequence[Sequence[float]]]) – Contact-property tracks keyed by property name.

• link_names (Optional[Sequence[str]]) – Optional articulation-link names to update. None updates every collision shape belonging to the target.

Raises:

• RuntimeError – If the backend is not Newton, the scene is already finalized, or its Arena count is inconsistent.

• KeyError – If uid does not identify a declared supported asset.

• ValueError – If the UID or keyframes are invalid.

Return type:

None

SimulationManager.register_particle_contact_material_schedule(keyframes)

Register time-varying Newton particle contact properties.

Supported tracks are dynamic_friction, stiffness, and damping. Values apply scene-wide to particle-versus-rigid contacts and are sampled piecewise-constantly in simulation time.

Attention

Register this control before prepare(). This host-side control requires direct Newton stepping and therefore disables CUDA Graph replay for the finalized simulation.

Parameters:

keyframes (Mapping[str, Sequence[Sequence[float]]]) – Particle contact-property tracks containing (time, value) pairs.

Raises:

• RuntimeError – If the backend is not Newton or the scene is already finalized.

• ValueError – If the keyframes are invalid.

Return type:

None

Native point-cloud visualization

SimulationManager.visualize_point_cloud(points, colors=None, point_size=2.0, name='point_cloud')

Visualize a static point cloud in the native simulation viewer.

Each invocation creates a separate native point-cloud object. This convenience API is intended for static data, not incremental or streaming updates.

Parameters:

• points (Tensor | ndarray) – Point positions with shape (N, 3).

• colors (Tensor | ndarray | None) – Optional per-point RGB or RGBA colors with shape (N, 3) or (N, 4). Values in [0, 255] are normalized to [0, 1]. The alpha channel of RGBA input is ignored by the native renderer. Defaults to green.

• point_size (float) – Native renderer point size. Defaults to 2.0.

• name (str) – Name assigned to the native point-cloud object.

Return type:

PointCloud

Returns:

The native DexSim point-cloud handle.

Raises:

• RuntimeError – If there is no active simulation environment.

• ValueError – If the points or colors do not have a supported shape.

class embodichain.lab.sim.sim_manager.SimulationManagerCfg

Bases: object

Global robot simulation configuration.

Attributes:

arena_space	The distance between each arena when building multiple arenas.
cpu_num	The number of CPU threads to use for the simulation engine.
device	The device for the physics simulation.
dexsim_startup_info	Show DexSim's native startup information in addition to our summary.
enable_entity_gizmo	Enable native object interaction when the first native window opens.
gpu_id	The gpu index that the simulation engine will be used.
gpu_memory_config	Legacy alias for the default backend GPU-memory configuration.
headless	Whether to run without an automatically opened native window.
height	The height of the simulation window.
num_envs	The number of parallel environments (arenas) to simulate.
physics_cfg	Physics backend configuration (type selects default vs Newton backend).
physics_config	Legacy alias for physics_cfg.
physics_dt	The time step for the physics simulation.
profiler	Optional simulation profiler.
render_cfg	The rendering configuration parameters.
robot_ik_gizmo	Automatically register robot parts with configured IK chain/TCP metadata.
scene_node_capacity	Maximum scene nodes, or None to retain the DexSim World default.
sim_device	Legacy alias for device.
startup_summary	Startup table detail.
thread_mode	The threading mode for the simulation engine.
visualization	Live browser visualization settings.
width	The width of the simulation window.
window_camera_pose	Interactive viewer camera-pose printing settings.
window_record	Viewer window recording settings (hotkey, paths, FPS, memory budget).

arena_space: float

The distance between each arena when building multiple arenas.

cpu_num: int

The number of CPU threads to use for the simulation engine.

property device: str | device

The device for the physics simulation.

dexsim_startup_info: bool

Show DexSim’s native startup information in addition to our summary.

Warnings and errors remain visible regardless of this setting. Requires a DexSim build exposing WorldConfig.log_startup_info.

enable_entity_gizmo: bool

Enable native object interaction when the first native window opens.

Headless and Viser simulations do not automatically create native gizmos. Explicit runtime enable/disable calls take precedence over this default; reopening a window preserves the current DexSim controller state. Robot IK interaction is controlled separately by robot_ik_gizmo.

gpu_id: int

The gpu index that the simulation engine will be used.

Note: it will affect the gpu physics device if using gpu physics.

property gpu_memory_config: GPUMemoryCfg | None

Legacy alias for the default backend GPU-memory configuration.

headless: bool

Whether to run without an automatically opened native window.

This is forced to True when the Viser backend is enabled. Viser and the native DexSim window are mutually exclusive; browser Gizmos do not require a native window.

height: int

The height of the simulation window.

num_envs: int

The number of parallel environments (arenas) to simulate.

physics_cfg: PhysicsBackendCfg

Physics backend configuration (type selects default vs Newton backend).

The concrete config owns the default device: Default uses cpu and Newton uses cuda:0. The constructor’s optional device/sim_device arguments are applied only when explicitly provided.

property physics_config: PhysicsBackendCfg

Legacy alias for physics_cfg.

property physics_dt: float

The time step for the physics simulation.

profiler: ProfilerCfg | None

Optional simulation profiler. None disables profiling.

Standalone calls to SimulationManager.update() are recorded below a sim_update root. When the manager is owned by an environment, the same profiler instance composes with the environment’s step/reset hierarchy.

render_cfg: RenderCfg

The rendering configuration parameters.

robot_ik_gizmo: GizmoCfg | None

Automatically register robot parts with configured IK chain/TCP metadata.

Native controls activate on the first I press; Viser creates its IK solver on the first drag and requires visualization.allow_commands. Pure headless and multi-environment simulations do not register controls. Defaults to DexSim IK. Use GizmoCfg(ik_solver="embodichain") to reuse configured solvers such as Pink, or None to disable automatic setup. GizmoCfg(ik_start_enabled=True) explicitly activates native controls on their first update with an open window, without waiting for I.

scene_node_capacity: int | None

Maximum scene nodes, or None to retain the DexSim World default.

Large batches of articulated robots may require more nodes than the default 65,536. NoRender caps larger native-renderer reservations at its 131,071-node limit while retaining the authored capacity in this config. Physical scene replication must fit the effective capacity. This changes allocation capacity, not physics settings.

property sim_device: str | device

Legacy alias for device.

startup_summary: Literal['compact', 'full', 'off']

Startup table detail. off disables both simulation and Gym summaries.

thread_mode: ThreadMode

The threading mode for the simulation engine.

• RENDER_SHARE_ENGINE: The rendering thread shares the same thread with the simulation engine.

• RENDER_SCENE_SHARE_ENGINE: The rendering thread and scene update thread share the same thread with the simulation engine.

visualization: VisualizationCfg

Live browser visualization settings.

width: int

The width of the simulation window.

window_camera_pose: WindowCameraPoseCfg

Interactive viewer camera-pose printing settings.

window_record: WindowRecordCfg

Viewer window recording settings (hotkey, paths, FPS, memory budget).

Active Physics Scene

embodichain.lab.sim.sim_manager.get_physics_scene(instance_id=0)

Return the active physics scene from a SimulationManager instance.

This is the unified EmbodiChain access point for code that previously reached through dexsim.default_world().get_physics_scene().