isaaclab_contrib.deformable

isaaclab_contrib.deformable#

Sub-package for externally contributed assets.

This package contains contributed code that depends on Isaac Lab’s public API but is not required for core functionality. This includes implementations of Newton solvers for deformables.

Classes

`deformable_object.DeformableObject`	A deformable object asset class (Newton backend).
`deformable_object_data.DeformableObjectData`	Data container for a deformable object (Newton backend).

Deformable Object#

class isaaclab_contrib.deformable.deformable_object.DeformableObject[source]#

Bases: BaseDeformableObject

A deformable object asset class (Newton backend).

This class manages cloth/deformable bodies in the Newton physics engine. Newton stores all particles in flat arrays (state.particle_q, state.particle_qd). This class builds a per-instance indexing layer on top of those flat arrays, enabling the standard BaseDeformableObject interface for reading/writing nodal state.

The cloth mesh is added to the Newton ModelBuilder during the MODEL_INIT phase. The mesh data is read from the USD prim at cfg.prim_path, and cloth simulation parameters (density, stiffness, etc.) come from DeformableObjectCfg.

Attributes:

`cfg`	Configuration instance for the deformable object.
`data`	Data container for the deformable object.
`num_instances`	Number of instances of the asset.
`num_bodies`	Number of bodies in the asset.
`max_sim_vertices_per_body`	The maximum number of simulation mesh vertices per deformable body.
`device`	Memory device for computation.
`has_debug_vis_implementation`	Whether the asset has a debug visualization implemented.
`is_initialized`	Whether the asset is initialized.

Methods:

`__init__`(cfg)	Initialize the deformable object.
`reset`([env_ids, env_mask])	Reset the deformable object.
`write_data_to_sim`()	Apply kinematic targets to the Newton simulation.
`update`(dt)	Update the internal buffers.
`write_nodal_pos_to_sim_index`(nodal_pos[, ...])	Set the nodal positions over selected environment indices into the simulation.
`write_nodal_velocity_to_sim_index`(nodal_vel)	Set the nodal velocity over selected environment indices into the simulation.
`write_nodal_kinematic_target_to_sim_index`(targets)	Set the kinematic targets of the simulation mesh for the deformable bodies.
`write_nodal_state_to_sim_mask`(nodal_state[, ...])	Set the nodal state over selected environment mask into the simulation.
`write_nodal_pos_to_sim_mask`(nodal_pos[, ...])	Set the nodal positions over selected environment mask into the simulation.
`write_nodal_velocity_to_sim_mask`(nodal_vel)	Set the nodal velocity over selected environment mask into the simulation.
`write_nodal_kinematic_target_to_sim_mask`(targets)	Set the kinematic targets over selected environment mask into the target buffer.
`assert_shape_and_dtype`(tensor, shape, dtype)	Assert the shape and dtype of a tensor or warp array.
`assert_shape_and_dtype_mask`(tensor, masks, dtype)	Assert the shape of a tensor or warp array against mask dimensions.
`set_debug_vis`(debug_vis)	Sets whether to visualize the asset data.
`set_visibility`(visible[, env_ids])	Set the visibility of the prims corresponding to the asset.
`transform_nodal_pos`(nodal_pos[, pos, quat])	Transform the nodal positions based on the pose transformation.
`write_nodal_kinematic_target_to_sim`(targets)	Deprecated.
`write_nodal_pos_to_sim`(nodal_pos[, env_ids])	Deprecated.
`write_nodal_state_to_sim`(nodal_state[, env_ids])	Deprecated.
`write_nodal_state_to_sim_index`(nodal_state)	Set the nodal state over selected environment indices into the simulation.
`write_nodal_velocity_to_sim`(nodal_vel[, env_ids])	Deprecated.

cfg: DeformableObjectCfg#: Configuration instance for the deformable object.

__init__(cfg: DeformableObjectCfg)[source]#

Initialize the deformable object.

Parameters:: cfg¶ – A configuration instance.

property data: DeformableObjectData#: Data container for the deformable object.

property num_instances: int#: Number of instances of the asset.

property num_bodies: int#

