Extended Attributes

Newton’s State and Contacts objects can optionally carry extra arrays that are not always needed. These extended attributes are allocated on demand when explicitly requested, reducing memory usage for simulations that don’t need them.

Extended Contact Attributes

Extended contact attributes are optional arrays on Contacts (e.g., contact forces for sensors). Request them via Model.request_contact_attributes or ModelBuilder.request_contact_attributes before creating a Contacts object.

import newton

builder = newton.ModelBuilder()
body = builder.add_body(mass=1.0)
builder.add_shape_sphere(body, radius=0.1)
model = builder.finalize()

# Request the "force" extended attribute directly
model.request_contact_attributes("force")

contacts = model.contacts()
print(contacts.force is not None)

True

Some components request attributes transparently. For example, SensorContact requests "force" at init time, so creating the sensor before allocating contacts is sufficient:

import warp as wp
import newton
from newton.sensors import SensorContact

builder = newton.ModelBuilder()
builder.add_ground_plane()
body = builder.add_body(xform=wp.transform((0, 0, 0.1), wp.quat_identity()))
builder.add_shape_sphere(body, radius=0.1, label="ball")
model = builder.finalize()

sensor = SensorContact(model, sensing_obj_shapes="ball")
contacts = model.contacts()
print(contacts.force is not None)

True

The canonical list is Contacts.EXTENDED_ATTRIBUTES:

Attribute	Description
force	Contact spatial forces (used by SensorContact)

Extended State Attributes

Extended state attributes are optional arrays on State (e.g., accelerations for sensors). Request them via Model.request_state_attributes or ModelBuilder.request_state_attributes before calling Model.state().

import newton

builder = newton.ModelBuilder()
body = builder.add_body(mass=1.0)
builder.request_state_attributes("body_qdd")
model = builder.finalize()

state = model.state()
print(state.body_qdd is not None)

True

The canonical list is State.EXTENDED_ATTRIBUTES:

Attribute	Description
body_qdd	Rigid-body spatial accelerations (used by SensorIMU)
body_parent_f	Rigid-body parent interaction wrenches
qfrc_actuator	Actuator forces in generalized (joint DOF) coordinates, namespaced under state.mujoco.qfrc_actuator. Only populated by SolverMuJoCo.

Notes

• Some components transparently request attributes they need. For example, SensorIMU requests body_qdd and SensorContact requests force. Create sensors before allocating State/Contacts for this to work automatically.

• Solvers populate extended attributes they support. Currently, SolverMuJoCo populates body_qdd, body_parent_f, mujoco:qfrc_actuator, and force.