kaolin.physics.common

API

class kaolin.physics.common.Boundary(integration_pt_volume)

Bases: object

Boundary class acts as a wrapper for the boundary energy, gradient, and hessian kernels for all sample points in the scene.

__init__(integration_pt_volume)

Initializes a Boundary object.

Parameters

integration_pt_volume (wp.array(dtype=wp.float32)) – Volume distributed across each point of size \((\text{num_pts},)\)

energy(dx, x0, coeff, energy=None)

Returns the boundary energy at each integration primitive.

Parameters

• dx (wp.array(dtype=wp.vec3)) – Delta in position of size \((\text{num_pts}, 3)\)

• x0 (wp.array(dtype=wp.vec3)) – Rest position of size \((\text{num_pts}, 3)\)

• coeff (float) – Coefficient

Returns

Boundary energy array of size \(1\)

Return type

wp.array(dtype=wp.float32)

gradient(dx, x0, coeff, gradients)

Returns the boundary gradient at each integration primitive.

Parameters

• dx (wp.array(dtype=wp.vec3)) – Delta in position of size \((\text{num_pts}, 3)\)

• x0 (wp.array(dtype=wp.vec3)) – Rest position of size \((\text{num_pts}, 3)\)

• coeff (float) – Coefficient

Returns

Boundary gradient of size \((\text{num_pts}, 3)\)

Return type

wp.array(dtype=wp.vec3)

hessian(dx, x0, coeff)

Returns the boundary hessian at each integration primitive.

Parameters

• dx (wp.array(dtype=wp.vec3)) – Delta in position of size \((\text{num_pts}, 3)\)

• x0 (wp.array(dtype=wp.vec3)) – Rest position of size \((\text{num_pts}, 3)\)

• coeff (float) – Coefficient

Returns

Boundary hessian as a wp.mat33 block-wise sparse matrix of size \((\text{num_pts}, 3, 3)\)

Return type

wp.array(dtype=wp.mat33)

set_pinned(indices, pinned_x)

Sets the pinned vertices and indices.

Parameters

• indices (wp.array(dtype=wp.int32)) – Indices of the pinned vertices of size \((\text{num_pinned_pts},)\)

• pinned_x (wp.array(dtype=wp.vec3)) – Pinned vertices of size \((\text{num_pinned_pts}, 3)\)

class kaolin.physics.common.Collision(dt, collision_particle_radius=0.1, detection_ratio=1.5, impenetrable_barrier_ratio=0.5, ignore_self_collision_ratio=100000.0, collision_penalty_stiffness=100.0, friction_regularization=0.1, friction_fluid=0.1, friction=0.5, max_contacting_pairs=10000, bounds=True)

Bases: object

__init__(dt, collision_particle_radius=0.1, detection_ratio=1.5, impenetrable_barrier_ratio=0.5, ignore_self_collision_ratio=100000.0, collision_penalty_stiffness=100.0, friction_regularization=0.1, friction_fluid=0.1, friction=0.5, max_contacting_pairs=10000, bounds=True)

Initialize the collision class. This class operates on the whole scene

Parameters

• dt (float) – Time step.

• collision_particle_radius (float) – Radius of the collision particle at which penalty begins to apply. Defaults to 0.1.

• detection_ratio (float) – Collision detection radius described as a ratio relative to the collision_particle_radius. Should be larger than collision_particle_radius. Defaults to 1.5.

• impenetrable_barrier_ratio (float) – Collision barrier radius described as a ratio relative to the collision_particle_radius. Should be smaller than collision_particle_radius. Defaults to 0.25.

• ignore_self_collision_ratio (float) – Collision immune radius described as a ratio relative to the collision_particle_radius. Defaults to 100000.0.

• collision_penalty_stiffness (float) – Penalty stiffness of the collision interactions. Defaults to 100.0.

• friction_regularization (float) – Friction regularization. Keeps friction forces proportional to timestep. Defaults to 0.1.

