ASR Model APIs

The Affine-Soft-Robot (ASR) model integrates the states of affine bodies, soft bodies, and robots. Robot links and rigid bodies are efficiently modeled as affine bodies to capture their primarily rigid motion, while VBTSs are simulated as soft bodies to accurately represent their deformation mechanics.

class warp_ipc.sim_model.ASRModel(num_envs: int = 1, viz_envs: list[int] = [], device='cuda:0')

Bases: Model

ABD-IPC-Robots Model

num_envs

Number of parallel simulation environments. Each environment has independent collision detection and iterative solving. Defaults to 1.

Type:

int

elapsed_time

The simulation time elapsed for the current model.

Type:

float

frame

Number of simulation frames elapsed for the current model.

Type:

int

viz

Enables visualization using warp.sim.

Type:

bool

viz_envs

Indices of environments to visualize. Must be within [0, num_envs).

Type:

list[int]

ground_plane_params

Ground plane for warp.sim visualization, defined as (normal_x, normal_y, normal_z, plane_height).

Type:

tuple[float, float, float, float]

handle_EE

Enables edge-edge interpenetration handling. Disabling improves simulation speed. Defaults to True.

Type:

bool

epsv

Velocity threshold \(\epsilon_{v}\) (in m/s). Contacts with relative velocity below this are treated as static frictional contacts. Defaults to 1e-3.

Type:

float

dhat

IPC barrier activation distance \(\hat{d}\) (in m). Contact forces are applied when distance is below this threshold. Defaults to 1e-4.

Type:

float

kappa

IPC barrier stiffness \(\kappa\) (in kg·s-2). Controls the magnitude of contact forces. Defaults to 1e5.

Type:

float

gravity

Gravity vector (in m/s²). Defaults to [0, -9.81, 0].

Type:

wp.vec3d

k_elasticity_damping

Elasticity damping coefficient (in Pa·s/m). Defaults to 0.01.

Type:

float

NUM_COLLISION_LAYERS: int

Max collision layers for filtering (default = 63). Recommended not to modify unless necessary.

X: <warp.types.array object at 0x7c33289fdcf0>

Node rest positions

add_affine_body(x: ndarray[Any, dtype[float64]], face: ndarray[Any, dtype[int]], density: float, E: float, mu: float, mass_xi: None | float = None, env_id: int = 0, nu: float = 0.3) → TriMeshBodyHandle

Add an affine rigid body using a triangle mesh surface.

The mesh can be closed or open. For open meshes, mass_xi must be provided to estimate the volume from surface area.

Must be called before init(), and before adding any soft volumetric or shell bodies.

Parameters:

  • x (NDArray[np.float64]) – Vertex positions (shape (N, 3)).

  • face (NDArray[int]) – Triangle face indices (shape (M, 3)).

  • density (float) – Material density (kg/m³).

  • E (float) – Young’s modulus (Pa).

  • mu (float) – Friction coefficient.

  • mass_xi (float, optional) – Thickness estimator for open meshes. Required if the mesh is not closed.

  • env_id (int, optional) – Index of the environment. Defaults to 0.

  • nu (float, optional) – Poisson’s ratio. Defaults to 0.3.

Returns:

Handle with metadata for this affine body.

Return type:

TriMeshBodyHandle

add_fix_point_constraint(parent_handle: TetMeshBodyHandle | TriMeshBodyHandle, child_handle: TetMeshBodyHandle | TriMeshBodyHandle, fix_point_location: Tensor | Sequence[float])

Add a fixed-point constraint between two affine bodies.

This constraint ensures that a specific world-space point remains at the same location when transformed by both the parent and child bodies’ local affine transforms. It effectively “welds” the two bodies together at that point.

The current states of both bodies must already satisfy this constraint when calling this function. Otherwise, unexpected behavior may occur.

Must be called after init() and before finalize().

Parameters:

  • parent_handle (BodyHandle) – Handle of the parent affine body.

  • child_handle (BodyHandle) – Handle of the child affine body.

  • fix_point_location (torch.Tensor | Sequence[float]) – World-space location of the fixed point (shape (3,)).

add_local_revolute_joint(parent_handle: TetMeshBodyHandle | TriMeshBodyHandle, child_handle: TetMeshBodyHandle | TriMeshBodyHandle, joint_origin_transform: ndarray[Any, dtype[_ScalarType_co]], joint_axis: ndarray[Any, dtype[_ScalarType_co]], env_id: int = 0) → LocalJointHandle

Add a revolute joint between two affine bodies.

The joint axis is defined in the parent frame. When calling this API, the current states of the parent link and the child link should satisfy the joint constraint. Otherwise, unexpected behavior may occur.

