newton.ModelBuilder#

class newton.ModelBuilder(up_axis=Axis.Z, gravity=-9.81)[source]#

Bases: object

A helper class for building simulation models at runtime.

Use the ModelBuilder to construct a simulation scene. The ModelBuilder represents the scene using standard Python data structures like lists, which are convenient but unsuitable for efficient simulation. Call finalize() to construct a simulation-ready Model.

Example

import newton
from newton.solvers import SolverXPBD

builder = newton.ModelBuilder()

# anchor point (zero mass)
builder.add_particle((0, 1.0, 0.0), (0.0, 0.0, 0.0), 0.0)

# build chain
for i in range(1, 10):
    builder.add_particle((i, 1.0, 0.0), (0.0, 0.0, 0.0), 1.0)
    builder.add_spring(i - 1, i, 1.0e3, 0.0, 0)

# create model
model = builder.finalize()

state_0, state_1 = model.state(), model.state()
control = model.control()
solver = SolverXPBD(model)

for i in range(10):
    state_0.clear_forces()
    contacts = model.collide(state_0)
    solver.step(state_0, state_1, control, contacts, dt=1.0 / 60.0)
    state_0, state_1 = state_1, state_0

World Grouping#

ModelBuilder supports world grouping to organize entities for multi-world simulations. Each entity (particle, body, shape, joint, articulation) has an associated world index:

Index -1: Global entities shared across all worlds (e.g., ground plane)
Index 0, 1, 2, …: World-specific entities

There are two ways to assign world indices:

Direct entity creation: Entities inherit the builder’s current_world value:

builder = ModelBuilder()
builder.current_world = -1  # Following entities will be global
builder.add_ground_plane()
builder.current_world = 0  # Following entities will be in world 0
builder.add_body(...)

Using add_builder(): ALL entities from the sub-builder are assigned to the specified world:

robot = ModelBuilder()
robot.add_body(...)  # World assignments here will be overridden

main = ModelBuilder()
main.add_builder(robot, world=0)  # All robot entities -> world 0
main.add_builder(robot, world=1)  # All robot entities -> world 1

Note

It is strongly recommended to use the ModelBuilder to construct a simulation rather than creating your own Model object directly, however it is possible to do so if desired.

class CustomAttribute(name, dtype, frequency, assignment=ModelAttributeAssignment.MODEL, namespace=None, default=None, values=None, usd_attribute_name=None, mjcf_attribute_name=None, urdf_attribute_name=None, usd_value_transformer=None, mjcf_value_transformer=None, urdf_value_transformer=None)#

Bases: object

Represents a custom attribute definition for the ModelBuilder. This is used to define custom attributes that are not part of the standard ModelBuilder API. Custom attributes can be defined for the Model, State, Control, or Contacts objects, depending on the ModelAttributeAssignment category. Custom attributes must be declared before use via the newton.ModelBuilder.add_custom_attribute() method.

See Custom Attributes for more information.

__init__(name, dtype, frequency, assignment=ModelAttributeAssignment.MODEL, namespace=None, default=None, values=None, usd_attribute_name=None, mjcf_attribute_name=None, urdf_attribute_name=None, usd_value_transformer=None, mjcf_value_transformer=None, urdf_value_transformer=None)#

build_array(count, device=None, requires_grad=False)#

Build wp.array from count, dtype, default and overrides.

assignment: ModelAttributeAssignment = 0#: Assignment category (see ModelAttributeAssignment), defaults to ModelAttributeAssignment.MODEL

dtype: type#: Warp dtype (e.g., wp.float32, wp.int32, wp.bool, wp.vec3) that is compatible with Warp arrays.

frequency: ModelAttributeFrequency#: Frequency category (see ModelAttributeFrequency) that determines how the attribute is indexed in the Model.

property key: str#

name” or “name” if no namespace is specified.

Type:: Return the full name of the attribute, formatted as “namespace

name: str#: Variable name to expose on the Model. Must be a valid Python identifier.

class JointDofConfig(axis=Axis.X, limit_lower=-JOINT_LIMIT_UNLIMITED, limit_upper=JOINT_LIMIT_UNLIMITED, limit_ke=1e4, limit_kd=1e1, target_pos=0.0, target_vel=0.0, target_ke=0.0, target_kd=0.0, armature=1e-2, effort_limit=1e6, velocity_limit=1e6, friction=0.0)#

Bases: object

Describes a joint axis (a single degree of freedom) that can have limits and be driven towards a target.

classmethod create_unlimited(axis)#

Creates a JointDofConfig with no limits.

__init__(axis=Axis.X, limit_lower=-JOINT_LIMIT_UNLIMITED, limit_upper=JOINT_LIMIT_UNLIMITED, limit_ke=1e4, limit_kd=1e1, target_pos=0.0, target_vel=0.0, target_ke=0.0, target_kd=0.0, armature=1e-2, effort_limit=1e6, velocity_limit=1e6, friction=0.0)#

armature#: Artificial inertia added around the joint axis. Defaults to 1e-2.

axis#: The 3D axis that this JointDofConfig object describes.

effort_limit#: Maximum effort (force or torque) the joint axis can exert. Defaults to 1e6.

friction#: Friction coefficient for the joint axis. Defaults to 0.0.

limit_kd#: The damping stiffness of the joint axis limits. Defaults to 1e1.

limit_ke#: The elastic stiffness of the joint axis limits. Defaults to 1e4.

limit_lower#: The lower position limit of the joint axis. Defaults to -JOINT_LIMIT_UNLIMITED (unlimited).

limit_upper#: The upper position limit of the joint axis. Defaults to JOINT_LIMIT_UNLIMITED (unlimited).

target_kd#: The derivative gain of the target drive PD controller. Defaults to 0.0.

target_ke#: The proportional gain of the target drive PD controller. Defaults to 0.0.

target_pos#: The target position of the joint axis. If the initial target_pos is outside the limits, it defaults to the midpoint of limit_lower and limit_upper. Otherwise, defaults to 0.0.

target_vel#: The target velocity of the joint axis.

velocity_limit#: Maximum velocity the joint axis can achieve. Defaults to 1e6.

class ShapeConfig(density=1000.0, ke=100000.0, kd=1000.0, kf=1000.0, ka=0.0, mu=0.5, restitution=0.0, thickness=1e-05, is_solid=True, collision_group=1, collision_filter_parent=True, has_shape_collision=True, has_particle_collision=True, is_visible=True, is_site=False)#

Bases: object

Represents the properties of a collision shape used in simulation.

__init__(density=1000.0, ke=100000.0, kd=1000.0, kf=1000.0, ka=0.0, mu=0.5, restitution=0.0, thickness=1e-05, is_solid=True, collision_group=1, collision_filter_parent=True, has_shape_collision=True, has_particle_collision=True, is_visible=True, is_site=False)#

mark_as_site()#

Marks this shape as a site and enforces all site invariants.

Sets: - is_site = True - has_shape_collision = False - has_particle_collision = False - density = 0.0 - collision_group = 0

collision_filter_parent: bool = True#: Whether to inherit collision filtering from the parent. Defaults to True.

collision_group: int = 1#: The collision group ID for the shape. Defaults to 1 (default group). Set to 0 to disable collisions for this shape.

density: float = 1000.0#: The density of the shape material.

property flags: int#: Returns the flags for the shape.

has_particle_collision: bool = True#: Whether the shape can collide with particles. Defaults to True.

has_shape_collision: bool = True#: Whether the shape can collide with other shapes. Defaults to True.

is_site: bool = False#: Indicates whether the shape is a site (non-colliding reference point). Directly setting this to True will NOT enforce site invariants. Use mark_as_site() or set via the flags property to ensure invariants. Defaults to False.

is_solid: bool = True#: Indicates whether the shape is solid or hollow. Defaults to True.

is_visible: bool = True#: Indicates whether the shape is visible in the simulation. Defaults to True.

ka: float = 0.0#: The contact adhesion distance.

kd: float = 1000.0#: The contact damping stiffness.

ke: float = 100000.0#: The contact elastic stiffness.

kf: float = 1000.0#: The contact friction stiffness.

mu: float = 0.5#: The coefficient of friction.

restitution: float = 0.0#: The coefficient of restitution.

thickness: float = 1e-05#: The thickness of the shape.

__init__(up_axis=Axis.Z, gravity=-9.81)#

Initializes a new ModelBuilder instance for constructing simulation models.

Parameters:

up_axis (AxisType, optional) – The axis to use as the “up” direction in the simulation. Defaults to Axis.Z.
gravity (float, optional) – The magnitude of gravity to apply along the up axis. Defaults to -9.81.

add_articulation(key=None, custom_attributes=None)#

Adds an articulation to the model. An articulation is a set of contiguous joints from articulation_start[i] to articulation_start[i+1]. Some functions, such as forward kinematics newton.eval_fk(), are parallelized over articulations. Articulations are automatically ‘closed’ when calling finalize().

Parameters:

key (str | None) – The key of the articulation. If None, a default key will be created.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for ARTICULATION frequency attributes.

add_body(xform=None, armature=None, com=None, I_m=None, mass=0.0, key=None, custom_attributes=None)#

Adds a rigid body to the model.

Parameters:

xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The location of the body in the world frame.
armature (float | None) – Artificial inertia added to the body. If None, the default value from default_body_armature is used.
com (list[float] | tuple[float, float, float] | vec3f | None) – The center of mass of the body w.r.t its origin. If None, the center of mass is assumed to be at the origin.
I_m (list[float] | mat33f | None) – The 3x3 inertia tensor of the body (specified relative to the center of mass). If None, the inertia tensor is assumed to be zero.
mass (float) – Mass of the body.
key (str | None) – Key of the body (optional).
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

Returns:

The index of the body in the model.

Return type:

int

Note

If the mass is zero then the body is treated as kinematic with no dynamics.

add_builder(builder, xform=None, update_num_world_count=True, world=None)#

Copies the data from builder, another ModelBuilder to this ModelBuilder.

World Grouping Behavior: When adding a builder, ALL entities from the source builder will be assigned to the same world, overriding any world assignments that existed in the source builder. This ensures that all entities from a sub-builder are grouped together as a single world.

Worlds automatically handle collision filtering between different worlds: - Entities from different worlds (except -1) do not collide with each other - Global entities (index -1) collide with all worlds - Collision groups from the source builder are preserved as-is for fine-grained collision control within each world

To create global entities that are shared across all worlds, set the main builder’s current_world to -1 before adding entities directly (not via add_builder).

Example:

main_builder = ModelBuilder()
# Create global ground plane
main_builder.current_world = -1
main_builder.add_ground_plane()

# Create robot builder
robot_builder = ModelBuilder()
robot_builder.add_body(...)  # These world assignments will be overridden

# Add multiple robot instances
main_builder.add_builder(robot_builder, world=0)  # All entities -> world 0
main_builder.add_builder(robot_builder, world=1)  # All entities -> world 1

Parameters:

builder (ModelBuilder) – a model builder to add model data from.
xform (Transform) – offset transform applied to root bodies.
update_num_world_count (bool) – if True, the number of worlds is updated appropriately. For non-global entities (world >= 0), this either increments num_worlds (when world is None) or ensures num_worlds is at least world+1. Global entities (world=-1) do not affect num_worlds.
world (int | None) – world index to assign to ALL entities from this builder. If None, uses the current world count as the index. Use -1 for global entities. Note: world=-1 does not increase num_worlds even when update_num_world_count=True.

add_cloth_grid(pos, rot, vel, dim_x, dim_y, cell_x, cell_y, mass, reverse_winding=False, fix_left=False, fix_right=False, fix_top=False, fix_bottom=False, tri_ke=None, tri_ka=None, tri_kd=None, tri_drag=None, tri_lift=None, edge_ke=None, edge_kd=None, add_springs=False, spring_ke=None, spring_kd=None, particle_radius=None)#

Helper to create a regular planar cloth grid

Creates a rectangular grid of particles with FEM triangles and bending elements automatically.

Parameters:

pos (list[float] | tuple[float, float, float] | vec3f) – The position of the cloth in world space
rot (list[float] | tuple[float, float, float, float] | quatf) – The orientation of the cloth in world space
vel (list[float] | tuple[float, float, float] | vec3f) – The velocity of the cloth in world space
dim_x (int) – The number of rectangular cells along the x-axis
dim_y (int) – The number of rectangular cells along the y-axis
cell_x (float) – The width of each cell in the x-direction
cell_y (float) – The width of each cell in the y-direction
mass (float) – The mass of each particle
reverse_winding (bool) – Flip the winding of the mesh
fix_left (bool) – Make the left-most edge of particles kinematic (fixed in place)
fix_right (bool) – Make the right-most edge of particles kinematic
fix_top (bool) – Make the top-most edge of particles kinematic
fix_bottom (bool) – Make the bottom-most edge of particles kinematic

add_cloth_mesh(pos, rot, scale, vel, vertices, indices, density, edge_callback=None, face_callback=None, tri_ke=None, tri_ka=None, tri_kd=None, tri_drag=None, tri_lift=None, edge_ke=None, edge_kd=None, add_springs=False, spring_ke=None, spring_kd=None, particle_radius=None)#

Helper to create a cloth model from a regular triangle mesh

Creates one FEM triangle element and one bending element for every face and edge in the input triangle mesh

Parameters:

pos (list[float] | tuple[float, float, float] | vec3f) – The position of the cloth in world space
rot (list[float] | tuple[float, float, float, float] | quatf) – The orientation of the cloth in world space
vel (list[float] | tuple[float, float, float] | vec3f) – The velocity of the cloth in world space
vertices (list[list[float] | tuple[float, float, float] | vec3f]) – A list of vertex positions
indices (list[int]) – A list of triangle indices, 3 entries per-face
density (float) – The density per-area of the mesh
edge_callback – A user callback when an edge is created
face_callback – A user callback when a face is created
particle_radius (float | None) – The particle_radius which controls particle based collisions.

Note

The mesh should be two manifold.

add_custom_attribute(attribute)#

Define a custom per-entity attribute to be added to the Model. See Custom Attributes for more information.

Parameters:: attribute (CustomAttribute) – The custom attribute to add.

Example

builder = newton.ModelBuilder()
builder.add_custom_attribute(
    newton.ModelBuilder.CustomAttribute(
        name="my_attribute",
        frequency=newton.ModelAttributeFrequency.BODY,
        dtype=wp.float32,
        default=20.0,
        assignment=newton.ModelAttributeAssignment.MODEL,
        namespace="my_namespace",
    )
)
builder.add_body(custom_attributes={"my_namespace:my_attribute": 30.0})
builder.add_body()  # we leave out the custom_attributes, so the attribute will use the default value 20.0
model = builder.finalize()
# the model has now an AttributeNamespace object with the name "my_namespace"
# and an attribute "my_attribute" that is a wp.array of shape (body_count, 1)
# with the default value 20.0
assert np.allclose(model.my_namespace.my_attribute.numpy(), [30.0, 20.0])

add_edge(i, j, k, l, rest=None, edge_ke=None, edge_kd=None)#

Adds a bending edge element between two adjacent triangles in the cloth mesh, defined by four vertices.

The bending energy model follows the discrete shell formulation from [Grinspun et al. 2003]. The bending stiffness is controlled by the edge_ke parameter, and the bending damping by the edge_kd parameter.

Parameters:

i (int) – The index of the first particle, i.e., opposite vertex 0
j (int) – The index of the second particle, i.e., opposite vertex 1
k (int) – The index of the third particle, i.e., vertex 0
l (int) – The index of the fourth particle, i.e., vertex 1
rest (float | None) – The rest angle across the edge in radians, if not specified it will be computed
edge_ke (float | None) – The bending stiffness coefficient
edge_kd (float | None) – The bending damping coefficient

Note

The edge lies between the particles indexed by ‘k’ and ‘l’ parameters with the opposing vertices indexed by ‘i’ and ‘j’. This defines two connected triangles with counterclockwise winding: (i, k, l), (j, l, k).

add_edges(i, j, k, l, rest=None, edge_ke=None, edge_kd=None)#

Adds bending edge elements between two adjacent triangles in the cloth mesh, defined by four vertices.

The bending energy model follows the discrete shell formulation from [Grinspun et al. 2003]. The bending stiffness is controlled by the edge_ke parameter, and the bending damping by the edge_kd parameter.

Parameters:

i – The index of the first particle, i.e., opposite vertex 0
j – The index of the second particle, i.e., opposite vertex 1
k – The index of the third particle, i.e., vertex 0
l – The index of the fourth particle, i.e., vertex 1
rest (list[float] | None) – The rest angles across the edges in radians, if not specified they will be computed
edge_ke (list[float] | None) – The bending stiffness coefficient
edge_kd (list[float] | None) – The bending damping coefficient

Note

The edge lies between the particles indexed by ‘k’ and ‘l’ parameters with the opposing vertices indexed by ‘i’ and ‘j’. This defines two connected triangles with counterclockwise winding: (i, k, l), (j, l, k).

add_equality_constraint(constraint_type, body1=-1, body2=-1, anchor=None, torquescale=None, relpose=None, joint1=-1, joint2=-1, polycoef=None, key=None, enabled=True)#

Generic method to add any type of equality constraint to this ModelBuilder.

Parameters:

constraint_type (constant) – Type of constraint (‘connect’, ‘weld’, ‘joint’)
body1 (int) – Index of the first body participating in the constraint (-1 for world)
body2 (int) – Index of the second body participating in the constraint (-1 for world)
anchor (Vec3) – Anchor point on body1
torquescale (float) – Scales the angular residual for weld
relpose (Transform) – Relative pose of body2 for weld. If None, the identity transform is used.
joint1 (int) – Index of the first joint for joint coupling
joint2 (int) – Index of the second joint for joint coupling
polycoef (list[float]) – Polynomial coefficients for joint coupling
key (str) – Optional constraint name
enabled (bool) – Whether constraint is active

Returns:

Constraint index

Return type:

int

add_equality_constraint_connect(body1=-1, body2=-1, anchor=None, key=None, enabled=True)#

Adds a connect equality constraint to the model. This constraint connects two bodies at a point. It effectively defines a ball joint outside the kinematic tree.

Parameters:

body1 (int) – Index of the first body participating in the constraint (-1 for world)
body2 (int) – Index of the second body participating in the constraint (-1 for world)
anchor (list[float] | tuple[float, float, float] | vec3f | None) – Anchor point on body1
key (str | None) – Optional constraint name
enabled (bool) – Whether constraint is active

Returns:

Constraint index

