isaaclab_contrib.custom_coupling

Opt-in example of a custom Newton coupling manager.

Import isaaclab_contrib.custom_coupling.tasks to register the example task.

The custom MJWarp and VBD manager is an opt-in example. Import isaaclab_contrib.custom_coupling.tasks explicitly to register IsaacContrib-Lift-Soft-Franka-Custom-Coupling. The environment requires a full Isaac Lab installation containing isaaclab_tasks.

Classes

newton_manager_cfg.CoupledMJWarpVBDSolverCfg	Configuration for the custom MJWarp and VBD coupling manager.
coupled_mjwarp_vbd_manager.NewtonCoupledMJWarpVBDManager	NewtonVBDManager specialization for custom MJWarp and VBD coupling.
franka_soft_env_cfg.FrankaSoftCustomCouplingEnvCfg	Franka soft lifting with manual MJWarp and VBD coupling.

Custom Coupling

class isaaclab_contrib.custom_coupling.newton_manager_cfg.CoupledMJWarpVBDSolverCfg

Bases: NewtonModelSolverCfg

Configuration for the custom MJWarp and VBD coupling manager.

Attributes:

class_type	Manager class for the coupled solver.
rigid_solver_cfg	MJWarp rigid-body solver configuration.
solver_type	Solver type metadata (deprecated).
model_cfg	Global Newton model parameters applied after builder finalization.
soft_solver_cfg	VBD deformable solver configuration.
coupling_mode	Coupling direction between the rigid and deformable solvers.

class_type: type[NewtonManager] | str

Manager class for the coupled solver.

rigid_solver_cfg: MJWarpSolverCfg

MJWarp rigid-body solver configuration.

solver_type: str

Solver type metadata (deprecated).

Deprecated since version Manager: dispatch is now driven by class_type; this field is retained as metadata for logging and debugging only. Do not branch on solver_type in new code.

model_cfg: NewtonModelCfg | None

Global Newton model parameters applied after builder finalization.

soft_solver_cfg: VBDSolverCfg

VBD deformable solver configuration.

coupling_mode: Literal['one_way', 'two_way']

Coupling direction between the rigid and deformable solvers.

class isaaclab_contrib.custom_coupling.coupled_mjwarp_vbd_manager.NewtonCoupledMJWarpVBDManager

Bases: NewtonVBDManager

NewtonVBDManager specialization for custom MJWarp and VBD coupling.

Reuses the VBD manager’s deformable stage handling and adds a custom rigid-deformable coupling step. Newton’s CollisionPipeline provides deformable contacts.

Methods:

step()	Step the physics simulation.
activate_newton_actuator_path()	Opt an articulation into the Newton actuator fast path.
add_contact_sensor([body_names_expr, ...])	Add a contact sensor for reporting contacts between bodies/shapes.
add_frame_transform_sensor(shapes, ...)	Add a frame transform sensor for measuring relative transforms.
add_imu_sensor(sites)	Add an IMU sensor for measuring acceleration and angular velocity at sites.
add_model_change(change)	Register a model change to notify the solver.
after_visualizers_render()	Hook after visualizers have stepped during render().
cl_register_site(body_pattern, xform, *[, ...])	Register a site request for injection into prototypes before replication.
clear()	Clear all Newton-specific state (callbacks cleared by super().close()).
clear_callbacks()	Remove all registered callbacks.
close()	Clean up Newton physics resources.
create_builder([up_axis])	Create a ModelBuilder configured with default settings.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
fix_articulation_root(articulation_prim[, stage])	Ensure that an articulation root has one enabled world fixed joint.
forward()	Update articulation kinematics without stepping physics.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_contacts()	Get the current Newton contact buffer, if the active solver exposes one.
get_control()	Get the control object.
get_device()	Get the physics simulation device.
get_dt()	Get the physics timestep.
get_model()	Get the Newton model.
get_physics_dt()	Get the physics timestep in seconds.
get_physics_sim_view()	Get the list of registered views.
get_scene_data_backend()	Return the SceneDataBackend for the SceneDataProvider.
get_scene_data_provider()	Return the active scene data provider.
get_simulation_time()	Get the current simulation time in seconds.
get_solver_dt()	Get the solver substep timestep.
get_state([scene_data_provider])	Get the current Newton state for visualization.
get_state_0()	Get the current state.
get_state_1()	Get the next state.
handles_decimation()	True when step() executes the full decimation loop internally.
initialize(sim_context)	Initialize the manager with simulation context.
initialize_solver()	Initialize the solver and collision pipeline.
instantiate_builder_from_stage()	Create builder from USD stage with special treatment for deformable bodies, as these are not read from USD yet.
invalidate_body_state([env_ids, env_mask])	Mark selected maximal-coordinate body state as changed without requesting FK.
invalidate_fk([env_mask, env_ids, ...])	Mark environments as needing FK recomputation and solver reset.
is_fabric_enabled()	Check if fabric interface is enabled (not applicable for Newton).
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
pre_render()	Refresh derived Newton state before cameras and visualizers read it.
provides_implicit_damping()	Whether this backend's integrator has implicit numerical damping.
register_callback(callback, event[, order, ...])	Register a callback.
register_particle_visual_prim(prim_path, ...)	Register a UsdGeom.Points prim whose points mirror a slice of Newton's particle state.
register_post_actuator_callback(callback)	Append a hook to the list invoked after the actuator step on every iteration.
register_post_step_callback(callback)	Append a hook to the list invoked after the last solver substep on every step.
request_extended_contact_attribute(attr)	Request an extended contact attribute (e.g. "force").
request_extended_state_attribute(attr)	Request an extended state attribute (e.g. "body_qdd").
reset([soft])	Reset physics simulation.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
set_builder(builder)	Set the Newton model builder.
set_decimation(decimation)	Set the decimation count and re-capture the CUDA graph.
start_simulation()	Start simulation by finalizing model and initializing state.
stop()	Stop physics simulation.
sync_cables_to_usd()	Write Newton cable segment endpoints to Fabric curve points.
sync_particles_to_usd()	Write Newton particle positions to USD/Fabric for Kit viewport rendering.
sync_transforms_to_usd()	Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.
unregister_post_step_callback(callback)	Remove a previously registered post-step callback.
update_visualization_state([scene_data_provider])	Refresh visualization state for the active sim backend.
video_capture_backend()	Newton GL headless perspective video capture.
wait_for_playing()	Block until the timeline is playing.

classmethod step() → None

Step the physics simulation.

classmethod activate_newton_actuator_path() → None

Opt an articulation into the Newton actuator fast path.

Idempotent — called by every Newton-fast-path articulation’s _process_actuators_cfg:

1. Sets _use_newton_actuators_active, which _is_all_graphable() checks (adapter presence alone cannot distinguish the fast path from the standard Lab path).

2. On first call, builds the single sim-level NewtonActuatorAdapter over the full flat DOF layout; later calls reuse it.

classmethod add_contact_sensor(body_names_expr: str | list[str] | None = None, shape_names_expr: str | list[str] | None = None, contact_partners_body_expr: str | list[str] | None = None, contact_partners_shape_expr: str | list[str] | None = None, verbose: bool = False) → tuple[str | list[str] | None, str | list[str] | None, str | list[str] | None, str | list[str] | None]

Add a contact sensor for reporting contacts between bodies/shapes.

Converts Isaac Lab pattern conventions (.* regex, full USD paths) to fnmatch globs and delegates to newton.sensors.SensorContact.

Parameters:

• body_names_expr – Expression for body names to sense.

• shape_names_expr – Expression for shape names to sense.

• contact_partners_body_expr – Expression for contact partner body names.

• contact_partners_shape_expr – Expression for contact partner shape names.

• verbose – Print verbose information.

classmethod add_frame_transform_sensor(shapes: list[int], reference_sites: list[int]) → int

Add a frame transform sensor for measuring relative transforms.

Creates a SensorFrameTransform from pre-resolved shape and reference site indices, appends it to the internal list, and returns its index.

Parameters:

• shapes – Ordered list of shape indices to measure.

• reference_sites – 1:1 list of reference site indices (same length as shapes).

Returns:

Index of the newly created sensor in _newton_frame_transform_sensors.

classmethod add_imu_sensor(sites: list[int]) → int

Add an IMU sensor for measuring acceleration and angular velocity at sites.

Creates a newton.sensors.SensorIMU from pre-resolved site indices, appends it to the internal list, and returns its index.

Parameters:

sites – Ordered list of site indices (one per environment).

Returns:

Index of the newly created sensor in the internal IMU sensor list.