The states should be previously updated by apply_set_state() if set_affine_state() was previously called for parent or child links.

Must be called after init() and before finalize().

Parameters:

  • parent_handle (BodyHandle) – Parent link body handle.

  • child_handle (BodyHandle) – Child link body handle.

  • joint_axis (NDArray) – Axis of the joint in the joint frame. Shape: (3,).

  • joint_origin_transform (NDArray) – Transform from joint frame to parent frame. Shape: (4, 4). The transform \(T\) should satisfy \([e_1^{\mathrm{parent}},\ e_2^{\mathrm{parent}},\ e_3^{\mathrm{parent}}] \cdot T = [e_1^{\mathrm{joint}},\ e_2^{\mathrm{joint}},\ e_3^{\mathrm{joint}}]\), where \(e_i^{\mathrm{frame}}\) denotes the basis vectors of the given frame.

Returns:

A handle for the added joint.

Return type:

LocalJointHandle

add_plane(n: ndarray[Any, dtype[float64]], o: ndarray[Any, dtype[float64]], mu: float, as_ground: bool = True) → None

Add a collision half-space defined by a plane.

The plane is specified by a normal vector n and a point o lying on the plane. It acts as a global collider and interacts with all simulation environments. Optionally, this plane can also serve as the ground plane for warp.sim visualization.

This method must be called before init() is invoked.

Parameters:

  • n (NDArray[np.float64]) – Normal vector of the plane (shape (3,)).

  • o (NDArray[np.float64]) – A point on the plane (shape (3,)).

  • mu (float) – Friction coefficient of the plane.

  • as_ground (bool, optional) – If True, sets this plane as the warp.sim ground plane. Defaults to True.

add_robot(urdf_path: str, env_id: int = 0, start_coll_layer: int = 2, coll_layers: list[int] = [], disable_coll_layers: list[int] = [], mu: float = 0.3, self_collision: bool = False, **kwargs) → Robot

Add a robot from URDF and register its bodies and constraints.

Supported URDFs must include rest_mesh for each link. Each link with a valid surface mesh will be registered as an affine body with default material and collision settings.

Must be called before init().

Parameters:

  • urdf_path (str) – Path to the URDF file describing the robot.

  • env_id (int) – Environment index for the robot instance. Defaults to 0.

  • start_coll_layer (int) – Starting collision layer ID for robot links. Defaults to 2.

  • coll_layers (list[int]) – Additional layers this robot can collide with. Defaults to [].

  • disable_coll_layers (list[int]) – Unused in current implementation. Defaults to [].

  • mu (float) – Friction coefficient for all link surfaces. Defaults to 0.3.

  • self_collision (bool) – Whether to enable collision between links of the same robot. Defaults to False.

  • **kwargs – Additional arguments passed to the Robot constructor.

Returns:

Handle of the Robot.

Return type:

Robot

add_soft_shell_body(mesh: Trimesh, edge_stretching_stiffness: float = 0, density: float = 1000, E: float = 0, nu: float = 0.3, compression_softening: float = 0, bending_stiffness: float = 0, mu: float = 0, xi: float = 0.001, mass_thickness: None | float = None, env_id: int = 0) → TriMeshBodyHandle

Add a soft shell body based on a triangle mesh using Baraff-Witkin membrane and dihedral bending models.

The shell is treated as a deformable surface discretized with triangle faces and boundary edges.

This method must be called before init() is invoked. It must be called after all affine bodies are added and before any soft volume body.

Parameters:

  • mesh (trimesh.Trimesh) – Triangle mesh defining the soft shell surface.

  • edge_stretching_stiffness (float, optional) – Stretching stiffness for boundary edges. Defaults to 0.

  • density (float, optional) – Material density (kg/m³). Defaults to 1000.

  • E (float, optional) – Young’s modulus. Defaults to 0.

  • nu (float, optional) – Poisson’s ratio. Defaults to 0.3.

  • compression_softening (float, optional) – Compression softening factor. Defaults to 0.

  • bending_stiffness (float, optional) – Bending stiffness coefficient. Defaults to 0.

  • mu (float, optional) – Friction coefficient. Defaults to 0.

  • xi (float, optional) – Effective surface thickness used for estimating the shell’s mass. The mass of each vertex is computed as: \(\text{mass} = \xi \times \text{surface_area} \times \text{density}\) Defaults to 0.001.

  • mass_thickness (float or None, optional) – Thickness used for mass calculation. Defaults to xi if None.

  • env_id (int, optional) – Index of the environment. Defaults to 0.

Returns:

Handle with metadata for this soft shell body.

Return type:

TriMeshBodyHandle