Return type:

int

add_equality_constraint_joint(joint1=-1, joint2=-1, polycoef=None, key=None, enabled=True)#

Adds a joint equality constraint to the model. Constrains the position or angle of one joint to be a quartic polynomial of another joint. Only scalar joint types (prismatic and revolute) can be used.

Parameters:

joint1 (int) – Index of the first joint
joint2 (int) – Index of the second joint
polycoef (list[float] | None) – Polynomial coefficients for joint coupling
key (str | None) – Optional constraint name
enabled (bool) – Whether constraint is active

Returns:

Constraint index

Return type:

int

add_equality_constraint_weld(body1=-1, body2=-1, anchor=None, torquescale=None, relpose=None, key=None, enabled=True)#

Adds a weld equality constraint to the model. Attaches two bodies to each other, removing all relative degrees of freedom between them (softly).

Parameters:

body1 (int) – Index of the first body participating in the constraint (-1 for world)
body2 (int) – Index of the second body participating in the constraint (-1 for world)
anchor (list[float] | tuple[float, float, float] | vec3f | None) – Coordinates of the weld point relative to body2
torquescale (float | None) – Scales the angular residual for weld
relpose (Transform) – Relative pose of body2 relative to body1. If None, the identity transform is used
key (str | None) – Optional constraint name
enabled (bool) – Whether constraint is active

Returns:

Constraint index

Return type:

int

add_free_joints_to_floating_bodies(new_bodies=None)#

Adds a free joint to every rigid body that is not a child in any joint and has positive mass.

Parameters:: new_bodies (Iterable[int] or None, optional) – The set of body indices to consider for adding free joints.

Note

Bodies that are already a child in any joint will be skipped.
Only bodies with strictly positive mass will receive a free joint.
This is useful for ensuring that all floating (unconnected) bodies are properly articulated.

add_ground_plane(cfg=None, key=None)#

Adds a ground plane collision shape to the model.

Parameters:

cfg (ShapeConfig | None) – The configuration for the shape’s physical and collision properties. If None, default_shape_cfg is used. Defaults to None.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated. Defaults to None.

Returns:

The index of the newly added shape.

Return type:

int

add_joint(joint_type, parent, child, linear_axes=None, angular_axes=None, key=None, parent_xform=None, child_xform=None, collision_filter_parent=True, enabled=True, custom_attributes=None)#

Generic method to add any type of joint to this ModelBuilder.

Parameters:

joint_type (JointType) – The type of joint to add (see Joint types).
parent (int) – The index of the parent body (-1 is the world).
child (int) – The index of the child body.
linear_axes (list(JointDofConfig)) – The linear axes (see JointDofConfig) of the joint.
angular_axes (list(JointDofConfig)) – The angular axes (see JointDofConfig) of the joint.
key (str) – The key of the joint (optional).
parent_xform (Transform) – The transform of the joint in the parent body’s local frame. If None, the identity transform is used.
child_xform (Transform) – The transform of the joint in the child body’s local frame. If None, the identity transform is used.
collision_filter_parent (bool) – Whether to filter collisions between shapes of the parent and child bodies.
enabled (bool) – Whether the joint is enabled (not considered by SolverFeatherstone).
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute keys (see CustomAttribute.key) to values. Note that custom attributes with frequency ModelAttributeFrequency.JOINT_DOF or ModelAttributeFrequency.JOINT_COORD require the respective values to be provided as lists with length equal to the joint’s DOF or coordinate count. Custom attributes with frequency ModelAttributeFrequency.JOINT require a single value to be defined.

Returns:

The index of the added joint.

Return type:

int

add_joint_ball(parent, child, parent_xform=None, child_xform=None, key=None, collision_filter_parent=True, enabled=True, custom_attributes=None)#

Adds a ball (spherical) joint to the model. Its position is defined by a 4D quaternion (xyzw) and its velocity is a 3D vector.

Parameters:

parent (int) – The index of the parent body.
child (int) – The index of the child body.
parent_xform (Transform) – The transform of the joint in the parent body’s local frame.
child_xform (Transform) – The transform of the joint in the child body’s local frame.
key (str | None) – The key of the joint.
collision_filter_parent (bool) – Whether to filter collisions between shapes of the parent and child bodies.
enabled (bool) – Whether the joint is enabled.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for JOINT, JOINT_DOF, or JOINT_COORD frequency attributes.

Returns:

The index of the added joint.

Return type:

int

add_joint_d6(parent, child, linear_axes=None, angular_axes=None, key=None, parent_xform=None, child_xform=None, collision_filter_parent=True, enabled=True, custom_attributes=None, **kwargs)#

Adds a generic joint with custom linear and angular axes. The number of axes determines the number of degrees of freedom of the joint.

Parameters:

parent (int) – The index of the parent body.
child (int) – The index of the child body.
linear_axes (Sequence[JointDofConfig] | None) – A list of linear axes.
angular_axes (Sequence[JointDofConfig] | None) – A list of angular axes.
key (str | None) – The key of the joint.
parent_xform (Transform) – The transform of the joint in the parent body’s local frame
child_xform (Transform) – The transform of the joint in the child body’s local frame
armature – Artificial inertia added around the joint axes. If None, the default value from default_joint_armature is used.
collision_filter_parent (bool) – Whether to filter collisions between shapes of the parent and child bodies.
enabled (bool) – Whether the joint is enabled.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for JOINT, JOINT_DOF, or JOINT_COORD frequency attributes.

Returns:

The index of the added joint.

Return type:

int

add_joint_distance(parent, child, parent_xform=None, child_xform=None, min_distance=-1.0, max_distance=1.0, collision_filter_parent=True, enabled=True, custom_attributes=None)#

Adds a distance joint to the model. The distance joint constraints the distance between the joint anchor points on the two bodies (see Forward / Inverse Kinematics) it connects to the interval [min_distance, max_distance]. It has 7 positional degrees of freedom (first 3 linear and then 4 angular dimensions for the orientation quaternion in xyzw notation) and 6 velocity degrees of freedom (first 3 linear and then 3 angular velocity dimensions).

Parameters:

parent (int) – The index of the parent body.
child (int) – The index of the child body.
parent_xform (Transform) – The transform of the joint in the parent body’s local frame.
child_xform (Transform) – The transform of the joint in the child body’s local frame.
min_distance (float) – The minimum distance between the bodies (no limit if negative).
max_distance (float) – The maximum distance between the bodies (no limit if negative).
collision_filter_parent (bool) – Whether to filter collisions between shapes of the parent and child bodies.
enabled (bool) – Whether the joint is enabled.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for JOINT, JOINT_DOF, or JOINT_COORD frequency attributes.

Returns:

The index of the added joint.

Return type:

int

Note

Distance joints are currently only supported in the newton.solvers.SolverXPBD.

add_joint_fixed(parent, child, parent_xform=None, child_xform=None, key=None, collision_filter_parent=True, enabled=True, custom_attributes=None)#

Adds a fixed (static) joint to the model. It has no degrees of freedom. See collapse_fixed_joints() for a helper function that removes these fixed joints and merges the connecting bodies to simplify the model and improve stability.

Parameters:

parent (int) – The index of the parent body.
child (int) – The index of the child body.
parent_xform (Transform) – The transform of the joint in the parent body’s local frame.
child_xform (Transform) – The transform of the joint in the child body’s local frame.
key (str | None) – The key of the joint.
collision_filter_parent (bool) – Whether to filter collisions between shapes of the parent and child bodies.
enabled (bool) – Whether the joint is enabled.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for JOINT frequency attributes.

Returns:

The index of the added joint

Return type:

int

add_joint_free(child, parent_xform=None, child_xform=None, parent=-1, key=None, collision_filter_parent=True, enabled=True, custom_attributes=None)#

Adds a free joint to the model. It has 7 positional degrees of freedom (first 3 linear and then 4 angular dimensions for the orientation quaternion in xyzw notation) and 6 velocity degrees of freedom (see Twist conventions in Newton). The positional dofs are initialized by the child body’s transform (see body_q and the xform argument to add_body()).

Parameters:

child (int) – The index of the child body.
parent_xform (Transform) – The transform of the joint in the parent body’s local frame.
child_xform (Transform) – The transform of the joint in the child body’s local frame.
parent (int) – The index of the parent body (-1 by default to use the world frame, e.g. to make the child body and its children a floating-base mechanism).
key (str | None) – The key of the joint.
collision_filter_parent (bool) – Whether to filter collisions between shapes of the parent and child bodies.
enabled (bool) – Whether the joint is enabled.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for JOINT, JOINT_DOF, or JOINT_COORD frequency attributes.

Returns:

The index of the added joint.

Return type:

int

add_joint_prismatic(parent, child, parent_xform=None, child_xform=None, axis=Axis.X, target_pos=None, target_vel=None, target_ke=None, target_kd=None, limit_lower=None, limit_upper=None, limit_ke=None, limit_kd=None, armature=None, effort_limit=None, velocity_limit=None, friction=None, key=None, collision_filter_parent=True, enabled=True, custom_attributes=None)#

Adds a prismatic (sliding) joint to the model. It has one degree of freedom.

Parameters:

parent (int) – The index of the parent body.
child (int) – The index of the child body.
parent_xform (Transform) – The transform of the joint in the parent body’s local frame.
child_xform (Transform) – The transform of the joint in the child body’s local frame.
axis (AxisType | Vec3 | JointDofConfig) – The axis of rotation in the parent body’s local frame, can be a JointDofConfig object whose settings will be used instead of the other arguments.
target_pos (float | None) – The target position of the joint.
target_vel (float | None) – The target velocity of the joint.
target_ke (float | None) – The stiffness of the joint target.
target_kd (float | None) – The damping of the joint target.
limit_lower (float | None) – The lower limit of the joint. If None, the default value from default_joint_limit_lower is used.
limit_upper (float | None) – The upper limit of the joint. If None, the default value from default_joint_limit_upper is used.
limit_ke (float | None) – The stiffness of the joint limit. If None, the default value from default_joint_limit_ke is used.
limit_kd (float | None) – The damping of the joint limit. If None, the default value from default_joint_limit_kd is used.
armature (float | None) – Artificial inertia added around the joint axis. If None, the default value from default_joint_armature is used.
effort_limit (float | None) – Maximum effort (force) the joint axis can exert. If None, the default value from default_joint_cfg.effort_limit is used.
velocity_limit (float | None) – Maximum velocity the joint axis can achieve. If None, the default value from default_joint_cfg.velocity_limit is used.
friction (float | None) – Friction coefficient for the joint axis. If None, the default value from default_joint_cfg.friction is used.
key (str | None) – The key of the joint.
collision_filter_parent (bool) – Whether to filter collisions between shapes of the parent and child bodies.
enabled (bool) – Whether the joint is enabled.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for JOINT, JOINT_DOF, or JOINT_COORD frequency attributes.

Returns:

The index of the added joint.

Return type:

int

add_joint_revolute(parent, child, parent_xform=None, child_xform=None, axis=None, target_pos=None, target_vel=None, target_ke=None, target_kd=None, limit_lower=None, limit_upper=None, limit_ke=None, limit_kd=None, armature=None, effort_limit=None, velocity_limit=None, friction=None, key=None, collision_filter_parent=True, enabled=True, custom_attributes=None, **kwargs)#

Adds a revolute (hinge) joint to the model. It has one degree of freedom.

Parameters:

parent (int) – The index of the parent body.
child (int) – The index of the child body.
parent_xform (Transform) – The transform of the joint in the parent body’s local frame.
child_xform (Transform) – The transform of the joint in the child body’s local frame.
axis (AxisType | Vec3 | JointDofConfig) – The axis of rotation in the parent body’s local frame, can be a JointDofConfig object whose settings will be used instead of the other arguments.
target_pos (float | None) – The target position of the joint.
target_vel (float | None) – The target velocity of the joint.
target_ke (float | None) – The stiffness of the joint target.
target_kd (float | None) – The damping of the joint target.
limit_lower (float | None) – The lower limit of the joint. If None, the default value from default_joint_limit_lower is used.
limit_upper (float | None) – The upper limit of the joint. If None, the default value from default_joint_limit_upper is used.
limit_ke (float | None) – The stiffness of the joint limit. If None, the default value from default_joint_limit_ke is used.
limit_kd (float | None) – The damping of the joint limit. If None, the default value from default_joint_limit_kd is used.
armature (float | None) – Artificial inertia added around the joint axis. If None, the default value from default_joint_armature is used.
effort_limit (float | None) – Maximum effort (force/torque) the joint axis can exert. If None, the default value from default_joint_cfg.effort_limit is used.
velocity_limit (float | None) – Maximum velocity the joint axis can achieve. If None, the default value from default_joint_cfg.velocity_limit is used.
friction (float | None) – Friction coefficient for the joint axis. If None, the default value from default_joint_cfg.friction is used.
key (str | None) – The key of the joint.
collision_filter_parent (bool) – Whether to filter collisions between shapes of the parent and child bodies.
enabled (bool) – Whether the joint is enabled.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for JOINT, JOINT_DOF, or JOINT_COORD frequency attributes.

Returns:

The index of the added joint.

Return type:

int

add_mjcf(source, xform=None, floating=None, base_joint=None, armature_scale=1.0, scale=1.0, hide_visuals=False, parse_visuals_as_colliders=False, parse_meshes=True, parse_sites=True, parse_visuals=True, up_axis=Axis.Z, ignore_names=(), ignore_classes=(), visual_classes=('visual',), collider_classes=('collision',), no_class_as_colliders=True, force_show_colliders=False, enable_self_collisions=False, ignore_inertial_definitions=True, ensure_nonstatic_links=True, static_link_mass=1e-2, collapse_fixed_joints=False, verbose=False, skip_equality_constraints=False, mesh_maxhullvert=MESH_MAXHULLVERT)#

Parses MuJoCo XML (MJCF) file and adds the bodies and joints to the given ModelBuilder.

Parameters:

source (str) – The filename of the MuJoCo file to parse, or the MJCF XML string content.
xform (Transform) – The transform to apply to the imported mechanism.
floating (bool) – If True, the articulation is treated as a floating base. If False, the articulation is treated as a fixed base. If None, the articulation is treated as a floating base if a free joint is found in the MJCF, otherwise it is treated as a fixed base.
base_joint (Union[str, dict]) – The joint by which the root body is connected to the world. This can be either a string defining the joint axes of a D6 joint with comma-separated positional and angular axis names (e.g. “px,py,rz” for a D6 joint with linear axes in x, y and an angular axis in z) or a dict with joint parameters (see ModelBuilder.add_joint()).
armature_scale (float) – Scaling factor to apply to the MJCF-defined joint armature values.
scale (float) – The scaling factor to apply to the imported mechanism.
hide_visuals (bool) – If True, hide visual shapes after loading them (affects visibility, not loading).
parse_visuals_as_colliders (bool) – If True, the geometry defined under the visual_classes tags is used for collision handling instead of the collider_classes geometries.
parse_meshes (bool) – Whether geometries of type “mesh” should be parsed. If False, geometries of type “mesh” are ignored.
parse_sites (bool) – Whether sites (non-colliding reference points) should be parsed. If False, sites are ignored.
parse_visuals (bool) – Whether visual geometries (non-collision shapes) should be loaded. If False, visual shapes are not loaded (different from hide_visuals which loads but hides them). Default is True.
up_axis (AxisType) – The up axis of the MuJoCo scene. The default is Z up.
ignore_names (Sequence[str]) – A list of regular expressions. Bodies and joints with a name matching one of the regular expressions will be ignored.
ignore_classes (Sequence[str]) – A list of regular expressions. Bodies and joints with a class matching one of the regular expressions will be ignored.
visual_classes (Sequence[str]) – A list of regular expressions. Visual geometries with a class matching one of the regular expressions will be parsed.
collider_classes (Sequence[str]) – A list of regular expressions. Collision geometries with a class matching one of the regular expressions will be parsed.
no_class_as_colliders (bool) – If True, geometries without a class are parsed as collision geometries. If False, geometries without a class are parsed as visual geometries.
force_show_colliders (bool) – If True, the collision shapes are always shown, even if there are visual shapes.
enable_self_collisions (bool) – If True, self-collisions are enabled.
ignore_inertial_definitions (bool) – If True, the inertial parameters defined in the MJCF are ignored and the inertia is calculated from the shape geometry.
ensure_nonstatic_links (bool) – If True, links with zero mass are given a small mass (see static_link_mass) to ensure they are dynamic.
static_link_mass (float) – The mass to assign to links with zero mass (if ensure_nonstatic_links is set to True).
collapse_fixed_joints (bool) – If True, fixed joints are removed and the respective bodies are merged.
verbose (bool) – If True, print additional information about parsing the MJCF.
skip_equality_constraints (bool) – Whether <equality> tags should be parsed. If True, equality constraints are ignored.
mesh_maxhullvert (int) – Maximum vertices for convex hull approximation of meshes.

add_muscle(bodies, positions, f0, lm, lt, lmax, pen)#

Adds a muscle-tendon activation unit.

Parameters:

bodies (list[int]) – A list of body indices for each waypoint
positions (list[list[float] | tuple[float, float, float] | vec3f]) – A list of positions of each waypoint in the body’s local frame
f0 (float) – Force scaling
lm (float) – Muscle length
lt (float) – Tendon length
lmax (float) – Maximally efficient muscle length

Returns:

The index of the muscle in the model

Return type:

float

Note

The simulation support for muscles is in progress and not yet fully functional.

add_particle(pos, vel, mass, radius=None, flags=ParticleFlags.ACTIVE)#

Adds a single particle to the model.

Parameters:

pos (list[float] | tuple[float, float, float] | vec3f) – The initial position of the particle.
vel (list[float] | tuple[float, float, float] | vec3f) – The initial velocity of the particle.
mass (float) – The mass of the particle.
radius (float | None) – The radius of the particle used in collision handling. If None, the radius is set to the default value (default_particle_radius).
flags (int) – The flags that control the dynamical behavior of the particle, see PARTICLE_FLAG_* constants.

Note

Set the mass equal to zero to create a ‘kinematic’ particle that is not subject to dynamics.

Returns:: The index of the particle in the system.
Return type:: int

add_particle_grid(pos, rot, vel, dim_x, dim_y, dim_z, cell_x, cell_y, cell_z, mass, jitter, radius_mean=None, radius_std=0.0, flags=None)#

Adds a regular 3D grid of particles to the model.

