newton.Model#

class newton.Model(device=None)[source]#

Bases: object

Represents the static (non-time-varying) definition of a simulation model in Newton.

The Model class encapsulates all geometry, constraints, and parameters that describe a physical system for simulation. It is designed to be constructed via the ModelBuilder, which handles the correct initialization and population of all fields.

Key Features:

Stores all static data for simulation: particles, rigid bodies, joints, shapes, soft/rigid elements, etc.
Supports grouping of entities by world using world indices (e.g., particle_world, body_world, etc.). - Index -1: global entities shared across all worlds. - Indices 0, 1, 2, …: world-specific entities.
Grouping enables: - Collision detection optimization (e.g., separating worlds) - Visualization (e.g., spatially separating worlds) - Parallel processing of independent worlds

Note

It is strongly recommended to use the ModelBuilder to construct a Model. Direct instantiation and manual population of Model fields is possible but discouraged.

class AttributeAssignment(*values)#

Bases: IntEnum

Enumeration of attribute assignment categories.

Defines which component of the simulation system owns and manages specific attributes. This categorization determines where custom attributes are attached during simulation object creation (Model, State, Control, or Contacts).

CONTACT = 3#: Contact attributes are attached to the Contacts object.

CONTROL = 2#: Control attributes are attached to the Control object.

MODEL = 0#: Model attributes are attached to the Model object.

STATE = 1#: State attributes are attached to the State object.

class AttributeFrequency(*values)#

Bases: IntEnum

Enumeration of attribute frequency categories.

Defines the dimensional structure and indexing pattern for custom attributes. This determines how many elements an attribute array should have and how it should be indexed in relation to the model’s entities such as joints, bodies, shapes, etc.

ARTICULATION = 7#: Attribute frequency follows the number of articulations (see articulation_count).

BODY = 5#: Attribute frequency follows the number of bodies (see body_count).

CONSTRAINT_MIMIC = 14#: Attribute frequency follows the number of mimic constraints (see constraint_mimic_count).

EDGE = 10#: Attribute frequency follows the number of edges (see edge_count).

EQUALITY_CONSTRAINT = 8#: Attribute frequency follows the number of equality constraints (see model.mujoco.equality_constraint_count).

Deprecated since version 1.3: Use the string frequency "mujoco:equality_constraint" instead. ModelBuilder.add_custom_attribute() translates this enum value to the string form for the duration of the deprecation window. Scheduled for removal in a future release.

JOINT = 1#: Attribute frequency follows the number of joints (see joint_count).

JOINT_CONSTRAINT = 4#: Attribute frequency follows the number of joint constraints (see joint_constraint_count).

JOINT_COORD = 3#: Attribute frequency follows the number of joint positional coordinates (see joint_coord_count).

JOINT_DOF = 2#: Attribute frequency follows the number of joint degrees of freedom (see joint_dof_count).

ONCE = 0#: Attribute frequency is a single value.

PARTICLE = 9#: Attribute frequency follows the number of particles (see particle_count).

SHAPE = 6#: Attribute frequency follows the number of shapes (see shape_count).

SPRING = 13#: Attribute frequency follows the number of springs (see spring_count).

TETRAHEDRON = 12#: Attribute frequency follows the number of tetrahedra (see tet_count).

TRIANGLE = 11#: Attribute frequency follows the number of triangles (see tri_count).

WORLD = 15#: Attribute frequency follows the number of worlds (see world_count).

class AttributeNamespace(name)#

Bases: object

A container for namespaced custom attributes.

Custom attributes are stored as regular instance attributes on this object, allowing hierarchical organization of related properties.

__init__(name)#

Initialize the namespace container.

Parameters:: name (str) – The name of the namespace

add_deprecated_alias(name, getter, message)#

Add a deprecated attribute alias.

Parameters:

name (str) – Alias name exposed on the namespace.
getter (Callable[[], Any]) – Callable returning the canonical target object.
message (str) – Deprecation warning message.

__init__(device=None)#

Initialize a Model object.

Parameters:: device (Device | str | None) – Device on which the Model’s data will be allocated.

add_attribute(name, attrib, frequency, assignment=None, namespace=None)#

Add a custom attribute to the model.

Parameters:

name (str) – Name of the attribute.
attrib (array | list[Any]) – The array to add as an attribute. Can be a wp.array for numeric types or a list for string attributes.
frequency (AttributeFrequency | str) – The frequency of the attribute. Can be a Model.AttributeFrequency enum value or a string for custom frequencies.
assignment (AttributeAssignment | None) – The assignment category using Model.AttributeAssignment enum. Determines which object will hold the attribute.
namespace (str | None) – Namespace for the attribute. If None, attribute is added directly to the assignment object (e.g., model.attr_name). If specified, attribute is added to a namespace object (e.g., model.namespace_name.attr_name).

Raises:

AttributeError – If the attribute already exists or is on the wrong device.

bvh_build_particles(state, *, bvh_constructor=None)#

Build or rebuild the particle BVH stored on this model.

Allocates bvh_particles and related fields from particle data in state. ModelBuilder.finalize() calls this for the initial model state when particles are present. Call it again to rebuild with a custom bvh_constructor. For ordinary state changes, use bvh_refit_particles().

Parameters:

state (newton.State) – Current simulation state with particle positions.
bvh_constructor (str | None) – Warp BVH construction algorithm. Valid choices are "sah", "median", "lbvh", or None to use Warp’s device-dependent default.

bvh_build_shapes(state, *, bvh_constructor=None)#