add_soft_vol_body(mesh: UnstructuredGrid, density: float, E: float, nu: float, mu: float, env_id: int = 0, coll_layer: int = 0, self_coll: bool = True) → TetMeshBodyHandle

Add a soft volumetric body (tetrahedral mesh) using a Neo-Hookean or StVK constitutive model. Only limited models (Neo-Hookean, StVK) are currently supported; Corotated Linear is not yet implemented. The added body will participate in collision and self-collision if enabled.

This function must be called after all affine bodies are added and before calling init().

Parameters:

  • mesh (pyvista.UnstructuredGrid) – Tetrahedral mesh representing the body volume. Must be a valid pyvista.UnstructuredGrid.

  • density (float) – Material density (kg/m³).

  • E (float) – Young’s modulus (Pa).

  • nu (float) – Poisson’s ratio.

  • mu (float) – Friction coefficient.

  • env_id (int, optional) – Index of the environment. Defaults to 0.

  • coll_layer (int, optional) – Collision layer index for this body. Controls inter-body collision groups. Defaults to 0.

  • self_coll (bool, optional) – Whether to enable self-collision for this body. Defaults to True.

Returns:

Handle with metadata for this soft volumetric body.

Return type:

TetMeshBodyHandle

add_world_prismatic_joint(handle: TetMeshBodyHandle | TriMeshBodyHandle, axis: ndarray[Any, dtype[_ScalarType_co]]) → WorldJointHandle

Add a world-to-body prismatic joint (1-DOF sliding) for an affine body.

This function constrains an affine body to translate only along a fixed axis in the world space, preventing motion in directions orthogonal to the axis.

Must be called after init() and before finalize().

Parameters:

  • handle (BodyHandle) – Handle of the target affine body.

  • axis (NDArray[np.float64]) – Translation axis in world coordinates (shape (3,)). Will be automatically normalized.

Returns:

Handle with metadata for this prismatic joint.

Return type:

WorldJointHandle

add_world_revolute_joint(handle: TetMeshBodyHandle | TriMeshBodyHandle, local_axis_position: ndarray[Any, dtype[_ScalarType_co]], axis_direction: ndarray[Any, dtype[_ScalarType_co]]) → WorldJointHandle

Add a world-to-body revolute joint (1-DOF hinge) for an affine body.

This function constrains an affine body to rotate around a fixed axis in the world space. The joint is defined by a local anchor point and an axis direction, both expressed in the body’s local frame.

Must be called after init() and before finalize().

Parameters:

  • handle (BodyHandle) – Handle of the target affine body.

  • local_axis_position (NDArray[np.float64]) – Anchor point on the body where the axis passes through (shape (3,)).

  • axis_direction (NDArray[np.float64]) – Vector representing the axis direction (shape (3,)); will be automatically normalized.

Returns:

Handle with metadata for this revolute joint.

Return type:

WorldJointHandle

apply_set_state(x=None, y=None) → None

Apply manually set states to internal buffers.

This function should be used only after setting states via set_affine_state() or set_soft_state(), typically for visualization before simulation starts.

Parameters:

  • x (Optional[wp.array]) – Custom particle_q buffer (default: particle_q).

  • y (Optional[wp.array]) – Custom y buffer (default: y).

check_initial_state_valid(exclude_self_collision: bool = False) → bool

Check if the initial state is collision-free before simulation starts.

This method checks for inter-object collisions (optionally ignoring self-collisions) at frame 0 before the simulation begins. It must be called before any stepping occurs.

Parameters:

exclude_self_collision (bool) – If True, disables self-collision checks during validation. Defaults to False.

Returns:

True if the initial state is valid (no collisions detected).

Return type:

bool

clear_force() → None

Clear all externally applied affine forces and torques.

Resets internal buffers used to accumulate affine body force and torque inputs.

Should be called before using IPCIntegrator.simulate() to advance each simulation step if external forces are updated dynamically.

property collision_map

Compute and return the collision filter map as a binary matrix.

The returned matrix indicates which collision layers interact with each other. Each row corresponds to a layer, and each column indicates whether collision is enabled with another layer.

Must be accessed after init().

Returns:

A (NUM_COLLISION_LAYERS, NUM_COLLISION_LAYERS) boolean array.

Return type:

np.ndarray

disable_affine_kinematic_constraint(handle: TetMeshBodyHandle | TriMeshBodyHandle) → None

Disable kinematic constraint for an affine body.

Parameters:

handle (BodyHandle) – Target affine body handle.

property dummy_robot: Robot | None

Return the first added robot, or None if no robot has been added.

enable_affine_kinematic_constraint(handle: TetMeshBodyHandle | TriMeshBodyHandle) → None