classmethod add_model_change(change: newton.ModelFlags) → None

Register a model change to notify the solver.

classmethod after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Default is a no-op.

classmethod cl_register_site(body_pattern: str | None, xform: warp.transform, *, per_world: bool = False) → str

Register a site request for injection into prototypes before replication.

Sensors call this during __init__. Sites are injected into prototype builders by _cl_inject_sites() (called from newton_replicate) before add_builder, so they replicate correctly per-world.

Identical (body_pattern, per_world, transform) registrations share sites.

The body_pattern is matched against prototype-local body labels (e.g. "Robot/link.*") when replication is active, or against the flat builder’s body labels in the fallback path. Wildcard patterns that match multiple bodies create one site per matched body.

Parameters:

• body_pattern – Regex pattern matched against body labels in the prototype builder (e.g. "Robot/link0" or "Robot/finger.*" for multi-body wildcards), or None for global sites (world-origin reference, etc.).

• xform – Site transform relative to body.

• per_world – When True, body_pattern must be None and one bodyless site is created in each cloned world’s frame.

Returns:

Assigned site label suffix.

classmethod clear()

Clear all Newton-specific state (callbacks cleared by super().close()).

classmethod clear_callbacks() → None

Remove all registered callbacks.

Do NOT reset _callback_id — handle IDs must remain monotonically unique across the lifetime of the process. Resetting the counter would let a future register_callback() hand out an ID that an old, still-alive CallbackHandle (e.g. on a sensor that has not been garbage-collected yet) holds, so when the old object eventually finalizes its __del__ would deregister the new callback. This bit ovphysx’s kitless multi-context tests where two InteractiveScene``s are created in sequence: the first scene's sensor would post-GC deregister the second scene's ``_initialize_callback by ID collision, leaving the second sensor forever uninitialized.

classmethod close() → None

Clean up Newton physics resources.

classmethod create_builder(up_axis: str | None = None, **kwargs) → newton.ModelBuilder

Create a ModelBuilder configured with default settings.

Forwards NewtonShapeCfg defaults onto Newton’s upstream ModelBuilder.default_shape_cfg via checked_apply(). Falls back to wrapper defaults when no Newton config is active so rough-terrain margin/gap still apply during early construction.

Parameters:

• up_axis – Override for the up-axis. Defaults to None, which uses the manager’s _up_axis.

• **kwargs – Forwarded to ModelBuilder.

Returns:

New builder with up-axis and per-shape defaults (gap, margin) applied.

classmethod deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

callback_id – The ID or CallbackHandle returned by register_callback().

classmethod dispatch_event(event: PhysicsEvent, payload: Any = None) → None

Dispatch an event to all registered callbacks.

This is the default implementation using simple callback lists. Subclasses may override or extend with platform-specific dispatch.

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

classmethod fix_articulation_root(articulation_prim: Any, stage: Any = None) → Any

Ensure that an articulation root has one enabled world fixed joint.

The base implementation leaves the root in place. Backends whose parser requires a different root topology may relocate it and return the resulting root prim.

Parameters:

• articulation_prim – The articulation-root prim to fix.

• stage – The stage containing the prim. Defaults to the current stage.

Returns:

The articulation-root prim after backend normalization.

Raises:

NotImplementedError – If a new joint is needed and the root is not a rigid body.

classmethod forward() → None

Update articulation kinematics without stepping physics.

Update body poses from joint coordinates via the solver-specialized FK delegate (_eval_fk, bound to the active subclass’s _eval_fk_impl() in initialize_solver()). Only the articulations flagged dirty in _fk_reset_mask and _world_reset_mask (see invalidate_fk()) are updated. The masks are consumed (zeroed) afterwards so the next step() does not redundantly re-solve them.

The delegate (rather than a direct cls._eval_fk_impl call) is required because the data layer invokes NewtonManager.forward() on the base class, where cls is the base NewtonManager; the bound delegate dispatches to the concrete subclass override.

classmethod get_backend() → str

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

classmethod get_contacts() → Contacts | None

Get the current Newton contact buffer, if the active solver exposes one.

classmethod get_control() → newton.Control

Get the control object.

classmethod get_device() → str

Get the physics simulation device.

classmethod get_dt() → float

Get the physics timestep. Alias for get_physics_dt().

classmethod get_model() → newton.Model