Build or rebuild the shape BVH stored on this model.

Allocates bvh_shapes and related fields from the current shape data and state. ModelBuilder.finalize() calls this for the initial model state. Call it again to rebuild with a custom bvh_constructor or after structural changes. For ordinary state changes, use bvh_refit_shapes().

Parameters:

state (newton.State) – Current simulation state with body transforms.
bvh_constructor (str | None) – Warp BVH construction algorithm. Valid choices are "sah", "median", "lbvh", or None to use Warp’s device-dependent default.

bvh_refit_particles(state)#

Refit the particle BVH stored on this model for the current state.

The particle BVH is built automatically by ModelBuilder.finalize() when particles are present. Manually populated models must call bvh_build_particles() first. Recomputes particle bounds from state.particle_q and refits the BVH in place.

Parameters:: state (newton.State) – Current simulation state with particle positions.

bvh_refit_shapes(state)#

Refit the shape BVH stored on this model for the current state.

The shape BVH is built automatically by ModelBuilder.finalize(). Manually populated models must call bvh_build_shapes() first. Updates world-space shape transforms from state.body_q and refits the BVH in place.

Parameters:: state (newton.State) – Current simulation state with body transforms.

collide(state, contacts=None, *, collision_pipeline=None)#

Generate contact points for the particles and rigid bodies in the model using the default collision pipeline.

Parameters:

state (State) – The current simulation state.
contacts (Contacts | None) – The contacts buffer to populate (will be cleared first). If None, a new contacts buffer is allocated via contacts().
collision_pipeline (CollisionPipeline | None) – Optional collision pipeline override.

contacts(collision_pipeline=None)#

Create and return a Contacts object for this model.

This method initializes a collision pipeline with default arguments (when not already cached) and allocates a contacts buffer suitable for storing collision detection results. Call collide() to run the collision detection and populate the contacts object.

Note

Rigid contact gaps are controlled per-shape via Model.shape_gap, which is populated from ModelBuilder.ShapeConfig.gap [m] during model building. If a shape doesn’t specify a gap [m], it defaults to builder.rigid_gap [m]. To adjust contact gaps [m], set them before calling ModelBuilder.finalize().

Returns:: The contact object containing collision information.
Return type:: Contacts

control(requires_grad=None, clone_variables=True)#

Create and return a new Control object for this model.

The returned control object is initialized with the control inputs from the model description.

Parameters:

requires_grad (bool | None) – Whether the control variables should have requires_grad enabled. If None, uses the model’s requires_grad setting.
clone_variables (bool) – If True, clone the control input arrays; if False, use references.

Returns:

The initialized control object.

Return type:

Control

get_attribute_frequency(name)#

Get the frequency of an attribute.

Parameters:

name (str) – Name of the attribute.

Returns:

The frequency of the attribute.: Either a Model.AttributeFrequency enum value or a string for custom frequencies.

Raises:

KeyError – If the attribute frequency is not known.

Return type:

AttributeFrequency | str

get_custom_frequency_count(frequency)#

Get the count for a custom frequency.

Parameters:: frequency (str) – The custom frequency (e.g., "mujoco:pair").
Returns:: The count of elements with this frequency.
Raises:: KeyError – If the frequency is not known.
Return type:: int

get_requested_contact_attributes()#

Get the set of requested contact attribute names.

Returns:: The set of requested contact attributes.
Return type:: set[str]

get_requested_state_attributes()#

Get the list of requested state attribute names that have been requested on the model.

See Extended State Attributes for details.

Returns:: The list of requested state attributes.
Return type:: list[str]

request_contact_attributes(*attributes)#

Request that specific contact attributes be allocated when creating a Contacts object.

Parameters:: *attributes (str) – Variable number of attribute names (strings).

request_state_attributes(*attributes)#

Request that specific state attributes be allocated when creating a State object.

See Extended State Attributes for details and usage.

Parameters:: *attributes (str) – Variable number of attribute names (strings).

set_gravity(gravity, world=None)#

Set gravity for runtime modification.

Parameters:

gravity (tuple[float, float, float] | list | vec3f | ndarray) – Gravity vector (3,) or per-world array (world_count, 3).
world (int | None) – If provided, set gravity only for this world.

Note

Call solver.notify_model_changed(ModelFlags.MODEL_PROPERTIES) after.

Global entities (particles/bodies not assigned to a specific world) use gravity from world 0.

state(requires_grad=None)#

Create and return a new State object for this model.

The returned state is initialized with the initial configuration from the model description.

Parameters:: requires_grad (bool | None) – Whether the state variables should have requires_grad enabled. If None, uses the model’s requires_grad setting.
Returns:: The state object.
Return type:: newton.State

actuators: list[Actuator]#: List of actuator instances for this model.

articulation_count: int#: Total number of articulations in the system.

articulation_end: wp.array[wp.int32] | None#: Exclusive end index of regular tree joints per articulation, shape [articulation_count], int.

articulation_label: list[str]#: Articulation labels, shape [articulation_count], str.

articulation_start: wp.array[wp.int32] | None#

Articulation start index plus sentinel, shape [articulation_count + 1], int.

The sentinel still bounds each articulation’s full joint range, including converted loop-closing joints. Use articulation_end for the exclusive end of regular tree joints.

articulation_world: wp.array[wp.int32] | None#: World index for each articulation, shape [articulation_count], int. -1 for global.

articulation_world_start: wp.array[wp.int32] | None#

Start index of the first articulation per world, shape [world_count + 2], int.