Enable kinematic constraint for an affine body.

Parameters:

handle (BodyHandle) – Target affine body handle.

finalize() → None

Finalize the ASRModel.

This function must be called once after all bodies, joints, and constraints are added, and after init() has been called. It initializes sparse matrix structures for Hessians, allocates buffers for per-step simulation, and builds collision and constraint metadata.

Must be called only once and after init().

get_affine_body_mesh_from_handle(handle: TriMeshBodyHandle) → Trimesh

Get mesh from an affine body.

Parameters:

handle (TriMeshBodyHandle) – Triangular mesh body handle.

Returns:

Mesh.

Return type:

trimesh.Trimesh

get_affine_body_meshes_from_handle(handles: List[TriMeshBodyHandle], concat=True) → list[Trimesh] | Trimesh

Get meshes from a list of affine body handles.

Parameters:

  • handles (List[TriMeshBodyHandle]) – TriMesh handles.

  • concat (bool) – Whether to merge the meshes. Defaults to True.

Returns:

Meshes.

Return type:

list[tm.Trimesh] or tm.Trimesh

get_affine_body_state(body_handle: TetMeshBodyHandle | TriMeshBodyHandle, return_numpy: bool = True) → Tuple[ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]]]

Get affine body state as rotation and translation.

Parameters:

  • body_handle (BodyHandle) – Handle to the affine body.

  • return_numpy (bool) – If True, returns NumPy arrays; otherwise torch tensors.

Returns:

Rotation matrix and translation vector.

Return type:

Tuple[NDArray | torch.Tensor, NDArray | torch.Tensor]

get_affine_body_state_matrix(body_handle: TetMeshBodyHandle | TriMeshBodyHandle, return_numpy: bool = True) → ndarray[Any, dtype[_ScalarType_co]]

Get affine body transform as 4x4 matrix.

Parameters:

  • body_handle (BodyHandle) – Handle to the affine body.

  • return_numpy (bool) – If True, returns a NumPy array; otherwise a torch tensor.

Returns:

4x4 transform matrix.

Return type:

NDArray | torch.Tensor

get_affine_body_velocity(body_handle: TetMeshBodyHandle | TriMeshBodyHandle, return_numpy: bool = True) → Tuple[ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]]]

Get affine body velocity as rotational and translational components.

Parameters:

  • body_handle (BodyHandle) – Handle to the affine body.

  • return_numpy (bool) – If True, returns NumPy arrays; otherwise torch tensors.

Returns:

Angular and linear velocities.

Return type:

Tuple[NDArray | torch.Tensor, NDArray | torch.Tensor]

get_affine_body_velocity_matrix(body_handle: TetMeshBodyHandle | TriMeshBodyHandle, return_numpy: bool = True) → ndarray[Any, dtype[_ScalarType_co]]

Get affine body velocity as a 4x4 matrix.

Parameters:

  • body_handle (BodyHandle) – Handle to the affine body.

  • return_numpy (bool) – If True, returns a NumPy array; otherwise a torch tensor.

Returns:

Velocity matrix (4x4), combining linear and angular velocity.

Return type:

NDArray | torch.Tensor

get_affine_body_wp_meshes_from_handle(handles: list[TriMeshBodyHandle]) → list[Mesh]

Get Warp mesh handles from affine body handles.

Parameters:

handles (list[TriMeshBodyHandle]) – Affine mesh handles.

Returns:

Warp mesh list.

Return type:

list[warp.sim.Mesh]

get_body_env_id(handle: TetMeshBodyHandle | TriMeshBodyHandle) → int

Get the environment ID of a body.

Parameters:

handle (BodyHandle) – Target body.

Returns:

Assigned environment ID.

Return type:

int

get_body_face(handle: TetMeshBodyHandle | TriMeshBodyHandle) → Tensor

Get face indices for a body’s surface mesh.

Parameters:

handle (BodyHandle) – Body handle.

Returns:

Face indices relative to the body.

Return type:

torch.Tensor

get_body_mesh(handle: TetMeshBodyHandle | TriMeshBodyHandle) → Trimesh

Get trimesh.Trimesh object for the body.

Parameters:

handle (BodyHandle) – Body handle.

Returns:

Mesh object.

Return type:

trimesh.Trimesh

get_body_nodal_collision_force(handle: TetMeshBodyHandle | TriMeshBodyHandle, dt: float) → Tensor

Return normal (barrier) contact force for each node of a body.

Should be called after update_contact_force().

Parameters:

  • handle (BodyHandle) – Handle for the queried body.

  • dt (float) – Time step used in the contact force update.

Returns:

Normal contact force per node. Shape: (x_num, 3).

Return type:

torch.Tensor

get_body_nodal_contact_force(handle: TetMeshBodyHandle | TriMeshBodyHandle, dt: float) → Tensor

Return total (normal + frictional) contact force for each node of a body.

Should be called after update_contact_force().

Parameters:

  • handle (BodyHandle) – Handle for the queried body.

  • dt (float) – Time step used in the contact force update.

Returns:

Contact force per node. Shape: (x_num, 3).

Return type:

torch.Tensor

get_body_nodal_friction_force(handle: TetMeshBodyHandle | TriMeshBodyHandle, dt: float) → Tensor

Return frictional contact force for each node of a body.

Should be called after update_contact_force().

Parameters:

  • handle (BodyHandle) – Handle for the queried body.

  • dt (float) – Time step used in the contact force update.

Returns:

Friction force per node. Shape: (x_num, 3).

Return type:

torch.Tensor

get_body_resultant_contact_force(handle: TetMeshBodyHandle | TriMeshBodyHandle, dt: float) → Tensor

Return total contact force (sum over all nodes) applied to a body.

Should be called after update_contact_force().

Parameters:

  • handle (BodyHandle) – Handle for the queried body.

  • dt (float) – Time step used in the contact force update.

Returns:

Total contact force vector. Shape: (3,).

Return type:

torch.Tensor

get_body_target_mesh(handle: TetMeshBodyHandle | TriMeshBodyHandle) → Trimesh

Get target mesh for a body using target positions.

Parameters:

handle (BodyHandle) – Body handle.

Returns:

Target mesh.

Return type:

trimesh.Trimesh

get_body_x(handle: TetMeshBodyHandle | TriMeshBodyHandle) → Tensor

Get particle positions for a body.

Parameters:

handle (BodyHandle) – Body handle.

Returns:

Positions of shape (num_particles, 3).

Return type:

torch.Tensor

get_body_x_target(handle: TetMeshBodyHandle | TriMeshBodyHandle) → Tensor

Get target positions for a body.

Parameters:

handle (BodyHandle) – Body handle.

Returns:

Target positions of shape (num_particles, 3).

Return type:

torch.Tensor

get_element_by_handle(handle: TetMeshBodyHandle, return_numpy=True) → Tuple[ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]]]

Get per-element mesh data by handle.

Parameters:

  • handle (TetMeshBodyHandle) – Tetrahedral mesh handle.

  • return_numpy (bool) – Return NumPy arrays if True.

Returns:

Vertex positions and face indices.

Return type:

Tuple[NDArray, NDArray]

static get_env_pos(num_envs: int, n_row: int, n_col: int | None = None, env_spacing: float = 0.5, up_axis: str = 'Z', device: str = 'cuda:0', return_numpy: bool = False) → tensor

Compute 3D base positions for multiple simulation environments arranged in a grid.

The environments are laid out in a 2D grid on a plane orthogonal to the up axis (default is Z-up). The resulting 3D positions can be used to initialize the base positions of each parallel environment.

Parameters:

  • num_envs (int) – Total number of environments.

  • n_row (int) – Number of rows in the layout grid.

  • n_col (int, optional) – Number of columns in the layout grid. If None, it will be computed automatically. Defaults to None.

  • env_spacing (float, optional) – Spacing between neighboring environments (in meters). Defaults to 0.5.

  • up_axis (str, optional) – Axis name to be treated as up axis. One of “X”, “Y”, or “Z”. Defaults to “Z”.

  • device (str, optional) – Device string for returned torch tensor. Defaults to “cuda:0”.

  • return_numpy (bool, optional) – If True, returns a NumPy array instead of a torch tensor. Defaults to False.

Returns:

Environment positions of shape (num_envs, 3), arranged in a 2D grid.

Return type:

torch.Tensor | np.ndarray

get_environment_states() → ndarray[Any, dtype[bool]]

Reset a specific environment to a valid state.

This function manually resets the environment state, used to resume simulation for that environment.

Parameters:

env_id (int) – The index of the environment to reset.

get_joint_value(joint_handle: WorldJointHandle) → float

Get the current value of a joint (angle or displacement).

Currently supports only REVOLUTE (rotation angle) and PRISMATIC (translation length) joints. Assumes identity initial pose and should only be used for affine bodies.

Parameters:

joint_handle (WorldJointHandle) – Handle representing the joint and its body.

Returns:

Joint value in radians (for JointType.REVOLUTE) or meters (for JointType.PRISMATIC).

Return type:

float

get_scene_mesh() → Trimesh

Get the entire current scene mesh.

Returns:

Scene mesh with all vertices and faces.

