newton.Model

class newton.Model(device=None)

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 equality_constraint_count).

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

__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.

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 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(SolverNotifyFlags.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:

State

actuators: list[Actuator]

List of actuator instances for this model.

articulation_count: int

Total number of articulations in the system.

articulation_label: list[str]

Articulation labels, shape [articulation_count], str.

articulation_start: wp.array(dtype=wp.int32) | None

Articulation start index, shape [articulation_count], int.

articulation_world: wp.array(dtype=wp.int32) | None

World index for each articulation, shape [articulation_count], int. -1 for global.

articulation_world_start: wp.array(dtype=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(dtype=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(dtype=wp.int32) | None

Color assignment for every rigid body.

body_com: wp.array(dtype=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(dtype=wp.int32) | None

Rigid body flags (BodyFlags), shape [body_count], int.

body_inertia: wp.array(dtype=wp.mat33) | None

Rigid body inertia tensor [kg·m²] (relative to COM), shape [body_count, 3, 3], float.

body_inv_inertia: wp.array(dtype=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(dtype=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(dtype=wp.float32) | None

Rigid body mass [kg], shape [body_count], float.

body_q: wp.array(dtype=wp.transform) | None

Rigid body poses [m, unitless quaternion] for state initialization, shape [body_count, 7], float.

body_qd: wp.array(dtype=wp.spatial_vector) | None

Rigid body velocities [m/s, rad/s] for state initialization, shape [body_count, 6], float.

body_shapes: dict[int, list[int]]

Mapping from body index to list of attached shape indices.

body_world: wp.array(dtype=wp.int32) | None

World index for each body, shape [body_count], int. Global entities have index -1.

body_world_start: wp.array(dtype=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]

constraint_mimic_coef0: wp.array(dtype=wp.float32) | None

Offset coefficient (coef0) for the mimic constraint (joint0 = coef0 + coef1 * joint1), shape [constraint_mimic_count], float.

constraint_mimic_coef1: wp.array(dtype=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(dtype=wp.bool) | None

Whether constraint is active, shape [constraint_mimic_count], bool.

constraint_mimic_joint0: wp.array(dtype=wp.int32) | None

Follower joint index (joint0 = coef0 + coef1 * joint1), shape [constraint_mimic_count], int.

constraint_mimic_joint1: wp.array(dtype=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(dtype=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.array(dtype=wp.float32, ndim=2) | 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(dtype=wp.float32) | None

Lagrange multipliers for edge constraints (internal use).

edge_count: int

Total number of edges in the system.

edge_indices: wp.array(dtype=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(dtype=wp.float32) | None

Bending edge rest angle [rad], shape [edge_count], float.

edge_rest_length: wp.array(dtype=wp.float32) | None

Bending edge rest length [m], shape [edge_count], float.

equality_constraint_anchor: wp.array(dtype=wp.vec3) | None

Anchor point on first body, shape [equality_constraint_count, 3], float.

equality_constraint_body1: wp.array(dtype=wp.int32) | None

First body index, shape [equality_constraint_count], int.

equality_constraint_body2: wp.array(dtype=wp.int32) | None

Second body index, shape [equality_constraint_count], int.

equality_constraint_count: int

Total number of equality constraints in the system.

equality_constraint_enabled: wp.array(dtype=wp.bool) | None

Whether constraint is active, shape [equality_constraint_count], bool.

equality_constraint_joint1: wp.array(dtype=wp.int32) | None

First joint index, shape [equality_constraint_count], int.

equality_constraint_joint2: wp.array(dtype=wp.int32) | None

Second joint index, shape [equality_constraint_count], int.

equality_constraint_label: list[str]

Constraint name/label, shape [equality_constraint_count], str.

equality_constraint_polycoef: wp.array(dtype=wp.float32, ndim=2) | None

Polynomial coefficients, shape [equality_constraint_count, 5], float.

equality_constraint_relpose: wp.array(dtype=wp.transform) | None

Relative pose, shape [equality_constraint_count, 7], float.

equality_constraint_torquescale: wp.array(dtype=wp.float32) | None

Torque scale, shape [equality_constraint_count], float.

equality_constraint_type: wp.array(dtype=wp.int32) | None

Type of equality constraint, shape [equality_constraint_count], int.

equality_constraint_world: wp.array(dtype=wp.int32) | None

World index for each constraint, shape [equality_constraint_count], int.

equality_constraint_world_start: wp.array(dtype=wp.int32) | None

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

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

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

num_equality_constraints_in_world = equality_constraint_world_start[w + 1] - equality_constraint_world_start[w]

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

num_global_equality_constraints = equality_constraint_world_start[-1] - equality_constraint_world_start[-2] + equality_constraint_world_start[0]

gravity: wp.array(dtype=wp.vec3) | None

Per-world gravity vectors [m/s²], shape [world_count, 3], dtype vec3.

heightfield_elevation_data: wp.array(dtype=wp.float32) | None

Concatenated 1D elevation array for all heightfields. Kernels index via HeightfieldData.data_offset.

joint_X_c: wp.array(dtype=wp.transform) | None

Joint mass frame in child frame [m, unitless quaternion], shape [joint_count, 7], float.

joint_X_p: wp.array(dtype=wp.transform) | None

Joint transform in parent frame [m, unitless quaternion], shape [joint_count, 7], float.

joint_act: wp.array(dtype=wp.float32) | None

Per-DOF feedforward actuation input for control initialization, shape [joint_dof_count], float.

joint_ancestor: wp.array(dtype=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(dtype=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(dtype=wp.int32) | None

Joint articulation index (-1 if not in any articulation), shape [joint_count], int.

joint_axis: wp.array(dtype=wp.vec3) | None

Joint axis in child frame, shape [joint_dof_count, 3], float.

joint_child: wp.array(dtype=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(dtype=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(dtype=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_dof_count: int

Total number of velocity degrees of freedom of all joints. Equals the number of joint axes.

joint_dof_dim: wp.array(dtype=wp.int32, ndim=2) | None

Number of linear and angular dofs per joint, shape [joint_count, 2], int.

joint_dof_world_start: wp.array(dtype=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(dtype=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(dtype=wp.bool) | None

Controls which joint is simulated (bodies become disconnected if False, only supported by SolverXPBD and SolverSemiImplicit), shape [joint_count], bool.

joint_f: wp.array(dtype=wp.float32) | None

Generalized joint forces [N or N·m, depending on joint type] for state initialization, shape [joint_dof_count], float.

joint_friction: wp.array(dtype=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(dtype=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(dtype=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(dtype=wp.float32) | None

Joint lower position limits [m or rad, depending on joint type], shape [joint_dof_count], float.

joint_limit_upper: wp.array(dtype=wp.float32) | None

Joint upper position limits [m or rad, depending on joint type], shape [joint_dof_count], float.

joint_parent: wp.array(dtype=wp.int32) | None

Joint parent body indices, shape [joint_count], int.

joint_q: wp.array(dtype=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(dtype=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(dtype=wp.float32) | None

Generalized joint velocities [m/s or rad/s, depending on joint type] for state initialization, shape [joint_dof_count], float.

joint_qd_start: wp.array(dtype=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(dtype=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(dtype=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(dtype=wp.int32) | None

Joint target mode per DOF, see newton.JointTargetMode. Shape [joint_dof_count], dtype int32.

joint_target_pos: wp.array(dtype=wp.float32) | None

Generalized joint position targets [m or rad, depending on joint type], shape [joint_dof_count], float.

joint_target_vel: wp.array(dtype=wp.float32) | None

Generalized joint velocity targets [m/s or rad/s, depending on joint type], shape [joint_dof_count], float.

joint_twist_lower: wp.array(dtype=wp.float32) | None

Joint lower twist limit [rad], shape [joint_count], float.

joint_twist_upper: wp.array(dtype=wp.float32) | None

Joint upper twist limit [rad], shape [joint_count], float.

joint_type: wp.array(dtype=wp.int32) | None

Joint type, shape [joint_count], int.

joint_velocity_limit: wp.array(dtype=wp.float32) | None

Joint velocity limits [m/s or rad/s, depending on joint type], shape [joint_dof_count], float.

joint_world: wp.array(dtype=wp.int32) | None

World index for each joint, shape [joint_count], int. -1 for global.

joint_world_start: wp.array(dtype=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).

muscle_activations: wp.array(dtype=wp.float32) | None

Muscle activations [dimensionless, 0 to 1], shape [muscle_count], float.

muscle_bodies: wp.array(dtype=wp.int32) | None

Body indices of the muscle waypoints, int.

muscle_count: int

Total number of muscles in the system.

muscle_params: wp.array(dtype=wp.float32, ndim=2) | 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(dtype=wp.vec3) | None

Local body offset of the muscle waypoints, float.

muscle_start: wp.array(dtype=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(dtype=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(dtype=wp.int32) | None

Color assignment for every particle.

particle_count: int

Total number of particles in the system.

particle_flags: wp.array(dtype=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(dtype=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(dtype=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(dtype=wp.vec3) | None

Particle positions [m], shape [particle_count, 3], float.

particle_qd: wp.array(dtype=wp.vec3) | None

Particle velocities [m/s], shape [particle_count, 3], float.

particle_radius: wp.array(dtype=wp.float32) | None

Particle radius [m], shape [particle_count], float.

particle_world: wp.array(dtype=wp.int32) | None

World index for each particle, shape [particle_count], int. -1 for global.

particle_world_start: wp.array(dtype=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.

sdf_block_coords: wp.array(dtype=wp.vec3us) | None

Compact flat array of active SDF block coordinates.

sdf_coarse_volume: list[wp.Volume | None]

Coarse SDF volumes matching sdf_data by index. Kept for reference counting.

sdf_data: wp.array(dtype=SDFData) | None

Compact array of SDFData structs, shape [num_sdfs].

sdf_index2blocks: wp.array(dtype=wp.vec2i) | None

Per-SDF [start, end) indices into sdf_block_coords, shape [num_sdfs, 2].

sdf_volume: list[wp.Volume | None]

Sparse SDF volumes matching sdf_data by index. Kept for reference counting.

shape_body: wp.array(dtype=wp.int32) | None

Rigid shape body index, shape [shape_count], int.

shape_collision_aabb_lower: wp.array(dtype=wp.vec3) | None

Local-space AABB lower bound [m] for each shape, shape [shape_count, 3], float. Computed from base geometry only (excludes shape margin; shape margin and gap are applied during contact margin calculations). Used for voxel-based contact reduction.

shape_collision_aabb_upper: wp.array(dtype=wp.vec3) | None

Local-space AABB upper bound [m] for each shape, shape [shape_count, 3], float. Computed from base geometry only (excludes shape margin; shape margin and gap are applied during contact margin calculations). Used for 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(dtype=wp.int32) | None

Collision group of each shape, shape [shape_count], int. Array populated during finalization.

shape_collision_radius: wp.array(dtype=wp.float32) | None

Collision radius [m] for bounding sphere broadphase, shape [shape_count], float. Not supported by SolverMuJoCo.

shape_contact_pair_count: int

Number of shape contact pairs.

shape_contact_pairs: wp.array(dtype=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_filter: wp.array(dtype=wp.int32) | None

Shape filter group, shape [shape_count], int.

shape_flags: wp.array(dtype=wp.int32) | None

Rigid shape flags, shape [shape_count], int.

shape_gap: wp.array(dtype=wp.float32) | None

Shape additional contact detection gap [m], shape [shape_count], float.

shape_heightfield_data: wp.array(dtype=HeightfieldData) | None

Array of HeightfieldData structs, shape [shape_count]. Contains grid metadata for collision kernels.

shape_is_solid: wp.array(dtype=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(dtype=wp.float32) | None

Shape surface margin [m], shape [shape_count], float.

shape_material_ka: wp.array(dtype=wp.float32) | None

Shape contact adhesion distance [m], shape [shape_count], float.

shape_material_kd: wp.array(dtype=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(dtype=wp.float32) | None

Shape contact elastic stiffness [N/m], shape [shape_count], float.

shape_material_kf: wp.array(dtype=wp.float32) | None

Shape contact friction stiffness [N·s/m], shape [shape_count], float.

shape_material_kh: wp.array(dtype=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(dtype=wp.float32) | None

Shape coefficient of friction [dimensionless], shape [shape_count], float.

shape_material_mu_rolling: wp.array(dtype=wp.float32) | None

Shape rolling friction coefficient [dimensionless] (resistance to rolling motion), shape [shape_count], float.

shape_material_mu_torsional: wp.array(dtype=wp.float32) | None

Shape torsional friction coefficient [dimensionless] (resistance to spinning at contact point), shape [shape_count], float.

shape_material_restitution: wp.array(dtype=wp.float32) | None

Shape coefficient of restitution [dimensionless], shape [shape_count], float.

shape_scale: wp.array(dtype=wp.vec3) | None

Shape 3D scale, shape [shape_count, 3], float.

shape_sdf_index: wp.array(dtype=wp.int32) | None

Per-shape SDF index, shape [shape_count]. -1 means shape has no SDF.

shape_source: list[object | None]

List of source geometry objects (e.g., Mesh) used for rendering and broadphase, shape [shape_count].

shape_source_ptr: wp.array(dtype=wp.uint64) | None

Geometry source pointer to be used inside the Warp kernels which can be generated by finalizing the geometry objects, see for example newton.Mesh.finalize(), shape [shape_count], uint64.

shape_transform: wp.array(dtype=wp.transform) | None

Rigid shape transforms [m, unitless quaternion], shape [shape_count, 7], float.

shape_type: wp.array(dtype=wp.int32) | None

Shape geometry type, shape [shape_count], int32.

shape_world: wp.array(dtype=wp.int32) | None

World index for each shape, shape [shape_count], int. -1 for global.

shape_world_start: wp.array(dtype=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(dtype=wp.float32) | None

Lagrange multipliers for spring constraints (internal use).

spring_control: wp.array(dtype=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(dtype=wp.float32) | None

Particle spring damping [N·s/m], shape [spring_count], float.

spring_indices: wp.array(dtype=wp.int32) | None

Particle spring indices, shape [spring_count*2], int.

spring_rest_length: wp.array(dtype=wp.float32) | None

Particle spring rest length [m], shape [spring_count], float.

spring_stiffness: wp.array(dtype=wp.float32) | None

Particle spring stiffness [N/m], shape [spring_count], float.

tet_activations: wp.array(dtype=wp.float32) | None

Tetrahedral volumetric activations, shape [tet_count], float.

tet_count: int

Total number of tetrahedra in the system.

tet_indices: wp.array(dtype=wp.int32) | None

Tetrahedral element indices, shape [tet_count*4], int.

tet_materials: wp.array(dtype=wp.float32, ndim=2) | 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(dtype=wp.mat33) | None

Tetrahedral rest poses, shape [tet_count, 3, 3], float.

tri_activations: wp.array(dtype=wp.float32) | None

Triangle element activations, shape [tri_count], float.

tri_areas: wp.array(dtype=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(dtype=wp.int32) | None

Triangle element indices, shape [tri_count*3], int.

tri_materials: wp.array(dtype=wp.float32, ndim=2) | 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(dtype=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

world_count: int

Number of worlds added to the ModelBuilder.