Get the Newton model.

When the active sim backend is Newton this returns the manager’s own authoritative model. When the active sim backend is PhysX a shadow Newton model is built lazily (from the visualizer prebuilt artifact) so renderers/visualizers that operate on Newton Model and State can still drive a PhysX-simulated scene.

classmethod get_physics_dt() → float

Get the physics timestep in seconds.

classmethod get_physics_sim_view() → list

Get the list of registered views.

Assets can append their views to this list, and sensors can access them. Returns a list that callers can append to.

Returns:

List of registered views (e.g., NewtonArticulationView instances).

classmethod get_scene_data_backend() → SceneDataBackend | None

Return the SceneDataBackend for the SceneDataProvider.

classmethod get_scene_data_provider() → SceneDataProvider

Return the active scene data provider.

classmethod get_simulation_time() → float

Get the current simulation time in seconds.

classmethod get_solver_dt() → float

Get the solver substep timestep.

classmethod get_state(scene_data_provider: SceneDataProvider | None = None) → newton.State

Get the current Newton state for visualization.

Use this method from visualizers/renderers/video recorders that need a backend-agnostic Newton State. When the sim backend is PhysX this refreshes the shadow _state_0.body_q from the live PhysX scene via update_visualization_state() before returning, so callers never observe stale transforms. Under the Newton sim backend, pending forward kinematics is applied before returning the live state.

classmethod get_state_0() → newton.State

Get the current state.

classmethod get_state_1() → newton.State

Get the next state.

classmethod handles_decimation() → bool

True when step() executes the full decimation loop internally.

This is the case when all Newton actuators are CUDA-graph-safe. The full decimation loop (including the trivial decimation=1 case) is folded into a single step() call.

classmethod initialize(sim_context: SimulationContext) → None

Initialize the manager with simulation context.

Parameters:

sim_context – Parent simulation context.

TODO: Subclass should not override this method, once deformables supported on Newton import_usd, this can be unified with NewtonManager’s implementation.

classmethod initialize_solver() → None

Initialize the solver and collision pipeline.

Thin orchestrator: delegates solver construction to _build_solver() (overridden by each solver subclass), allocates the collision pipeline (when applicable) via _initialize_contacts(), then either captures the CUDA graph immediately or defers capture until the first step() call (RTX-active path).

Warning

When using a CUDA-enabled device, the simulation is graphed. This means the function steps the simulation once to capture the graph, so it should only be called after everything else in the simulation is initialized.

classmethod instantiate_builder_from_stage()

Create builder from USD stage with special treatment for deformable bodies, as these are not read from USD yet.

Detects env Xforms (e.g. /World/Env_0, /World/Env_1) and builds each as a separate Newton world via begin_world/end_world. Falls back to a flat add_usd when no env Xforms are found.

TODO: Subclass should not override this method, once deformables supported on Newton import_usd, this can be unified with NewtonManager’s implementation.

classmethod invalidate_body_state(env_ids: wp.array(dtype=wp.int32) | None = None, env_mask: wp.array(dtype=wp.bool) | None = None) → None

Mark selected maximal-coordinate body state as changed without requesting FK.

Parameters:

• env_ids – Integer indices of dirtied environments. Used by index write methods.

• env_mask – Boolean mask of dirtied environments. Used by mask write methods.

classmethod invalidate_fk(env_mask: wp.array | None = None, env_ids: wp.array | None = None, articulation_ids: wp.array | None = None) → None

Mark environments as needing FK recomputation and solver reset.

Called by asset write methods that modify joint coordinates or root transforms. The masks are consumed by the next forward, raw-state, rendering, or physics-step boundary.

Parameters:

• env_mask – Boolean mask of dirtied environments. Shape (num_envs,). Used by _mask write methods.

• env_ids – Integer indices of dirtied environments. Used by _index write methods.

• articulation_ids – Mapping from (world, arti) to model articulation index. Shape (world_count, count_per_world). Obtained from ArticulationView.articulation_ids.

classmethod is_fabric_enabled() → bool

Check if fabric interface is enabled (not applicable for Newton).

classmethod pause() → None

Pause physics simulation. Default is no-op.

classmethod play() → None

Start or resume physics simulation. Default is no-op.

classmethod pre_render() → None

Refresh derived Newton state before cameras and visualizers read it.

classmethod provides_implicit_damping() → bool