The entries at indices 0 to world_count - 1 store the start index of the articulations belonging to that world. The second-last element (accessible via index -2) stores the start index of the global articulations (i.e. with world index -1) added to the end of the model, and the last element stores the total articulation count.

The number of articulations in a given world w can be computed as:

num_articulations_in_world = articulation_world_start[w + 1] - articulation_world_start[w]

The total number of global articulations can be computed as:

num_global_articulations = articulation_world_start[-1] - articulation_world_start[-2] + articulation_world_start[0]

attribute_assignment: dict[str, Model.AttributeAssignment]#: Assignment for custom attributes using Model.AttributeAssignment enum values. If an attribute is not in this dictionary, it is assumed to be a Model attribute (assignment=Model.AttributeAssignment.MODEL).

attribute_frequency: dict[str, Model.AttributeFrequency | str]#: Classifies each attribute using Model.AttributeFrequency enum values (per body, per joint, per DOF, etc.) or custom frequencies for custom entity types (e.g., "mujoco:pair").

body_color_groups: list[wp.array[wp.int32]]#: Coloring of all rigid bodies for Gauss-Seidel iteration (see SolverVBD). Each array contains indices of bodies sharing the same color.

body_colors: wp.array[wp.int32] | None#: Color assignment for every rigid body.

body_com: wp.array[wp.vec3] | None#: Rigid body center of mass [m] (in local frame), shape [body_count, 3], float.

body_count: int#: Total number of bodies in the system.

body_flags: wp.array[wp.int32] | None#: Rigid body flags (BodyFlags), shape [body_count], int.

body_inertia: wp.array[wp.mat33] | None#: Rigid body inertia tensor [kg·m²] (relative to COM), shape [body_count, 3, 3], float.

body_inv_inertia: wp.array[wp.mat33] | None#: Rigid body inverse inertia tensor [1/(kg·m²)] (relative to COM), shape [body_count, 3, 3], float.

body_inv_mass: wp.array[wp.float32] | None#: Rigid body inverse mass [1/kg], shape [body_count], float.

body_label: list[str]#: Rigid body labels, shape [body_count], str.

body_mass: wp.array[wp.float32] | None#: Rigid body mass [kg], shape [body_count], float.

body_q: wp.array[wp.transform] | None#: Rigid body poses [m, unitless quaternion] for state initialization, shape [body_count, 7], float.

body_qd: wp.array[wp.spatial_vector] | None#: Rigid body velocities [m/s, rad/s] for state initialization, shape [body_count, 6], float. The linear component is the body COM velocity in world frame.

body_shapes: dict[int, list[int]]#: Mapping from body index to list of attached shape indices.

body_world: wp.array[wp.int32] | None#: World index for each body, shape [body_count], int. Global entities have index -1.

body_world_start: wp.array[wp.int32] | None#

Start index of the first body per world, shape [world_count + 2], int.

The entries at indices 0 to world_count - 1 store the start index of the bodies belonging to that world. The second-last element (accessible via index -2) stores the start index of the global bodies (i.e. with world index -1) added to the end of the model, and the last element stores the total body count.

The number of bodies in a given world w can be computed as:

num_bodies_in_world = body_world_start[w + 1] - body_world_start[w]

The total number of global bodies can be computed as:

num_global_bodies = body_world_start[-1] - body_world_start[-2] + body_world_start[0]

bvh_particles: wp.Bvh | None#: BVH over particles. Built by ModelBuilder.finalize() when particles are present.

bvh_particles_group_roots: wp.array[wp.int32] | None#: Per-world BVH group roots for particles, shape [world_count + 1] (last slot is global).

bvh_shape_bounds: wp.array2d[wp.vec3f] | None#: Local-space AABB per shape (min/max) for mesh and gaussian shapes, shape [shape_count, 2] [m].

bvh_shape_count_enabled: int#: Number of shapes included in the shape BVH.

bvh_shape_enabled: wp.array[wp.uint32] | None#: Shape indices included in the shape BVH, shape [bvh_shape_count_enabled].

bvh_shape_world_transforms: wp.array[wp.transformf] | None#: World-space shape transforms computed during shape BVH build/refit, shape [shape_count] [m, unitless quaternion].

bvh_shapes: wp.Bvh | None#: BVH over visible shapes, indexed by bvh_shape_enabled. Built by ModelBuilder.finalize().

bvh_shapes_group_roots: wp.array[wp.int32] | None#: Per-world BVH group roots for shapes, shape [world_count + 1] (last slot is global).

constraint_mimic_coef0: wp.array[wp.float32] | None#: Offset coefficient (coef0) for the mimic constraint (joint0 = coef0 + coef1 * joint1), shape [constraint_mimic_count], float.

constraint_mimic_coef1: wp.array[wp.float32] | None#: Scale coefficient (coef1) for the mimic constraint (joint0 = coef0 + coef1 * joint1), shape [constraint_mimic_count], float.

constraint_mimic_count: int#: Total number of mimic constraints in the system.

constraint_mimic_enabled: wp.array[wp.bool] | None#: Whether constraint is active, shape [constraint_mimic_count], bool.

constraint_mimic_joint0: wp.array[wp.int32] | None#: Follower joint index (joint0 = coef0 + coef1 * joint1), shape [constraint_mimic_count], int.

constraint_mimic_joint1: wp.array[wp.int32] | None#: Leader joint index (joint0 = coef0 + coef1 * joint1), shape [constraint_mimic_count], int.

