newton.State#

class newton.State[source]#

Bases: object

Represents the time-varying state of a Model in a simulation.

The State object holds all dynamic quantities that change over time during simulation, such as particle and rigid body positions, velocities, and forces, as well as joint coordinates.

State objects are typically created via newton.Model.state() and are used to store and update the simulation’s current configuration and derived data.

__init__()#

assign(other)#

Copies the array attributes of another State object into this one.

Parameters:: other (State) – The source State object to copy from.
Raises:: ValueError – If the states have mismatched attributes (one has an array where the other is None).

clear_forces()#

Clear all force arrays (for particles and bodies) in the state object.

Sets all entries of particle_f and body_f to zero, if present.

property body_count: int#: The number of bodies represented in the state.

body_f: array | None#: Rigid body forces (spatial), shape (body_count,), dtype spatial_vector. First three entries: linear force; last three: torque.

Note

body_f represents external wrenches in world frame, measured at the body’s center of mass (COM). The linear force component is applied at the COM, and the torque is about the COM. This convention is consistent across all solvers (XPBD, SemiImplicit, Featherstone, MuJoCo, VBD).

body_q: array | None#: Rigid body transforms (7-DOF), shape (body_count,), dtype transform.

body_q_prev: array | None#: Previous rigid body transforms for finite-difference velocity computation.

body_qd: array | None#: Rigid body velocities (spatial), shape (body_count,), dtype spatial_vector. First three entries: linear velocity; last three: angular velocity.

property joint_coord_count: int#: The number of generalized joint position coordinates represented in the state.

property joint_dof_count: int#: The number of generalized joint velocity coordinates represented in the state.

joint_q: array | None#: Generalized joint position coordinates, shape (joint_coord_count,), dtype float.

joint_qd: array | None#: Generalized joint velocity coordinates, shape (joint_dof_count,), dtype float.

property particle_count: int#: The number of particles represented in the state.

particle_f: array | None#: 3D forces on particles, shape (particle_count,), dtype vec3.

particle_q: array | None#: 3D positions of particles, shape (particle_count,), dtype vec3.

particle_qd: array | None#: 3D velocities of particles, shape (particle_count,), dtype vec3.

property requires_grad: bool#: Indicates whether the state arrays have gradient computation enabled.