Return type:

trimesh.Trimesh

get_soft_body_from_handle(handle: TetMeshBodyHandle) → UnstructuredGrid

Get tetrahedral grid from a soft body.

Parameters:

handle (TetMeshBodyHandle) – Tetrahedral mesh body handle.

Returns:

PyVista unstructured tetrahedral grid.

Return type:

pyvista.UnstructuredGrid

get_soft_body_mesh_from_handle(handle: TetMeshBodyHandle) → Trimesh

Get surface mesh for a soft body.

Parameters:

handle (TetMeshBodyHandle) – Soft body handle.

Returns:

Mesh object.

Return type:

trimesh.Trimesh

get_soft_body_meshes_from_handle(handles: List[TetMeshBodyHandle], concat=True) → list[Trimesh] | Trimesh

Get surface meshes from a list of soft bodies.

Parameters:

  • handles (List[TetMeshBodyHandle]) – List of handles.

  • concat (bool) – Whether to merge all meshes. Defaults to True.

Returns:

Meshes.

Return type:

list[trimesh.Trimesh] or trimesh.Trimesh

get_soft_body_pos(body_handle: TetMeshBodyHandle | TriMeshBodyHandle, return_numpy: bool = True) → ndarray[Any, dtype[_ScalarType_co]]

Get positions of all nodes in a soft body.

Parameters:

  • body_handle (BodyHandle) – Handle to the soft body (non-affine).

  • return_numpy (bool) – If True, returns a NumPy array; otherwise a torch tensor.

Returns:

Node positions with shape (x_num, 3).

Return type:

NDArray | torch.Tensor

get_soft_body_velocity(body_handle: TetMeshBodyHandle | TriMeshBodyHandle, return_numpy: bool = True) → ndarray[Any, dtype[_ScalarType_co]]

Get nodal velocities for a soft body.

Parameters:

  • body_handle (BodyHandle) – Handle to the soft body (non-affine).

  • return_numpy (bool) – If True, returns a NumPy array; otherwise a torch tensor.

Returns:

Velocity of each node with shape (x_num, 3).

Return type:

NDArray | torch.Tensor

get_soft_nodes_from_idxs(idxs: list[tuple[int, int]]) → ndarray[Any, dtype[_ScalarType_co]]

Get particle positions by index list.

Parameters:

idxs (list[tuple[int, int]]) – List of (env_id, local_id) indices.

Returns:

Particle positions.

Return type:

NDArray

get_soft_surf_verts_from_handle(handle: TetMeshBodyHandle | TriMeshBodyHandle) → ndarray[Any, dtype[_ScalarType_co]]

Get surface vertex positions from soft body.

Parameters:

handle (BodyHandle) – Soft body handle.

Returns:

Surface vertex positions.

Return type:

NDArray

get_soft_verts_from_handle(handle: TetMeshBodyHandle | TriMeshBodyHandle) → ndarray[Any, dtype[_ScalarType_co]]

Get particle positions from a soft body handle.

Parameters:

handle (BodyHandle) – Soft body handle.

Returns:

Positions array.

Return type:

NDArray

get_target_scene_mesh() → Trimesh

Get the target scene mesh.

Returns:

Target scene mesh.

Return type:

trimesh.Trimesh

init() → None

Initialize the ASRModel.

This function must be called once after all bodies are added and before adding any constraints or joints. It finalizes memory allocations, transfers host data to the device, and prepares helper modules such as constraint and kinematic solvers.

If visualization is enabled, this also sets up rendering buffers.

Must be called before finalize().

max_collisions

Maximum collision pairs to track (default = 2^23). Auto-scaled if exceeded; manual change usually unnecessary.

particle_q: <warp.types.array object at 0x7c33289fdd20>

Node positions

particle_qd: <warp.types.array object at 0x7c33169f4a30>

Node velocities

particle_qdd: <warp.types.array object at 0x7c33169f4a00>

Node accelerations

reset_environement(env_id: int) → None

Get the simulation state (valid/invalid) of each environment.

Returns:

A NumPy array indicating whether each environment is currently in a valid state.

Return type:

NDArray[bool]

set_affine_external_force_field(handle: TetMeshBodyHandle | TriMeshBodyHandle, target_force_acceleration: ndarray[Any, dtype[_ScalarType_co]] | Tensor) → None

Set an external force field (acceleration) applied to an affine body.

Only applies to affine bodies. The force is specified in world space and added per timestep.

Parameters:

  • handle (BodyHandle) – Handle for the target affine body.

  • target_force_acceleration (NDArray | torch.Tensor) – Target acceleration vector. Shape: (3,).