Whether this backend’s integrator has implicit numerical damping.

With implicit damping (PhysX, OV-PhysX) a camera policy can infer velocity from a single frame. Without it (Newton’s symplectic integrator) the policy needs a temporal cue in the observation (e.g. frame stacking).

The base default is True; backends without implicit damping override to False.

Returns:

Whether the backend’s integrator has implicit numerical damping.

classmethod register_callback(callback: Callable, event: PhysicsEvent, order: int = 0, name: str | None = None, wrap_weak_ref: bool = True) → CallbackHandle

Register a callback. Passes event to parent class.

classmethod register_particle_visual_prim(prim_path: str, particle_offset: int, particle_count: int, sync_frequency: int = 1) → None

Register a UsdGeom.Points prim whose points mirror a slice of Newton’s particle state.

Parameters:

• prim_path – Stage path of an existing UsdGeom.Points prim.

• particle_offset – First index of the prim’s slice in state.particle_q.

• particle_count – Number of particles in the slice.

• sync_frequency – Sync the prim every N dirty render frames.

classmethod register_post_actuator_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the actuator step on every iteration.

Each callback runs inside the captured CUDA graph (when _is_all_graphable() is True) right after NewtonActuatorAdapter.step() and before the solver substeps, so kernel writes to state/control are visible to the integrator on the same iteration. Multiple articulations register their own implicit-DOF telemetry / FF-routing kernels here; all registered callbacks fire in registration order each step.

classmethod register_post_step_callback(callback: Callable[[], None]) → None

Append a hook to the list invoked after the last solver substep on every step.

Each callback runs inside the stepped (and, when _is_all_graphable() is True, captured) region right after the final solver substep of the decimation loop and before _update_sensors(), so the launches it issues are recorded into every captured CUDA graph and replayed on each tick. The hook fires exactly once per step() call, reflecting the state after all decimation iterations (and their solver substeps) have completed – not once per substep and not once per decimation iteration. Callbacks must be graph-safe (fixed shapes, no host branching on device data) and must be registered before capture. Articulations with non-identity ordering register their backend-to-user state republish here; all registered callbacks fire in registration order each step.

classmethod request_extended_contact_attribute(attr: str) → None

Request an extended contact attribute (e.g. "force").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the model in start_simulation() so that subsequent Contacts creation includes them.

Parameters:

attr – Contact attribute name.

classmethod request_extended_state_attribute(attr: str) → None

Request an extended state attribute (e.g. "body_qdd").

Sensors call this during __init__, before model finalization. Attributes are forwarded to the builder in start_simulation() so that subsequent model.state() calls allocate them.

Parameters:

attr – State attribute name (must be in State.EXTENDED_ATTRIBUTES).

classmethod reset(soft: bool = False) → None

Reset physics simulation.

A hard reset (soft=False) re-finalizes the Newton model, reallocating its device arrays. The cached collision pipeline, contacts and any captured CUDA graph reference the old buffers, so they are released here and rebuilt against the re-finalized model by initialize_solver(). This avoids the illegal CUDA memory access (CUDA error 700) that would otherwise occur on the first step after a hard reset.

A soft reset (soft=True) skips this full reinitialization and reuses the existing model, solver, collision pipeline and CUDA graph.

Parameters:

soft – If True, skip full reinitialization.

static safe_callback_invoke(fn: Callable, *args, physics_manager: type[PhysicsManager] | None = None) → None

Invoke a callback, catching exceptions that would be swallowed by external event buses.

Ignores ReferenceError (from garbage-collected weakref proxies). All other exceptions are forwarded to physics_manager.``store_callback_exception`` when available (see note below), or re-raised immediately otherwise.

Note (Octi):

The carb event bus used by PhysX/Omniverse silently swallows exceptions raised inside callbacks. PhysxManager works around this by storing the exception and re-raising it after event dispatch completes (in reset() / step()). Backends that dispatch events directly (e.g. Newton) don’t need this — exceptions propagate normally — so store_callback_exception is not called for them. This is a known wart; a cleaner solution is actively being explored.

classmethod set_builder(builder: newton.ModelBuilder) → None

Set the Newton model builder.

classmethod set_decimation(decimation: int) → None

Set the decimation count and re-capture the CUDA graph.

When all actuators are graphable the entire decimation loop (actuators + solver substeps, repeated decimation times) is captured as a single CUDA graph.