This helper function creates a grid of particles arranged in a rectangular lattice, with optional random jitter and per-particle radius variation. The grid is defined by its dimensions along each axis and the spacing between particles.

Parameters:

pos (Vec3) – The world-space position of the grid origin.
rot (Quat) – The rotation to apply to the grid (as a quaternion).
vel (Vec3) – The initial velocity to assign to each particle.
dim_x (int) – Number of particles along the X axis.
dim_y (int) – Number of particles along the Y axis.
dim_z (int) – Number of particles along the Z axis.
cell_x (float) – Spacing between particles along the X axis.
cell_y (float) – Spacing between particles along the Y axis.
cell_z (float) – Spacing between particles along the Z axis.
mass (float) – Mass to assign to each particle.
jitter (float) – Maximum random offset to apply to each particle position.
radius_mean (float, optional) – Mean radius for particles. If None, uses the builder’s default.
radius_std (float, optional) – Standard deviation for particle radii. If > 0, radii are sampled from a normal distribution.
flags (int, optional) – Flags to assign to each particle. If None, uses the builder’s default.

Returns:

None

add_particles(pos, vel, mass, radius=None, flags=None)#

Adds a group particles to the model.

Parameters:

pos (list[list[float] | tuple[float, float, float] | vec3f]) – The initial positions of the particle.
vel (list[list[float] | tuple[float, float, float] | vec3f]) – The initial velocities of the particle.
mass (list[float]) – The mass of the particles.
radius (list[float] | None) – The radius of the particles used in collision handling. If None, the radius is set to the default value (default_particle_radius).
flags (list[uint32] | None) – The flags that control the dynamical behavior of the particles, see PARTICLE_FLAG_* constants.

Note

Set the mass equal to zero to create a ‘kinematic’ particle that is not subject to dynamics.

add_shape(body, type, xform=None, cfg=None, scale=None, src=None, is_static=False, key=None, custom_attributes=None)#

Adds a generic collision shape to the model.

This is the base method for adding shapes; prefer using specific helpers like add_shape_sphere() where possible.

Parameters:

body (int) – The index of the parent body this shape belongs to. Use -1 for shapes not attached to any specific body (e.g., static world geometry).
type (int) – The geometry type of the shape (e.g., GeoType.BOX, GeoType.SPHERE).
xform (Transform | None) – The transform of the shape in the parent body’s local frame. If None, the identity transform wp.transform() is used. Defaults to None.
cfg (ShapeConfig | None) – The configuration for the shape’s physical and collision properties. If None, default_shape_cfg is used. Defaults to None.
scale (Vec3 | None) – The scale of the geometry. The interpretation depends on the shape type. Defaults to (1.0, 1.0, 1.0) if None.
src (SDF | Mesh | Any | None) – The source geometry data, e.g., a Mesh object for GeoType.MESH or an SDF object for GeoType.SDF. Defaults to None.
is_static (bool) – If True, the shape will have zero mass, and its density property in cfg will be effectively ignored for mass calculation. Typically used for fixed, non-movable collision geometry. Defaults to False.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated (e.g., “shape_N”). Defaults to None.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

Returns:

The index of the newly added shape.

Return type:

int

add_shape_box(body, xform=None, hx=0.5, hy=0.5, hz=0.5, cfg=None, as_site=False, key=None, custom_attributes=None)#

Adds a box collision shape or site to a body.

The box is centered at its local origin as defined by xform.

Parameters:

body (int) – The index of the parent body this shape belongs to. Use -1 for shapes not attached to any specific body.
xform (Transform | None) – The transform of the box in the parent body’s local frame. If None, the identity transform wp.transform() is used. Defaults to None.
hx (float) – The half-extent of the box along its local X-axis. Defaults to 0.5.
hy (float) – The half-extent of the box along its local Y-axis. Defaults to 0.5.
hz (float) – The half-extent of the box along its local Z-axis. Defaults to 0.5.
cfg (ShapeConfig | None) – The configuration for the shape’s properties. If None, uses default_shape_cfg (or default_site_cfg when as_site=True). If as_site=True and cfg is provided, a copy is made and site invariants are enforced via mark_as_site(). Defaults to None.
as_site (bool) – If True, creates a site (non-colliding reference point) instead of a collision shape. Defaults to False.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated. Defaults to None.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

Returns:

The index of the newly added shape or site.

Return type:

int

add_shape_capsule(body, xform=None, radius=1.0, half_height=0.5, cfg=None, as_site=False, key=None, custom_attributes=None)#

Adds a capsule collision shape or site to a body.

The capsule is centered at its local origin as defined by xform. Its length extends along the Z-axis.

Parameters:

body (int) – The index of the parent body this shape belongs to. Use -1 for shapes not attached to any specific body.
xform (Transform | None) – The transform of the capsule in the parent body’s local frame. If None, the identity transform wp.transform() is used. Defaults to None.
radius (float) – The radius of the capsule’s hemispherical ends and its cylindrical segment. Defaults to 1.0.
half_height (float) – The half-length of the capsule’s central cylindrical segment (excluding the hemispherical ends). Defaults to 0.5.
cfg (ShapeConfig | None) – The configuration for the shape’s properties. If None, uses default_shape_cfg (or default_site_cfg when as_site=True). If as_site=True and cfg is provided, a copy is made and site invariants are enforced via mark_as_site(). Defaults to None.
as_site (bool) – If True, creates a site (non-colliding reference point) instead of a collision shape. Defaults to False.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated. Defaults to None.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

Returns:

The index of the newly added shape or site.

Return type:

int

add_shape_cone(body, xform=None, radius=1.0, half_height=0.5, cfg=None, as_site=False, key=None, custom_attributes=None)#

Adds a cone collision shape to a body.

The cone’s origin is at its geometric center, with the base at -half_height and apex at +half_height along the Z-axis. The center of mass is located at -half_height/2 from the origin (1/4 of the total height from the base toward the apex).

Parameters:

body (int) – The index of the parent body this shape belongs to. Use -1 for shapes not attached to any specific body.
xform (Transform | None) – The transform of the cone in the parent body’s local frame. If None, the identity transform wp.transform() is used. Defaults to None.
radius (float) – The radius of the cone’s base. Defaults to 1.0.
half_height (float) – The half-height of the cone (distance from the geometric center to either the base or apex). The total height is 2*half_height. Defaults to 0.5.
cfg (ShapeConfig | None) – The configuration for the shape’s physical and collision properties. If None, default_shape_cfg is used. Defaults to None.
as_site (bool) – If True, creates a site (non-colliding reference point) instead of a collision shape. Defaults to False.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated. Defaults to None.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for SHAPE frequency attributes.

Returns:

The index of the newly added shape.

Return type:

int

add_shape_convex_hull(body, xform=None, mesh=None, scale=None, cfg=None, key=None)#

Adds a convex hull collision shape to a body.

Parameters:

body (int) – The index of the parent body this shape belongs to. Use -1 for shapes not attached to any specific body.
xform (Transform | None) – The transform of the convex hull in the parent body’s local frame. If None, the identity transform wp.transform() is used. Defaults to None.
mesh (Mesh | None) – The Mesh object containing the vertex data for the convex hull. Defaults to None.
scale (Vec3 | None) – The scale of the convex hull. Defaults to None, in which case the scale is (1.0, 1.0, 1.0).
cfg (ShapeConfig | None) – The configuration for the shape’s physical and collision properties. If None, default_shape_cfg is used. Defaults to None.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated. Defaults to None.

Returns:

The index of the newly added shape.

Return type:

int

add_shape_cylinder(body, xform=None, radius=1.0, half_height=0.5, cfg=None, as_site=False, key=None, custom_attributes=None)#

Adds a cylinder collision shape or site to a body.

The cylinder is centered at its local origin as defined by xform. Its length extends along the Z-axis.

Parameters:

body (int) – The index of the parent body this shape belongs to. Use -1 for shapes not attached to any specific body.
xform (Transform | None) – The transform of the cylinder in the parent body’s local frame. If None, the identity transform wp.transform() is used. Defaults to None.
radius (float) – The radius of the cylinder. Defaults to 1.0.
half_height (float) – The half-length of the cylinder along the Z-axis. Defaults to 0.5.
cfg (ShapeConfig | None) – The configuration for the shape’s properties. If None, uses default_shape_cfg (or default_site_cfg when as_site=True). If as_site=True and cfg is provided, a copy is made and site invariants are enforced via mark_as_site(). Defaults to None.
as_site (bool) – If True, creates a site (non-colliding reference point) instead of a collision shape. Defaults to False.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated. Defaults to None.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for SHAPE frequency attributes.

Returns:

The index of the newly added shape or site.

Return type:

int

add_shape_mesh(body, xform=None, mesh=None, scale=None, cfg=None, key=None, custom_attributes=None)#

Adds a triangle mesh collision shape to a body.

Parameters:

body (int) – The index of the parent body this shape belongs to. Use -1 for shapes not attached to any specific body.
xform (Transform | None) – The transform of the mesh in the parent body’s local frame. If None, the identity transform wp.transform() is used. Defaults to None.
mesh (Mesh | None) – The Mesh object containing the vertex and triangle data. Defaults to None.
scale (Vec3 | None) – The scale of the mesh. Defaults to None, in which case the scale is (1.0, 1.0, 1.0).
cfg (ShapeConfig | None) – The configuration for the shape’s physical and collision properties. If None, default_shape_cfg is used. Defaults to None.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated. Defaults to None.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for SHAPE frequency attributes.