Number of bodies in the asset.

This is always 1 since each object is a single deformable body.

property max_sim_vertices_per_body: int#: The maximum number of simulation mesh vertices per deformable body.

reset(env_ids: Sequence[int] | None = None, env_mask: wp.array | None = None) → None[source]#

Reset the deformable object.

No-op to match the PhysX deformable object convention.

Parameters:

env_ids¶ – Environment indices. If None, then all indices are used.
env_mask¶ – Environment mask. If None, then all the instances are updated. Shape is (num_instances,).

write_data_to_sim()[source]#

Apply kinematic targets to the Newton simulation.

Reads the stored kinematic target buffer and enforces it on particles: kinematic particles (flag=0) get inv_mass=0, particle_flags=0, target position, and zero velocity; free particles (flag=1) get their original inv_mass and particle_flags=1 (ACTIVE) restored.

Writes to both state_0 and state_1 so kinematic positions survive the state swaps that happen between substeps.

update(dt: float)[source]#

Update the internal buffers.

Parameters:: dt¶ – The amount of time passed from last update() call [s].

Set the nodal positions over selected environment indices into the simulation.

Parameters:

nodal_pos¶ – Nodal positions in simulation frame [m]. Shape is (len(env_ids), max_sim_vertices_per_body, 3) or (num_instances, max_sim_vertices_per_body, 3).
env_ids¶ – Environment indices. If None, then all indices are used.
full_data¶ – Whether to expect full data. Defaults to False.

Set the nodal velocity over selected environment indices into the simulation.

Parameters:

nodal_vel¶ – Nodal velocities in simulation frame [m/s]. Shape is (len(env_ids), max_sim_vertices_per_body, 3) or (num_instances, max_sim_vertices_per_body, 3).
env_ids¶ – Environment indices. If None, then all indices are used.
full_data¶ – Whether to expect full data. Defaults to False.

Set the kinematic targets of the simulation mesh for the deformable bodies.

Newton has no native kinematic target API. Instead: - Kinematic (flag=0.0): set particle_inv_mass to 0, write target pos, zero vel - Free (flag=1.0): restore original particle_inv_mass

Parameters:

targets¶ – The kinematic targets comprising of nodal positions and flags [m]. Shape is (len(env_ids), max_sim_vertices_per_body, 4) or (num_instances, max_sim_vertices_per_body, 4).
env_ids¶ – Environment indices. If None, then all indices are used.
full_data¶ – Whether to expect full data. Defaults to False.

write_nodal_state_to_sim_mask(nodal_state: torch.Tensor | wp.array | ProxyArray, env_mask: wp.array | torch.Tensor | None = None) → None[source]#

Set the nodal state over selected environment mask into the simulation.

Parameters:

nodal_state¶ – Nodal state in simulation frame [m, m/s]. Shape is (num_instances, max_sim_vertices_per_body, 6).
env_mask¶ – Environment mask. If None, then all indices are used. Shape is (num_instances,).

write_nodal_pos_to_sim_mask(nodal_pos: torch.Tensor | wp.array | ProxyArray, env_mask: wp.array | torch.Tensor | None = None) → None[source]#

Set the nodal positions over selected environment mask into the simulation.

Parameters:

nodal_pos¶ – Nodal positions in simulation frame [m]. Shape is (num_instances, max_sim_vertices_per_body, 3).
env_mask¶ – Environment mask. If None, then all indices are used. Shape is (num_instances,).

write_nodal_velocity_to_sim_mask(nodal_vel: torch.Tensor | wp.array | ProxyArray, env_mask: wp.array | torch.Tensor | None = None) → None[source]#

Set the nodal velocity over selected environment mask into the simulation.

Parameters:

nodal_vel¶ – Nodal velocities in simulation frame [m/s]. Shape is (num_instances, max_sim_vertices_per_body, 3).
env_mask¶ – Environment mask. If None, then all indices are used. Shape is (num_instances,).

write_nodal_kinematic_target_to_sim_mask(targets: torch.Tensor | wp.array | ProxyArray, env_mask: wp.array | torch.Tensor | None = None) → None[source]#