• friction_fluid (float) – Dampens and smoothens the friction forces. Defaults to 0.1.

• friction (float) – Friction coefficient. Defaults to 0.5.

• max_contacting_pairs (int) – Number of contact points. Defaults to 10000.

• bounds (bool) – Bounds the dofs in the line search to prevent any interpenetration. Defaults to True.

calculate_jacobian(cp_w, cp_x0, cp_is_static=None, qr_tfm=None)

Builds the jacobians of the collision points w.r.t the dofs. For contact pairs \(x_a \in \mathbb{R}^3, x_b \in \mathbb{R}^3\), the jacobians are:

\[J_a = \frac{\partial x_a}{\partial z} \in \mathbb{R}^{3 \times n} J_b = \frac{\partial x_b}{\partial z} \in \mathbb{R}^{3 \times n} J = J_a - J_b \in \mathbb{R}^{3 \times n}\]

The difference, \(J = J_a - J_b\), is the jacobian of the collision gaps.

Parameters

• cp_w (wp.array2d(dtype=wp.float32)) – Contact point skinning weights of size \((\text{num_pts}, \text{num_handles})\)

• cp_x0 (wp.array(dtype=wp.vec3)) – Rest contact point positions of size \((\text{num_pts}, 3)\)

• cp_is_static (wp.array(dtype=int), optional) – Array indicating which contact points are static (1 for static, 0 for dynamic). Defaults to None.

• qr_tfm (torch.Tensor, optional) – Block-diagonal handle-DOF rotation that maps the raw (pre-QR) basis to the post-QR basis used for elastic/inertia terms. When provided, collision_J and collision_J_dense are rotated into the post-QR basis for gradient/Hessian assembly, while collision_J_a/collision_J_b are kept in the raw basis so the bounds kernel can still read meaningful per-DOF sparsity. Defaults to None.

Note

The jacobian set by this function is a sparse matrix of size \((3 \times \text{num_contacts}, 12 \times \text{num_handles})\).

detect_collisions(cp_dx, cp_x0, cp_obj_ids, cp_is_static=None)

Detects collisions between contact points and stores the results in the collision buffers.

Parameters

• cp_dx (wp.array(dtype=wp.vec3)) – Current contact point displacements.

• cp_x0 (wp.array(dtype=wp.vec3)) – Rest contact point positions.

• cp_obj_ids (wp.array(dtype=int)) – Map from contact point to object id.

• cp_is_static (wp.array(dtype=int), optional) – Array indicating which contact points are static (1 for static, 0 for dynamic). Defaults to None.

Note

The function sets the collision indices in the collision_indices_a and collision_indices_b buffers, collision normals in the collision_normals buffer, and kinematic gaps between the contact points in the collision_kinematic_gaps buffer.

The number of contacts is stored in the num_contacts attribute.

energy(dx, x0, coeff, energy=None)

Compute the collision energy.

Parameters

• dx (wp.array(dtype=wp.vec3)) – Current CP displacements with the current dofs of size \((\text{num_pts}, 3)\)

• x0 (wp.array(dtype=wp.vec3)) – Rest contact point positions of size \((\text{num_pts}, 3)\)

• coeff (float) – Coefficient for the collision energy.

• energy (wp.array(dtype=float)) – Output energy. Used for cuda-graph capture of size \(1\)

Returns

Optional output energy of size \(1\)

Return type

wp.array(dtype=float)

get_bounds(cp_delta_dx, cp_dx, cp_x0)

Compute the bounds of the update for each dof. This is used to guarantee intersection-free contact. See kaolin.physics.optimization.apply_bounds() for more details.

Parameters

• cp_delta_dx (wp.array(dtype=wp.vec3)) – \((B*dz).reshape(-1, 3)\) where \(dz\) is the newton update of size \((\text{num_pts}, 3)\)

• cp_dx (wp.array(dtype=wp.vec3)) – \((B*z).reshape(-1, 3)\) where \(z\) is the current dofs of size \((\text{num_pts}, 3)\)