Returns:

The index of the newly added shape.

Return type:

int

add_shape_plane(plane=(0.0, 0.0, 1.0, 0.0), xform=None, width=10.0, length=10.0, body=-1, cfg=None, key=None, custom_attributes=None)#

Adds a plane collision shape to the model.

If xform is provided, it directly defines the plane’s position and orientation. The plane’s collision normal is assumed to be along the local Z-axis of this xform. If xform is None, it will be derived from the plane equation a*x + b*y + c*z + d = 0. Plane shapes added via this method are always static (massless).

Parameters:

plane (Vec4 | None) – The plane equation (a, b, c, d). If xform is None, this defines the plane. The normal is (a,b,c) and d is the offset. Defaults to (0.0, 0.0, 1.0, 0.0) (an XY ground plane at Z=0) if xform is also None.
xform (Transform | None) – The transform of the plane in the world or parent body’s frame. If None, transform is derived from plane. Defaults to None.
width (float) – The visual/collision extent of the plane along its local X-axis. If 0.0, considered infinite for collision. Defaults to 10.0.
length (float) – The visual/collision extent of the plane along its local Y-axis. If 0.0, considered infinite for collision. Defaults to 10.0.
body (int) – The index of the parent body this shape belongs to. Use -1 for world-static planes. Defaults to -1.
cfg (ShapeConfig | None) – The configuration for the shape’s physical and collision properties. If None, default_shape_cfg is used. Defaults to None.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated. Defaults to None.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for SHAPE frequency attributes.

Returns:

The index of the newly added shape.

Return type:

int

add_shape_sdf(body, xform=None, sdf=None, cfg=None, key=None, custom_attributes=None)#

Adds a signed distance field (SDF) collision shape to a body.

Parameters:

body (int) – The index of the parent body this shape belongs to. Use -1 for shapes not attached to any specific body.
xform (Transform | None) – The transform of the SDF in the parent body’s local frame. If None, the identity transform wp.transform() is used. Defaults to None.
sdf (SDF | None) – The SDF object representing the signed distance field. Defaults to None.
cfg (ShapeConfig | None) – The configuration for the shape’s physical and collision properties. If None, default_shape_cfg is used. Defaults to None.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated. Defaults to None.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for SHAPE frequency attributes.

Returns:

The index of the newly added shape.

Return type:

int

add_shape_sphere(body, xform=None, radius=1.0, cfg=None, as_site=False, key=None, custom_attributes=None)#

Adds a sphere collision shape or site to a body.

Parameters:

body (int) – The index of the parent body this shape belongs to. Use -1 for shapes not attached to any specific body.
xform (Transform | None) – The transform of the sphere in the parent body’s local frame. The sphere is centered at this transform’s position. If None, the identity transform wp.transform() is used. Defaults to None.
radius (float) – The radius of the sphere. Defaults to 1.0.
cfg (ShapeConfig | None) – The configuration for the shape’s properties. If None, uses default_shape_cfg (or default_site_cfg when as_site=True). If as_site=True and cfg is provided, a copy is made and site invariants are enforced via mark_as_site(). Defaults to None.
as_site (bool) – If True, creates a site (non-colliding reference point) instead of a collision shape. Defaults to False.
key (str | None) – An optional unique key for identifying the shape. If None, a default key is automatically generated. Defaults to None.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

Returns:

The index of the newly added shape or site.

Return type:

int

add_site(body, xform=None, type=GeoType.SPHERE, scale=(0.01, 0.01, 0.01), key=None, visible=False, custom_attributes=None)#

Adds a site (non-colliding reference point) to a body.

Sites are abstract markers that don’t participate in physics simulation or collision detection. They are useful for: - Sensor attachment points (IMU, camera, etc.) - Frame of reference definitions - Debugging and visualization markers - Spatial tendon attachment points (when exported to MuJoCo)

Parameters:

body (int) – The index of the parent body this site belongs to. Use -1 for sites not attached to any specific body (for sites defined a at static world position).
xform (Transform | None) – The transform of the site in the parent body’s local frame. If None, the identity transform wp.transform() is used. Defaults to None.
type (int) – The geometry type for visualization (e.g., GeoType.SPHERE, GeoType.BOX). Defaults to GeoType.SPHERE.
scale (Vec3) – The scale/size of the site for visualization. Defaults to (0.01, 0.01, 0.01).
key (str | None) – An optional unique key for identifying the site. If None, a default key is automatically generated. Defaults to None.
visible (bool) – If True, the site will be visible for debugging. If False (default), the site is hidden.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

Returns:

The index of the newly added site (which is stored as a shape internally).

Return type:

int

Example

Add an IMU sensor site to a robot torso:

body = builder.add_body()
imu_site = builder.add_site(
    body,
    xform=wp.transform((0.0, 0.0, 0.1), wp.quat_identity()),
    key="imu_sensor",
    visible=True,  # Show for debugging
)

add_soft_grid(pos, rot, vel, dim_x, dim_y, dim_z, cell_x, cell_y, cell_z, density, k_mu, k_lambda, k_damp, fix_left=False, fix_right=False, fix_top=False, fix_bottom=False, tri_ke=None, tri_ka=None, tri_kd=None, tri_drag=None, tri_lift=None)#

Helper to create a rectangular tetrahedral FEM grid

Creates a regular grid of FEM tetrahedra and surface triangles. Useful for example to create beams and sheets. Each hexahedral cell is decomposed into 5 tetrahedral elements.

Parameters:

pos (list[float] | tuple[float, float, float] | vec3f) – The position of the solid in world space
rot (list[float] | tuple[float, float, float, float] | quatf) – The orientation of the solid in world space
vel (list[float] | tuple[float, float, float] | vec3f) – The velocity of the solid in world space
dim_x (int) – The number of rectangular cells along the x-axis
dim_y (int) – The number of rectangular cells along the y-axis
dim_z (int) – The number of rectangular cells along the z-axis
cell_x (float) – The width of each cell in the x-direction
cell_y (float) – The width of each cell in the y-direction
cell_z (float) – The width of each cell in the z-direction
density (float) – The density of each particle
k_mu (float) – The first elastic Lame parameter
k_lambda (float) – The second elastic Lame parameter
k_damp (float) – The damping stiffness
fix_left (bool) – Make the left-most edge of particles kinematic (fixed in place)
fix_right (bool) – Make the right-most edge of particles kinematic
fix_top (bool) – Make the top-most edge of particles kinematic
fix_bottom (bool) – Make the bottom-most edge of particles kinematic

add_soft_mesh(pos, rot, scale, vel, vertices, indices, density, k_mu, k_lambda, k_damp, tri_ke=None, tri_ka=None, tri_kd=None, tri_drag=None, tri_lift=None)#

Helper to create a tetrahedral model from an input tetrahedral mesh

Parameters:

pos (list[float] | tuple[float, float, float] | vec3f) – The position of the solid in world space
rot (list[float] | tuple[float, float, float, float] | quatf) – The orientation of the solid in world space
vel (list[float] | tuple[float, float, float] | vec3f) – The velocity of the solid in world space
vertices (list[list[float] | tuple[float, float, float] | vec3f]) – A list of vertex positions, array of 3D points
indices (list[int]) – A list of tetrahedron indices, 4 entries per-element, flattened array
density (float) – The density per-area of the mesh
k_mu (float) – The first elastic Lame parameter
k_lambda (float) – The second elastic Lame parameter
k_damp (float) – The damping stiffness

add_spring(i, j, ke, kd, control)#

Adds a spring between two particles in the system

Parameters:

i (int) – The index of the first particle
j – The index of the second particle
ke (float) – The elastic stiffness of the spring
kd (float) – The damping stiffness of the spring
control (float) – The actuation level of the spring

Note

The spring is created with a rest-length based on the distance between the particles in their initial configuration.

add_tetrahedron(i, j, k, l, k_mu=1.0e3, k_lambda=1.0e3, k_damp=0.0)#

Adds a tetrahedral FEM element between four particles in the system.

Tetrahedra are modeled as viscoelastic elements with a NeoHookean energy density based on [Smith et al. 2018].

Parameters:

i (int) – The index of the first particle
j (int) – The index of the second particle
k (int) – The index of the third particle
l (int) – The index of the fourth particle
k_mu (float) – The first elastic Lame parameter
k_lambda (float) – The second elastic Lame parameter
k_damp (float) – The element’s damping stiffness

Returns:

The volume of the tetrahedron

Return type:

float

Note

The tetrahedron is created with a rest-pose based on the particle’s initial configuration

add_triangle(i, j, k, tri_ke=None, tri_ka=None, tri_kd=None, tri_drag=None, tri_lift=None)#

Adds a triangular FEM element between three particles in the system.

Triangles are modeled as viscoelastic elements with elastic stiffness and damping parameters specified on the model. See model.tri_ke, model.tri_kd.

Parameters:

i (int) – The index of the first particle
j (int) – The index of the second particle
k (int) – The index of the third particle

Returns:

The area of the triangle

Return type:

float

Note

The triangle is created with a rest-length based on the distance between the particles in their initial configuration.

add_triangles(i, j, k, tri_ke=None, tri_ka=None, tri_kd=None, tri_drag=None, tri_lift=None)#

Adds triangular FEM elements between groups of three particles in the system.