Set the kinematic targets over selected environment mask into the target buffer.

Parameters:

targets¶ – The kinematic targets comprising of nodal positions and flags [m]. Shape is (num_instances, max_sim_vertices_per_body, 4).
env_mask¶ – Environment mask. If None, then all indices are used. Shape is (num_instances,).

assert_shape_and_dtype(tensor: float | torch.Tensor | wp.array, shape: tuple[int, ...], dtype: type, name: str = '', *, axis_sizes: tuple[int, ...] | None = None) → None#

Assert the shape and dtype of a tensor or warp array.

Controlled by AssetBaseCfg.disable_shape_checks. When checks are disabled this method is a no-op.

Parameters:

tensor¶ – The tensor or warp array to assert the shape of. Floats are skipped.
shape¶ – The expected leading dimensions (e.g. (num_envs, num_joints)).
dtype¶ – The expected warp dtype.
name¶ – Optional parameter name for error messages.
axis_sizes¶ – Optional selector sizes. Defaults to the expected leading dimensions.

assert_shape_and_dtype_mask(tensor: float | torch.Tensor | wp.array, masks: tuple[wp.array, ...], dtype: type, name: str = '', trailing_dims: tuple[int, ...] = ()) → None#

Assert the shape of a tensor or warp array against mask dimensions.

Mask-based write methods expect full-sized data — one element per entry in each mask dimension, regardless of how many entries are True. The expected leading shape is therefore (mask_0.shape[0], mask_1.shape[0], ...) (i.e. the total size of each dimension, not the number of selected entries).

Controlled by AssetBaseCfg.disable_shape_checks. When checks are disabled this method is a no-op.

Parameters:

tensor¶ – The tensor or warp array to assert the shape of. Floats are skipped.
masks¶ – Tuple of mask arrays whose shape[0] dimensions form the expected leading shape.
dtype¶ – The expected warp dtype.
name¶ – Optional parameter name for error messages.
trailing_dims¶ – Extra trailing dimensions to append (e.g. (9,) for inertias with wp.float32).

property device: str#: Memory device for computation.

property has_debug_vis_implementation: bool#: Whether the asset has a debug visualization implemented.

property is_initialized: bool#

Whether the asset is initialized.

Returns True if the asset is initialized, False otherwise.

set_debug_vis(debug_vis: bool) → bool#

Sets whether to visualize the asset data.

Parameters:: debug_vis¶ – Whether to visualize the asset data.
Returns:: Whether the debug visualization was successfully set. False if the asset does not support debug visualization.

set_visibility(visible: bool, env_ids: Sequence[int] | None = None)#

Set the visibility of the prims corresponding to the asset.

This operation affects the visibility of the prims corresponding to the asset in the USD stage. It is useful for toggling the visibility of the asset in the simulator. For instance, one can hide the asset when it is not being used to reduce the rendering overhead.

Note

This operation uses the PXR API to set the visibility of the prims. Thus, the operation may have an overhead if the number of prims is large.

Parameters:

visible¶ – Whether to make the prims visible or not.
env_ids¶ – The indices of the object to set visibility. Defaults to None (all instances).

transform_nodal_pos(nodal_pos: torch.Tensor, pos: torch.Tensor | None = None, quat: torch.Tensor | None = None) → torch.Tensor#

Transform the nodal positions based on the pose transformation.

This function computes the transformation of the nodal positions based on the pose transformation. It multiplies the nodal positions with the rotation matrix of the pose and adds the translation. Internally, it calls the isaaclab.utils.math.transform_points() function.

Parameters:

nodal_pos¶ – The nodal positions in the simulation frame [m]. Shape is (N, max_sim_vertices_per_body, 3).
pos¶ – The position transformation [m]. Shape is (N, 3). Defaults to None, in which case the position is assumed to be zero.
quat¶ – The orientation transformation as quaternion (x, y, z, w). Shape is (N, 4). Defaults to None, in which case the orientation is assumed to be identity.

Returns:

The transformed nodal positions [m]. Shape is (N, max_sim_vertices_per_body, 3).