set_affine_external_torque(handle: TetMeshBodyHandle | TriMeshBodyHandle, torque: ndarray[Any, dtype[_ScalarType_co]] | Tensor = tensor([0., 0., 0.], dtype=torch.float64)) → None

Apply an external torque to an affine body by modifying its affine force vector.

The torque is specified in world space. This modifies the internal force buffer of the affine body.

Parameters:

  • handle (BodyHandle) – Handle for the target affine body.

  • torque (NDArray | torch.Tensor, optional) – Torque vector. Shape: (3,). Defaults to a zero vector.

set_affine_external_wrench(handle: TetMeshBodyHandle | TriMeshBodyHandle, target_force_acceleration: ndarray[Any, dtype[_ScalarType_co]] | Tensor, torque: ndarray[Any, dtype[_ScalarType_co]] | Tensor = tensor([0., 0., 0.], dtype=torch.float64)) → None

Apply both external force field and torque to an affine body.

This is a combined API that calls set_affine_external_force_field() and set_affine_external_torque() in one call.

Parameters:

  • handle (BodyHandle) – Handle for the target affine body.

  • target_force_acceleration (NDArray | torch.Tensor) – Acceleration force field. Shape: (3,).

  • torque (NDArray | torch.Tensor, optional) – Torque vector. Shape: (3,). Defaults to a zero vector.

set_affine_kinematic_target(handle: TetMeshBodyHandle | TriMeshBodyHandle, target_rot_mat: ndarray[Any, dtype[_ScalarType_co]] | Tensor, target_translation: ndarray[Any, dtype[_ScalarType_co]] | Tensor) → None

Set affine body’s target pose (used for kinematic optimization in next sim step).

Parameters:

  • handle (BodyHandle) – Affine body handle.

  • target_rot_mat (NDArray | torch.Tensor) – Target rotation matrix (3x3).

  • target_translation (NDArray | torch.Tensor) – Target translation vector (3,).

set_affine_state(handle: TetMeshBodyHandle | TriMeshBodyHandle, rotation: ndarray[Any, dtype[_ScalarType_co]] | Tensor, translation: ndarray[Any, dtype[_ScalarType_co]] | Tensor) → None

Set the affine body state (rotation and translation).

Should be called before apply_set_state().

Parameters:

  • handle (BodyHandle) – Target affine body handle.

  • rotation (NDArray | torch.Tensor) – Rotation matrix of shape (3, 3).

  • translation (NDArray | torch.Tensor) – Translation vector of shape (3,).

set_body_collision_layer(handle: TetMeshBodyHandle | TriMeshBodyHandle, layer_index: int) → None

Assign the collision layer index to a body.

Must be called after init(). This defines the collision layer the body belongs to.

Parameters:

  • handle (BodyHandle) – The body to assign.

  • layer_index (int) – Index of the collision layer (0 to NUM_COLLISION_LAYERS - 1).

set_body_env_id(handle: TetMeshBodyHandle | TriMeshBodyHandle, env_id: int) → None

Assign environment ID to a body (after init()).

Parameters:

  • handle (BodyHandle) – Target body.

  • env_id (int) – Environment ID.

set_body_self_collision(handle: TetMeshBodyHandle | TriMeshBodyHandle, to_enable: bool) → None

Enable or disable self-collision for a specific body.

Must be called after init(). Controls whether the (soft) body is allowed to collide with itself.

Parameters:

  • handle (BodyHandle) – The target body.

  • to_enable (bool) – Whether to enable (True) or disable (False) self-collision.

set_collision_layer_filter(layer_i: int, layer_j: int, to_enable_collision: bool) → None

Enable or disable collisions between two collision layers.

Must be called after init(). Collision filters define which layers can interact.

Parameters:

  • layer_i (int) – Index of the first collision layer.

  • layer_j (int) – Index of the second collision layer.

  • to_enable_collision (bool) – If True, enable collisions between the layers; otherwise disable.

set_kinematic_stiffness(weight: float) → None

Set the initial stiffness weight for kinematic constraints.

Parameters:

weight (float) – Stiffness value applied to all kinematic constraints.

set_robot_states(joint_params: list[dict[str, float]] | ndarray[Any, dtype[_ScalarType_co]] | Tensor, root_tf: ndarray[Any, dtype[_ScalarType_co]] | Tensor | None = None, env_ids: list[int] = []) → None

Set the current states (pose) of the robot in each environment.

This function directly overwrites the affine state of each link using the given joint parameters and root transform. It is typically used once during initialization to place robots into their starting poses.

