kaolin.experimental.newton

API

class kaolin.experimental.newton.SimplicitsModel(*args: Any, **kwargs: Any)

Bases: Model

Extends Newton’s Model for Simplicits physics simulations.

simplicits_scene

Simplicits scene instance.

Type

kaolin.physics.simplicits.SimplicitsScene

__init__(device=None)

Initialize the model with an empty Simplicits scene.

Parameters

device (wp.device or str or None) – Target device for simulation (GPU).

sim_z_dot_to_full(sim_z_dot: array)

Convert reduced coordinate velocities to full particle velocities.

Parameters

sim_z_dot (wp.array) – Reduced coordinate velocity vector.

Returns

Full particle velocities, or empty array if scene uninitialized.

Return type

(wp.array(dtype=wp.vec3))

sim_z_to_full(sim_z: array)

Convert reduced coordinates to full particle positions.

Parameters

sim_z (wp.array) – Reduced coordinate state vector.

Returns

Full particle positions, or empty array if scene uninitialized.

Return type

(wp.array(dtype=wp.vec3))

state(requires_grad: bool | None = None) → SimplicitsState

Create a new simulation state initialized from the Simplicits scene.

Parameters

requires_grad (bool or None) – Whether to enable gradient tracking for state variables.

Returns

State with initialized position, velocity, and DOF arrays.

Return type

(SimplicitsState)

class kaolin.experimental.newton.SimplicitsModelBuilder(*args: Any, **kwargs: Any)

Bases: ModelBuilder

Extends Newton’s ModelBuilder to handle SimplicitsModel construction.

model

The SimplicitsModel being constructed by this builder.

Type

SimplicitsModel

__init__(up_axis: newton._src.core.types.AxisType = newton._src.core.types.Axis.Z, gravity: float = - 9.81)

Initialize the builder with an empty SimplicitsModel.

Parameters

  • up_axis (AxisType) – The axis to use as the “up” direction in the simulation. Defaults to Axis.Z.

  • gravity (float) – The magnitude of gravity to apply along the up axis. Defaults to -9.81.

add_simplicits_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)

Enable soft-body to soft-body collisions between Simplicits objects.

Wraps SimplicitsScene.enable_collisions() for self-collisions and inter-object collisions. The call is deferred until finalize().

Parameters

  • collision_particle_radius (float) – Scene-wide collision particle radius; penalty begins here. Defaults to 0.1.

  • detection_ratio (float) – Collision detection radius as ratio of collision_particle_radius. Defaults to 1.5.

  • impenetrable_barrier_ratio (float) – Collision barrier radius as ratio of collision_particle_radius. Defaults to 0.25.

  • collision_penalty (float) – Stiffness of the collision interaction. Defaults to 1000.0.

  • max_contact_pairs (int) – Maximum number of contact pairs to detect. Defaults to 10000.

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

add_simplicits_object(sim_object: Union[SimplicitsObject, SkinnedPhysicsPoints], num_qp=None, init_transform=None, is_kinematic=False, renderable_pts=None)

Add a Simplicits soft-body object to the model.

Wraps SimplicitsScene.add_object() to add deformable objects to the simulation.

Parameters

  • sim_object (SimplicitsObject | SkinnedPhysicsPoints) – trained simplicits object or already sampled skinned points, e.g. from USD file.

  • num_qp (int) – Number of quadrature points (sample points to integrate over). If not provided, the object will not be subsampled.

  • init_transform (torch.Tensor or None) – 3x4 or 4x4 tensor for the object’s initial skinning transform. Takes a standard transformation, not a delta; the identity matrix is subtracted and the delta is saved.

  • is_kinematic (bool) – If True, object is kinematic and not solved during dynamics.

  • renderable_pts (torch.Tensor or None) – Optional rest positions for a separate rendered point set (see kaolin.physics.simplicits.simulation.SimplicitsScene.add_object()). This is not to be used with already baked SkinnedPhysicsPointsProtocol.

add_simplicits_object_boundary_condition(obj_idx, name, fcn, bdry_penalty=10000.0, pinned_x=None)

Add boundary conditions to the Simplicits scene.

Wraps SimplicitsScene.set_object_boundary_condition() for a specific object. The call is deferred until finalize().

Parameters

  • obj_idx (int) – Id of the object.

  • name (str) – Boundary condition name.

  • fcn (Callable) – Function defining which indices the boundary condition applies to; returns a boolean \((n,)\) vector where boundary indices are True.

  • bdry_penalty (float) – Boundary condition penalty coefficient.

  • pinned_x (torch.Tensor or None) – Pinned positions for the boundary. If None, positions are taken from the current object positions.

finalize(device='cuda', requires_grad=False, **kwargs) → SimplicitsModel

Finalize and build the SimplicitsModel instance.

Registers Simplicits particles with Newton, finalizes the base model, and automatically enables soft-rigid body collisions if objects exist.

Parameters

  • device (str or torch.device) – Target device for the model.

  • requires_grad (bool) – Whether gradients are required. Defaults to False. If True, a warning is issued; Simplicits is not differentiable yet and finalize still runs with requires_grad=False.

  • **kwargs – Forwarded to newton.ModelBuilder.finalize() (e.g. validation skips).

Returns

Fully constructed model ready for simulation.

Return type

(SimplicitsModel)

class kaolin.experimental.newton.SimplicitsSolver(*args: Any, **kwargs: Any)

Bases: SolverBase

Integrates Simplicits’s solver with other newton solvers.

The model attribute (inherited from the base solver) holds the SimplicitsModel instance containing scene and simulation data.

__init__(model: SimplicitsModel)

Initialize the solver with a SimplicitsModel.

Parameters

model (SimplicitsModel) – The SimplicitsModel to simulate.

model: SimplicitsModel
step(state_in: SimplicitsState, state_out: SimplicitsState, control: newton.Control, contacts: newton.Contacts, dt: float) → SimplicitsState

Advance simulation by one timestep.

If state includes simplicits DOFs, copies the state to Simplicits scene and runs the simulation in the Simplicits scene with collision handling. Only updates the Simplicits particle subset of the state’s particle arrays.

Parameters

  • state_in (SimplicitsState) – Current simulation state.

  • state_out (SimplicitsState) – Output state to populate.

  • control (Control) – Control inputs (unused by Simplicits).

  • contacts (Contacts) – Contact information for soft-rigid collisions.

  • dt (float) – Timestep size in seconds.

Returns

Updated state_out with new simulation state.

Return type

(SimplicitsState)

class kaolin.experimental.newton.SimplicitsState(*args: Any, **kwargs: Any)

Bases: State

Extended Newton state for flattened Simplicits DOFs.

sim_z

Flattened dofs with shape \((3*4*\text{num_handles}, )\).

Type

wp.array or None

sim_z_prev

Flattened dofs with shape \((3*4*\text{num_handles},)\).

Type

wp.array or None

sim_z_dot

Flattened dofs with shape \((3*4*\text{num_handles},)\).

Type

wp.array or None

__init__()

Initialize a SimplicitsState with None values for simulation variables (no arguments).