kaolin.physics.simplicits¶
API¶
- class kaolin.physics.simplicits.SimplicitsMLP(spatial_dimensions, layer_width, num_handles, num_layers)¶
Bases:
ModuleThis implements an MLP with ELU activations
- Parameters
- forward(x)¶
Calls the network
- Parameters
x (torch.Tensor) – Tensor of spatial points in \(\mathbb{R}^dim\), of shape \((\text{batch_dim}, \text{dim})\)
- Returns
Skinning weights, of shape \((\text{batch_dim}, \text{num_handles})\)
- Return type
- class kaolin.physics.simplicits.SimplicitsObject(pts, yms, prs, rhos, appx_vol, skinning_weight_function=None)¶
Bases:
object- static create_from_function(pts, yms, prs, rhos, appx_vol, fcn)¶
Creates a SimplicitsObject with a custom skinning weight function.
This method creates a SimplicitsObject using a user-provided function to compute skinning weights. The function should take points as input and return a matrix of skinning weights.
- Parameters
pts (torch.Tensor) – Points tensor of shape (N, 3) representing the object’s geometry
yms (Union[torch.Tensor, float]) – Young’s moduli defining material stiffness. Can be either: - A tensor of shape (N,) for per-point values - A float value that will be applied to all points
prs (Union[torch.Tensor, float]) – Poisson’s ratios defining material compressibility. Can be either: - A tensor of shape (N,) for per-point values - A float value that will be applied to all points
rhos (Union[torch.Tensor, float]) – Density defining material density. Can be either: - A tensor of shape (N,) for per-point values - A float value that will be applied to all points
appx_vol (Union[torch.Tensor, float]) – Approximate volume. Can be either: - A tensor of shape (1,) - A float value
fcn (callable) – Function that takes points and returns skinning weights matrix
- Returns
A SimplicitsObject with the provided skinning weight function
- Return type
- static create_rigid(pts, yms, prs, rhos, appx_vol=1)¶
Creates a rigid SimplicitsObject with a single weight for affine deformations.
This method creates a SimplicitsObject that behaves as a rigid body. At low stiffness values (young’s modulus/ym), deformations will not be expressive, but with high stiffness values, the object will act as rigid.
- Parameters
pts (torch.Tensor) – Points tensor of shape \((N, 3)\) representing the object’s geometry
yms (Union[torch.Tensor, float]) – Young’s moduli defining material stiffness. Can be either: - A tensor of shape \((N,)\) for per-point values - A float value that will be applied to all points
prs (Union[torch.Tensor, float]) – Poisson’s ratios defining material compressibility. Can be either: - A tensor of shape \((N,)\) for per-point values - A float value that will be applied to all points
rhos (Union[torch.Tensor, float]) – Density defining material density. Can be either: - A tensor of shape \((N,)\) for per-point values - A float value that will be applied to all points
appx_vol (Union[torch.Tensor, float], optional) – Approximate volume. Can be either: - A tensor of shape \((1,)\) - A float value. Defaults to 1
- Returns
A rigid SimplicitsObject with a constant weight function
- Return type
- static create_trained(pts, yms, prs, rhos, appx_vol, num_handles=10, num_samples=1000, model_layers=6, training_batch_size=10, training_num_steps=10000, training_lr_start=0.001, training_lr_end=0.001, training_le_coeff=0.1, training_lo_coeff=1000000.0, training_log_every=1000, normalize_for_training=True)¶
Constructs a SimplicitsObject by training a neural network to learn skinning weights.
This method creates a SimplicitsObject by training a neural network to learn skinning weights that can be used for deformation. The network is trained to minimize a combination of local and global energy terms.
Note
If num_handles is set to 0, the object will be created as rigid instead of deformable. The training process uses a combination of local and global energy terms to ensure both local detail preservation and global shape maintenance.
- Parameters
pts (torch.Tensor) – Points tensor of shape \((N, 3)\) representing the object’s geometry
yms (Union[torch.Tensor, float]) – Young’s moduli defining material stiffness. Can be either: - A tensor of shape \((N,)\) for per-point values - A float value that will be applied to all points
prs (Union[torch.Tensor, float]) – Poisson’s ratios defining material compressibility. Can be either: - A tensor of shape \((N,)\) for per-point values - A float value that will be applied to all points
rhos (Union[torch.Tensor, float]) – Density defining material density. Can be either: - A tensor of shape \((N,)\) for per-point values - A float value that will be applied to all points
appx_vol (torch.Tensor) – Approximate volume tensor of shape \((1,)\)
num_handles (int, optional) – Number of control handles for deformation. Defaults to 10
num_samples (int, optional) – Number of samples used for training. Defaults to 1000
model_layers (int, optional) – Number of layers in the neural network. Defaults to 6
training_batch_size (int, optional) – Batch size for training. Defaults to 10
training_num_steps (int, optional) – Number of training iterations. Defaults to 10000
training_lr_start (float, optional) – Initial learning rate. Defaults to 1e-3
training_lr_end (float, optional) – Final learning rate. Defaults to 1e-3
training_le_coeff (float, optional) – Coefficient for local energy term. Defaults to 1e-1
training_lo_coeff (float, optional) – Coefficient for global energy term. Defaults to 1e6
training_log_every (int, optional) – Logging frequency during training. Defaults to 1000
normalize_for_training (bool, optional) – Whether to normalize points to unit cube for training. Defaults to True
- Returns
A trained SimplicitsObject with learned skinning weights
- Return type
- class kaolin.physics.simplicits.SimplicitsScene(device='cuda', dtype=torch.float32, direct_solve=True, use_cuda_graphs=False, timestep=0.03, max_newton_steps=5, max_ls_steps=10, newton_hessian_regularizer=0.0001, cg_tol=0.0001, cg_iters=100, conv_tol=0.0001)¶
Bases:
object- add_object(sim_object, num_qp=1000, init_transform=None, is_kinematic=False)¶
Adds a simplicits object to the scene as a SimulatedObject.
- Parameters
sim_object (SimplicitsObject) – Simplicits object that will be wrapped into a SimulatedObject for this scene.
num_qp (float) – Number of quadrature points (sample points to integrate over)
init_transform (torch.Tensor) – 3x4 or 4x4 torch tensor specifying object’s initial skinning transform. This argument takes a standard transformation, not a delta. Subsequently, the Identity matrix is subtracted from it and the delta transform is saved.
is_kinematic (bool) – Object is kinematic if it is not solved for during dynamics simulation.
- enable_collisions(collision_particle_radius=0.1, detection_ratio=1.5, impenetrable_barrier_ratio=0.25, collision_penalty=1000.0, max_contact_pairs=10000, friction=0.5)¶
Sets collision for object in scene
- Parameters
collision_particle_radius (float, optional) – Scene-wide collision particle radius at which penalty begins to apply. Change this depending on the size of the object. Defaults: 0.1.
detection_ratio (float, optional) – Collision detection radius described as a ratio relative to the collision_particle_radius. Defaults: 1.5 times the collision_particle_radius.
impenetrable_barrier_ratio (float, optional) – Collision barrier radius described as a ratio relative to the collision_particle_radius. Defaults: 0.25 times the collision_particle_radius.
collision_penalty (float, optional) – Controls the stiffness of the collision interaction. Defaults: 1000 times the collision_particle_radius.
max_contact_pairs (int, optional) – Maximum number of contact pairs to detect. If this is too low, some contacts may be missed. If this is too high, memory may run out/jacobian may be too large. Defaults: 10000 contact pairs.
friction (float, optional) – Friction coefficient. Defaults: 0.5.
- get_object(obj_idx)¶
Get a particular object in the scene by its id.
- Parameters
obj_idx (int) – Id of object
- Returns
Simulated Object used by the scene. Also contains ref to simplicits object.
- Return type
- get_object_deformed_pts(obj_idx, points=None)¶
Applies linear blend skinning using object’s transformation to points provided. By default, points = sim_object.pts
- Parameters
obj_idx (int) – Id of object being transformed
points (torch.Tensor, optional) – Points on the object to be transformed. Defaults to None, which means using all object’s points.
- Returns
Transformed points
- Return type
- get_object_transforms(object_id)¶
Returns the current 4x4 padded relative transforms of the object’s handles. Add identity to the result get standard transform.
- Parameters
object_id (int) – Id of the object to get the transforms of
- Returns
Torch tensor of size \(( ext{num_handles}, 4, 4)\) for relative transforms.
- Return type
torch.tensor
- reset_scene()¶
Resets the scene and all objects in it.
- run_sim_step()¶
Runs a single simulation step.
- set_kinematic_object_transform(obj_idx, transform)¶
Sets the transform of a kinematic object. This can be done during simulation to script the kinematic object’s motion.
- Parameters
obj_idx (int) – Id of object
transform (torch.Tensor) – 3x4 or 4x4 torch tensor specifying object’s transform.
- set_object_boundary_condition(obj_idx, name, fcn, bdry_penalty=10000.0, pinned_x=None)¶
Sets boundary condition for object in scene
- Parameters
obj_idx (int) – Id of object
name (str) – Boundary condition name
fcn (Callable) – Function that defines which indices the boundary condition applies to. fcn should return a boolean \((n)\) vector where bdry indices are 1.
bdry_penalty (float) – Boundary condition penalty coefficient.
pinned_x (torch.Tensor, optional) – Pinned positions of the boundary condition. Used for setting the boundary to a specific position. Default: The pinned positions are set from the current object’s positions.
- set_object_initial_transform(object_id, init_transform)¶
Sets the initial transform of an object.
Note
This method reset the scene
- Parameters
object_id (int) – Id of the object to set the initial transform of
init_transform (torch.Tensor) – 4x4 torch tensor specifying object’s initial skinning transform. This argument takes a standard transformation, not a delta. Subsequently, the Identity matrix is subtracted from it and the delta transform is saved.
- set_scene_floor(floor_height=0.0, floor_axis=1, floor_penalty=10000.0, flip_floor=False)¶
Sets the floor in the scene. Applies it to all objects in scene.
- Parameters
floor_height (float, optional) – Floor height. Defaults to 0.
floor_axis (int, optional) – Direction of floor. 0 is x, 1 is y, 2 is z. Defaults to 1.
floor_penalty (float, optional) – Stiffness of floor. Defaults to 10000.
flip_floor (bool, optional) – Flips the direction of the floor. Defaults to False.
- set_scene_gravity(acc_gravity=tensor([0.0000, 9.8000, 0.0000]), gravity_coeff=1.0)¶
Sets the gravity in the scene. Applies it to all objects in scene.
- Parameters
acc_gravity (torch.Tensor, optional) – Gravity acceleration. Defaults to torch.tensor([0, 9.8, 0]) with acceleration due to gravity in the downward y direction.
gravity_coeff (float, optional) – Gravity coefficient. Defaults to 1.0.
- class kaolin.physics.simplicits.SimulatedObject(obj, id, num_qp, num_cp, init_transform, is_kinematic=False)¶
Bases:
object- Parameters
obj (SimplicitsObject) –
- reset_sim_state()¶
Reset the simulation state. Object’s handle transforms are set back to initial deformations. This does not reset any material parameters or simplicits object parameters.
- kaolin.physics.simplicits.compute_losses(model, normalized_pts, yms, prs, rhos, en_interp, batch_size, num_handles, appx_vol, num_samples, le_coeff, lo_coeff)¶
Perform a step of the simplicits training process
- Parameters
model (nn.module) – Simplicits network
normalized_pts (torch.Tensor) – Spatial points in \(R^3\), of shape \((\text{num_pts}, 3)\)
yms (torch.Tensor) – Point-wise youngs modulus, of shape \((\text{num_pts})\)
prs (torch.Tensor) – Point-wise poissons ratio, of shape \((\text{num_pts})\)
rhos (torch.Tensor) – Point-wise density, of shape \((\text{num_pts})\)
en_interp (float) – interpolation between energy at current step
batch_size (int) – Number of sample deformations
num_handles (int) – Number of handles
appx_vol (float) – Approximate volume of object
num_samples (int) – Number of sample points.
le_coeff (float) – floating point coefficient for elastic loss
lo_coeff (float) – floating point coefficient for orthogonal loss
- Returns
The elastic loss term, the orthogonality losses terms
- Return type
- kaolin.physics.simplicits.compute_losses_warp(model, normalized_pts, yms, prs, rhos, en_interp, batch_size, num_handles, appx_vol, num_samples, le_coeff, lo_coeff)¶
Perform a step of the simplicits training process
- Parameters
model (nn.module) – Simplicits network
normalized_pts (torch.Tensor) – Spatial points in \(\mathbb{R}^3\), of shape \((\text{num_pts}, 3)\)
yms (torch.Tensor) – Point-wise youngs modulus, of shape \((\text{num_pts})\)
prs (torch.Tensor) – Point-wise poissons ratio, of shape \((\text{num_pts})\)
rhos (torch.Tensor) – Point-wise density, of shape \((\text{num_pts})\)
en_interp (float) – interpolation between energy at current step
batch_size (int) – Number of sample deformations
num_handles (int) – Number of handles
appx_vol (float) – Approximate volume of object
num_samples (int) – Number of sample points.
le_coeff (float) – floating point coefficient for elastic loss
lo_coeff (float) – floating point coefficient for orthogonal loss
- Returns
The elastic loss term, the orthogonality losses terms
- Return type
- kaolin.physics.simplicits.jacobian_dF_dz(model, x0, z)¶
Calculates jacobian dF/dz
- Parameters
model (nn.Module) – Simplicits object network + constant handle
x0 (torch.Tensor) – Matrix of sample points, of shape \((\text{num_samples}, 3)\)
z (torch.Tensor) – Vector of flattened transforms, of shape \((12 \text{num_samples})\)
- Returns
Jacobian matrix, of shape \((9 \text{num_samples}, 12 \text{num_handles})\)
- Return type
- kaolin.physics.simplicits.jacobian_dx_dz(model, x0, z)¶
Calculates jacobian \(\frac{\partial x}{\partial z}\)
- Parameters
model (nn.Module) – Simplicits object network + constant handle
x0 (torch.Tensor) – Matrix of sample points, of shape \((\text{num_samples}, 3)\)
z (torch.Tensor) – Vector of flattened transforms, of shape \((12 \text{num_samples})\)
- Returns
Jacobian matrix, of shape \((3 \text{num_samples}, 12 \text{num_handles})\)
- Return type
- kaolin.physics.simplicits.lbs_matrix(x0, w)¶
Encodes the lbs equation \(x_i = sum(w(x^0_i)_j * T_j * \begin{pmatrix}x^0_i\\1\end{pmatrix},\; \forall \; j=0...\|handles\|)\) for all pts into matrix B such that flatten(x) = B(x0, w(x0))*flatten(T)
- Parameters
x0 (torch.Tensor) – Input points, of shape \((\text{num_samples}, 3)\)
w (torch.Tensor) – Weights, of shape \((\text{num_samples}, \text{num_handles})\)
- Returns
Matrix that encodes the lbs transformation, given a set of vertices and corresponding weights, shape \((3 \text{num_samples}, 12 \text{num_handles})\)
- Return type
- kaolin.physics.simplicits.loss_elastic(model, pts, yms, prs, rhos, transforms, appx_vol, interp_step, elasticity_type='neohookean', interp_material=False)¶
Calculate a version of simplicits elastic loss for training.
- Parameters
model (nn.Module) – Simplicits object network
pts (torch.Tensor) – Tensor of sample points in \(\mathbb{R}^dim\), for now dim=3, of shape \((\text{num_samples}, \text{dim})\)
yms (torch.Tensor) – Length pt-wise youngs modulus, of shape \((\text{num_samples})\)
prs (torch.Tensor) – Length pt-wise poisson ratios, of shape \((\text{num_samples})\)
rhos (torch.Tensor) – Length pt-wise density, of shape \((\text{num_samples})\)
transforms (torch.Tensor) – Batch of sample transformations, of shape \((\text{batch_size}, \text{num_handles}, \text{dim}, \text{dim}+1)\)
appx_vol (float) – Approximate (or exact) volume of object (in \(m^3\))
interp_step (float) – Length interpolation schedule for neohookean elasticity (0%->100%)
- Returns
Elastic loss, single value tensor
- Return type
- kaolin.physics.simplicits.loss_elastic_warp(model, pts, yms, prs, rhos, transforms, appx_vol, interp_step)¶
Calculate a version of simplicits elastic loss for training. This version uses Nvidia’s Warp .
- Parameters
model (nn.Module) – Simplicits object network
pts (torch.Tensor) – Tensor of sample points in \(\mathbb{R}^dim\), for now dim=3, of shape \((\text{num_samples}, \text{dim})\)
yms (torch.Tensor) – Length pt-wise youngs modulus, of shape \((\text{num_samples})\)
prs (torch.Tensor) – Length pt-wise poisson ratios, of shape \((\text{num_samples})\)
rhos (torch.Tensor) – Length pt-wise density, of shape \((\text{num_samples})\)
transforms (torch.Tensor) – Batch of sample transformations, of shape \((\text{batch_size}, \text{num_handles}, \text{dim}, \text{dim}+1)\)
appx_vol (float) – Approximate (or exact) volume of object (in \(m^3\))
interp_step (float) – Length interpolation schedule for neohookean elasticity (0%->100%)
- Returns
Elastic loss, single value tensor
- Return type
- kaolin.physics.simplicits.loss_ortho(weights)¶
Calculate orthogonality of weights
- Parameters
weights (torch.Tensor) – Tensor of weights, of shape \((\text{num_samples}, \text{num_handles})\)
- Returns
Orthogonality loss, single value tensor
- Return type
- kaolin.physics.simplicits.lumped_mass_matrix(rhos, total_volume, dim=3)¶
Calculate the lumped mass matrix of an object sampled via points with spatially uniform sampling, and potentially spatially varying density
- Parameters
rhos (torch.Tensor) – Point-wise vector of densities, of shape \((\text{num_samples})\)
total_volume (float) – Total volume of object in \(m^3\)
dim (int, optional) – Spatial dimensions. Defaults to 3.
- Returns
Diagonal mass matrix of size \((3 \text{num_samples}, 3 \text{num_samples})\) torch.Tensor: Diagonal INVERSE mass matrix of size \((3 \text{num_samples}, 3 \text{num_samples})\)
- Return type
- kaolin.physics.simplicits.sparse_collision_jacobian_matrix(sim_weights, sim_pts, indices, cp_is_static)¶
Creates a sparse collision Jacobian matrix from the global weights and points of the scene. Indices holds to the indices of the sim_pts and sim_weights to include in the matrix. If index corresponds to a static object, the point is not included, but zeros are added instead.
- Parameters
sim_weights (wp.array2d(dtype=wp.float32)) – Skinning weights.
sim_pts (wp.array(dtype=wp.vec3)) – Sample points.
indices (wp.array(dtype=wp.int32)) – Indices of the sim_pts and sim_weights to include in the matrix.
cp_is_static (wp.array(dtype=wp.int32)) – 1 if the point is in a static object, 0 otherwise.
- Returns
Sparse LBS matrix size \((3 \text{num_indices}, 12 \text{num_handles})\)
- Return type
wp.sparse.bsr_matrix
- kaolin.physics.simplicits.sparse_dFdz_matrix_from_dense(enriched_weights_fcn, pts)¶
Creates a sparse Jacobian matrix of the deformation gradient with respect to the sample points.
- Parameters
enriched_weights_fcn (function) – Function that returns the skinning weights for a given point.
pts (torch.Tensor) – Sample points.
- Returns
Sparse Jacobian matrix of size \((9 \text{num_samples}, 12 \text{num_handles})\)
- Return type
wp.sparse.bsr_matrix
- kaolin.physics.simplicits.sparse_lbs_matrix(sim_weights, sim_pts)¶
Creates a sparse LBS matrix from a set of points and corresponding weights.
- Parameters
sim_weights (wp.array2d(dtype=wp.float32)) – Skinning weights.
sim_pts (wp.array(dtype=wp.vec3)) – Sample points.
- Returns
Sparse LBS matrix of size \((3 \text{num_samples}, 12 \text{num_handles})\)
- Return type
wp.sparse.bsr_matrix
- kaolin.physics.simplicits.sparse_mass_matrix(sim_rhos)¶
Creates a sparse mass matrix from a set of densities.
- Parameters
sim_rhos (np.ndarray) – Densities.
- Returns
Sparse mass matrix of size \((3 \text{num_samples}, 3 \text{num_samples})\)
- Return type
wp.sparse.bsr_matrix
- kaolin.physics.simplicits.standard_lbs(x0, tfms, w_x0)¶
Applies the linear blend skinning transform batched over all pts (\(x_0\)) for a batch of transforms (\(T\)), given skinning weights (\(w_{x0}\)), as \(x_i = \sum_{j=1}^{n} w_j(x_{0,i}) \cdot T_j \begin{bmatrix} x_{0,i} \\ 1 \end{bmatrix} + x_{0,i}\)
- Parameters
x0 (torch.Tensor) – Rest state points, of shape \((\text{num_pts}, \text{dim})\)
tfms (torch.Tensor) – Tensor of affine handles, of shape \((\text{batch_size}, \text{num_handles}, \text{dim}, \text{dim}+1)\)
w_x0 (torch.Tensor) – Matrix of skinning weights, of shape \((\text{num_pts}, \text{num_handles})\)
- Returns
Transformed points, of shape \((\text{num_pts}, \text{dim})\)
- Return type
- kaolin.physics.simplicits.weight_function_lbs(x0, tfms, fcn)¶
Applies the linear blend skinning transform batched over all pts: x0 for a batch of transforms, given skinning weight function fcn. Differentiable over fcn.
- Parameters
x0 (torch.Tensor) – Rest state points, of shape \((\text{num_pts}, \text{dim})\)
tfms (torch.Tensor) – Tensor of affine handles, of shape \((\text{batch_size}, \text{num_handles}, \text{dim}, \text{dim}+1)\)
fcn (callable) – Skinning weights function
- Returns
Transformed points, of shape \((\text{num_pts}, \text{dim})\)
- Return type