• cp_x0 (wp.array(dtype=wp.vec3)) – Rest contact point positions of size \((\text{num_pts}, 3)\)

Returns

Bounds of the update for each dof of size \((\text{num_dofs},)\)

Return type

wp.array(dtype=float)

gradient(dx, x0, coeff)

Compute the gradient of the collision energy.

Parameters

• dx (wp.array(dtype=wp.vec3)) – Current CP displacements with the current dofs of size \((\text{num_pts}, 3)\)

• x0 (wp.array(dtype=wp.vec3)) – Rest contact point positions of size \((\text{num_pts}, 3)\)

• coeff (float) – Coefficient for the collision energy.

Returns

Gradient of the collision energy of size \((\text{num_contacts}, 3)\)

Return type

wp.array(dtype=wp.vec3)

hessian(dx, x0, coeff)

Compute the hessian of the collision energy.

Parameters

• dx (wp.array(dtype=wp.vec3)) – Current CP displacements with the current dofs of size \((\text{num_pts}, 3)\)

• x0 (wp.array(dtype=wp.vec3)) – Rest contact point positions of size \((\text{num_pts}, 3)\)

• coeff (float) – Coefficient for the collision energy.

Returns

Hessian of the collision energy of size \((\text{num_contacts}, 3, 3)\)

Return type

wp.array(dtype=wp.mat33)

class kaolin.physics.common.Floor(floor_height, floor_axis, flip_floor, integration_pt_volume)

Bases: object

Floor class acts as a wrapper for the floor energy, gradient, and hessian kernels.

__init__(floor_height, floor_axis, flip_floor, integration_pt_volume)

Initializes a Floor object.

Parameters

• floor_height (wp.float32) – Floor height

• floor_axis (wp.int32) – Floor axis (0-x, or 1-y, or 2-z)

• flip_floor (wp.int32) – Flips the direction of the floor (0-False, 1-True)

• integration_pt_volume (wp.array) – Volume at each point of size \((\text{num_pts},)\)

energy(dx, x0, coeff, energy=None)

Returns the floor energy at each integration primitive.

Parameters

• dx (wp.array) – Delta in position of size \((\text{num_pts}, 3)\)

• x0 (wp.array) – Rest position of size \((\text{num_pts}, 3)\)

• coeff (wp.float32) – Coefficient

Returns

Floor energy array of size \(1\)

Return type

wp.array(dtype=wp.float32)

gradient(dx, x0, coeff, gradients)

Returns the floor gradient at each integration primitive.

Parameters

• dx (wp.array) – Delta in position of size \((\text{num_pts}, 3)\)

• x0 (wp.array) – Rest position of size \((\text{num_pts}, 3)\)

• coeff (wp.float32) – Coefficient

Returns

Floor gradient of size \((\text{num_pts}, 3)\)

Return type

wp.array(dtype=wp.vec3)

hessian(dx, x0, coeff)

Returns the floor hessian at each integration primitive.

Parameters

• dx (wp.array) – Delta in position of size \((\text{num_pts}, 3)\)

• x0 (wp.array) – Rest position of size \((\text{num_pts}, 3)\)

• coeff (wp.float32) – Coefficient

Returns

Floor hessian as an array of wp.mat33 block-wise matrices of size \((\text{num_pts}, 3, 3)\)

Return type

wp.array(dtype=wp.mat33)

class kaolin.physics.common.Gravity(g, integration_pt_density, integration_pt_volume)

Bases: object

Gravity class acts as a wrapper for the gravity energy, gradient, and hessian kernels.

__init__(g, integration_pt_density, integration_pt_volume)

Initializes a Gravity object.

Parameters

• g (wp.vec3) – Gravity acceleration (0, -9.81, 0)

• integration_pt_density (wp.array) – Density at each point of size \((\text{num_pts})\) (in \(kg/m^3\))