If a CUDA graph was previously captured, it is automatically re-captured with the new decimation count using the same strategy as start_simulation(): standard wp.ScopedCapture when no USDRT stage is active, or deferred relaxed capture when RTX is running.

classmethod start_simulation() → None

Start simulation by finalizing model and initializing state.

This function finalizes the model and initializes the simulation state. Note: Collision pipeline is initialized later in initialize_solver() after we determine whether the solver needs external collision detection.

TODO: Subclass should not override this method, missing piece is having Newton bind a surface mesh to volume deformable tetrahedral mesh in addition to removing the deformable_registry data structure.

classmethod stop() → None

Stop physics simulation. Default is no-op.

classmethod sync_cables_to_usd() → None

Write Newton cable segment endpoints to Fabric curve points.

classmethod sync_particles_to_usd() → None

Write Newton particle positions to USD/Fabric for Kit viewport rendering.

Two prim families are synced from state_0.particle_q:

• Fabric mesh prims tagged with newton:particleOffset / newton:particleCount (deformable visual meshes) receive local-frame points on the GPU via _sync_fabric_mesh_particles().

• UsdGeom.Points prims registered through register_particle_visual_prim() (MPM particle clouds) receive world-frame points via _sync_particle_points_prims().

No-op when there is no particle state or nothing changed since the last sync.

classmethod sync_transforms_to_usd() → None

Write Newton body_q to USD Fabric world matrices for Kit viewport / RTX rendering.

No-op when _usdrt_stage is None (i.e. Kit visualizer is not active) or when transforms have not changed since the last sync.

Called at render cadence by pre_render() (via render()). Physics stepping marks transforms dirty via _mark_transforms_dirty() so that the expensive Fabric hierarchy update only runs once per render frame rather than after every physics step.

Uses wp.fabricarray directly (no isaacsim.physics.newton extension needed). The Warp kernel reads state_0.body_q[newton_index[i]] and writes the corresponding mat44d to omni:fabric:worldMatrix for each prim.

When IFabricHierarchy.update_world_xforms_gpu_with_options is available the method mirrors PhysX’s DirectGpuHelper pattern: pause Fabric change tracking, write transforms, resume tracking, then run the GPU hierarchy update with RIGID_BODY | FORCE_UPDATE so Newton-authored world matrices stay authoritative on rigid-body prims. Otherwise it falls back to the CPU update_world_xforms() path.

classmethod unregister_post_step_callback(callback: Callable[[], None]) → None

Remove a previously registered post-step callback.

Symmetric to register_post_step_callback(), this lets an articulation deregister its republish hook when its callbacks are cleared so the bound method does not linger on the class-level list after the articulation is gone. Removing a callback that was never registered (or was already removed) is a safe no-op, matching the tolerant deregistration of other handles.

classmethod update_visualization_state(scene_data_provider: SceneDataProvider | None = None) → None

Refresh visualization state for the active sim backend.

Newton sim backend: no-op — _state_0 is the live, authoritative state already advanced by step() / forward kinematics.

PhysX / OVPhysX sim backend: pull rigid-body transforms and deformable nodal positions from the SceneDataProvider and write them into the shadow _state_0.body_q / particle_q so Newton-native consumers (Newton renderer, Newton/Rerun/Viser visualizers, OVRTX renderer, Newton GL video) see fresh poses and mesh points.

Calls use allow_passthrough=False so identity mappings still copy into the pre-bound shadow buffers. Passthrough would rebind the temporary SceneDataFormat fields away from _state_0, leaving OVRTX and other get_state() consumers on stale rest-pose particle / body state.

Invoked lazily from get_state() so consumers do not need to coordinate the sync explicitly.

classmethod video_capture_backend() → str

Newton GL headless perspective video capture.

classmethod wait_for_playing() → None

Block until the timeline is playing. Default is no-op.

class isaaclab_contrib.custom_coupling.franka_soft_env_cfg.FrankaSoftCustomCouplingEnvCfg

Bases: FrankaSoftEnvCfg

Franka soft lifting with manual MJWarp and VBD coupling.

Methods:

__init__([sim, ui_window_class_type, seed, ...])

Attributes:

sim	Physics simulation configuration.
ui_window_class_type	The class type of the UI window.
seed	The seed for the random number generator.
decimation	Number of control action updates @ sim dt per policy dt.
scene	Scene settings.
recorders	Recorder settings.
observations	Observation space settings.
actions	Action space settings.
events	Event settings.
rerender_on_reset	Whether a render step is performed again after at least one environment has been reset.
num_rerenders_on_reset	Number of render steps to perform after reset.
wait_for_textures	True to wait for assets to be loaded completely, False otherwise.
xr	Configuration for viewing and interacting with the environment through an XR device.
teleop_devices	Configuration for teleoperation devices.
isaac_teleop	Configuration for IsaacTeleop-based teleoperation.
export_io_descriptors	Whether to export the IO descriptors for the environment.
log_dir	Directory for logging experiment artifacts.
video_recorders	Video recording streams.
viewer	Deprecated viewer configuration.
is_finite_horizon	Whether the learning task is treated as a finite or infinite horizon problem for the agent.
compute_final_obs	Whether to capture the terminal observation before a Same-Step autoreset and expose it.
episode_length_s	Duration of an episode (in seconds).
rewards	Reward settings.
terminations	Termination settings.
curriculum	Curriculum settings.
commands	Command settings.

__init__(sim: SimulationCfg = <factory>, ui_window_class_type: type | str | None = <factory>, seed: int | None = <factory>, decimation: int = <factory>, scene: FrankaSoftSceneCfg = <factory>, recorders: object = <factory>, observations: ObservationsCfg = <factory>, actions: ActionsCfg = <factory>, events: EventCfg = <factory>, rerender_on_reset: bool = <factory>, num_rerenders_on_reset: int = <factory>, wait_for_textures: bool = <factory>, xr: XrCfg | None = <factory>, teleop_devices: DevicesCfg = <factory>, isaac_teleop: object | None = <factory>, export_io_descriptors: bool = <factory>, log_dir: str | None = <factory>, video_recorders: list[VideoRecorderCfg] = <factory>, viewer: ViewerCfg = <factory>, is_finite_horizon: bool = <factory>, compute_final_obs: bool = <factory>, episode_length_s: float = <factory>, rewards: RewardsCfg = <factory>, terminations: TerminationsCfg = <factory>, curriculum: object | None = <factory>, commands: CommandsCfg = <factory>) → None

sim: SimulationCfg

Physics simulation configuration. Default is SimulationCfg().

ui_window_class_type: type | str | None

The class type of the UI window. Default is None.

If None, then no UI window is created.

Note

If you want to make your own UI window, you can create a class that inherits from from isaaclab.envs.ui.base_env_window.BaseEnvWindow. Then, you can set this attribute to your class type.

seed: int | None

The seed for the random number generator. Defaults to None, in which case the seed is not set.

Note

The seed is set at the beginning of the environment initialization. This ensures that the environment creation is deterministic and behaves similarly across different runs.

decimation: int

Number of control action updates @ sim dt per policy dt.

For instance, if the simulation dt is 0.01s and the policy dt is 0.1s, then the decimation is 10. This means that the control action is updated every 10 simulation steps.

scene: FrankaSoftSceneCfg

Scene settings.

Please refer to the isaaclab.scene.InteractiveSceneCfg class for more details.

recorders: object

Recorder settings. Defaults to recording nothing.

Please refer to the isaaclab.managers.RecorderManager class for more details.

observations: ObservationsCfg

Observation space settings.

Please refer to the isaaclab.managers.ObservationManager class for more details.

actions: ActionsCfg

Action space settings.

Please refer to the isaaclab.managers.ActionManager class for more details.

events: EventCfg

Event settings. Defaults to the basic configuration that resets the scene to its default state.

Please refer to the isaaclab.managers.EventManager class for more details.

rerender_on_reset: bool

Whether a render step is performed again after at least one environment has been reset. Defaults to False, which means no render step will be performed after reset.

• When this is False, data collected from sensors after performing reset will be stale and will not reflect the latest states in simulation caused by the reset.

• When this is True, an extra render step will be performed to update the sensor data to reflect the latest states from the reset. This comes at a cost of performance as an additional render step will be performed after each time an environment is reset.

Deprecated since version 2.3.1: This attribute is deprecated and will be removed in the future. Please use num_rerenders_on_reset instead.

To get the same behaviour as setting this parameter to True or False, set num_rerenders_on_reset to 1 or 0, respectively.

