newton.Contacts#

class newton.Contacts(rigid_contact_max, soft_contact_max, requires_grad=False, device=None, per_contact_shape_properties=False, clear_buffers=False, requested_attributes=None)[source]#

Bases: object

Stores contact information for rigid and soft body collisions, to be consumed by a solver.

This class manages buffers for contact data such as positions, normals, thicknesses, and shape indices for both rigid-rigid and soft-rigid contacts. The buffers are allocated on the specified device and can optionally require gradients for differentiable simulation.

Note

This class is a temporary solution and its interface may change in the future.

classmethod validate_extended_attributes(attributes)#

Validate names passed to request_contact_attributes().

Only extended contact attributes listed in EXTENDED_ATTRIBUTES are accepted.

Parameters:

attributes (tuple[str, ...]) – Tuple of attribute names to validate.

Raises:

ValueError – If any attribute name is not in EXTENDED_ATTRIBUTES.

__init__(rigid_contact_max, soft_contact_max, requires_grad=False, device=None, per_contact_shape_properties=False, clear_buffers=False, requested_attributes=None)#

Initialize Contacts storage.

Parameters:

  • rigid_contact_max (int) – Maximum number of rigid contacts

  • soft_contact_max (int) – Maximum number of soft contacts

  • requires_grad (bool) – Whether soft contact arrays require gradients for differentiable simulation. Rigid contact arrays are always allocated without gradients because the narrow phase kernels do not support backward passes. Soft contact arrays (body_pos, body_vel, normal) are allocated with requires_grad so that gradient-based optimisation can flow through particle-shape contacts.

  • device (Device | str | None) – Device to allocate buffers on

  • per_contact_shape_properties (bool) – Enable per-contact stiffness/damping/friction arrays

  • clear_buffers (bool) – If True, clear() will zero all contact buffers (slower but conservative). If False (default), clear() only resets counts, relying on collision detection to overwrite active contacts. This is much faster (86-90% fewer kernel launches) and safe since solvers only read up to contact_count.

  • requested_attributes (set[str] | None) – Set of extended contact attribute names to allocate. See EXTENDED_ATTRIBUTES for available options.

clear()#

Clear contact data, resetting counts and optionally clearing all buffers.

By default (clear_buffers=False), only resets contact counts. This is highly optimized, requiring just 1 kernel launch. Collision detection overwrites all data up to the new contact_count, and solvers only read up to count, so clearing stale data is unnecessary.

If clear_buffers=True (conservative mode), performs full buffer clearing with sentinel values and zeros. This requires 7-10 kernel launches but may be useful for debugging.

EXTENDED_ATTRIBUTES: frozenset[str] = frozenset({'force'})#

Names of optional extended contact attributes that are not allocated by default.

These can be requested via newton.ModelBuilder.request_contact_attributes() or newton.Model.request_contact_attributes() before calling newton.Model.contacts() or newton.CollisionPipeline.contacts().

See Extended Contact Attributes for details and usage.

property device#

Returns the device on which the contact buffers are allocated.

force: array | None#

Contact forces (spatial), shape (rigid_contact_max + soft_contact_max,), dtype spatial_vector. Force and torque exerted on body0 by body1, referenced to the center of mass (COM) of body0, and in world frame, where body0 and body1 are the bodies of shape0 and shape1. First three entries: linear force; last three entries: torque (moment). When both rigid and soft contacts are present, soft contact forces follow rigid contact forces.

This is an extended contact attribute; see Extended Contact Attributes for more information.