constraint_mimic_label: list[str]#: Constraint name/label, shape [constraint_mimic_count], str.

constraint_mimic_world: wp.array[wp.int32] | None#: World index for each constraint, shape [constraint_mimic_count], int.

custom_frequency_counts: dict[str, int]#: Counts for custom frequencies (e.g., {"mujoco:pair": 5}). Set during finalize().

device: wp.Device#: Device on which the Model was allocated.

edge_bending_properties: wp.array2d[wp.float32] | None#: Bending edge stiffness and damping, shape [edge_count, 2], float. Components: [0] stiffness [N·m/rad], [1] damping [N·s].

edge_constraint_lambdas: wp.array[wp.float32] | None#: Lagrange multipliers for edge constraints (internal use).

edge_count: int#: Total number of edges in the system.

edge_indices: wp.array[wp.int32] | None#: Bending edge indices, shape [edge_count*4], int, each row is [o0, o1, v1, v2], where v1, v2 are on the edge.

edge_rest_angle: wp.array[wp.float32] | None#: Bending edge rest angle [rad], shape [edge_count], float.

edge_rest_length: wp.array[wp.float32] | None#: Bending edge rest length [m], shape [edge_count], float.

property equality_constraint_anchor: wp.array[wp.vec3] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_anchor.

property equality_constraint_body1: wp.array[wp.int32] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_body1.

property equality_constraint_body2: wp.array[wp.int32] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_body2.

property equality_constraint_count: int#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_count.

property equality_constraint_enabled: wp.array[wp.bool] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_enabled.

property equality_constraint_joint1: wp.array[wp.int32] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_joint1.

property equality_constraint_joint2: wp.array[wp.int32] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_joint2.

property equality_constraint_label: list[str]#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_label.

property equality_constraint_polycoef: wp.array2d[wp.float32] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_polycoef.

property equality_constraint_relpose: wp.array[wp.transform] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_relpose.

property equality_constraint_torquescale: wp.array[wp.float32] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_torquescale.

property equality_constraint_type: wp.array[wp.int32] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_type.

property equality_constraint_world: wp.array[wp.int32] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_world.

property equality_constraint_world_start: wp.array[wp.int32] | None#: Deprecated in Newton 1.3; will be removed in a future release. Use model.mujoco.equality_constraint_world_start.

gaussians_count#: Number of gaussians.

gaussians_data#: Data for Gaussian Splats, shape [gaussians_count], Gaussian.Data.

gravity: wp.array[wp.vec3] | None#: Per-world gravity vectors [m/s²], shape [world_count, 3], dtype vec3.

property has_heightfields: bool#: Deprecated boolean alias for heightfield_count.

Deprecated since version 1.3: Use heightfield_count, or heightfield_count > 0 for boolean checks, instead.

heightfield_count: int#: Number of GeoType.HFIELD shapes in the model.

heightfield_data: wp.array[HeightfieldData] | None#: Compact array of HeightfieldData structs, one per actual heightfield shape.

heightfield_elevations: wp.array[wp.float32] | None#: Concatenated 1D elevation array for all heightfields. Kernels index via HeightfieldData.data_offset.

heightfield_meshes: list[wp.Mesh]#: wp.Mesh objects built from heightfield shapes, kept alive for the model’s lifetime.

joint_X_c: wp.array[wp.transform] | None#: Joint mass frame in child frame [m, unitless quaternion], shape [joint_count, 7], float.

joint_X_p: wp.array[wp.transform] | None#: Joint transform in parent frame [m, unitless quaternion], shape [joint_count, 7], float.

joint_act: wp.array[wp.float32] | None#: Per-DOF feedforward actuation input for control initialization, shape [joint_dof_count], float.

joint_ancestor: wp.array[wp.int32] | None#: Maps from joint index to the index of the joint that has the current joint parent body as child (-1 if no such joint ancestor exists), shape [joint_count], int.

joint_armature: wp.array[wp.float32] | None#: Armature [kg·m² (rotational) or kg (translational)] for each joint axis (used by SolverMuJoCo and SolverFeatherstone), shape [joint_dof_count], float.

joint_articulation: wp.array[wp.int32] | None#: Joint articulation index (-1 if not in any articulation), shape [joint_count], int.

joint_axis: wp.array[wp.vec3] | None#: Joint axis in child frame, shape [joint_dof_count, 3], float.

joint_child: wp.array[wp.int32] | None#: Joint child body indices, shape [joint_count], int.

joint_constraint_count: int#: Total number of joint constraints of all joints.

joint_constraint_world_start: wp.array[wp.int32] | None#

Start index of the first joint constraint per world, shape [world_count + 2], int.

The entries at indices 0 to world_count - 1 store the start index of the joint constraints belonging to that world. The second-last element (accessible via index -2) stores the start index of the global joint constraints (i.e. with world index -1) added to the end of the model, and the last element stores the total joint constraint count.

The number of joint constraints in a given world w can be computed as:

num_joint_constraints_in_world = joint_constraint_world_start[w + 1] - joint_constraint_world_start[w]

The total number of global joint constraints can be computed as:

num_global_joint_constraints = joint_constraint_world_start[-1] - joint_constraint_world_start[-2] + joint_constraint_world_start[0]

joint_coord_count: int#: Total number of position degrees of freedom of all joints.

joint_coord_world_start: wp.array[wp.int32] | None#

Start index of the first joint coordinate per world, shape [world_count + 2], int.