num_rerenders_on_reset: int

Number of render steps to perform after reset. Defaults to 0, which means no render step will be performed after reset.

• When this is 0, no render step will be performed after reset. Data collected from sensors after performing reset will be stale and will not reflect the latest states in simulation caused by the reset.

• When this is greater than 0, the specified number of extra render steps will be performed to update the sensor data to reflect the latest states from the reset. This comes at a cost of performance as additional render steps will be performed after each time an environment is reset.

wait_for_textures: bool

True to wait for assets to be loaded completely, False otherwise. Defaults to True.

xr: XrCfg | None

Configuration for viewing and interacting with the environment through an XR device.

teleop_devices: DevicesCfg

Configuration for teleoperation devices.

isaac_teleop: object | None

Configuration for IsaacTeleop-based teleoperation.

When set, the environment uses the IsaacTeleop stack for XR teleoperation instead of the native Isaac Lab teleop devices. This should be a IsaacTeleopCfg instance from the isaaclab_teleop package.

The teleop scripts will automatically detect this configuration and use the IsaacTeleop stack when present.

export_io_descriptors: bool

Whether to export the IO descriptors for the environment. Defaults to False.

log_dir: str | None

Directory for logging experiment artifacts. Defaults to None, in which case no specific log directory is set.

video_recorders: list[VideoRecorderCfg]

Video recording streams. Each entry records from its configured source independently.

Leave empty to disable recording. Set --video on the CLI to auto-populate this list with a default stream from the active visualizer.

viewer: ViewerCfg

Deprecated viewer configuration. Use default_visualizer_cfg or visualizer_cfgs instead.

Deprecated since version This: field is deprecated and will be removed in a future release. Configure the viewport camera via VisualizerCfg on the simulation config::

from isaaclab.visualizers import VisualizerCfg env_cfg.sim.default_visualizer_cfg = VisualizerCfg(eye=(4.5, 0.0, 6.0))

is_finite_horizon: bool

Whether the learning task is treated as a finite or infinite horizon problem for the agent. Defaults to False, which means the task is treated as an infinite horizon problem.

This flag handles the subtleties of finite and infinite horizon tasks:

• Finite horizon: no penalty or bootstrapping value is required by the the agent for running out of time. However, the environment still needs to terminate the episode after the time limit is reached.

• Infinite horizon: the agent needs to bootstrap the value of the state at the end of the episode. This is done by sending a time-limit (or truncated) done signal to the agent, which triggers this bootstrapping calculation.

If True, then the environment is treated as a finite horizon problem and no time-out (or truncated) done signal is sent to the agent. If False, then the environment is treated as an infinite horizon problem and a time-out (or truncated) done signal is sent to the agent.

Note

The base ManagerBasedRLEnv class does not use this flag directly. It is used by the environment wrappers to determine what type of done signal to send to the corresponding learning agent.

compute_final_obs: bool

Whether to capture the terminal observation before a Same-Step autoreset and expose it.

Under Same-Step autoreset (see metadata), an environment that terminates is reset within the same step() call, so the returned observation belongs to the new episode. When this flag is True, the observation is computed once more before the reset and stored under extras["final_obs"], so wrappers can report it as the true terminal observation for value bootstrapping.

Defaults to False, which preserves the previous behavior: no terminal observation is captured, extras["final_obs"] is not populated, and the extra observation computation is skipped.

Note

Currently consumed by the Sb3VecEnvWrapper wrapper.

episode_length_s: float

Duration of an episode (in seconds).

Based on the decimation rate and physics time step, the episode length is calculated as:

episode_length_steps = ceil(episode_length_s / (decimation_rate * physics_time_step))

For example, if the decimation rate is 10, the physics time step is 0.01, and the episode length is 10 seconds, then the episode length in steps is 100.

rewards: RewardsCfg

Reward settings.

Please refer to the isaaclab.managers.RewardManager class for more details.

terminations: TerminationsCfg

Termination settings.

Please refer to the isaaclab.managers.TerminationManager class for more details.

curriculum: object | None

Curriculum settings. Defaults to None, in which case no curriculum is applied.

Please refer to the isaaclab.managers.CurriculumManager class for more details.

commands: CommandsCfg

Command settings. Defaults to None, in which case no commands are generated.

Please refer to the isaaclab.managers.CommandManager class for more details.