Triangles are modeled as viscoelastic elements with elastic stiffness and damping Parameters specified on the model. See model.tri_ke, model.tri_kd.

Parameters:

i (list[int]) – The indices of the first particle
j (list[int]) – The indices of the second particle
k (list[int]) – The indices of the third particle

Returns:

The areas of the triangles

Return type:

list[float]

Note

A triangle is created with a rest-length based on the distance between the particles in their initial configuration.

add_urdf(source, xform=None, floating=False, base_joint=None, scale=1.0, hide_visuals=False, parse_visuals_as_colliders=False, up_axis=Axis.Z, force_show_colliders=False, enable_self_collisions=True, ignore_inertial_definitions=True, ensure_nonstatic_links=True, static_link_mass=1e-2, joint_ordering='dfs', bodies_follow_joint_ordering=True, collapse_fixed_joints=False, mesh_maxhullvert=MESH_MAXHULLVERT)#

Parses a URDF file and adds the bodies and joints to the given ModelBuilder.

Parameters:

source (str) – The filename of the URDF file to parse, or the URDF XML string content.
xform (Transform) – The transform to apply to the root body. If None, the transform is set to identity.
floating (bool) – If True, the root body is a free joint. If False, the root body is connected via a fixed joint to the world, unless a base_joint is defined.
base_joint (Union[str, dict]) – The joint by which the root body is connected to the world. This can be either a string defining the joint axes of a D6 joint with comma-separated positional and angular axis names (e.g. “px,py,rz” for a D6 joint with linear axes in x, y and an angular axis in z) or a dict with joint parameters (see ModelBuilder.add_joint()).
scale (float) – The scaling factor to apply to the imported mechanism.
hide_visuals (bool) – If True, hide visual shapes.
parse_visuals_as_colliders (bool) – If True, the geometry defined under the <visual> tags is used for collision handling instead of the <collision> geometries.
up_axis (AxisType) – The up axis of the URDF. This is used to transform the URDF to the builder’s up axis. It also determines the up axis of capsules and cylinders in the URDF. The default is Z.
force_show_colliders (bool) – If True, the collision shapes are always shown, even if there are visual shapes.
enable_self_collisions (bool) – If True, self-collisions are enabled.
ignore_inertial_definitions (bool) – If True, the inertial parameters defined in the URDF are ignored and the inertia is calculated from the shape geometry.
ensure_nonstatic_links (bool) – If True, links with zero mass are given a small mass (see static_link_mass) to ensure they are dynamic.
static_link_mass (float) – The mass to assign to links with zero mass (if ensure_nonstatic_links is set to True).
joint_ordering (str) – The ordering of the joints in the simulation. Can be either “bfs” or “dfs” for breadth-first or depth-first search, or None to keep joints in the order in which they appear in the URDF. Default is “dfs”.
bodies_follow_joint_ordering (bool) – If True, the bodies are added to the builder in the same order as the joints (parent then child body). Otherwise, bodies are added in the order they appear in the URDF. Default is True.
collapse_fixed_joints (bool) – If True, fixed joints are removed and the respective bodies are merged.
mesh_maxhullvert (int) – Maximum vertices for convex hull approximation of meshes.

add_usd(source, xform=None, only_load_enabled_rigid_bodies=False, only_load_enabled_joints=True, joint_drive_gains_scaling=1.0, verbose=False, ignore_paths=None, cloned_world=None, collapse_fixed_joints=False, enable_self_collisions=True, apply_up_axis_from_stage=False, root_path='/', joint_ordering='dfs', bodies_follow_joint_ordering=True, skip_mesh_approximation=False, load_sites=True, load_visual_shapes=True, hide_collision_shapes=False, mesh_maxhullvert=MESH_MAXHULLVERT, schema_resolvers=None)#

Parses a Universal Scene Description (USD) stage containing UsdPhysics schema definitions for rigid-body articulations and adds the bodies, shapes and joints to the given ModelBuilder.

The USD description has to be either a path (file name or URL), or an existing USD stage instance that implements the Stage interface.

See USD Parsing and Schema Resolver System for more information.

Parameters:

source (str | pxr.Usd.Stage) – The file path to the USD file, or an existing USD stage instance.
xform (Transform) – The transform to apply to the entire scene.
only_load_enabled_rigid_bodies (bool) – If True, only rigid bodies which do not have physics:rigidBodyEnabled set to False are loaded.
only_load_enabled_joints (bool) – If True, only joints which do not have physics:jointEnabled set to False are loaded.
joint_drive_gains_scaling (float) – The default scaling of the PD control gains (stiffness and damping), if not set in the PhysicsScene with as “newton:joint_drive_gains_scaling”.
verbose (bool) – If True, print additional information about the parsed USD file. Default is False.
ignore_paths (List[str]) – A list of regular expressions matching prim paths to ignore.
cloned_world (str) – The prim path of a world which is cloned within this USD file. Siblings of this world prim will not be parsed but instead be replicated via ModelBuilder.add_builder(builder, xform) to speed up the loading of many instantiated worlds.
collapse_fixed_joints (bool) – If True, fixed joints are removed and the respective bodies are merged. Only considered if not set on the PhysicsScene as “newton:collapse_fixed_joints”.
enable_self_collisions (bool) – Determines the default behavior of whether self-collisions are enabled for all shapes within an articulation. If an articulation has the attribute physxArticulation:enabledSelfCollisions defined, this attribute takes precedence.
apply_up_axis_from_stage (bool) – If True, the up axis of the stage will be used to set newton.ModelBuilder.up_axis. Otherwise, the stage will be rotated such that its up axis aligns with the builder’s up axis. Default is False.
root_path (str) – The USD path to import, defaults to “/”.
joint_ordering (str) – The ordering of the joints in the simulation. Can be either “bfs” or “dfs” for breadth-first or depth-first search, or None to keep joints in the order in which they appear in the USD. Default is “dfs”.
bodies_follow_joint_ordering (bool) – If True, the bodies are added to the builder in the same order as the joints (parent then child body). Otherwise, bodies are added in the order they appear in the USD. Default is True.
skip_mesh_approximation (bool) – If True, mesh approximation is skipped. Otherwise, meshes are approximated according to the physics:approximation attribute defined on the UsdPhysicsMeshCollisionAPI (if it is defined). Default is False.
load_sites (bool) – If True, sites (prims with MjcSiteAPI) are loaded as non-colliding reference points. If False, sites are ignored. Default is True.
load_visual_shapes (bool) – If True, non-physics visual geometry is loaded. If False, visual-only shapes are ignored (sites are still controlled by load_sites). Default is True.
hide_collision_shapes (bool) – If True, collision shapes are hidden. Default is False.
mesh_maxhullvert (int) – Maximum vertices for convex hull approximation of meshes.
schema_resolvers (list[SchemaResolver]) –
Resolver instances in priority order. Default is no schema resolution. Schema resolvers collect per-prim “solver-specific” attributes, see 1. Solver Attribute Remapping for more information. These include namespaced attributes such as newton:*, physx* (e.g., physxScene:*, physxRigidBody:*, physxSDFMeshCollision:*), and mjc:* that are authored in the USD but not strictly required to build the simulation. This is useful for inspection, experimentation, or custom pipelines that read these values via newton.usd.SchemaResolverManager.schema_attrs.

Note

Using the schema_resolvers argument is an experimental feature that may be removed or changed significantly in the future.

Returns:

Dictionary with the following entries:

”fps”	USD stage frames per second
”duration”	Difference between end time code and start time code of the USD stage
”up_axis”	`Axis` representing the stage’s up axis (“X”, “Y”, or “Z”)
”path_shape_map”	Mapping from prim path (str) of the UsdGeom to the respective shape index in `ModelBuilder`
”path_body_map”	Mapping from prim path (str) of a rigid body prim (e.g. that implements the PhysicsRigidBodyAPI) to the respective body index in `ModelBuilder`
”path_shape_scale”	Mapping from prim path (str) of the UsdGeom to its respective 3D world scale
”mass_unit”	The stage’s Kilograms Per Unit (KGPU) definition (1.0 by default)
”linear_unit”	The stage’s Meters Per Unit (MPU) definition (1.0 by default)
”scene_attributes”	Dictionary of all attributes applied to the PhysicsScene prim
”collapse_results”	Dictionary returned by `newton.ModelBuilder.collapse_fixed_joints()` if collapse_fixed_joints is True, otherwise None.
”physics_dt”	The resolved physics scene time step (float or None)
”schema_attrs”	Dictionary of collected per-prim schema attributes (dict)
”max_solver_iterations”	The resolved maximum solver iterations (int or None)
”path_body_relative_transform”	Mapping from prim path to relative transform for bodies merged via collapse_fixed_joints
”path_original_body_map”	Mapping from prim path to original body index before collapse_fixed_joints

Return type:

dict

approximate_meshes(method='convex_hull', shape_indices=None, raise_on_failure=False, keep_visual_shapes=False, **remeshing_kwargs)#

Approximates the mesh shapes of the model.

The following methods are supported:

Method	Description
`"coacd"`	Convex decomposition using CoACD
`"vhacd"`	Convex decomposition using V-HACD
`"bounding_sphere"`	Approximate the mesh with a sphere
`"bounding_box"`	Approximate the mesh with an oriented bounding box
`"convex_hull"`	Approximate the mesh with a convex hull (default)
`<remeshing_method>`	Any remeshing method supported by `newton.geometry.remesh_mesh()`

