Migration of Deformables

In the newer versions of Omni Physics (107.0 and later), the old deformable body functionality has become deprecated. The following sections describe the changes to migrate to the new Omni Physics API, specifically moving away from Soft Bodies and towards Surface and Volume Deformables. The deformable object asset classes remain in isaaclab.assets. Schema define/modify functions remain unified in isaaclab.sim.schemas, and deformable material spawning remains unified in isaaclab.sim.spawners.materials. Deformable property and material configuration classes are backend-specific: PhysX configurations live in isaaclab_physx.sim and Newton configurations live in isaaclab_newton.sim.

Note

The following changes are with respect to Isaac Lab v3.0.0 and Omni Physics v110.0. Please refer to the release notes for any changes in the future releases.

Surface and Volume Deformables

With the new Omni Physics API, deformable bodies are split into two distinct types, as described in the Omni Physics documentation:

• Volume deformables: 3D objects simulated with a tetrahedral FEM mesh (e.g., soft cubes, spheres, capsules). These support kinematic targets on individual vertices. The simulation operates on a tetrahedral mesh internally, while a separate triangle surface mesh handles rendering.

• Surface deformables: 2D surfaces simulated directly on a triangle mesh (e.g., cloth, fabric, membranes). These have additional material properties for controlling stretch, shear, and bend stiffness, but do not support kinematic vertex targets.

The type of deformable is determined by the physics material assigned to the object:

• PhysxDeformableBodyMaterialCfg creates a PhysX volume deformable.

• PhysxSurfaceDeformableBodyMaterialCfg creates a PhysX surface deformable.

• NewtonDeformableBodyMaterialCfg creates a Newton volume deformable.

• NewtonSurfaceDeformableBodyMaterialCfg creates a Newton surface deformable.

Migration from the Old API

Import Changes

Deformable object cfgs remain in isaaclab.assets. Deformable schema and material cfgs should be imported from the physics backend package:

Old Import	New Import
from isaaclab.sim import DeformableBodyPropertiesCfg	from isaaclab_physx.sim import PhysxDeformableBodyPropertiesCfg
from isaaclab.sim import DeformableBodyMaterialCfg	from isaaclab_physx.sim import PhysxDeformableBodyMaterialCfg
from isaaclab.sim import SurfaceDeformableBodyMaterialCfg	from isaaclab_physx.sim import PhysxSurfaceDeformableBodyMaterialCfg
from isaaclab.sim import DeformableBodyPropertiesCfg	from isaaclab_newton.sim.schemas import NewtonDeformableBodyPropertiesCfg
from isaaclab.sim import DeformableBodyMaterialCfg	from isaaclab_newton.sim.spawners.materials import NewtonDeformableBodyMaterialCfg
from isaaclab.sim import SurfaceDeformableBodyMaterialCfg	from isaaclab_newton.sim.spawners.materials import NewtonSurfaceDeformableBodyMaterialCfg
from isaaclab_physx.assets import DeformableObjectCfg	from isaaclab.assets import DeformableObjectCfg

Removed Properties

The following properties have been removed from PhysxDeformableBodyPropertiesCfg:

• collision_simplification and related parameters (collision_simplification_remeshing, collision_simplification_target_triangle_count, collision_simplification_force_conforming, collision_simplification_remove_open_edges) — collision mesh generation is now handled automatically by PhysX through deformableUtils.create_auto_volume_deformable_hierarchy() and deformableUtils.create_auto_surface_deformable_hierarchy().

• simulation_hexahedral_resolution — the simulation mesh resolution is no longer user-configurable; PhysX determines it automatically.

• vertex_velocity_damping — replaced by the more general linear_damping property from the PhysX deformable schema.

• sleep_damping — replaced by settling_damping in the PhysX deformable schema.

Added Properties

The following properties have been added to PhysxDeformableBodyPropertiesCfg:

• deformable_body_enabled, kinematic_enabled, and mass — OmniPhysics deformable body properties owned by the PhysX backend cfg.

• linear_damping — linear damping coefficient [1/s].

• max_linear_velocity — maximum allowable linear velocity [m/s]. A negative value lets the simulation choose a per-vertex value dynamically (currently only supported for surface deformables).

• settling_damping — additional damping applied when vertex velocity falls below settling_threshold [1/s].

• enable_speculative_c_c_d — enables speculative continuous collision detection.

• disable_gravity — per-deformable gravity control.

• collision_pair_update_frequency — how often surface-to-surface collision pairs are updated per time step (surface deformables only).

• collision_iteration_multiplier — collision subiterations per solver iteration (surface deformables only).

For a full description of all available properties, refer to the PhysX deformable schema and OmniPhysics deformable schema documentation.

Material Changes

The deformable material hierarchy is now split by backend:

• DeformableBodyMaterialBaseCfg and SurfaceDeformableBodyMaterialBaseCfg — empty base classes for backend-specific deformable material configs.

