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.

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

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)

get_jacobian(cp_w, cp_x0, cp_is_static=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.

Note

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

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.

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.

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)

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.

Returns

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

Return type

wp.array