Note

The coacd and vhacd methods require additional dependencies (coacd or trimesh and vhacdx respectively) to be installed. The convex hull approximation requires scipy to be installed.

The raise_on_failure parameter controls the behavior when the remeshing fails:

If True, an exception is raised when the remeshing fails.
If False, a warning is logged, and the method falls back to the next available method in the order of preference:
- If convex decomposition via CoACD or V-HACD fails or dependencies are not available, the method will fall back to using the convex_hull method.
- If convex hull approximation fails, it will fall back to the bounding_box method.

Parameters:

method (Literal['coacd', 'vhacd', 'bounding_sphere', 'bounding_box', 'ftetwild', 'alphashape', 'quadratic', 'convex_hull']) – The method to use for approximating the mesh shapes.
shape_indices (list[int] | None) – The indices of the shapes to simplify. If None, all mesh shapes that have the ShapeFlags.COLLIDE_SHAPES flag set are simplified.
raise_on_failure (bool) – If True, raises an exception if the remeshing fails. If False, it will log a warning and continue with the fallback method.
**remeshing_kwargs (dict[str, Any]) – Additional keyword arguments passed to the remeshing function.

Returns:

A set of indices of the shapes that were successfully remeshed.

Return type:

set[int]

collapse_fixed_joints(verbose=wp.config.verbose)#: Removes fixed joints from the model and merges the bodies they connect. This is useful for simplifying the model for faster and more stable simulation.

color(include_bending=False, balance_colors=True, target_max_min_color_ratio=1.1, coloring_algorithm=ColoringAlgorithm.MCS)#

Runs coloring algorithm to generate coloring information.

Parameters:

include_bending_energy – Whether to consider bending energy for trimeshes in the coloring process. If set to True, the generated graph will contain all the edges connecting o1 and o2; otherwise, the graph will be equivalent to the trimesh.
balance_colors – Whether to apply the color balancing algorithm to balance the size of each color
target_max_min_color_ratio – the color balancing algorithm will stop when the ratio between the largest color and the smallest color reaches this value
algorithm – Value should be an enum type of ColoringAlgorithm, otherwise it will raise an error. ColoringAlgorithm.mcs means using the MCS coloring algorithm, while ColoringAlgorithm.ordered_greedy means using the degree-ordered greedy algorithm. The MCS algorithm typically generates 30% to 50% fewer colors compared to the ordered greedy algorithm, while maintaining the same linear complexity. Although MCS has a constant overhead that makes it about twice as slow as the greedy algorithm, it produces significantly better coloring results. We recommend using MCS, especially if coloring is only part of the preprocessing.

Note

References to the coloring algorithm:

MCS: Pereira, F. M. Q., & Palsberg, J. (2005, November). Register allocation via coloring of chordal graphs. In Asian Symposium on Programming Languages and Systems (pp. 315-329). Berlin, Heidelberg: Springer Berlin Heidelberg.

Ordered Greedy: Ton-That, Q. M., Kry, P. G., & Andrews, S. (2023). Parallel block Neo-Hookean XPBD using graph clustering. Computers & Graphics, 110, 1-10.

finalize(device=None, requires_grad=False)#

Finalize the builder and create a concrete Model for simulation.

This method transfers all simulation data from the builder to device memory, returning a Model object ready for simulation. It should be called after all elements (particles, bodies, shapes, joints, etc.) have been added to the builder.

Parameters:

device (Device | str | None) – The simulation device to use (e.g., ‘cpu’, ‘cuda’). If None, uses the current Warp device.
requires_grad (bool) – If True, enables gradient computation for the model (for differentiable simulation).

Returns:

A fully constructed Model object containing all simulation data on the specified device.

Return type:

Model

Notes

Performs validation and correction of rigid body inertia and mass properties.
Closes all start-index arrays (e.g., for muscles, joints, articulations) with sentinel values.
Sets up all arrays and properties required for simulation, including particles, bodies, shapes, joints, springs, muscles, constraints, and collision/contact data.

find_shape_contact_pairs(model)#

Identifies and stores all potential shape contact pairs for collision detection.

This method examines the collision groups and collision masks of all shapes in the model to determine which pairs of shapes should be considered for contact generation. It respects any user-specified collision filter pairs to avoid redundant or undesired contacts.

The resulting contact pairs are stored in the model as a 2D array of shape indices.

Uses the exact same filtering logic as the broad phase kernels (test_world_and_group_pair) to ensure consistency between EXPLICIT mode (precomputed pairs) and NXN/SAP modes.

Parameters:: model (Model) – The simulation model to which the contact pairs will be assigned.

Side Effects:

Sets model.shape_contact_pairs to a wp.array of shape pairs (wp.vec2i).
Sets model.shape_contact_pair_count to the number of contact pairs found.

get_custom_attributes_by_frequency(frequencies)#

Get custom attributes by frequency. This is useful for processing custom attributes for different kinds of simulation objects. For example, you can get all the custom attributes for bodies, shapes, joints, etc.

Parameters:: frequencies (Sequence[ModelAttributeFrequency]) – The frequencies to get custom attributes for.
Returns:: A list of custom attributes.
Return type:: list[CustomAttribute]

has_custom_attribute(key)#

Check if a custom attribute is defined.

plot_articulation(show_body_keys=True, show_joint_keys=True, show_joint_types=True, plot_shapes=True, show_shape_keys=True, show_shape_types=True, show_legend=True)#

Visualizes the model’s articulation graph using matplotlib and networkx. Uses the spring layout algorithm from networkx to arrange the nodes. Bodies are shown as orange squares, shapes are shown as blue circles.

Parameters:

show_body_keys (bool) – Whether to show the body keys or indices
show_joint_keys (bool) – Whether to show the joint keys or indices
show_joint_types (bool) – Whether to show the joint types
plot_shapes (bool) – Whether to render the shapes connected to the rigid bodies
show_shape_keys (bool) – Whether to show the shape keys or indices
show_shape_types (bool) – Whether to show the shape geometry types
show_legend (bool) – Whether to show a legend

replicate(builder, num_worlds, spacing=(0.0, 0.0, 0.0))#

Replicates the given builder multiple times, offsetting each copy according to the supplied spacing.

This method is useful for creating multiple instances of a sub-model (e.g., robots, scenes) arranged in a regular grid or along a line. Each copy is offset in space by a multiple of the specified spacing vector, and all entities from each copy are assigned to a new world.

Note

For visual separation of worlds, it is recommended to use the viewer’s set_world_offsets() method instead of physical spacing. This improves numerical stability by keeping all worlds at the origin in the physics simulation.

Parameters:

builder (ModelBuilder) – The builder to replicate. All entities from this builder will be copied.
num_worlds (int) – The number of worlds to create.
spacing (tuple[float, float, float], optional) – The spacing between each copy along each axis. For example, (5.0, 5.0, 0.0) arranges copies in a 2D grid in the XY plane. Defaults to (0.0, 0.0, 0.0).

set_coloring(particle_color_groups)#

Sets coloring information with user-provided coloring.

Parameters:: particle_color_groups – A list of list or np.array with dtype`=`int. The length of the list is the number of colors and each list or np.array contains the indices of vertices with this color.

property articulation_count#: The number of articulations in the model.

balance_inertia#: Whether to automatically correct rigid body inertia tensors that violate the triangle inequality. When True, adds a scalar multiple of the identity matrix to preserve rotation structure while ensuring physical validity (I1 + I2 >= I3 for principal moments). Default: True.

property body_count#: The number of rigid bodies in the model.

bound_inertia#: Minimum allowed eigenvalue for rigid body inertia tensors. If set, ensures all principal moments of inertia are at least this value. Set to None to disable inertia eigenvalue clamping. Default: None.

bound_mass#: Minimum allowed mass value for rigid bodies. If set, any body mass below this value will be clamped to this minimum. Set to None to disable mass clamping. Default: None.

property default_site_cfg: ShapeConfig#

Returns a ShapeConfig configured for sites (non-colliding reference points).

This config has all site invariants enforced: - is_site = True - has_shape_collision = False - has_particle_collision = False - density = 0.0 - collision_group = 0

Returns:: A new configuration suitable for creating sites.
Return type:: ShapeConfig

property edge_count#: The number of edges (for bending) in the model.

property joint_count#: The number of joints in the model.

property muscle_count#: The number of muscles in the model.

property particle_count#: The number of particles in the model.

property shape_count#: The number of shapes in the model.

property spring_count#: The number of springs in the model.

property tet_count#: The number of tetrahedra in the model.

property tri_count#: The number of triangles in the model.

property up_vector: list[float] | tuple[float, float, float] | vec3f#

Returns the 3D unit vector corresponding to the current up axis (read-only).

This property computes the up direction as a 3D vector based on the value of up_axis. For example, if up_axis is Axis.Z, this returns (0, 0, 1).

Returns:: The 3D up vector corresponding to the current up axis.
Return type:: Vec3

validate_inertia_detailed#: Whether to use detailed (slower) inertia validation that provides per-body warnings. When False, uses a fast GPU kernel that reports only the total number of corrected bodies and directly assigns the corrected arrays to the Model (ModelBuilder state is not updated). When True, uses a CPU implementation that reports specific issues for each body and updates the ModelBuilder’s internal state. Default: False.