Parameters:

  • joint_params (list[dict[str, float]] | NDArray | torch.Tensor) – Joint configuration per robot.

  • root_tf (NDArray | torch.Tensor | None) – Optional root transformation per robot (SE(3) matrix).

  • env_ids (list[int]) – Environment indices to apply the states to. Defaults to all.

set_robot_targets(joint_params: list[dict[str, float]] | ndarray[Any, dtype[_ScalarType_co]] | Tensor, root_tf: ndarray[Any, dtype[_ScalarType_co]] | Tensor | None = None, env_ids: list[int] = [])

Set the target poses for the robot links for the next simulation step.

Unlike set_robot_states(), this function does not immediately update the current state. Instead, it sets the optimization targets used by the simulator in the next time step to apply kinematic constraints.

Parameters:

  • joint_params (list[dict[str, float]] | NDArray | torch.Tensor) – Joint configuration per robot.

  • root_tf (NDArray | torch.Tensor | None) – Optional root transformation per robot (SE(3) matrix).

  • env_ids (list[int]) – Environment indices to apply the targets to. Defaults to all.

set_soft_kinematic_constraint(handle: TetMeshBodyHandle | TriMeshBodyHandle, verts_mask: ndarray[Any, dtype[_ScalarType_co]] | Tensor) → None

Enable or disable soft body vertex-level kinematic constraints.

This mask determines which vertices are constrained in the next simulation step. Must be used together with set_soft_kinematic_target() to define target positions.

Parameters:

  • handle (BodyHandle) – Soft body handle.

  • verts_mask (NDArray | torch.Tensor) – Mask of shape (num_vertices,), type bool or int.

set_soft_kinematic_target(handle: TetMeshBodyHandle | TriMeshBodyHandle, target_verts: ndarray[Any, dtype[_ScalarType_co]] | Tensor) → None

Set target positions for constrained soft body vertices.

These targets are used in the next simulation step for the vertices enabled via set_soft_kinematic_constraint().

Parameters:

  • handle (BodyHandle) – Soft body handle.

  • target_verts (NDArray | torch.Tensor) – Target positions, shape (num_vertices, 3).

set_soft_state(handle: TetMeshBodyHandle | TriMeshBodyHandle, positions: ndarray[Any, dtype[_ScalarType_co]] | Tensor) → None

Set the soft body vertex positions.

Should be called before apply_set_state().

Parameters:

  • handle (BodyHandle) – Target soft body handle.

  • positions (NDArray | torch.Tensor) – Vertex positions of shape (x_num, 3).

property shape_count_sim: int

Get the total number of shape instances in the simulation.

This includes all affine bodies and soft volumetric bodies that have been added to the simulation model.

Returns:

Total number of simulated shapes (affine + soft bodies).

Return type:

int

property soft_kinematic_constraint: Tensor

Return the soft-body kinematic constraint mask.

Returns:

Boolean mask of shape (soft_verts_num,) indicating constrained DOFs.

Return type:

torch.Tensor

property soft_kinematic_target: Tensor

Return the target DOF values for soft-body kinematic constraints.

Returns:

Target DOF positions of shape (soft_verts_num, 3).

Return type:

torch.Tensor

state(requires_grad=None) → State

Returns a state object for the model

The returned state will be initialized with the initial configuration given in the model description.

Parameters:

requires_grad (bool) – Manual overwrite whether the state variables should have requires_grad enabled (defaults to None to use the model’s setting requires_grad)

Returns:

The state object

Return type:

State

property tac_handles: list[list[TetMeshBodyHandle]]

Get tactile mesh handles for all robots.

Returns:

List of tactile mesh handle lists, one per robot.

Return type:

list[list[TetMeshBodyHandle]]

update_contact_force(dt: float) → Tensor

Compute and update contact and friction forces for all particles.

Must be called before any get_body_nodal_contact_force() or related force queries.

Parameters:

dt (float) – Time step for the current simulation step.

Returns:

Normal and frictional contact forces for all particles (shape: [x_num, 3]).

Return type:

Tuple[torch.Tensor, torch.Tensor]

write_scene(filename: str, divide: bool = False, double_face: bool = False) → None

Export the current scene mesh.

Parameters:

  • filename (str) – Output file path.

  • divide (bool) – Whether to split mesh into submeshes. Defaults to False.

  • double_face (bool) – Whether to include reversed faces. Defaults to False.

write_target_scene(filename: str) → None

Export the current target scene as a mesh file.

Parameters:

filename (str) – Output file path.

property x_target: Tensor

Return current target positions for all particles.

Combines soft and affine kinematic constraints into a full particle target buffer.

Returns:

Target particle positions of shape (num_x, 3).

Return type:

torch.Tensor

y: <warp.types.array object at 0x7c33169f47c0>

Affine body states