Extended State Attributes#

Newton’s State object can optionally carry extra arrays that are not always needed (e.g., accelerations for sensors). These are called extended state attributes and are allocated by the Model.state method, if they have been previously requested on the Model or ModelBuilder.

Allocation of State Attributes#

  • Core state attributes are allocated automatically based on what exists in the model (for example, rigid bodies imply body_q/body_qd).

  • Extended state attributes are allocated and computed only if you request them before calling Model.state().

  • You can request them either on the finalized model (Model.request_state_attributes) or earlier on the builder (ModelBuilder.request_state_attributes).

  • Once an attribute has been requested, subsequent requests for the same attribute have no effect.

Example:

builder = newton.ModelBuilder()
# build/import model ...
builder.request_state_attributes("body_qdd")  # can request on the builder
model = builder.finalize()
model.request_state_attributes("body_parent_f")  # can also request on the finalized model

state = model.state()  # state.body_qdd and state.body_parent_f are allocated

List of extended state attributes#

The canonical list of requestable extended state attribute names is State.EXTENDED_STATE_ATTRIBUTES.

The following optional State attributes can currently be requested and allocated by Model.state():

Attribute name

Description

body_qdd

Rigid-body spatial accelerations (used by SensorIMU)

body_parent_f

Rigid-body parent interaction wrenches

Notes#

  • Some components transparently request the attributes they need. For example, SensorIMU requires body_qdd and requests it from the model you pass in. For this to work, you must create the sensor before you allocate the State via Model.state(). See SensorIMU.

  • Solvers only populate optional outputs they explicitly support. When an extended state attribute is allocated on the State, a supporting solver will update it during its step() method. Currently, only SolverMuJoCo supports populating body_qdd and body_parent_f.