The entries at indices 0 to world_count - 1 store the start index of the joint coordinates belonging to that world. The second-last element (accessible via index -2) stores the start index of the global joint coordinates (i.e. with world index -1) added to the end of the model, and the last element stores the total joint coordinate count.

The number of joint coordinates in a given world w can be computed as:

num_joint_coords_in_world = joint_coord_world_start[w + 1] - joint_coord_world_start[w]

The total number of global joint coordinates can be computed as:

num_global_joint_coords = joint_coord_world_start[-1] - joint_coord_world_start[-2] + joint_coord_world_start[0]

joint_count: int#: Total number of joints in the system.

joint_damping: wp.array[wp.float32] | None#: Passive velocity damping [N·s/m or N·m·s/rad, depending on joint type] always active on the joint, shape [joint_dof_count], float.

joint_dof_count: int#: Total number of velocity degrees of freedom of all joints. Equals the number of joint axes.

joint_dof_dim: wp.array2d[wp.int32] | None#: Number of linear and angular dofs per joint, shape [joint_count, 2], int.

joint_dof_world_start: wp.array[wp.int32] | None#

Start index of the first joint degree of freedom per world, shape [world_count + 2], int.

The entries at indices 0 to world_count - 1 store the start index of the joint DOFs belonging to that world. The second-last element (accessible via index -2) stores the start index of the global joint DOFs (i.e. with world index -1) added to the end of the model, and the last element stores the total joint DOF count.

The number of joint DOFs in a given world w can be computed as:

num_joint_dofs_in_world = joint_dof_world_start[w + 1] - joint_dof_world_start[w]

The total number of global joint DOFs can be computed as:

num_global_joint_dofs = joint_dof_world_start[-1] - joint_dof_world_start[-2] + joint_dof_world_start[0]

joint_effort_limit: wp.array[wp.float32] | None#: Joint effort (force/torque) limits [N or N·m, depending on joint type], shape [joint_dof_count], float.

joint_enabled: wp.array[wp.bool] | None#: Controls which joint is simulated (bodies become disconnected if False, supported by SolverXPBD, SolverVBD, and SolverSemiImplicit), shape [joint_count], bool.

joint_f: wp.array[wp.float32] | None#: Default generalized joint forces [N or N·m, depending on joint type] used to initialize newton.Control.joint_f, shape [joint_dof_count], float. For FREE and DISTANCE joints, the linear entries are world-frame force at the child COM and the angular entries are world-frame torque about the child COM.

joint_friction: wp.array[wp.float32] | None#: Joint friction force/torque [N or N·m, depending on joint type], shape [joint_dof_count], float.

joint_label: list[str]#: Joint labels, shape [joint_count], str.

joint_limit_kd: wp.array[wp.float32] | None#: Joint position limit damping [N·s/m or N·m·s/rad, depending on joint type] (used by SolverSemiImplicit and SolverFeatherstone), shape [joint_dof_count], float.

joint_limit_ke: wp.array[wp.float32] | None#: Joint position limit stiffness [N/m or N·m/rad, depending on joint type] (used by SolverSemiImplicit and SolverFeatherstone), shape [joint_dof_count], float.

joint_limit_lower: wp.array[wp.float32] | None#: Joint lower position limits [m or rad, depending on joint type], shape [joint_dof_count], float. Values must be finite; use -newton.MAXVAL to indicate no lower limit.

joint_limit_upper: wp.array[wp.float32] | None#: Joint upper position limits [m or rad, depending on joint type], shape [joint_dof_count], float. Values must be finite; use newton.MAXVAL to indicate no upper limit.

joint_parent: wp.array[wp.int32] | None#: Joint parent body indices, shape [joint_count], int.

joint_q: wp.array[wp.float32] | None#: Generalized joint positions [m or rad, depending on joint type] for state initialization, shape [joint_coord_count], float.

joint_q_start: wp.array[wp.int32] | None#: Start index of the first position coordinate per joint (last value is a sentinel for dimension queries), shape [joint_count + 1], int.

joint_qd: wp.array[wp.float32] | None#: Generalized joint velocities [m/s or rad/s, depending on joint type] for state initialization, shape [joint_dof_count], float. For FREE and DISTANCE joints, the linear entries are child-COM velocity in the joint parent frame and the angular entries are angular velocity in that same frame.

joint_qd_start: wp.array[wp.int32] | None#: Start index of the first velocity coordinate per joint (last value is a sentinel for dimension queries), shape [joint_count + 1], int.

joint_target_kd: wp.array[wp.float32] | None#: Joint damping [N·s/m or N·m·s/rad, depending on joint type], shape [joint_dof_count], float.

joint_target_ke: wp.array[wp.float32] | None#: Joint stiffness [N/m or N·m/rad, depending on joint type], shape [joint_dof_count], float.

joint_target_mode: wp.array[wp.int32] | None#: Joint target mode per DOF, see newton.JointTargetMode. Shape [joint_dof_count], dtype int32.

property joint_target_pos: array | None#: Deprecated alias for joint_target_q (DOF-shape only). Raises AttributeError when this Model was built under use_coord_layout_targets True.

Deprecated since version 1.3: Use joint_target_q instead.

joint_target_q: wp.array[wp.float32] | None#

Generalized joint position targets [m or rad, depending on joint type] used to initialize newton.Control.joint_target_q, shape [joint_coord_count] or [joint_dof_count], float.

Shape matches joint_q (joint_coord_count) when newton.use_coord_layout_targets is True; otherwise the array is shaped (joint_dof_count,) for backward compatibility with the deprecated joint_target_pos alias. Index via joint_target_q_start, which aliases joint_q_start or joint_qd_start to match the active layout.

