---

name: physics-simulation description: "Operate Kaolin Simplicits physics, material, and experimental Newton-coupling workflows without running expensive simulations by default." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Kaolin physics simulation

Use this sub-skill for Kaolin physics tasks involving Simplicits soft bodies, point-sampled material data, scene setup, Warp/CUDA backend checks, and experimental Newton coupling. Keep it as an operating router: read the bundled references before proposing code, and use the bundled probe before promising a simulation can run.

Read first

• API reference for Simplicits objects, material tensors, scene methods, and experimental Newton classes.
• Workflows for bounded mesh, point-cloud, Gaussian, baked-object, scene, and Newton-coupling plans.
• Troubleshooting for Warp/CUDA, shape/device, scene setup, collision, Newton, and long-running notebook failures.
• Backend probe for safe import/device checks.

Use when

• A task asks for kaolin.physics, kaolin.physics.simplicits, PhysicsPoints, SimplicitsObject, SkinnedPhysicsPoints, SimplicitsScene, Simplicits training/baking/simulation, elastic materials, gravity/floor/boundaries/collisions, or reduced-coordinate deformation.
• A user has mesh, point-cloud, Gaussian, or baked skinned-physics data and wants a bounded plan to create physics inputs, add objects to a scene, step the simulation, or query deformed/rendered points.
• A task mentions Newton coupling with rigid bodies, MPM, or articulated robots; treat that path as experimental and optional-dependency gated.
• A setup fails due to missing Warp/CUDA/Newton, invalid material tensor shapes, wrong num_qp/renderable_pts usage, or scene-force ordering.

Route elsewhere

• General geometry loading, OBJ/PLY/USD/GLTF importer details, SurfaceMesh, PointSamples, or GaussianSplatModel container construction: route to geometry-io-representations.
• Sampling/conversions such as mesh or Gaussian point sampling, densification, packed/padded tensor utilities, SPC, metrics, quaternion math, or generic tensor transforms: route to ops-metrics-conversions.
• Output visualization, Timelapse logging, notebook widgets, Dash3D/web servers, or rendered result presentation: route to visualization-workflows.
• Camera/rasterization/lighting setup for rendered images: route to rendering-cameras-lighting.

Operating rules

1. Probe before running. Simplicits scene stepping is Warp/CUDA-sensitive; run or request python scripts/physics_backend_probe.py --json before recommending a real simulation run. Do not treat CPU tensor construction as proof that scene stepping works.
2. Separate input preparation from simulation. Ask geometry/ops owners to produce point samples and optional renderable points; this sub-skill owns the physics tensors, Simplicits object creation, scene forces, stepping, and deformation queries.
3. Prefer bounded plans. For notebooks/tutorial-style requests, avoid long MLP/RKPM training or asset downloads by default. Offer rigid/small-sample or baked-object smoke plans first, then mark full training as expensive.
4. Keep tensor contracts explicit. pts and renderable points are (N, 3); yms, prs, and rhos are scalar or (N,); appx_vol is scalar-like; skinning_weights are (N, H); dwdx is (N, H, 3).
5. Record backend gates. Warp and CUDA are required for practical scene stepping; Newton coupling additionally requires a compatible newton package. Browser/Jupyter/USD output paths are optional and routed to other sub-skills.
6. Use internal references only. Do not depend on the original repository, notebooks, tests, or local checkout paths at runtime; this sub-skill is the operating context.

Minimal decision flow

1. Identify the representation: already point-sampled, mesh-derived, Gaussian- derived, or baked SkinnedPhysicsPoints.
2. Confirm backend target: dry-plan only, CPU construction smoke, CUDA/Warp simulation, or experimental Newton coupling.
3. Build/validate PhysicsPoints or SkinnedPhysicsPoints using the API table.
4. Choose object construction: rigid, custom function, MLP training, RKPM basis, or pre-baked load.
5. Build SimplicitsScene, add objects with correct num_qp and renderable points, set forces/collisions, then step only when backend probes pass.
6. Query get_object_deformed_pts or get_object_point_transforms; route logging/USD/visualization to the visualization or geometry I/O sub-skills.