• PhysxDeformableBodyMaterialCfg — for PhysX volume deformables. Contains density, static_friction, dynamic_friction, youngs_modulus, poissons_ratio, and elasticity_damping.

• PhysxSurfaceDeformableBodyMaterialCfg — extends the PhysX volume material config with surface-specific properties: surface_thickness, surface_stretch_stiffness, surface_shear_stiffness, surface_bend_stiffness, and bend_damping.

• NewtonDeformableBodyMaterialCfg and NewtonSurfaceDeformableBodyMaterialCfg contain Newton-specific fields such as density, particle radius, direct Lame parameters k_mu/k_lambda for volume deformables, and VBD stiffness parameters for surface deformables.

The old damping_scale property has been removed. Use elasticity_damping directly instead.

DeformableObject View Change

The internal PhysX view type has changed from physx.SoftBodyView to physx.DeformableBodyView. The property root_physx_view has been deprecated in favor of root_view.

Code Examples

Volume Deformable (Before and After)

Before:

import isaaclab.sim as sim_utils
from isaaclab.assets import DeformableObject, DeformableObjectCfg

cfg = DeformableObjectCfg(
    prim_path="/World/Origin.*/Cube",
    spawn=sim_utils.MeshCuboidCfg(
        size=(0.2, 0.2, 0.2),
        deformable_props=sim_utils.DeformableBodyPropertiesCfg(),
        visual_material=sim_utils.PreviewSurfaceCfg(),
        physics_material=sim_utils.DeformableBodyMaterialCfg(poissons_ratio=0.4, youngs_modulus=1e5),
    ),
)
cube_object = DeformableObject(cfg=cfg)

After:

import isaaclab.sim as sim_utils
from isaaclab.assets import DeformableObject, DeformableObjectCfg
from isaaclab_physx.sim import PhysxDeformableBodyMaterialCfg, PhysxDeformableBodyPropertiesCfg

cfg = DeformableObjectCfg(
    prim_path="/World/Origin.*/Cube",
    spawn=sim_utils.MeshCuboidCfg(
        size=(0.2, 0.2, 0.2),
        deformable_props=PhysxDeformableBodyPropertiesCfg(),
        visual_material=sim_utils.PreviewSurfaceCfg(),
        physics_material=PhysxDeformableBodyMaterialCfg(poissons_ratio=0.4, youngs_modulus=1e5),
    ),
)
cube_object = DeformableObject(cfg=cfg)

Surface Deformable (New)

Surface deformables use MeshRectangleCfg for 2D meshes, combined with PhysxSurfaceDeformableBodyMaterialCfg:

import isaaclab.sim as sim_utils
from isaaclab.assets import DeformableObject, DeformableObjectCfg
from isaaclab_physx.sim import PhysxDeformableBodyPropertiesCfg, PhysxSurfaceDeformableBodyMaterialCfg

cfg = DeformableObjectCfg(
    prim_path="/World/Origin.*/Cloth",
    spawn=sim_utils.MeshRectangleCfg(
        size=(1.5, 1.5),
        resolution=(21, 21),
        deformable_props=PhysxDeformableBodyPropertiesCfg(),
        visual_material=sim_utils.PreviewSurfaceCfg(),
        physics_material=PhysxSurfaceDeformableBodyMaterialCfg(poissons_ratio=0.4, youngs_modulus=1e5),
    ),
)
cloth_object = DeformableObject(cfg=cfg)

USD File Deformable

Deformable properties can also be applied to imported USD assets using UsdFileCfg:

import isaaclab.sim as sim_utils
from isaaclab.assets import DeformableObject, DeformableObjectCfg
from isaaclab_physx.sim import PhysxDeformableBodyMaterialCfg, PhysxDeformableBodyPropertiesCfg

from isaaclab.utils.assets import ISAACLAB_NUCLEUS_DIR

cfg = DeformableObjectCfg(
    prim_path="/World/Origin.*/Teddy",
    spawn=sim_utils.UsdFileCfg(
        usd_path=f"{ISAACLAB_NUCLEUS_DIR}/Objects/Teddy_Bear/teddy_bear.usd",
        deformable_props=PhysxDeformableBodyPropertiesCfg(),
        physics_material=PhysxDeformableBodyMaterialCfg(poissons_ratio=0.4, youngs_modulus=1e5),
        scale=[0.05, 0.05, 0.05],
    ),
)
teddy_object = DeformableObject(cfg=cfg)

Limitations

• Kinematic targets are volume-only. Calling write_nodal_kinematic_target_to_sim_index() on a surface deformable will raise a ValueError.

• Surface-specific solver properties (collision_pair_update_frequency, collision_iteration_multiplier) have no effect on volume deformables.

• Newton deformables are experimental. They are implemented in isaaclab_contrib.deformable and currently target VBD-based solvers and coupled rigid-deformable workflows.