property joint_target_q_start: array | None#: Per-joint start index into joint_target_q, shape (joint_count + 1,). Aliases joint_q_start under coord layout, joint_qd_start otherwise. Solvers and actuators should index joint_target_q through this regardless of layout.

joint_target_qd: wp.array[wp.float32] | None#

Generalized joint velocity targets [m/s or rad/s, depending on joint type] used to initialize newton.Control.joint_target_qd, shape [joint_dof_count], float.

Matches the layout of joint_qd. Replaces the deprecated joint_target_vel.

property joint_target_vel: array | None#: Deprecated alias for joint_target_qd. Raises AttributeError when this Model was built under use_coord_layout_targets True.

Deprecated since version 1.3: Use joint_target_qd instead.

joint_twist_lower: wp.array[wp.float32] | None#: Joint lower twist limit [rad], shape [joint_count], float.

joint_twist_upper: wp.array[wp.float32] | None#: Joint upper twist limit [rad], shape [joint_count], float.

joint_type: wp.array[wp.int32] | None#: Joint type, shape [joint_count], int.

joint_velocity_limit: wp.array[wp.float32] | None#: Joint velocity limits [m/s or rad/s, depending on joint type], shape [joint_dof_count], float.

joint_world: wp.array[wp.int32] | None#: World index for each joint, shape [joint_count], int. -1 for global.

joint_world_start: wp.array[wp.int32] | None#

Start index of the first joint per world, shape [world_count + 2], int.

The entries at indices 0 to world_count - 1 store the start index of the joints belonging to that world. The second-last element (accessible via index -2) stores the start index of the global joints (i.e. with world index -1) added to the end of the model, and the last element stores the total joint count.

The number of joints in a given world w can be computed as:

num_joints_in_world = joint_world_start[w + 1] - joint_world_start[w]

The total number of global joints can be computed as:

num_global_joints = joint_world_start[-1] - joint_world_start[-2] + joint_world_start[0]

max_dofs_per_articulation: int#: Maximum number of degrees of freedom in any articulation (used for Jacobian/mass matrix computation).

max_joints_per_articulation: int#: Maximum number of joints in any articulation (used for IK kernel dimensioning).

mesh_edge_indices: wp.array[wp.vec2i] | None#: Packed unique edge vertex pairs for all mesh shapes, shape [total_edge_count].

muscle_activations: wp.array[wp.float32] | None#: Muscle activations [dimensionless, 0 to 1], shape [muscle_count], float.

muscle_bodies: wp.array[wp.int32] | None#: Body indices of the muscle waypoints, int.

muscle_count: int#: Total number of muscles in the system.

muscle_params: wp.array2d[wp.float32] | None#: Muscle parameters, shape [muscle_count, 5], float. Components: [0] f0 [N] (force scaling), [1] lm [m] (muscle fiber length), [2] lt [m] (tendon slack length), [3] lmax [m] (max efficient length), [4] pen [dimensionless] (penalty factor).

muscle_points: wp.array[wp.vec3] | None#: Local body offset of the muscle waypoints, float.

muscle_start: wp.array[wp.int32] | None#: Start index of the first muscle point per muscle, shape [muscle_count], int.

particle_adhesion: float#: Particle adhesion strength [m].

particle_cohesion: float#: Particle cohesion strength [m].

particle_color_groups: list[wp.array[wp.int32]]#: Coloring of all particles for Gauss-Seidel iteration (see SolverVBD). Each array contains indices of particles sharing the same color.

particle_colors: wp.array[wp.int32] | None#: Color assignment for every particle.

particle_count: int#: Total number of particles in the system.

particle_flags: wp.array[wp.int32] | None#: Particle enabled state, shape [particle_count], int.

particle_grid: wp.HashGrid | None#: HashGrid instance for accelerated simulation of particle interactions.

particle_inv_mass: wp.array[wp.float32] | None#: Particle inverse mass [1/kg], shape [particle_count], float.

particle_kd: float#: Particle normal contact damping [N·s/m] (used by SolverSemiImplicit).

particle_ke: float#: Particle normal contact stiffness [N/m] (used by SolverSemiImplicit).

particle_kf: float#: Particle friction force stiffness [N·s/m] (used by SolverSemiImplicit).

particle_mass: wp.array[wp.float32] | None#: Particle mass [kg], shape [particle_count], float.

particle_max_radius: float#: Maximum particle radius [m] (useful for HashGrid construction).

particle_max_velocity: float#: Maximum particle velocity [m/s] (to prevent instability).

particle_mu: float#: Particle friction coefficient [dimensionless].

particle_q: wp.array[wp.vec3] | None#: Particle positions [m], shape [particle_count, 3], float.

particle_qd: wp.array[wp.vec3] | None#: Particle velocities [m/s], shape [particle_count, 3], float.

particle_radius: wp.array[wp.float32] | None#: Particle radius [m], shape [particle_count], float.

particle_world: wp.array[wp.int32] | None#: World index for each particle, shape [particle_count], int. -1 for global.

particle_world_start: wp.array[wp.int32] | None#

Start index of the first particle per world, shape [world_count + 2], int.

The entries at indices 0 to world_count - 1 store the start index of the particles belonging to that world. The second-last element (accessible via index -2) stores the start index of the global particles (i.e. with world index -1) added to the end of the model, and the last element stores the total particle count.

The number of particles in a given world w can be computed as:

num_particles_in_world = particle_world_start[w + 1] - particle_world_start[w]

The total number of global particles can be computed as:

num_global_particles = particle_world_start[-1] - particle_world_start[-2] + particle_world_start[0]

requires_grad: bool#: Whether the model was finalized (see ModelBuilder.finalize()) with gradient computation enabled.

rigid_contact_max: int#: Number of potential contact points between rigid bodies.

property sdf_block_coords#

Deprecated. Lazily-computed flat wp.vec3us block coords.

Per-SDF active-block coordinates were dropped when the hydroelastic broadphase started deriving them arithmetically from each SDF’s coarse-texture dimensions. This property recomputes the legacy layout on first access (and caches it) so external callers that still read the attribute keep working.

Deprecated since version 1.3: This attribute will be removed in a future release.

property sdf_index2blocks#

Deprecated. Lazily-computed per-SDF [start, end) ranges.

Per-SDF [start, end) indices into sdf_block_coords were dropped when the hydroelastic broadphase started deriving block ranges arithmetically from each SDF’s coarse-texture dimensions. This property recomputes the legacy layout on first access (and caches it) so external callers that still read the attribute keep working.

Deprecated since version 1.3: This attribute will be removed in a future release.

shape_body: wp.array[wp.int32] | None#: Rigid shape body index, shape [shape_count], int.

shape_collision_aabb_lower: wp.array[wp.vec3] | None#: Scaled local-space AABB lower bound [m] for each shape, shape [shape_count, 3], float. Includes shape scale but excludes margin and gap (those are applied at runtime). Used for broadphase AABB computation and voxel-based contact reduction.

shape_collision_aabb_upper: wp.array[wp.vec3] | None#: Scaled local-space AABB upper bound [m] for each shape, shape [shape_count, 3], float. Includes shape scale but excludes margin and gap (those are applied at runtime). Used for broadphase AABB computation and voxel-based contact reduction.

shape_collision_filter_pairs: set[tuple[int, int]]#

s1 < s2.

Type:: Pairs of shape indices (s1, s2) that should not collide. Pairs are in canonical order

shape_collision_group: wp.array[wp.int32] | None#: Collision group of each shape, shape [shape_count], int. Array populated during finalization.

shape_collision_radius: wp.array[wp.float32] | None#: Collision radius [m] for bounding sphere broadphase, shape [shape_count], float. Not supported by SolverMuJoCo.

shape_color: wp.array[wp.vec3] | None#: Shape display colors [0, 1], shape [shape_count], vec3.

shape_contact_pair_count: int#: Number of shape contact pairs.

shape_contact_pairs: wp.array[wp.vec2i] | None#: Pairs of shape indices that may collide, shape [contact_pair_count, 2], int.

shape_count: int#: Total number of shapes in the system.

shape_edge_range: wp.array[wp.vec2i] | None#: Per-shape (start, count) into mesh_edge_indices, shape [shape_count]. (-1,0) if no edges.

shape_filter: wp.array[wp.int32] | None#: Shape filter group, shape [shape_count], int.

shape_flags: wp.array[wp.int32] | None#: Rigid shape flags, shape [shape_count], int.

shape_gap: wp.array[wp.float32] | None#: Shape additional contact detection gap [m], shape [shape_count], float.

shape_heightfield_index: wp.array[wp.int32] | None#: Per-shape heightfield index, shape [shape_count]. -1 means shape has no heightfield.

shape_is_solid: wp.array[wp.bool] | None#: Whether shape is solid or hollow, shape [shape_count], bool.

shape_label: list[str]#: List of labels for each shape.

shape_margin: wp.array[wp.float32] | None#: Shape surface margin [m], shape [shape_count], float.

shape_material_ka: wp.array[wp.float32] | None#: Shape contact adhesion distance [m], shape [shape_count], float.

shape_material_kd: wp.array[wp.float32] | None#: Shape contact damping stiffness, shape [shape_count], float. Interpretation is solver-dependent: used directly as damping [N·s/m] by SemiImplicit, but multiplied by ke as a relative damping factor by VBD.

shape_material_ke: wp.array[wp.float32] | None#: Shape contact elastic stiffness [N/m], shape [shape_count], float.

shape_material_kf: wp.array[wp.float32] | None#: Shape contact friction stiffness [N·s/m], shape [shape_count], float.

shape_material_kh: wp.array[wp.float32] | None#: Shape hydroelastic stiffness coefficient [N/m^3], shape [shape_count], float. Contact stiffness is computed as area * kh, yielding an effective spring constant [N/m].

shape_material_mu: wp.array[wp.float32] | None#: Shape coefficient of friction [dimensionless], shape [shape_count], float.

shape_material_mu_rolling: wp.array[wp.float32] | None#: Shape rolling friction coefficient [dimensionless] (resistance to rolling motion), shape [shape_count], float.

shape_material_mu_torsional: wp.array[wp.float32] | None#: Shape torsional friction coefficient [dimensionless] (resistance to spinning at contact point), shape [shape_count], float.

shape_material_restitution: wp.array[wp.float32] | None#: Shape coefficient of restitution [dimensionless], shape [shape_count], float.

shape_scale: wp.array[wp.vec3] | None#: Shape 3D scale, shape [shape_count], vec3.

property shape_sdf_index: wp.array[wp.int32] | None#: Deprecated alias for _shape_sdf_index.

Deprecated since version 1.3: Use the underscored private member or the appropriate accessor. This alias will be removed in a future release.