• integration_pt_volume (wp.array) – Volume at each point of size \((\text{num_pts})\) (in \(m^3\))

energy(dx, x0, coeff, energy=None)

Returns the gravity energy at each integration primitive.

Parameters

• dx (wp.array) – Delta in position of size \((\text{num_pts}, 3)\)

• x0 (wp.array) – Rest position of size \((\text{num_pts}, 3)\)

• coeff (wp.float32) – Coefficient

Returns

Gravity energy array of size \(1\)

Return type

wp.array(dtype=wp.float32)

gradient(dx, x0, coeff, gradients)

Returns the gravity gradient at each integration primitive.

Parameters

• dx (wp.array) – Delta in position of size \((\text{num_pts}, 3)\)

• x0 (wp.array) – Rest position of size \((\text{num_pts}, 3)\)

• coeff (wp.float32) – Coefficient

Returns

Gravity gradient of size \((\text{num_pts}, 3)\)

Return type

wp.array(dtype=wp.vec3)

hessian(dx, x0, coeff)

Returns the gravity hessian at each integration primitive.

Parameters

• dx (wp.array) – Delta in position of size \((\text{num_pts}, 3)\)

• x0 (wp.array) – Rest position of size \((\text{num_pts}, 3)\)

• coeff (wp.float32) – Coefficient of hessian

Returns

Gravity hessian of size \((\text{num_pts}, 3, 3)\)

Return type

wp.array(dtype=wp.mat33)

kaolin.physics.common.newtons_method(x, energy_fcn, gradient_fcn, hessian_fcn, bounds_fcn=None, preconditioner_fcn=None, P=None, Pt=None, nm_max_iters=5, cg_tol=0.0001, cg_iters=100, conv_tol=0.0001, direct_solve=False, bounds_qr_tfm=None, bounds_qr_tfm_inv=None)

Newton’s method optimizes for the updated dofs at the next time step. At each iteration, it computes the updated direction dz, finds an appropriate step size, and updates the dofs. It continues to do this iteratively until the directional update is small which indicates the energy is minimized.

Parameters

• x (wp.array) – Initial guess of size \((\text{num_dofs},)\)

• energy_fcn (function) – Energy function. Takes in warp.array and returns a scalar.

• gradient_fcn (function) – Gradient function. Takes in warp.array and returns a warp.array.

• hessian_fcn (function) – Hessian function. Takes in warp.array and returns a sparse matrix (wps.bsr_matrix).

• bounds_fcn (function) – Bounds function to compute the collision bounds of each DOF. Takes two warp.arrays and returns a warp.array.

• preconditioner_fcn (function) – Preconditioner function. Takes in a sparse matrix and returns a preconditioner.

• P (wps.bsr_matrix, optional) – Projection matrix. Defaults to None.

• Pt (wps.bsr_matrix, optional) – Projection matrix transpose. Defaults to None.

• nm_max_iters (int, optional) – Maximum number of iterations. Defaults to 5.

• cg_tol (float, optional) – CG tolerance. Defaults to 1e-4.

• cg_iters (int, optional) – CG iterations. Defaults to 100.

• conv_tol (float, optional) – Convergence tolerance. Defaults to 1e-4.

• direct_solve (bool, optional) – Whether to use a dense direct solver, or a sparse CG solver. Defaults to False.

• bounds_qr_tfm (torch.Tensor, optional) – If apply_qr=True, this is the forward direction used in the line search’s apply_bounds for collision bounds in the raw sparse-DOF basis. If apply_qr=False, this is None. Forwarded to _apply_bounds; see that function for the basis-change semantics.

• bounds_qr_tfm_inv (torch.Tensor, optional) – If apply_qr=True, this is the inverse direction used in the line search’s apply_bounds for collision bounds in the raw sparse-DOF basis. If apply_qr=False, this is None. Forwarded to _apply_bounds.

Returns

Optimized objective of size \((\text{num_dofs},)\)

Return type

wp.array