write_nodal_kinematic_target_to_sim(targets: torch.Tensor | wp.array | ProxyArray, env_ids: Sequence[int] | torch.Tensor | wp.array | None = None) → None#: Deprecated. Please use write_nodal_kinematic_target_to_sim_index() instead.

write_nodal_pos_to_sim(nodal_pos: torch.Tensor | wp.array | ProxyArray, env_ids: Sequence[int] | torch.Tensor | wp.array | None = None) → None#: Deprecated. Please use write_nodal_pos_to_sim_index() instead.

write_nodal_state_to_sim(nodal_state: torch.Tensor | wp.array | ProxyArray, env_ids: Sequence[int] | torch.Tensor | wp.array | None = None) → None#: Deprecated. Please use write_nodal_state_to_sim_index() instead.

Set the nodal state over selected environment indices into the simulation.

The nodal state comprises of the nodal positions and velocities. Since these are nodes, the velocity only has a translational component. All the quantities are in the simulation frame.

Parameters:

nodal_state¶ – Nodal state in simulation frame [m, m/s]. Shape is (len(env_ids), max_sim_vertices_per_body, 6) or (num_instances, max_sim_vertices_per_body, 6).
env_ids¶ – Environment indices. If None, then all indices are used.
full_data¶ – Whether to expect full data. Defaults to False.

write_nodal_velocity_to_sim(nodal_vel: torch.Tensor | wp.array | ProxyArray, env_ids: Sequence[int] | torch.Tensor | wp.array | None = None) → None#: Deprecated. Please use write_nodal_velocity_to_sim_index() instead.

class isaaclab_contrib.deformable.deformable_object_data.DeformableObjectData[source]#

Bases: BaseDeformableObjectData

Data container for a deformable object (Newton backend).

Newton stores all particles in flat arrays (model.particle_q, state.particle_qd). This data class builds a per-instance view by gathering from the flat arrays using precomputed offsets.

The data is lazily updated, meaning that the data is only updated when it is accessed.

Attributes:

`default_nodal_state_w`	Default nodal state `[nodal_pos, nodal_vel]` in simulation world frame.
`nodal_kinematic_target`	Simulation mesh kinematic targets for the deformable bodies.
`nodal_pos_w`	Nodal positions in simulation world frame [m].
`nodal_vel_w`	Nodal velocities in simulation world frame [m/s].
`nodal_state_w`	Nodal state `[nodal_pos, nodal_vel]` in simulation world frame [m, m/s].
`root_pos_w`	Root position from nodal positions [m].
`root_vel_w`	Root velocity from nodal velocities [m/s].

Methods:

update(dt)

Update the data for the deformable object.

default_nodal_state_w: ProxyArray = None#: Default nodal state [nodal_pos, nodal_vel] in simulation world frame. Shape is (num_instances, particles_per_body) with dtype vec6f.

nodal_kinematic_target: ProxyArray = None#: Simulation mesh kinematic targets for the deformable bodies. Shape is (num_instances, particles_per_body) with dtype vec4f.

property nodal_pos_w: ProxyArray#: Nodal positions in simulation world frame [m]. Shape is (num_instances, particles_per_body) vec3f.

property nodal_vel_w: ProxyArray#: Nodal velocities in simulation world frame [m/s]. Shape is (num_instances, particles_per_body) vec3f.

property nodal_state_w: ProxyArray#

Nodal state [nodal_pos, nodal_vel] in simulation world frame [m, m/s].

Shape is (num_instances, particles_per_body) vec6f.

property root_pos_w: ProxyArray#

Root position from nodal positions [m]. Shape is (num_instances,) vec3f.

This quantity is computed as the mean of the nodal positions.

update(dt: float)#

Update the data for the deformable object.

Parameters:: dt¶ – The time step for the update [s]. This must be a positive value.

property root_vel_w: ProxyArray#

Root velocity from nodal velocities [m/s]. Shape is (num_instances,) vec3f.

This quantity is computed as the mean of the nodal velocities.

isaaclab_contrib.deformable

Contents

isaaclab_contrib.deformable#

Deformable Object#