shape_source: list[object | None]#: List of source geometry objects (e.g., Mesh) used for broadphase collision detection and rendering, shape [shape_count].

shape_source_ptr: wp.array[wp.uint64] | None#: Geometry source pointers to be used inside the Warp kernels which are generated by finalizing the geometry objects, see for example newton.Mesh.finalize(), shape [shape_count], uint64.

shape_transform: wp.array[wp.transform] | None#: Rigid shape transforms [m, unitless quaternion], shape [shape_count, 7], float.

shape_type: wp.array[wp.int32] | None#: Shape geometry type, shape [shape_count], int32.

shape_world: wp.array[wp.int32] | None#: World index for each shape, shape [shape_count], int. -1 for global.

shape_world_start: wp.array[wp.int32] | None#

Start index of the first shape per world, shape [world_count + 2], int.

The entries at indices 0 to world_count - 1 store the start index of the shapes belonging to that world. The second-last element (accessible via index -2) stores the start index of the global shapes (i.e. with world index -1) added to the end of the model, and the last element stores the total shape count.

The number of shapes in a given world w can be computed as:

num_shapes_in_world = shape_world_start[w + 1] - shape_world_start[w]

The total number of global shapes can be computed as:

num_global_shapes = shape_world_start[-1] - shape_world_start[-2] + shape_world_start[0]

soft_contact_kd: float#: Damping of soft contacts (used by SolverSemiImplicit and SolverFeatherstone). Interpretation is solver-dependent: used directly as damping [N·s/m] by SemiImplicit, but multiplied by ke as a relative damping factor by VBD.

soft_contact_ke: float#: Stiffness of soft contacts [N/m] (used by SolverSemiImplicit and SolverFeatherstone).

soft_contact_kf: float#: Stiffness of friction force in soft contacts [N·s/m] (used by SolverSemiImplicit and SolverFeatherstone).

soft_contact_mu: float#: Friction coefficient of soft contacts [dimensionless].

soft_contact_restitution: float#: Restitution coefficient of soft contacts [dimensionless] (used by SolverXPBD).

spring_constraint_lambdas: wp.array[wp.float32] | None#: Lagrange multipliers for spring constraints (internal use).

spring_control: wp.array[wp.float32] | None#: Particle spring activation [dimensionless], shape [spring_count], float.

spring_count: int#: Total number of springs in the system.

spring_damping: wp.array[wp.float32] | None#: Particle spring damping [N·s/m], shape [spring_count], float.

spring_indices: wp.array[wp.int32] | None#: Particle spring indices, shape [spring_count*2], int.

spring_rest_length: wp.array[wp.float32] | None#: Particle spring rest length [m], shape [spring_count], float.

spring_stiffness: wp.array[wp.float32] | None#: Particle spring stiffness [N/m], shape [spring_count], float.

tet_activations: wp.array[wp.float32] | None#: Tetrahedral volumetric activations, shape [tet_count], float.

tet_count: int#: Total number of tetrahedra in the system.

tet_indices: wp.array[wp.int32] | None#: Tetrahedral element indices, shape [tet_count*4], int.

tet_materials: wp.array2d[wp.float32] | None#: Tetrahedral elastic parameters in form \(k_{mu}, k_{lambda}, k_{damp}\), shape [tet_count, 3]. Components: [0] k_mu [Pa], [1] k_lambda [Pa], [2] k_damp [Pa·s]. Stored per-element; kernels multiply by rest volume internally.

tet_poses: wp.array[wp.mat33] | None#: Tetrahedral rest poses, shape [tet_count, 3, 3], float.

property texture_sdf_coarse_textures: list#: Deprecated alias for _texture_sdf_coarse_textures.

Deprecated since version 1.3: Use the underscored private member. The alias will be removed in a future release.

property texture_sdf_data#: Deprecated alias for _texture_sdf_data.

Deprecated since version 1.3: Use the underscored private member. The alias will be removed in a future release.

property texture_sdf_subgrid_start_slots: list#: Deprecated alias for _texture_sdf_subgrid_start_slots.

Deprecated since version 1.3: Use the underscored private member. The alias will be removed in a future release.

property texture_sdf_subgrid_textures: list#: Deprecated alias for _texture_sdf_subgrid_textures.

Deprecated since version 1.3: Use the underscored private member. The alias will be removed in a future release.

tri_activations: wp.array[wp.float32] | None#: Triangle element activations, shape [tri_count], float.

tri_areas: wp.array[wp.float32] | None#: Triangle element rest areas [m²], shape [tri_count], float.

tri_count: int#: Total number of triangles in the system.

tri_indices: wp.array[wp.int32] | None#: Triangle element indices, shape [tri_count*3], int.

tri_materials: wp.array2d[wp.float32] | None#: Triangle element materials, shape [tri_count, 5], float. Components: [0] k_mu [Pa], [1] k_lambda [Pa], [2] k_damp [Pa·s], [3] k_drag [Pa·s], [4] k_lift [Pa]. Stored per-element; kernels multiply by rest area internally.

tri_poses: wp.array[wp.mat22] | None#: Triangle element rest pose, shape [tri_count, 2, 2], float.

up_axis: int#

0 for x, 1 for y, 2 for z.

Type:: Up axis

use_coord_layout_targets: bool#: Snapshot of newton.use_coord_layout_targets taken at ModelBuilder.finalize(). All layout decisions for this Model consult this — toggling the global later doesn’t change behavior.

world_count: int#: Number of worlds added to the ModelBuilder.