newton.ModelBuilder#

class newton.ModelBuilder(up_axis=Axis.Z, gravity=None, sdf_texture_paired_samples=True)[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)
collision_pipeline = newton.CollisionPipeline(model)
contacts = collision_pipeline.contacts()

for i in range(10):
    state_0.clear_forces()
    collision_pipeline.collide(state_0, contacts)
    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

See Worlds for a full overview of world semantics, layout, and supported workflows.

There are two supported workflows for assigning world indices:

Using begin_world()/end_world(): Entities added outside any world context, before the first begin_world() or after the matching end_world(), are assigned to the global world (index -1). ModelBuilder manages current_world while a world context is active:
```
builder = ModelBuilder()
builder.add_ground_plane()  # global (world -1)

builder.begin_world(label="robot_0")
builder.add_body(...)  # world 0
builder.end_world()
```

Using add_world()/replicate(): All entities from the sub-builder are assigned to a new world:

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

main = ModelBuilder()
main.add_world(robot)  # All robot entities -> world 0
main.replicate(robot, copy_count=2)  # Add more worlds from the same source

With separate_worlds=False, replicate() instead adds all copies to the current world context in one batched pass, as repeated add_builder() calls would.

current_world is builder-managed, read-only state. Use begin_world(), end_world(), add_world(), or replicate() to manage world assignment.

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 ActuatorEntry(drive_class, clamping_classes, clamping_shared_kwargs, drive_shared_kwargs, indices, pos_indices, drive_args, delay_args=_ACTUATOR_ENTRY_DELAY_ARGS_UNSET, clamping_args=None, *, input_processor_classes=(), input_processor_shared_kwargs=(), input_processor_args=None, actuator_indices=None, motor_class=None, motor_shared_kwargs=None, motor_args=None)#

Bases: object

Stores accumulated specs for one group of compatible composed actuators.

Each element in indices is a single DOF index. The entry key is (drive_class, input_processor_key, clamping_key, drive_shared_key, motor_key) where shared params (e.g. model_path, lookup tables) must be identical across all actuators in a group. Per-actuator params such as delay step values may differ within a group.

__init__(drive_class, clamping_classes, clamping_shared_kwargs, drive_shared_kwargs, indices, pos_indices, drive_args, delay_args=_ACTUATOR_ENTRY_DELAY_ARGS_UNSET, clamping_args=None, *, input_processor_classes=(), input_processor_shared_kwargs=(), input_processor_args=None, actuator_indices=None, motor_class=None, motor_shared_kwargs=None, motor_args=None)#

Initialize an actuator entry.

Parameters:

delay_args (list[dict[str, Any]] | object) – Deprecated in Newton 1.9; pass an InputProcessorDelay in input_processor_classes and its per-actuator params in input_processor_args instead.
actuator_indices (list[int] | None) – Index of each actuator in per-actuator arrays, as returned by ModelBuilder.add_actuator(). Entries built by hand without it get no per-actuator arrays.

actuator_indices: list[int]#

clamping_args: list[list[dict[str, Any]]]#

clamping_classes: tuple#

clamping_shared_kwargs: tuple#

property delay_args: list[dict[str, Any]]#

Deprecated alias for the delay entries of input_processor_args.

The returned list is a new list holding the per-actuator delay dicts: changing a dict changes the entry, but appending to the list does not. Assign a new list to replace the delay entries.

Deprecated since version 1.9: Use input_processor_args instead.

drive_args: list[dict[str, Any]]#

drive_class: type#

drive_shared_kwargs: dict#

indices: list[int]#

input_processor_args: list[list[dict[str, Any]]]#

input_processor_classes: tuple = ()#

input_processor_shared_kwargs: tuple = ()#

motor_args: list[dict[str, Any]]#

motor_shared_kwargs: dict#

pos_indices: list[int]#

class BatteryEntry(battery_class, args=<factory>, actuators=<factory>, world=<factory>)#

Bases: object

Stores accumulated specs for the batteries of one battery class.

__init__(battery_class, args=<factory>, actuators=<factory>, world=<factory>)#

actuators: list[list[int]]#

args: list[dict[str, Any]]#

battery_class: type#

world: list[int]#

class BvhConfig(mesh_constructor=None, gaussian_constructor=None, shape_constructor=None, shape_flags=ShapeFlags.VISIBLE)#

Bases: object

Default BVH construction settings used during model finalization.

__init__(mesh_constructor=None, gaussian_constructor=None, shape_constructor=None, shape_flags=ShapeFlags.VISIBLE)#

gaussian_constructor: str | None = None#: Warp Gaussian BVH constructor backend. If None, Warp’s default is used.

mesh_constructor: str | None = None#: Warp mesh BVH constructor backend. If None, Warp’s default is used.

shape_constructor: str | None = None#: Warp model shape BVH constructor backend. If None, Warp’s default is used.

shape_flags: ShapeFlags = 1#: Mask of ShapeFlags; a shape is included in the model shape BVH if any of its flags are set in the mask.

class CustomAttribute(name, dtype, frequency, assignment=AttributeAssignment.MODEL, namespace=None, references=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, reference_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 Model.AttributeAssignment 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=AttributeAssignment.MODEL, namespace=None, references=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, reference_value_transformer=None)#

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

Build wp.array (or list for string dtype) from count, dtype, default and overrides.

For string dtype, returns a Python list[str] instead of a Warp array.

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

default: Any = None#: Default value for the attribute. If None, the default value is determined based on the dtype.

dtype: type#: Warp dtype (e.g., wp.float32, wp.int32, wp.bool, wp.vec3) that is compatible with Warp arrays, or str for string attributes that remain as Python lists.

frequency: AttributeFrequency | str#

Frequency category that determines how the attribute is indexed in the Model.

Can be either:

A Model.AttributeFrequency enum value for built-in frequencies (BODY, SHAPE, JOINT, etc.) Uses dict-based storage where keys are entity indices, allowing sparse assignment.
A string for custom frequencies using the full frequency key (e.g., "mujoco:pair"). Uses list-based storage for sequential data appended via add_custom_values(). All attributes sharing the same custom frequency must have the same count, validated by finalize.

property is_custom_frequency: bool#

Check if this attribute uses a custom (string) frequency.

Returns:: True if the frequency is a string (custom frequency), False if it’s a Model.AttributeFrequency enum (built-in frequency like BODY, SHAPE, etc.).

property key: str#

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

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

mjcf_attribute_name: str | None = None#: Name of the attribute in the MJCF definition. If None, the attribute name is used.

mjcf_value_transformer: Callable[[str, dict[str, Any] | None], Any] | None = None#: Transformer function that converts a MJCF attribute value string to a valid Warp dtype. If undefined, the generic converter from newton.utils.parse_warp_value_from_string() is used. Receives an optional context dict with parsing-time information (e.g., use_degrees, joint_type).

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

namespace: str | None = None#: Namespace for the attribute. If None, the attribute is added directly to the assigned object without a namespace.

reference_value_transformer: Callable[[list[Any], dict[str, Any]], list[Any]] | None = None#

Batch transformer for entity references copied by ModelBuilder.add_builder().

Use this instead of references when the referenced entity type depends on other values in the same row. For each copied builder, the callback is invoked once for this attribute if its value container is nonempty. It receives a list of the source builder’s authored values and a context dictionary with these keys:

"builder" (ModelBuilder): Source builder. Companion attribute values can be read using row_indices.
"destination_builder" (ModelBuilder): Builder receiving the copy. It is partway through merging; callbacks must not depend on which other custom attributes have already been copied.
"entity_offsets" (dict[str, int]): Index offsets for this copy’s built-in entities. Keys are "body", "shape", "joint", "joint_dof", "joint_coord", "joint_constraint", "articulation", "particle", "edge", "triangle", "tetrahedron", "spring", "tendon", "tendon_guide", "tendon_segment", "constraint_mimic", and "attachment_particle_body".
"custom_frequency_offsets" (dict[str, int]): Destination row counts before this copy’s custom attributes are merged, keyed by full frequency name (for example, "mujoco:tendon"). Missing keys have offset zero.
"row_indices" (Sequence[int]): Source index corresponding to each input value. Custom-frequency lists use consecutive indices; sparse enum-frequency attributes use their authored dictionary keys, which need not be sorted.
"world" (int): Destination world for this copy, or -1 for global entities. Use this value for world references instead of adding an offset.
"label_prefix" (str | None): Optional label prefix for this copy.

The callback must return a list in the same order and of the same length, preserving None entries for unset rows. Treat the supplied builders, mappings, and source values as read-only; create replacement values instead of mutating source objects. Replication invokes the callback separately for each copy with its own offsets.

Mutually exclusive with references; the callback owns reference remapping.

references: AttributeFrequency | str | None = None#

For attributes containing entity indices, specifies how values are transformed during add_builder/add_world/replicate merging.

Use Model.AttributeFrequency for a built-in reference domain, such as Model.AttributeFrequency.CURVE, or a string for a custom frequency. Unlike frequency, which indexes the attribute’s rows, this field identifies what its stored integer values refer to.

Built-in string names are also supported (values are offset by entity count):

"body", "shape", "joint", "joint_dof", "joint_coord", "articulation", "constraint_mimic", "particle", "edge", "triangle", "tetrahedron", "spring", "tendon", "tendon_guide", "tendon_segment"

For experimental deformable object types, use Model.AttributeFrequency.CURVE, SURFACE, or VOLUME. The strings "curve", "surface", and "volume" refer to custom frequencies, regardless of registration order. Registration preserves the supplied value of this field.

Special handling:

"world": Missing custom-frequency row values are initialized from ModelBuilder.current_world. During builder merging, values are replaced with the destination builder’s active world context (not offset).

Custom frequencies (values are offset by that frequency’s count):

Any custom frequency string, e.g., "mujoco:pair"

urdf_attribute_name: str | None = None#: Name of the attribute in the URDF definition. If None, the attribute name is used.

urdf_value_transformer: Callable[[str, dict[str, Any] | None], Any] | None = None#: Transformer function that converts a URDF attribute value string to a valid Warp dtype. If undefined, the generic converter from newton.utils.parse_warp_value_from_string() is used. Receives an optional context dict with parsing-time information.

usd_attribute_name: str | None = None#

Name of the USD attribute to read values from during USD parsing.

If None (default), the name is derived automatically as "newton:<key>" where <key> is "<namespace>:<name>" or just "<name>" if no namespace is set.
If set to "*", the usd_value_transformer is called for every prim matching the attribute’s frequency, regardless of which USD attributes exist on the prim. The transformer receives None as the value argument. This is useful for computing attribute values from arbitrary prim data rather than reading a specific USD attribute. A usd_value_transformer must be provided when using "*"; otherwise, add_custom_attribute() raises a ValueError.

usd_value_transformer: Callable[[Any, dict[str, Any]], Any] | None = None#: Transformer function that converts a USD attribute value to a valid Warp dtype. If undefined, the generic converter from newton.usd.convert_warp_value() is used. Receives a context dict with the following keys: - "prim": The USD prim to query. - "attr": The CustomAttribute object to get the value for.

values: dict[int, Any] | list[Any] | None = None#

Storage for specific values (overrides).

For enum frequencies (BODY, SHAPE, etc.): dict[int, Any] mapping entity indices to values. For WORLD, keys are world indices, and key -1 is global world -1, whose value is also the default of local worlds without one unless the attribute stores references through references or reference_value_transformer. For string frequencies (“mujoco:pair”, etc.): list[Any] for sequential custom data.

If None, the attribute is not initialized with any values. Values can be assigned in subsequent ModelBuilder.add_*(..., custom_attributes={...}) method calls for specific entities after the CustomAttribute has been added through the ModelBuilder.add_custom_attribute() method.

class CustomFrequency(name, namespace=None, usd_prim_filter=None, usd_entry_expander=None, articulation_owner_attribute=None, articulation_owner_resolver=None, label_attribute=None)#

Bases: object

Represents a custom frequency definition for the ModelBuilder.

Custom frequencies allow defining entity types beyond the built-in ones (BODY, SHAPE, JOINT, etc.). They must be registered via ModelBuilder.add_custom_frequency() before assigning them to an attribute’s CustomAttribute.frequency field.

The optional usd_prim_filter callback enables automatic USD parsing for this frequency. When provided, ModelBuilder.add_usd() will call this function for each prim in the USD stage to determine whether custom attribute values with this frequency should be extracted from it.

See Custom Attributes for more information on custom frequencies.

Example

# Define a custom frequency for MuJoCo actuators with USD parsing support
def is_actuator_prim(prim: Usd.Prim, context: dict[str, Any]) -> bool:
    return prim.GetTypeName() == "MjcActuator"


builder.add_custom_frequency(
    ModelBuilder.CustomFrequency(
        name="actuator",
        namespace="mujoco",
        usd_prim_filter=is_actuator_prim,
    )
)

__init__(name, namespace=None, usd_prim_filter=None, usd_entry_expander=None, articulation_owner_attribute=None, articulation_owner_resolver=None, label_attribute=None)#

articulation_owner_attribute: str | None = None#

Full key of the attribute that assigns each row to an articulation.

The key must be named <frequency>_articulation. The attribute must use this custom frequency, be assigned to the model, and declare references="articulation". When provided, ArticulationView automatically exposes every array that uses this frequency.

articulation_owner_resolver: Callable[[ModelBuilder], Sequence[int]] | None = None#

Optional callback that computes the articulation owner for every row.

The callback runs before this builder is merged or finalized and its results populate articulation_owner_attribute. This keeps solver-specific ownership logic local to the custom-frequency registration while preserving ordinary reference remapping. Rows whose ownership was already remapped by a merge are preserved when later rows are appended and resolved.

property key: str#: The key of the custom frequency (e.g., "mujoco:actuator" or "pair").

label_attribute: str | None = None#

Optional full key of a string attribute containing row labels.

The key must be named <frequency>_label. The attribute must use this custom frequency and be assigned to the model. ArticulationView uses it to expose labels for the template articulation. Builder merging applies label_prefix to these values like other entity labels.

name: str#: The name of the custom frequency (e.g., "actuator", "pair").

namespace: str | None = None#: Namespace for the custom frequency. If provided, the frequency key becomes "namespace:name". If None, the custom frequency is registered without a namespace.

usd_entry_expander: Callable[[Usd.Prim, dict[str, Any]], Iterable[dict[str, Any]]] | None = None#

Build row entries for a matching USD prim.

Called by newton.ModelBuilder.add_usd() after usd_prim_filter returns True. Return an iterable of dictionaries; each dictionary is one row passed to newton.ModelBuilder.add_custom_values().

Use this when one prim should produce multiple rows. Missing keys in a row are filled with None so defaults still apply. Returning an empty iterable adds no rows.

See also

When this callback is set, newton.ModelBuilder.add_usd() does not run default per-attribute extraction for this frequency on matched prims (usd_attribute_name / usd_value_transformer).

Example

def expand_tendon_rows(prim: Usd.Prim, context: dict[str, Any]) -> Iterable[dict[str, Any]]:
    for joint_path in prim.GetCustomDataByKey("joint_paths") or []:
        yield {"joint": joint_path, "stiffness": prim.GetCustomDataByKey("stiffness")}

usd_prim_filter: Callable[[Usd.Prim, dict[str, Any]], bool] | None = None#

Select which USD prims are used for this frequency.

Called by newton.ModelBuilder.add_usd() for each visited prim with:

prim: current Usd.Prim
context: callback context dictionary with prim, result, and builder

Return True to parse this prim for the frequency, or False to skip it. If this is None, the frequency is not parsed automatically from USD.

Example

def is_actuator_prim(prim: Usd.Prim, context: dict[str, Any]) -> bool:
    return prim.GetTypeName() == "MjcActuator"

class JointDofConfig(*, axis=Axis.X, limit_lower=-MAXVAL, limit_upper=MAXVAL, limit_ke=1e4, limit_kd=1e1, target_q=None, target_qd=None, target_ke=0.0, target_kd=0.0, damping=0.0, stiffness=0.0, rest_q=None, armature=0.0, effort_limit=1e6, velocity_limit=1e6, friction=0.0, actuator_mode=None, target_pos=None, target_vel=None)#

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=-MAXVAL, limit_upper=MAXVAL, limit_ke=1e4, limit_kd=1e1, target_q=None, target_qd=None, target_ke=0.0, target_kd=0.0, damping=0.0, stiffness=0.0, rest_q=None, armature=0.0, effort_limit=1e6, velocity_limit=1e6, friction=0.0, actuator_mode=None, target_pos=None, target_vel=None)#

actuator_mode#: Actuator mode for this DOF. Determines which actuators are installed (see JointTargetMode). If None, the mode is inferred from gains and targets.

armature#: Artificial inertia added around the joint axis [kg·m² or kg]. Defaults to 0.

axis#: The 3D joint axis in the joint parent anchor frame.

damping#: Passive velocity damping [N·s/m or N·m·s/rad, depending on joint type] that is always active. Defaults to 0.0.

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 coefficient of the joint axis limits [N·s/m or N·m·s/rad, depending on joint type]. 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 -MAXVAL (unlimited).

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

rest_q#: Passive spring rest coordinate [m or rad], independent of joint limits. None leaves the coordinate unspecified (effectively zero unless a legacy spring input supplies it). An explicit zero takes precedence over legacy defaults.

stiffness#: Passive spring stiffness [N/m or N·m/rad]. Defaults to zero.

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.

property target_pos: float#: Deprecated position target.

Deprecated since version 1.8: Use target_q instead.

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

target_qd#: The target velocity of the joint axis.

property target_vel: float#: Deprecated velocity target.

Deprecated since version 1.8: Use target_qd instead.

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

class MeshApproximationConfig(coacd_threshold=0.05)#

Bases: object

Default settings for mesh approximation.

ModelBuilder.default_mesh_approximation_cfg supplies defaults for settings not passed to ModelBuilder.approximate_meshes() explicitly, including approximation triggered by ModelBuilder.add_usd() via the authored physics:approximation attribute.

__init__(coacd_threshold=0.05)#

coacd_threshold: float = 0.05#: CoACD concavity threshold. Lower values produce finer convex decompositions with more parts.

class ShapeConfig(*, density=1000.0, ke=2500.0, kd=100.0, kf=1000.0, ka=0.0, mu=1.0, mu_static=None, restitution=0.0, mu_torsional=0.005, mu_rolling=0.0001, margin=0.0, gap=None, is_solid=True, collision_group=1, collision_filter_parent=True, has_shape_collision=True, has_particle_collision=True, is_visible=True, is_site=False, sdf_narrow_band_range=(-0.1, 0.1), sdf_target_voxel_size=None, sdf_max_resolution=None, force_sdf=False, sdf_texture_format='uint16', is_hydroelastic=False, kh=10000000000.0, sdf_padding=None)#

Bases: object

Represents per-shape collision, material, mass, and SDF settings.

These fields are general model data, and not every field is respected or needed by every solver. Solvers and contact backends may use, combine, or ignore individual fields according to their formulation; see solver-specific documentation for behavior.

__init__(*, density=1000.0, ke=2500.0, kd=100.0, kf=1000.0, ka=0.0, mu=1.0, mu_static=None, restitution=0.0, mu_torsional=0.005, mu_rolling=0.0001, margin=0.0, gap=None, is_solid=True, collision_group=1, collision_filter_parent=True, has_shape_collision=True, has_particle_collision=True, is_visible=True, is_site=False, sdf_narrow_band_range=(-0.1, 0.1), sdf_target_voxel_size=None, sdf_max_resolution=None, force_sdf=False, sdf_texture_format='uint16', is_hydroelastic=False, kh=10000000000.0, sdf_padding=None)#

configure_sdf(*, max_resolution=None, target_voxel_size=None, is_hydroelastic=False, kh=1.0e10, texture_format=None, force_sdf=False)#

Configure texture SDF generation and hydroelastic contact.

Primitive texture SDFs require CUDA and are generated for hydroelastic shape contacts on spheres, boxes, capsules, cylinders, cones, and ellipsoids. Outside hydroelastic mode, only boxes honor explicit resolution requests, with either shape or particle collisions enabled.

Particle and full-surface contacts with these primitives use analytic distances and do not need textures. Leave sdf_max_resolution and sdf_target_voxel_size unset for CPU particle-only models.

Parameters:

max_resolution (int | None) – Maximum dimension for sparse SDF grid (must be divisible by 8). If provided, clears any previous target_voxel_size setting.
target_voxel_size (float | None) – Target voxel size [m] for sparse SDF grid. If provided, clears any previous max_resolution setting.
is_hydroelastic (bool) – Whether to use SDF-based hydroelastic contacts. Both shapes in a pair must have this enabled.
kh (float) – Hydroelastic contact stiffness coefficient.
texture_format (str | None) – Subgrid texture storage format. "uint16" (default) uses 16-bit normalized textures. "float32" uses full-precision. "uint8" uses 8-bit textures.
force_sdf (bool) – Build the SDF even when neither max_resolution nor target_voxel_size is given (uses the default resolution). Provisions the SDF needed for full-surface rigid-soft contact without picking a resolution.

Raises:

ValueError – If both max_resolution and target_voxel_size are provided.

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

validate(shape_type=None)#

Validate ShapeConfig parameters.

Parameters:: shape_type (int | None) – Optional shape geometry type used for context-specific validation.

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.

force_sdf: bool = False#: If True, ModelBuilder.finalize() builds a volume SDF for this mesh/convex shape even when neither sdf_max_resolution nor sdf_target_voxel_size is set (built at the default resolution). Use to provision SDFs for full-surface rigid-soft contact; see configure_sdf().

gap: float | None = None#: Additional contact detection gap [m]. If None, uses builder.rigid_gap as default. Broad phase uses (margin + gap) [m] for AABB expansion and pair filtering.

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_hydroelastic: bool = False#: Whether the shape collides using SDF-based hydroelastics. For hydroelastic collisions, both participating shapes must have is_hydroelastic set to True. Defaults to False.

Note

Hydroelastic collision handling only works with volumetric shapes and in particular will not work for shapes like flat meshes or cloth. This flag will be automatically set to False for planes and heightfields in ModelBuilder.add_shape().

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 [m].

Distance within which the normal force attracts the shapes, used by SolverSemiImplicit and SolverFeatherstone. 0 disables adhesion. See Friction gain and adhesion.

kd: float = 100.0#: The normal contact damping coefficient [N·s/m].

ke: float = 2500.0#: The normal contact stiffness [N/m].

kf: float = 1000.0#

The contact friction gain [N·s/m].

Slope of the viscous friction regularization in SolverSemiImplicit and SolverFeatherstone; also used by SolverMuJoCo. See Friction gain and adhesion.

kh: float = 10000000000.0#: Hydroelastic contact stiffness coefficient [N/m^3].

Note

The default linear pressure law is pressure = -kh * signed_depth. Effective contact force scales with contact area, so kh sets a pressure-to-penetration ratio, not a direct force-to-penetration ratio. Solvers and contact backends may scale or otherwise interpret this coefficient according to their formulation.

For SolverMuJoCo, stiffness values are internally scaled by masses when Newton-generated contacts are passed through the MuJoCo contact path. Tune kh with that scaling in mind.

margin: float = 0.0#: Outward offset from the shape’s surface [m] for collision detection. Extends the effective collision surface outward by this amount. When two shapes collide, their margins are summed (margin_a + margin_b) to determine the total separation [m]. This value is also used when computing inertia for hollow shapes (is_solid=False).

mu: float = 1.0#: The coefficient of friction [dimensionless]; the dynamic (kinetic) coefficient when mu_static is set.

mu_rolling: float = 0.0001#: The coefficient of rolling friction [m] (resistance to rolling motion).

mu_static: float | None = None#: The coefficient of static friction [dimensionless], the break-away threshold for sticking contacts. None uses mu (no static/dynamic distinction); a set value must not be below mu, so code that overrides mu alone has to resolve this field as well. No built-in solver models stick-slip friction yet; the value is stored for solvers that do.

mu_torsional: float = 0.005#: The coefficient of torsional friction [m] (resistance to spinning at contact point).

restitution: float = 0.0#

The coefficient of restitution.

SolverXPBD requires enable_restitution=True on the solver constructor for this field to take effect. SolverSteel uses the arithmetic mean of the two shapes’ coefficients, each clamped to [0, 1], for contacts whose closing speed at the start of the step exceeds its restitution_velocity_threshold. Non-finite contact material values on colliding shapes are rejected by ModelBuilder.finalize() unless shape validation is disabled.

sdf_max_resolution: int | None = None#: Maximum dimension for sparse SDF grid (must be divisible by 8). See configure_sdf() for supported shapes and CUDA requirements.

sdf_narrow_band_range: tuple[float, float] | list[float] = (-0.1, 0.1)#: The narrow band distance range (inner, outer) for primitive SDF computation.

sdf_padding: float | None = None#: SDF AABB padding [m] for primitive texture SDFs. Falls back to gap, plus margin for hydroelastic shapes, when None. Hydroelastic padding must cover margin + gap. Rejected on MESH / CONVEX_MESH shapes — pass margin to build_sdf() instead.

sdf_target_voxel_size: float | None = None#: Target voxel size [m] for primitive texture SDF generation. See configure_sdf() for supported shapes and CUDA requirements.

sdf_texture_format: str = 'uint16'#: Subgrid texture storage format for the SDF. "uint16" (default) stores subgrid voxels as 16-bit normalized textures (half the memory of "float32"). "float32" stores full-precision values. "uint8" uses 8-bit textures for minimum memory.

__init__(up_axis=Axis.Z, gravity=None, sdf_texture_paired_samples=True)#

Initializes a new ModelBuilder instance for constructing simulation models.

Parameters:

up_axis (Axis | Literal['X', 'Y', 'Z'] | ~typing.Literal[0, 1, 2] | int | str) – The axis to use as the “up” direction in the simulation. Defaults to Axis.Z.
gravity (list[float] | tuple[float, float, float] | vec3f | None) – Default gravity vector [m/s^2]. If omitted, gravity defaults to -9.81 along up_axis.
sdf_texture_paired_samples (bool) – Store adjacent X samples together in SDF textures for faster software interpolation. Disable to halve SDF texture memory at the cost of slower hydroelastic sampling. This optimization is automatically disabled on CUDA devices with architectures older than SM90 when Warp was built with CUDA Toolkit 13.0 or earlier. Every prebuilt mesh SDF added to this builder must use the same effective layout, selected by the paired_samples argument to Mesh.build_sdf() and the target device.

add_actuator(drive_class=None, index=None, clamping=None, delay_steps=None, pos_index=None, *, input_processors=None, motor=None, **kwargs)#

Add an external actuator for a single DOF.

External actuators apply forces computed outside the physics engine. Multiple calls with the same drive_class, clamping, input processor and motor types, and identical shared parameters are accumulated into one Actuator instance during finalize. Per-actuator parameters, such as delay step values, may differ within the same group.

Parameters:

drive_class (type[DriveBase] | None) – Drive class (e.g. DrivePD).
index (int | None) – DOF index into joint_qd-shaped arrays (velocities, velocity targets, feedforward, forces).
clamping (list[tuple[type[ClampingBase], dict[str, Any]]] | None) – Optional list of (ClampingClass, kwargs) tuples applied post-drive. E.g. [(ClampingMaxEffort, {'max_effort': 50.0})]. Clamps must accept the drive output space. DUTY clamps run before the motor; EFFORT clamps require an actuator without a motor.
delay_steps (int | None) – Deprecated in Newton 1.9; use input_processors=[(InputProcessorDelay, {"delay_steps": ...})] instead.
pos_index (int | None) – DOF index into joint_q-shaped arrays (positions, position targets). Defaults to index. Differs from index for floating-base or ball-joint articulations where joint_q and joint_qd have different layouts.
input_processors (list[tuple[type[InputProcessorBase], dict[str, Any]]] | None) – Optional list of (InputProcessorClass, kwargs) tuples applied in order before the drive. E.g. [(InputProcessorDelay, {"delay_steps": 3})]. Parameters listed in the class’s JOINT_PARAMS take a joint index or a joint label; None selects the actuated joint.
motor (tuple[type[MotorDC], dict[str, Any]] | None) – Optional (MotorClass, kwargs) tuple applied after DUTY clamping and duty-to-voltage conversion. E.g. (MotorDC, {"kt": 1.0, "resistance": 2.0, "vin": 12.0}).
**kwargs (Any) – Per-DOF drive parameters (e.g. kp, kd).

Returns:

The index of the actuator in per-actuator arrays, e.g. for add_battery().

Raises:

ValueError – index belongs to another world than the current one, a joint parameter of an input processor does not identify a single-DOF joint of the current world or a global joint, of the same type as the actuated joint, or the drive and clamps do not match the modeling path: DUTY with a motor, EFFORT without one.

Return type:

int

add_articulation(joints, label=None, custom_attributes=None)#

Adds an articulation to the model from a list of joint indices.

The articulation is a set of joints that must be contiguous and monotonically increasing. Some functions, such as forward kinematics newton.eval_fk(), are parallelized over articulations.

Parameters:

joints (list[int]) – List of joint indices to include in the articulation. Must be contiguous and monotonic.
label (str | None) – The label of the articulation. If None, a default label will be created.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for ARTICULATION frequency attributes.

Raises:

ValueError – If joints are not contiguous, not monotonic, or belong to different worlds.

Example

link1 = builder.add_link(...)
link2 = builder.add_link(...)
link3 = builder.add_link(...)

joint1 = builder.add_joint_revolute(parent=-1, child=link1)
joint2 = builder.add_joint_revolute(parent=link1, child=link2)
joint3 = builder.add_joint_revolute(parent=link2, child=link3)

# Create articulation from the joints
builder.add_articulation([joint1, joint2, joint3])

add_attachment_particle_body(particle, body, *, body_point=None, stiffness=1.0e4, damping=0.0, enabled=True, custom_attributes=None)#

Adds an attachment between a rigid body and a particle.

The attachment pulls the particle toward a body-local anchor and transfers equal-and-opposite forces between both endpoints in SolverVBD. The constraint is translational; a single particle does not define an orientation. Finite-stiffness attachments whose endpoints are owned by different solvers are coupled by SolverCoupledADMM instead. See Particle-Body Attachments.

Parameters:

particle (int) – Index of the attached particle.
body (int) – Index of the rigid body.
body_point (list[float] | tuple[float, float, float] | vec3f | None) – Attachment point in the body’s local frame [m]. If None, the body origin is used.
stiffness (float) – Attachment stiffness [N/m]. Use math.inf for a hard point constraint in SolverVBD.
damping (float) – Attachment damping [N·s/m]. Ignored for hard attachments.
enabled (bool) – Whether the attachment is active.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

Returns:

Index of the attachment.

Raises:

IndexError – If particle or body is out of range.
ValueError – If the endpoints belong to different worlds, a coefficient is negative or NaN, a finite coefficient cannot be represented in float32, or damping or body_point is not finite.

Return type:

int

add_battery(battery_class, actuators, **kwargs)#

Add a battery shared by several actuators of the current world.

Multiple calls with the same battery_class are accumulated into one BatteryBase instance during finalize. Per-battery parameters, such as the nominal voltage, may differ within the same group.

Parameters:

battery_class (type[BatteryBase]) – Battery class (e.g. BatteryConstantResistance).
actuators (Sequence[int]) – Actuator indices returned by add_actuator(). At least one is required, and each must belong to the current world and have a motor that draws from a battery (e.g. MotorDC with supply_from_battery=True).
**kwargs (Any) – Per-battery parameters (e.g. nominal_voltage, resistance).

Raises:

ValueError – actuators is empty or lists an actuator twice, an actuator does not exist, belongs to another world, does not draw from a battery or already has a battery, or a battery parameter is invalid.

add_body(*, xform=None, com=None, inertia=None, mass=0.0, label=None, lock_inertia=False, is_kinematic=False, custom_attributes=None)#

Adds a stand-alone free-floating rigid body to the model.

This is a convenience method that creates a single-body articulation with a free joint, allowing the body to move freely in 6 degrees of freedom. This is equivalent to calling:

add_link() to create the body
add_joint_free() to add a free joint connecting the body to the world
add_articulation() to create a new articulation from the joint

For creating articulations with multiple linked bodies, use add_link(), the appropriate joint methods, and add_articulation() directly.

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.
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.
inertia (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.
label (str | None) – Label of the body. When provided, the auto-created free joint and articulation are assigned labels {label}_free_joint and {label}_articulation respectively.
lock_inertia (bool) – If True, prevents subsequent shape additions from modifying this body’s mass, center of mass, or inertia. This does not affect merging behavior in collapse_fixed_joints(), which always accumulates mass and inertia across merged bodies.
is_kinematic (bool) – If True, the body is kinematic and does not respond to forces.
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

add_body_variants(body, variants, *, initial=0, labels=None)#

Declare alternative shape sets for a body, one of which is selected at a time.

Each variant is a builder with exactly one body, such as an asset loaded with add_usd() or add_mjcf(): its shapes, colliders and visuals of any type and count, and its body’s mass, center of mass, and inertia. body gets one block of shape rows per role (colliders, then other shapes such as visuals, then sites), each with as many rows as the variant with the most shapes of that role has. Selecting a variant with Model.select_body_variants copies each of its shapes into the next row of its role’s block, in the variant’s order, empties the remaining rows, and sets the body’s mass properties to those of the body as built plus the variant’s. Shapes added to body directly stay in place for every variant.

A row takes everything authored on the variant shape it holds: geometry, flags, color, opacity, materials, and model-assigned shape custom attributes. It keeps its label, world, collision group, and filter pairs, so the i-th colliders of all variants must share a collision group. An empty row has its collision and visibility flags cleared, so it neither collides nor renders. Variant shapes are expressed in the variant body’s frame, which maps onto body’s frame; the variant body’s pose, joints, and other entities are ignored, as are body custom attributes and shape custom attributes that reference other entities. The variants are copied at declaration, so later edits to the variant builders have no effect, and finalize() replaces edits to the rows in this builder, such as by approximate_meshes(), with the initial variant; edit the variant builders instead.

Bodies copied with add_builder() or replicate() share the variants, which finalize() stores once, and select independently per world. Variant ids are positions in variants and are the same for every copy.

Experimental

Body variants may change without a deprecation period.

Parameters:

body (int) – Index of the body that receives the variants.
variants (Sequence[ModelBuilder]) – Single-body builders defining the variants.
initial (int) – Index of the variant selected in the finalized model.
labels (Sequence[str] | None) – Variant labels. Defaults to each variant’s body label.

Raises:

IndexError – If body or initial is out of range.
ValueError – If body already has variants, labels does not match variants, colliders held by the same row have different collision groups, a shape custom attribute is declared differently than here or in another variant, shapes of a later world or trailing global shapes were added after body’s world, or a variant builder is this builder, declares variants itself, uses a different up axis, does not contain exactly one body, contains shapes not attached to it, contains planes, heightfields, Gaussians, or hydroelastic shapes, or has values for shape custom attributes not assigned to the model.

add_builder(builder, xform=None, label_prefix=None)#

Copies the data from another ModelBuilder into this ModelBuilder.

All entities from the source builder are added to this builder’s current world context (the value of current_world). Any world assignments that existed in the source builder are overwritten - all entities will be assigned to the active world context.

Use begin_world(), end_world(), add_world(), or replicate() to manage world assignment. current_world is read-only and should not be set directly.

The gravity of builder replaces the gravity of the current world, or this builder’s gravity outside a world context.

To add many copies of the same builder to the current world, call replicate() with separate_worlds=False instead of calling this method in a loop; it merges all copies in one batched pass.

The source builder acts as a template: merged entries may share objects with it (and across copies when replicating). Mutating such entries in place afterwards (e.g. xform.p = ...) writes through to every builder sharing them and is unsupported; reassign entries instead (shape_transform[i] = xform).

Example:

main_builder = ModelBuilder()
sub_builder = ModelBuilder()
sub_builder.add_body(...)
sub_builder.add_shape_box(...)

# Adds all entities from sub_builder to main_builder's active
# world context (-1 by default)
main_builder.add_builder(sub_builder)

# With transform and label prefix
main_builder.add_builder(sub_builder, xform=wp.transform((1, 0, 0)), label_prefix="left")

Parameters:

builder (ModelBuilder) – The model builder to copy data from.
xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – Optional offset transform applied to root bodies.
label_prefix (str | None) – Optional prefix prepended to all entity labels from the source builder. Labels are joined with / (e.g., "left/panda/base_link").

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, color=None, opacity=None, custom_attributes_particles=None, custom_attributes_edges=None, custom_attributes_triangles=None, label=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
label (str | None) – Optional name forwarded to newton.utils.validate_triangle_mesh() via add_cloth_mesh() so a mesh-quality warning can identify this cloth. The same name is appended to surface_label for this cloth; if None, a generated surface_N label is used. See Deformable Objects.
color (list[float] | tuple[float, float, float] | vec3f | list[list[float] | tuple[float, float, float] | vec3f] | ndarray | None) – Display color in [0, 1] for the cloth surface. If a single RGB value, applied to all triangles. If array-like, RGB values are applied per triangle.
opacity (float | list[float] | ndarray | None) – Display opacity in [0, 1] for the cloth surface. If scalar, applied to all triangles. If array-like, values are applied per triangle.

add_cloth_mesh(*, pos, rot, scale, vel, vertices, indices, density, 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, color=None, opacity=None, custom_attributes_particles=None, custom_attributes_edges=None, custom_attributes_triangles=None, custom_attributes_springs=None, validate_mesh=False, label=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
particle_radius (float | None) – The particle_radius which controls particle based collisions.
color (list[float] | tuple[float, float, float] | vec3f | list[list[float] | tuple[float, float, float] | vec3f] | ndarray | None) – Display color in [0, 1] for the cloth surface. If a single RGB value, applied to all triangles. If array-like, RGB values are applied per triangle.
opacity (float | list[float] | ndarray | None) – Display opacity in [0, 1] for the cloth surface. If scalar, applied to all triangles. If array-like, values are applied per triangle.
custom_attributes_particles (dict[str, Any] | None) – Dictionary of custom attribute names to values for the particles.
custom_attributes_edges (dict[str, Any] | None) – Dictionary of custom attribute names to values for the edges.
custom_attributes_triangles (dict[str, Any] | None) – Dictionary of custom attribute names to values for the triangles.
custom_attributes_springs (dict[str, Any] | None) – Dictionary of custom attribute names to values for the springs.
validate_mesh (bool) – If True, run quality checks on the input mesh and emit warnings for degenerate or sliver triangles and extreme interior angles. See newton.utils.validate_triangle_mesh(). (Non-manifold edges are reported separately by MeshAdjacency, which is built unconditionally for the bending-edge pipeline.)
label (str | None) – Optional name forwarded to newton.utils.validate_triangle_mesh() so a mesh-quality warning emitted with validate_mesh=True can identify this cloth. The same name is appended to surface_label for this cloth; if None, a generated surface_N label is used. See Deformable Objects.

Note

The mesh should be two-manifold.

add_constraint_mimic(joint0, joint1, coef0=0.0, coef1=1.0, enabled=True, label=None, custom_attributes=None)#

Adds a mimic constraint to the model.

Deprecated since version 1.7: Use set_joint_mimic() for joints with matching dimensions. Mimic metadata is now stored per joint rather than as a separate constraint.

A mimic constraint enforces that joint0 = coef0 + coef1 * joint1, following URDF mimic joint semantics. Both scalar (prismatic, revolute) and multi-DOF joints are supported. For multi-DOF joints, the mimic behavior is applied equally to all degrees of freedom.

Parameters:

joint0 (int) – Index of the follower joint (the one being constrained)
joint1 (int) – Index of the leader joint (the one being mimicked)
coef0 (float) – Offset added after scaling
coef1 (float) – Scale factor applied to joint1’s position/angle
enabled (bool) – Whether constraint is active
label (str | None) – Optional constraint label
custom_attributes (dict[str, Any] | None) – Custom attributes to set on the constraint

Returns:

Constraint index

Return type:

int

add_custom_attribute(attribute)#

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

For attributes with custom string frequencies (not enum frequencies like BODY, SHAPE, etc.), the frequency must be registered first via add_custom_frequency(). This ensures explicit declaration of custom entity types and enables USD parsing support.

Parameters:: attribute (CustomAttribute) – The custom attribute to add.
Raises:: ValueError – If the attribute key already exists with incompatible specification, if the attribute uses a custom string frequency that hasn’t been registered, if the attribute uses a contact frequency (reserved for solver observables), or if usd_attribute_name is "*" without a usd_value_transformer.

Example

builder = newton.ModelBuilder()
builder.add_custom_attribute(
    newton.ModelBuilder.CustomAttribute(
        name="my_attribute",
        frequency=newton.Model.AttributeFrequency.BODY,
        dtype=wp.float32,
        default=20.0,
        assignment=newton.Model.AttributeAssignment.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 a Model.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_custom_frequency(frequency)#

Register a custom frequency for the builder.

Custom frequencies must be registered before assigning them to an attribute’s CustomAttribute.frequency field. This enables explicit declaration of custom entity types and optionally provides USD parsing support via the usd_prim_filter callback.

This method is idempotent: registering the same frequency multiple times is silently ignored (useful when loading multiple files that all register the same frequencies).

Parameters:: frequency (CustomFrequency) – A CustomFrequency object with full configuration.

Example

# Full registration with USD parsing support
builder.add_custom_frequency(
    ModelBuilder.CustomFrequency(
        name="actuator",
        namespace="mujoco",
        usd_prim_filter=is_actuator_prim,
    )
)

add_custom_values(**kwargs)#

Append values to custom attributes with custom string frequencies.

Each keyword argument specifies an attribute key and the value to append. Values are stored in a list and appended sequentially for robust indexing. Only works with attributes that have a custom string frequency (not built-in enum frequencies).

This is useful for custom entity types that aren’t built into the model, such as user-defined groupings or solver-specific data.

For each custom frequency touched by a call, attributes declared with references="world" are initialized from current_world when omitted or set to None. Explicit world values, including -1, are preserved.

Parameters:

**kwargs (Any) – Mapping of attribute keys to values. Keys should be the full attribute key (e.g., "mujoco:pair_geom1" or just "my_attr" if no namespace).

Returns:

A mapping from attribute keys to the index where each value was added. This includes inferred world-reference attributes. If all attributes had the same count before the call, all indices will be equal.

Raises:

AttributeError – If an attribute key is not defined.
TypeError – If an attribute has an enum frequency (must have custom frequency).

Return type:

dict[str, int]

Example

builder.add_custom_values(
    **{
        "mujoco:pair_geom1": 0,
        "mujoco:pair_geom2": 1,
    }
)
# Returns: {'mujoco:pair_geom1': 0, 'mujoco:pair_geom2': 0, 'mujoco:pair_world': 0}

add_custom_values_batch(entries)#

Append multiple custom-frequency rows in a single call.

Each row uses add_custom_values(), including automatic initialization of omitted world-reference attributes.

Parameters:: entries (Sequence[dict[str, Any]]) – Sequence of rows where each row maps custom attribute keys to values. Each row is forwarded to add_custom_values().
Returns:: Index maps returned by add_custom_values() for each row.
Return type:: list[dict[str, int]]

add_deformable_visual_mesh(vertices, indices, *, kind, parent=None, weights=None, tri_range=None, tet_range=None, surface=None, volume=None, curve=None, bodies=None, uvs=None, texture=None, label=None)#

Store a visual triangle mesh bound to particles, triangles, tetrahedra, or rigid bodies.

Each visual vertex follows the element selected by parent; vertices only records the bind pose. Triangle and tetrahedron bindings take the owning elements, named either by a recorded surface or volume deformable object or by a raw tri_range/tet_range, and barycentric weights that must be finite, nonnegative, and sum to one (accepted roundoff is normalized). Omit both parent and weights for automatic binding: a triangle binding projects each vertex onto the nearest non-degenerate owning triangle without keeping the normal offset, and a tetrahedron binding finds the containing non-degenerate owning tetrahedron, clamping an outside vertex into the one with the nearest centroid and logging the count. Body bindings follow one rigid body per vertex, named through parent or found by nearest center of mass among bodies or a recorded curve object’s bodies; the bind pose is kept as body-local offsets, so separate body bindings can show seams. Geometry adds no mass or collision. After finalization, evaluate it with DeformableVisuals.

Parameters:

vertices (list[list[float] | tuple[float, float, float] | vec3f] | ndarray) – Bind-pose visual positions [m], shape [vertex_count, 3].
indices (list[int] | ndarray) – Flattened triangle indices into vertices.
kind (Kind | str) – Particle, triangle, tetrahedron or body binding, as Kind or its lowercase name.
parent (list[int] | ndarray | None) – One global simulation element index per visual vertex, inside the owning elements for triangle and tetrahedron bindings. Omit it together with weights for automatic triangle or tetrahedron binding. Body bindings take this, bodies or curve.
weights (ndarray | None) – Three or four barycentric weights per vertex, for triangles or tetrahedra respectively; not accepted for particle bindings.
tri_range (tuple[int, int] | None) – Owning [start, end) triangle range for triangle bindings built without a deformable object record.
tet_range (tuple[int, int] | None) – Owning [start, end) tetrahedron range for tetrahedron bindings built without a deformable object record.
surface (int | None) – Index of a recorded surface deformable object (its position in surface_label) whose triangles own a triangle binding.
volume (int | None) – Index of a recorded volume deformable object (its position in volume_label) whose tetrahedra own a tetrahedron binding.
curve (int | None) – Index of a recorded curve deformable object (its position in curve_label) whose rigid bodies are the candidates of a nearest-body binding.
bodies (list[int] | ndarray | None) – Candidate rigid bodies, such as rod segments, for a nearest-center-of-mass binding; equal distances use candidate order.
uvs (list[list[float] | tuple[float, float] | vec2f] | ndarray | None) – Per-vertex texture coordinates, shape [vertex_count, 2].
texture (ndarray | str | PathLike[str] | None) – Albedo image as an array of shape (H, W, 3) or (H, W, 4), or an image path that the viewer decodes. Requires uvs.
label (str | None) – Display label, which need not be unique.

Returns:

Index in Model.deformable_visual_meshes.

Raises:

ValueError – If the geometry, kind, owning elements or bodies, parent indices, or weights are invalid.

Return type:

int

Experimental

Experimental feature. API, behavior, defaults, and supported use cases may change without prior notice.

add_edge(i, j, k, l, *, rest=None, edge_ke=None, edge_kd=None, custom_attributes=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
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

Returns:

The index of the edge.

Return type:

int

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, custom_attributes=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 (list[int]) – The indices of the first particles, i.e., opposite vertex 0
j (list[int]) – The indices of the second particles, i.e., opposite vertex 1
k (list[int]) – The indices of the third particles, i.e., vertex 0
l (list[int]) – The indices of the fourth particles, 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 coefficients
edge_kd (list[float] | None) – The bending damping coefficients
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

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_ground_plane(*, height=0.0, cfg=None, color=_DEFAULT_GROUND_PLANE_COLOR, opacity=None, label=None)#

Adds a ground plane collision shape to the model.

Parameters:

height (float) – The vertical offset of the ground plane along the up-vector axis. Positive values raise the plane, negative values lower it. Defaults to 0.0.
cfg (ShapeConfig | None) – The configuration for the shape’s physical and collision properties. If None, default_shape_cfg is used. Defaults to None.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. Defaults to the ground plane color (0.125, 0.125, 0.15). Pass None to use the per-shape palette color instead.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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, label=None, parent_xform=None, child_xform=None, collision_filter_parent=None, 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] | None) – The linear axes (see JointDofConfig) of the joint, defined in the joint parent anchor frame.
angular_axes (list[JointDofConfig] | None) – The angular axes (see JointDofConfig) of the joint, defined in the joint parent anchor frame.
label (str | None) – The label of the joint (optional).
parent_xform (Transform | None) – The transform from the parent body frame to the joint parent anchor frame. If None, the identity transform is used.
child_xform (Transform | None) – The transform from the child body frame to the joint child anchor frame. If None, the identity transform is used.
collision_filter_parent (bool | None) – Whether to filter collisions between shapes of the parent and child bodies. Defaults to False for non-fixed joints to world, True otherwise.
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 Model.AttributeFrequency.JOINT_DOF or Model.AttributeFrequency.JOINT_COORD can be provided as: (1) lists with length equal to the joint’s DOF or coordinate count, (2) dicts mapping DOF/coordinate indices to values, or (3) a single scalar value that is broadcast to all DOFs/coordinates of the joint. For joints with zero DOFs (e.g., fixed joints), JOINT_DOF attributes are silently skipped. Custom attributes with frequency Model.AttributeFrequency.JOINT require a single value to be defined.

Returns:

The index of the added joint.

Return type:

int

Note

Avoid creating several joints between the same pair of bodies, as this is ambiguous and may be handled differently by different solvers. Bodies created with add_body() are implicitly connected to the world by a free joint. To connect a body to the world with a different joint type, use add_link() instead.

add_joint_ball(parent, child, *, parent_xform=None, child_xform=None, armature=None, friction=None, damping=None, stiffness=None, actuator_mode=None, label=None, collision_filter_parent=None, 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 (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform from the parent body frame to the joint parent anchor frame.
child_xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform from the child body frame to the joint child anchor frame.
armature (float | None) – Artificial inertia added around the joint axes. If None, the default value from ModelBuilder.default_joint_cfg.armature is used.
friction (float | None) – Friction coefficient for the joint axes. If None, the default value from ModelBuilder.default_joint_cfg.friction is used.
damping (float | None) – Passive angular velocity damping [N·s/m or N·m·s/rad, depending on joint type] always active on all three BALL joint angular DOFs. If None, the default value from ModelBuilder.default_joint_cfg.damping is used.
stiffness (float | None) – Isotropic passive angular spring stiffness [N·m/rad], supported by SolverMuJoCo. If None, the default value from ModelBuilder.default_joint_cfg.stiffness is used.
actuator_mode (JointTargetMode | None) – The actuator mode for this joint’s DOFs. If None, defaults to NONE.
label (str | None) – The label of the joint.
collision_filter_parent (bool | None) – Whether to filter collisions between shapes of the parent and child bodies. Defaults to False for joints to world, True otherwise.
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

The spring rest orientation defaults to the identity quaternion. After adding the joint, set its four joint_rest_q entries in xyzw order using builder.joint_rest_q[builder.joint_q_start[joint]:builder.joint_q_start[joint] + 4]. The scalar default_joint_cfg.rest_q does not apply to ball joints. To edit the rest orientation after finalization, update Model.joint_rest_q and notify the solver with ModelFlags.JOINT_DOF_PROPERTIES.

Note

Target position and velocity control for ball joints is currently only supported in newton.solvers.SolverMuJoCo.

add_joint_d6(parent, child, *, linear_axes=None, angular_axes=None, label=None, parent_xform=None, child_xform=None, collision_filter_parent=None, 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.
label (str | None) – The label of the joint.
parent_xform (Transform | None) – The transform from the parent body frame to the joint parent anchor frame.
child_xform (Transform | None) – The transform from the child body frame to the joint child anchor frame.
armature – Artificial inertia added around the joint axes. If None, the default value from ModelBuilder.default_joint_cfg.armature is used.
collision_filter_parent (bool | None) – Whether to filter collisions between shapes of the parent and child bodies. Defaults to False for joints to world, True otherwise.
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=None, enabled=True, custom_attributes=None, label=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 (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform of the joint in the parent body’s local frame.
child_xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – 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 | None) – Whether to filter collisions between shapes of the parent and child bodies. Defaults to False for joints to world, True otherwise.
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.
label (str | None) – The label of the joint.

Returns:

The index of the added joint.

Return type:

int

Note

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

add_joint_fixed(parent, child, *, parent_xform=None, child_xform=None, label=None, collision_filter_parent=None, 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 (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform of the joint in the parent body’s local frame.
child_xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform of the joint in the child body’s local frame.
label (str | None) – The label of the joint.
collision_filter_parent (bool | None) – Whether to filter collisions between shapes of the parent and child bodies. Defaults to True.
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, label=None, collision_filter_parent=None, 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 so that forward kinematics reproduces the child body’s transform, accounting for the parent body and both joint anchor transforms (see body_q and the xform argument to add_body()).

Parameters:

child (int) – The index of the child body.
parent_xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform of the joint in the parent body’s local frame.
child_xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – 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).
label (str | None) – The label of the joint.
collision_filter_parent (bool | None) – Whether to filter collisions between shapes of the parent and child bodies. Defaults to False for joints to world, True otherwise.
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_q=None, target_qd=None, target_ke=None, target_kd=None, damping=None, stiffness=None, rest_q=None, limit_lower=None, limit_upper=None, limit_ke=None, limit_kd=None, armature=None, effort_limit=None, velocity_limit=None, friction=None, actuator_mode=None, target_pos=None, target_vel=None, label=None, collision_filter_parent=None, 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 | None) – The transform from the parent body frame to the joint parent anchor frame.
child_xform (Transform | None) – The transform from the child body frame to the joint child anchor frame.
axis (AxisType | Vec3 | JointDofConfig) – The axis of translation in the joint parent anchor frame, which is the parent body’s local frame transformed by parent_xform. It can be a JointDofConfig object whose settings will be used instead of the other arguments.
target_q (float | None) – The target position of the joint. If None, the default value from ModelBuilder.default_joint_cfg.target_q is used.
target_qd (float | None) – The target velocity of the joint. If None, the default value from ModelBuilder.default_joint_cfg.target_qd is used.
target_ke (float | None) – The stiffness of the joint target.
target_kd (float | None) – The damping of the joint target.
damping (float | None) – Passive velocity damping [N·s/m or N·m·s/rad, depending on joint type] always active on the joint. If None, the default value from ModelBuilder.default_joint_cfg.damping is used.
stiffness (float | None) – Passive spring stiffness [N/m]. If None, the default value from ModelBuilder.default_joint_cfg.stiffness is used.
rest_q (float | None) – Spring rest coordinate [m], which may lie outside joint limits. If None, the default value from ModelBuilder.default_joint_cfg.rest_q is used.
limit_lower (float | None) – The lower limit of the joint. If None, the default value from ModelBuilder.default_joint_cfg.limit_lower is used.
limit_upper (float | None) – The upper limit of the joint. If None, the default value from ModelBuilder.default_joint_cfg.limit_upper is used.
limit_ke (float | None) – The stiffness of the joint limit. If None, the default value from ModelBuilder.default_joint_cfg.limit_ke is used.
limit_kd (float | None) – The damping of the joint limit. If None, the default value from ModelBuilder.default_joint_cfg.limit_kd is used.
armature (float | None) – Artificial inertia added around the joint axis. If None, the default value from ModelBuilder.default_joint_cfg.armature is used.
effort_limit (float | None) – Maximum effort (force) the joint axis can exert. If None, the default value from ModelBuilder.default_joint_cfg.effort_limit is used.
velocity_limit (float | None) – Maximum velocity the joint axis can achieve. If None, the default value from ModelBuilder.default_joint_cfg.velocity_limit is used.
friction (float | None) – Friction coefficient for the joint axis. If None, the default value from ModelBuilder.default_joint_cfg.friction is used.
actuator_mode (JointTargetMode | None) – The actuator mode for the joint axis. If None, the default value from ModelBuilder.default_joint_cfg.actuator_mode is used.
target_pos (float | None) – Deprecated since 1.8; use target_q.
target_vel (float | None) – Deprecated since 1.8; use target_qd.
label (str | None) – The label of the joint.
collision_filter_parent (bool | None) – Whether to filter collisions between shapes of the parent and child bodies. Defaults to False for joints to world, True otherwise.
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_q=None, target_qd=None, target_ke=None, target_kd=None, damping=None, stiffness=None, rest_q=None, limit_lower=None, limit_upper=None, limit_ke=None, limit_kd=None, armature=None, effort_limit=None, velocity_limit=None, friction=None, actuator_mode=None, target_pos=None, target_vel=None, label=None, collision_filter_parent=None, 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 | None) – The transform from the parent body frame to the joint parent anchor frame.
child_xform (Transform | None) – The transform from the child body frame to the joint child anchor frame.
axis (AxisType | Vec3 | JointDofConfig | None) – The axis of rotation in the joint parent anchor frame, which is the parent body’s local frame transformed by parent_xform. It can be a JointDofConfig object whose settings will be used instead of the other arguments.
target_q (float | None) – The target position of the joint. If None, the default value from ModelBuilder.default_joint_cfg.target_q is used.
target_qd (float | None) – The target velocity of the joint. If None, the default value from ModelBuilder.default_joint_cfg.target_qd is used.
target_ke (float | None) – The stiffness of the joint target.
target_kd (float | None) – The damping of the joint target.
damping (float | None) – Passive velocity damping [N·s/m or N·m·s/rad, depending on joint type] always active on the joint. If None, the default value from ModelBuilder.default_joint_cfg.damping is used.
stiffness (float | None) – Passive spring stiffness [N·m/rad]. If None, the default value from ModelBuilder.default_joint_cfg.stiffness is used.
rest_q (float | None) – Spring rest coordinate [rad], which may lie outside joint limits. If None, the default value from ModelBuilder.default_joint_cfg.rest_q is used.
limit_lower (float | None) – The lower limit of the joint. If None, the default value from ModelBuilder.default_joint_cfg.limit_lower is used.
limit_upper (float | None) – The upper limit of the joint. If None, the default value from ModelBuilder.default_joint_cfg.limit_upper is used.
limit_ke (float | None) – The stiffness of the joint limit. If None, the default value from ModelBuilder.default_joint_cfg.limit_ke is used.
limit_kd (float | None) – The damping of the joint limit. If None, the default value from ModelBuilder.default_joint_cfg.limit_kd is used.
armature (float | None) – Artificial inertia added around the joint axis. If None, the default value from ModelBuilder.default_joint_cfg.armature is used.
effort_limit (float | None) – Maximum effort (force/torque) the joint axis can exert. If None, the default value from ModelBuilder.default_joint_cfg.effort_limit is used.
velocity_limit (float | None) – Maximum velocity the joint axis can achieve. If None, the default value from ModelBuilder.default_joint_cfg.velocity_limit is used.
friction (float | None) – Friction coefficient for the joint axis. If None, the default value from ModelBuilder.default_joint_cfg.friction is used.
actuator_mode (JointTargetMode | None) – The actuator mode for the joint axis. If None, the default value from ModelBuilder.default_joint_cfg.actuator_mode is used.
target_pos (float | None) – Deprecated since 1.8; use target_q.
target_vel (float | None) – Deprecated since 1.8; use target_qd.
label (str | None) – The label of the joint.
collision_filter_parent (bool | None) – Whether to filter collisions between shapes of the parent and child bodies. Defaults to False for joints to world, True otherwise.
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_rod(parent, child, *, parent_xform=None, child_xform=None, rest_rotation=None, stretch_stiffness=None, stretch_damping=None, shear_stiffness=None, shear_damping=None, bend_stiffness=None, bend_damping=None, twist_stiffness=None, twist_damping=None, label=None, collision_filter_parent=None, enabled=True, custom_attributes=None, **kwargs)#

Adds a rod joint to the model.

Its kinematic state uses a 7-coordinate relative pose in joint_q and a 6-DoF relative twist in joint_qd. See Rod joints for structural-rest conventions.

Rod joints have split linear stretch/shear material response plus separate angular bend and twist response. When both shear_stiffness and shear_damping are omitted, shear uses the stretch stiffness / damping, reproducing the isotropic linear energy while using the split layout. When both twist_stiffness and twist_damping are omitted, twist uses the bend stiffness / damping, reproducing the isotropic angular energy while using the split layout.

Note

Rod joints are supported by newton.solvers.SolverVBD. Their six canonical axes represent four material responses: stretch, shear, bend, and twist. Rod body transforms are integrated directly by newton.solvers.SolverVBD, while newton.eval_fk() can reconstruct them from joint_q and joint_qd.

Rod joints use each anchor frame’s local +Z as the corresponding segment’s material tangent axis for separating axial stretch from shear and twist from bend. At structural rest, the transformed parent and child anchor points coincide. add_rod() satisfies both conventions automatically.

Parameters:

parent (int) – The index of the parent body.
child (int) – The index of the child body.
parent_xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform from the parent body frame to the joint parent anchor frame; its translation is the attachment point and its local +Z axis is the parent-side material tangent.
child_xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform from the child body frame to the joint child anchor frame; its translation is the attachment point and its local +Z axis is the child-side material tangent.
rest_rotation (list[float] | tuple[float, float, float, float] | quatf | None) – Child anchor rotation relative to the parent anchor at structural rest [unitless quaternion], stored in joint_rest_q. If None, it uses the initial relative anchor rotation at creation.
stretch_stiffness (float | None) – Rod stretch stiffness (stored as target_ke) [N/m]. If None, defaults to 1.0e5.
stretch_damping (float | None) – Rod stretch damping [N·s/m] (stored as target_kd). If None, defaults to 0.0.
shear_stiffness (float | None) – Optional transverse shear stiffness [N/m]. If None, defaults to stretch_stiffness.
shear_damping (float | None) – Optional transverse shear damping [N·s/m]. If None, defaults to stretch_damping only when both shear_stiffness and shear_damping are None. Otherwise defaults to 0.0.
bend_stiffness (float | None) – Rod bend stiffness (stored as target_ke) [N·m/rad]. If None, defaults to 0.0.
bend_damping (float | None) – Rod bend damping [N·m·s/rad] (stored as target_kd). If None, defaults to 0.0.
twist_stiffness (float | None) – Optional twist stiffness [N·m/rad]. If None, defaults to bend_stiffness.
twist_damping (float | None) – Optional twist damping [N·m·s/rad]. If None, defaults to bend_damping only when both twist_stiffness and twist_damping are None. Otherwise defaults to 0.0.
label (str | None) – The label of the joint.
collision_filter_parent (bool | None) – Whether to filter collisions between shapes of the parent and child bodies. Defaults to False for joints to world, True otherwise.
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.

Raises:

ValueError – If rest_rotation contains non-finite values or has zero norm, or if any material stiffness is negative.

Return type:

int

add_link(*, xform=None, com=None, inertia=None, mass=0.0, label=None, lock_inertia=False, is_kinematic=False, custom_attributes=None)#

Adds a link (rigid body) to the model within an articulation.

This method creates a link without automatically adding a joint. To connect this link to the articulation structure, you must explicitly call one of the joint methods (e.g., add_joint_revolute(), add_joint_fixed(), etc.) after creating the link.

After calling this method and one of the joint methods, ensure that an articulation is created using add_articulation().

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.
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.
inertia (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.
label (str | None) – Label of the body (optional).
lock_inertia (bool) – If True, prevents subsequent shape additions from modifying this body’s mass, center of mass, or inertia. This does not affect merging behavior in collapse_fixed_joints(), which always accumulates mass and inertia across merged bodies.
is_kinematic (bool) – If True, the body is kinematic and does not respond to forces. Only root bodies (bodies whose joint parent is -1) may be kinematic.
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

add_mjcf(source, *, xform=None, floating=None, base_joint=None, parent_body=-1, armature_scale=1.0, scale=1.0, hide_visuals=False, parse_visuals_as_colliders=False, parse_meshes=True, parse_sites=True, parse_visuals=True, parse_mujoco_options=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=True, ignore_inertial_definitions=False, collapse_fixed_joints=False, collapse_massless_fixed_root=False, verbose=False, skip_equality_constraints=False, convert_mjc_equality_constraints=True, convert_3d_hinge_to_ball_joints=False, mesh_maxhullvert=None, ctrl_direct=False, path_resolver=None, override_root_xform=False, legacy_margin_gap=False)#

Parses MuJoCo XML (MJCF) file and adds the bodies and joints to the given ModelBuilder. MuJoCo-specific custom attributes are registered on the builder automatically. Importing <dcmotor> actuators requires the optional mujoco package (included in newton[sim]) to resolve native defaults, and raises ImportError if it is unavailable. Other MJCF import remains independent of MuJoCo.

Geom material defaults and RGBA are preserved. Meshes also retain base-color textures (the texture attribute or rgb/rgba layers) and non-negative roughness and metallic values. Texture paths are retained for lazy loading by renderers. RGB bindings take precedence over RGBA bindings, including inherited defaults. MJCF textures default to a white tint. Without an MJCF color or base-color texture, mesh-file appearance and primitive palette colors are retained for compatibility. Other PBR texture layers are not imported.

Parameters:

source (str) – The filename of the MuJoCo file to parse, or the MJCF XML string content.
xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform to apply to the imported mechanism. If parent_body is set, imported bodies are placed relative to that body’s frame; static shapes still use xform in the world frame.
override_root_xform (bool) – If True, the articulation root’s world-space transform is replaced by xform instead of being composed with it, preserving only the internal structure (relative body positions). Useful for cloning articulations at explicit positions. Not intended for sources containing multiple articulations, as all roots would be placed at the same xform. Defaults to False.
floating (bool | None) –
Controls the base joint type for the root body.
- None (default): Uses format-specific default (honors <freejoint> tags in MJCF, otherwise creates a FIXED joint).
- True: Creates a FREE joint with 6 DOF (3 translation + 3 rotation). Only valid when parent_body == -1 since FREE joints must connect to world frame.
- False: Creates a FIXED joint (0 DOF).
Cannot be specified together with base_joint.
base_joint (dict | None) –
Custom joint specification for connecting the root body to the world (or to parent_body if specified). This parameter enables hierarchical composition with custom mobility. Dictionary with joint parameters as accepted by ModelBuilder.add_joint() (e.g., joint type, axes, limits, stiffness).

Cannot be specified together with floating.

parent_body (int) –

Parent body index for hierarchical composition. If specified, attaches the imported root body to this existing body, making them part of the same kinematic articulation. The connection type is determined by floating or base_joint. If -1 (default), the root connects to the world frame. Restriction: Only the most recently added articulation can be used as parent; attempting to attach to an older articulation will raise a ValueError.

Note

Valid combinations of floating, base_joint, and parent_body:

floating	base_joint	parent_body	Result
`None`	`None`	`-1`	Format default (MJCF: honors `<freejoint>`, else FIXED)
`True`	`None`	`-1`	FREE joint to world (6 DOF)
`False`	`None`	`-1`	FIXED joint to world (0 DOF)
`None`	`{dict}`	`-1`	Custom joint to world (e.g., D6)
`False`	`None`	`body_idx`	FIXED joint to parent body
`None`	`{dict}`	`body_idx`	Custom joint to parent body (e.g., D6)
explicitly set	explicitly set	any	❌ Error: mutually exclusive (cannot specify both)
`True`	`None`	`body_idx`	❌ Error: FREE joints require world frame

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.
parse_mujoco_options (bool) – Whether solver options from the MJCF <option> tag should be parsed. If False, solver options are not loaded and custom attributes retain their default values. Default is True.
up_axis (Axis | Literal['X', 'Y', 'Z'] | ~typing.Literal[0, 1, 2] | int | str) – 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. Collider planes in MJCF groups 0-2 remain visible even when this is False.
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.
collapse_fixed_joints (bool) – If True, fixed joints are removed and the respective bodies are merged.
collapse_massless_fixed_root (bool) – If True, collapse only the massless fixed-joint chain below an imported free root body. Ignored when collapse_fixed_joints is True.
verbose (bool) – If True, log additional information about parsing the MJCF.
skip_equality_constraints (bool) – Whether <equality> tags should be parsed. If True, equality constraints are ignored.
convert_mjc_equality_constraints (bool) – Whether MuJoCo equality constraints should be converted to Newton loop joints or mimic constraints while preserving MuJoCo equality metadata for SolverMuJoCo. A weld becomes a FIXED loop joint, or a BALL loop joint when its torquescale is 0 (see “Link-break welds and MuJoCo welds” in the articulation docs). If False, equality constraints are preserved in the mujoco:equality_constraint custom-attribute namespace and finalize under model.mujoco.equality_constraint_*. Joint equalities that omit joint2 or target a multi-DoF joint (such as joints sharing a body) are preserved this way even when True, with a NewtonWarning; only SolverMuJoCo enforces them.
convert_3d_hinge_to_ball_joints (bool) – If True, series of three hinge joints are converted to a single ball joint. Nonzero scalar spring rest coordinates cannot be preserved by this conversion; it warns and uses an identity rest orientation. Default is False.
mesh_maxhullvert (int | None) – Maximum vertices for convex hull approximation of meshes.
ctrl_direct (bool) – If True, all actuators use CTRL_DIRECT mode where control comes directly from control.mujoco.ctrl (MuJoCo-native behavior). See Custom Attributes for details on custom attributes. If False (default), position/velocity actuators use JOINT_TARGET mode where control comes from newton.Control.joint_target_q and newton.Control.joint_target_qd. A scalar gear on a one-DOF (hinge or slide) position/velocity actuator is folded into the joint-target drive, so the targets stay in joint units: the actuator is imported with unit gear, kp, kv, damping and armature are scaled by gear**2, forcerange by gear and ctrlrange by 1 / gear (bounds swapped for a negative gear). Position/velocity actuators whose gear cannot be folded (a gear on a multi-DOF joint, a vector gear or a zero gear) are imported as CTRL_DIRECT so that MuJoCo applies the gear. For position-only joint-target drives using dampratio, constructing SolverMuJoCo initializes zero entries in newton.Model.joint_target_kd with the resolved damping coefficients. Subsequent damping edits use joint_target_kd as usual. This does not apply to CTRL_DIRECT actuators: their gains stay in the MuJoCo actuator (in actuator units), and joint_target_kd is neither written nor read for them.
path_resolver (Callable[[str | None, str], str] | None) – Callback to resolve file paths. Takes (base_dir, file_path) and returns a resolved path. For <include> elements, can return either a file path or XML content directly. For asset elements (mesh, texture, etc.), must return an absolute file path. By default, assets are searched relative to the main model with the compiler asset directory, then relative to the included file without that directory prefix, and finally relative to the included file with it. Custom resolvers receive the authoring file’s directory and the file path with that file’s compiler asset directory prefix.
legacy_margin_gap (bool) – If True, restore pre-MuJoCo-3.9 import behavior where shape_margin is computed as mj_margin - mj_gap. Use for MJCF files authored against MuJoCo <= 3.8. Defaults to False (identity translation matching MuJoCo 3.9 semantics).

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

Adds a legacy muscle-tendon activation unit.

Deprecated since version 1.9: Legacy muscles will be removed in a future release. Only SolverSemiImplicit evaluates them, and it ignores the muscle parameters, applying a force of magnitude Control.muscle_activations along each waypoint segment. Use SolverMuJoCo muscle actuators instead, either imported from MJCF <muscle> actuators or built in code: route a spatial tendon through sites on the waypoint bodies with newton.solvers.mujoco.add_tendon_spatial(), then actuate it with newton.solvers.mujoco.add_actuator_general() using ActuatorTarget.tendon() and dyntype, gaintype and biastype set to "muscle". Pass explicit muscle parameters, since MuJoCo rejects the generic defaults of add_actuator_general() for muscles. MuJoCo’s <muscle> defaults are dynprm=(0.01, 0.04) and gainprm = biasprm = (0.75, 1.05, -1.0, 200.0, 0.5, 1.6, 1.5, 1.3, 1.2), which hold range, force, scale, lmin, lmax, vmax, fpmax and fvmax. A negative force derives the peak force from scale.

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
pen (float) – Penalty factor

Returns:

The index of the muscle in the model

Return type:

int

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

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 newton.ParticleFlags.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

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, custom_attributes=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 (list[float] | tuple[float, float, float] | vec3f) – The world-space position of the grid origin.
rot (list[float] | tuple[float, float, float, float] | quatf) – The rotation to apply to the grid (as a quaternion).
vel (list[float] | tuple[float, float, float] | vec3f) – 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 | None) – Mean radius for particles. If None, uses the builder’s default.
radius_std (float) – Standard deviation for particle radii. If > 0, radii are sampled from a normal distribution.
flags (list[int] | int | None) – Flags to assign to each particle. If None, uses the builder’s default.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values for the particles.

Returns:

Nothing. The builder is updated in place.

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

Adds a group of particles to the model.

Parameters:

pos (list[list[float] | tuple[float, float, float] | vec3f]) – The initial positions of the particles.
vel (list[list[float] | tuple[float, float, float] | vec3f]) – The initial velocities of the particles.
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[int] | None) – The flags that control the dynamical behavior of the particles, see newton.ParticleFlags.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to lists of values (one value for each particle).

Note

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

Raises:: ValueError – If a particle input or custom attribute list has a mismatched length.

add_rod(*, rod, cfg=None, total_mass=None, stretch_stiffness=None, stretch_damping=None, shear_stiffness=None, shear_damping=None, bend_stiffness=None, bend_damping=None, twist_stiffness=None, twist_damping=None, label=None, wrap_in_articulation=True, color=None, body_frame_origin='com', junction_collision_filter=True)#

Adds a rod composed of capsule bodies connected by rod joints.

Uses the geometry, frames, topology, and optional constitutive data stored on a newton.Rod, which may represent an ordered chain or an explicit graph.

The remaining arguments configure assembly. Each segment becomes a capsule body, and incident segments are connected by rod joints with a relative pose and twist plus stretch, shear, bend, and twist response.

Supplied initial and rest frames must align local +Z with their segment tangent (dot product at least 0.999). Accepted frames are normalized and minimally rotated to align while preserving roll.

Parameters:

rod (Rod) – Initial/rest geometry, frame, topology, and constitutive-data source.
cfg (ShapeConfig | None) – Shape configuration for the capsules. If None, default_shape_cfg is used.
total_mass (float | None) – Optional total rod mass [kg], distributed in proportion to each segment’s rest volume (equivalently, rest length for the uniform cross section). Overrides cfg.density. Must be finite and nonnegative; zero sets every segment’s mass and inertia to zero without setting the kinematic body flag. If None, mass is derived from density.
stretch_stiffness (float | None) – Per-joint rod stretch stiffness, stored directly as target_ke [N/m]. If None, it is derived locally from Rod material or section rigidity; otherwise it defaults to 1.0e5.
stretch_damping (float | None) – Stretch damping [N·s/m] for the rod joints (applied per-joint; not length-normalized). If None, defaults to 0.0.
shear_stiffness (float | None) – Optional per-joint transverse shear stiffness [N/m]. If None, defaults to the locally derived Rod shear stiffness, or to stretch_stiffness otherwise.
shear_damping (float | None) – Optional per-joint transverse shear damping [N·s/m]. If None, defaults to stretch_damping only when both shear_stiffness and shear_damping are None. Otherwise defaults to 0.0.
bend_stiffness (float | None) – Per-joint rod bend stiffness, stored directly as target_ke [N·m/rad]. If None, it is derived locally from Rod material or section rigidity; otherwise it defaults to 0.0.
bend_damping (float | None) – Bend damping [N·m·s/rad] for the rod joints (applied per-joint; not length-normalized). If None, defaults to 0.0.
twist_stiffness (float | None) – Optional per-joint rod twist stiffness [N·m/rad]. If None, defaults to the locally derived Rod twist stiffness, or to bend_stiffness otherwise.
twist_damping (float | None) – Optional per-joint rod twist damping [N·m·s/rad]. If None, defaults to bend_damping only when both twist_stiffness and twist_damping are None. Otherwise defaults to 0.0.
label (str | None) – Optional label prefix for bodies, shapes, joints, and articulations. The same name is appended to curve_label for this rod; if None, a generated curve_N label is used. See Deformable Objects. Generated joint labels retain the historical {label}_cable_{n} form for compatibility.
wrap_in_articulation (bool) – Whether Newton automatically creates articulations for the generated tree joints. Defaults to True. See the Articulations section below.
color (Vec3 | None) – Optional display RGB color with values in [0, 1] applied to all generated capsule shapes. If None, the rod uses the default rod color.
body_frame_origin (Literal['start', 'com']) –
Body-frame placement for each generated capsule. "start" places the origin at the local start of the rest-sized capsule, with the COM/shape offset by half its rest length. The world-space origin equals the initial segment start only when initial and rest lengths match. "com" places the body origin at the initial segment midpoint so the body origin and COM coincide. Defaults to "com".

Deprecated since version 1.8: "start" emits a NewtonDeprecationWarning. Use "com" instead. For manually authored body-local anchors, subtract the old body_com offset.
junction_collision_filter (bool) – Whether to suppress self-collisions between incident, non-jointed segments at graph junctions. Has no effect for an ordered chain.

Returns:

A pair (body_indices, joint_indices). Bodies follow segment order. An open ordered chain has one fewer joint than segments; a closed ordered chain has one joint per segment. Graph joint count depends on topology and articulation wrapping. Automatically generated root joints are not included in joint_indices.

Return type:

tuple[list[int], list[int]]

Articulations:: With wrap_in_articulation=True (the default), Newton creates a free joint to the world and places it with an ordered chain’s non-closure joints in one articulation. A closed chain’s loop-closing joint remains outside it. For an explicit graph, Newton creates one free-rooted, articulation-safe spanning tree per connected component; cyclic adjacency joints are omitted. With wrap_in_articulation=False, Newton creates no root joints or articulations. Before finalize, callers must place the tree or forest joints in articulations. Loop-closing joints whose child is already reachable through those articulations may remain outside them.

Raises:

TypeError – If rod is not a newton.Rod.
ValueError – If initial/rest positions or frames have incompatible lengths, non-finite or too-short edges, or invalid frame alignment.
ValueError – If the structural-rest centerline of a closed chain does not close.
ValueError – If the Rod uses rest_straight with explicit rest inputs or a graph.
ValueError – If body_frame_origin is not "start" or "com".
ValueError – If total_mass is negative or non-finite.
ValueError – If a hollow rod with positive assigned mass has a negative or non-finite wall thickness cfg.margin, or one at least as large as the stored radius. A positive total_mass also requires nonzero hollow wall thickness.
ValueError – If automatic section-rigidity discretization is requested for branching topology or for a wrapped explicit cycle.

Note

Bend defaults are 0.0 (no bending resistance unless specified). Stretch defaults to 1.0e5; pass a larger value when neighboring capsules should remain nearly inextensible.
Direct stiffness and damping values are applied unchanged to every generated joint.
For a material- or section-rigidity-defined newton.Rod, stiffness is derived per generated joint as R / L_dual, where R is the corresponding section rigidity and L_dual is the mean rest length of the two adjacent segments. Explicit stiffness arguments override the derived value per mode.
Each segment is implemented as a capsule primitive. half_height is the half-length of the cylindrical centerline, excluding the hemispherical caps.
Density-based mass is cfg.density * area * rest_length per segment, excluding the overlapping caps. area is the circular cross section pi * radius**2, as in USD cable import, or for hollow rods the tube wall of thickness cfg.margin.
Inertia uses the solid-cylinder or open-tube tensor at each segment’s assigned mass and rest length, as in USD cable import for solid sections. Collision geometry and the caller’s cfg are unchanged.
With body_frame_origin="start", the body origin is at the local start of the rest-sized capsule centerline. The COM and shape are at local (0, 0, half_height), and the other centerline endpoint is at (0, 0, 2 * half_height). These offsets use rest lengths; the world-space body origin equals the initial segment start only when the initial and rest lengths match.
With body_frame_origin="com", the body origin and COM coincide at the segment midpoint, and centerline endpoints are at local (0, 0, -half_height) and (0, 0, half_height).

add_shape(*, body, type, xform=None, cfg=None, scale=None, src=None, is_static=False, color=None, opacity=None, label=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. Negative components are accepted and silently absorbed via abs() for symmetric primitives (sphere, box, capsule, cylinder, ellipsoid, plane, gaussian) since these shapes are point-symmetric. Mesh-class shapes (MESH, CONVEX_MESH, SDF, hydroelastic) preserve the sign and treat det(scale) < 0 as a mirror; the same Mesh instance can be shared across shapes with different signed scales. Cone and heightfield shapes raise ValueError on negative components.
src (Mesh | Gaussian | Heightfield | Any | None) – The source geometry data, e.g., a Mesh object for GeoType.MESH. 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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, mesh-backed shapes fall back to color; otherwise the per-shape palette sequence is used.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity. Mesh-backed shapes fall back to opacity.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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, color=None, opacity=None, label=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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, uses the per-shape palette color.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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, color=None, opacity=None, label=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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, uses the per-shape palette color.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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_collision_filter_pair(shape_a, shape_b)#

Add a collision filter pair in canonical order.

Parameters:

shape_a (int) – First shape index
shape_b (int) – Second shape index

add_shape_cone(body, *, xform=None, radius=1.0, half_height=0.5, cfg=None, as_site=False, color=None, opacity=None, label=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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, uses the per-shape palette color.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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, color=None, opacity=None, label=None, custom_attributes=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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, falls back to color when available.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, falls back to opacity when available.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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_cylinder(body, *, xform=None, radius=1.0, half_height=0.5, barrel_radius=0.0, cfg=None, as_site=False, color=None, opacity=None, label=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 at its ends [m]. Defaults to 1.0.
half_height (float) – The half-length of the cylinder along the Z-axis [m]. Defaults to 0.5.
barrel_radius (float) – The radius of the symmetric circular arc revolved around the Z-axis to form the cylinder’s side [m]. Use 0.0 for a straight-sided cylinder. Nonzero values must be at least half_height. Defaults to 0.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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, uses the per-shape palette color.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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_ellipsoid(body, *, xform=None, rx=1.0, ry=0.75, rz=0.5, cfg=None, as_site=False, color=None, opacity=None, label=None, custom_attributes=None)#

Adds an ellipsoid collision shape or site to a body.

The ellipsoid is centered at its local origin as defined by xform, with semi-axes rx, ry, rz along the local X, Y, Z axes respectively.

Note

Ellipsoid collision is handled by the GJK/MPR collision pipeline, which provides accurate collision detection for all convex shape pairs.

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 ellipsoid in the parent body’s local frame. If None, the identity transform wp.transform() is used. Defaults to None.
rx (float) – The semi-axis of the ellipsoid along its local X-axis [m]. Defaults to 1.0.
ry (float) – The semi-axis of the ellipsoid along its local Y-axis [m]. Defaults to 0.75.
rz (float) – The semi-axis of the ellipsoid along its local Z-axis [m]. 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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, uses the per-shape palette color.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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

Example

Create an ellipsoid with different semi-axes:

builder = newton.ModelBuilder()
body = builder.add_body()

# Add an ellipsoid with semi-axes 1.0, 0.5, 0.25
builder.add_shape_ellipsoid(
    body=body,
    rx=1.0,  # X semi-axis
    ry=0.5,  # Y semi-axis
    rz=0.25,  # Z semi-axis
)

# A sphere is a special case where rx = ry = rz
builder.add_shape_ellipsoid(body=body, rx=0.5, ry=0.5, rz=0.5)

add_shape_gaussian(body, *, xform=None, gaussian=None, scale=None, cfg=None, collision_proxy=None, color=None, opacity=None, label=None, custom_attributes=None)#

Adds a Gaussian splat shape to a body.

The Gaussian is attached as a GeoType.GAUSSIAN shape for rendering. Collision is handled separately via collision_proxy.

Parameters:

body (int) – The index of the parent body this shape belongs to. Use -1 for static world geometry.
xform (Transform | None) – Transform in parent body’s local frame. Defaults to identity.
gaussian (Gaussian | None) – The Gaussian splat asset.
scale (Vec3 | None) – 3D scale applied to Gaussian positions. Defaults to (1, 1, 1).
cfg (ShapeConfig | None) – Shape configuration. If None, uses default_shape_cfg with has_shape_collision=False (Gaussians are render-only by default).
collision_proxy (str | Mesh | None) –
Collision strategy. Options:
- None: no collision (render-only).
- "convex_hull": auto-generate convex hull from Gaussian positions.
- A Mesh instance: use the provided mesh as collision proxy.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, uses the per-shape palette color.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity.
label (str | None) – Optional unique label for identifying the shape.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute values for SHAPE frequency attributes.

Returns:

The index of the Gaussian shape.

Return type:

int

add_shape_heightfield(*, xform=None, heightfield=None, scale=None, cfg=None, color=None, opacity=None, label=None, custom_attributes=None)#

Adds a heightfield (2D elevation grid) collision shape to the model.

Heightfields are efficient representations of terrain using a 2D grid of elevation values. They are always static (body=-1) and more memory-efficient than equivalent triangle meshes.

Parameters:

xform (Transform | None) – The transform of the heightfield in world frame. If None, the identity transform wp.transform() is used. Defaults to None.
heightfield (Heightfield | None) – The Heightfield object containing the elevation grid data. Defaults to None.
scale (Vec3 | None) – Per-instance scale applied to the heightfield extents (hx, hy, min_z, max_z). Lets the same Heightfield asset be reused at different sizes across shapes. Defaults to None, which is treated as (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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, uses the per-shape palette color.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity.
label (str | None) – An optional label for identifying the shape. If None, a default label 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_mesh(body, *, xform=None, mesh=None, scale=None, cfg=None, color=None, opacity=None, label=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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, falls back to color when available.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, falls back to opacity when available.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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, color=None, opacity=None, label=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). If (a,b,c) is unit-length, d is the negative signed offset from the origin along that normal, so (0.0, 0.0, 1.0, -h) defines the plane z = h. 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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, uses the per-shape palette color.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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, color=None, opacity=None, label=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.
color (Vec3 | None) – Optional display RGB color with values in [0, 1]. If None, uses the per-shape palette color.
opacity (float | None) – Optional display opacity with value in [0, 1]. If None, uses full opacity.
label (str | None) – An optional unique label for identifying the shape. If None, a default label 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), label=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 (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | 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 (list[float] | tuple[float, float, float] | vec3f) – The scale/size of the site for visualization. Defaults to (0.01, 0.01, 0.01).
label (str | None) – An optional unique label for identifying the site. If None, a default label 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()),
    label="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=0.0, tri_ka=0.0, tri_kd=0.0, tri_drag=0.0, tri_lift=0.0, add_surface_mesh_edges=True, edge_ke=0.0, edge_kd=0.0, particle_radius=None, color=None, opacity=None, label=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 viscous damping coefficient [Pa·s].
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
tri_ke (float) – Stiffness for surface mesh triangles. Defaults to 0.0.
tri_ka (float) – Area stiffness for surface mesh triangles. Defaults to 0.0.
tri_kd (float) – Damping for surface mesh triangles. Defaults to 0.0.
tri_drag (float) – Drag coefficient for surface mesh triangles. Defaults to 0.0.
tri_lift (float) – Lift coefficient for surface mesh triangles. Defaults to 0.0.
add_surface_mesh_edges (bool) – Whether to create zero-stiffness bending edges on the generated surface mesh. These edges improve collision robustness for VBD solver. Defaults to True.
edge_ke (float) – Bending edge stiffness used when add_surface_mesh_edges is True. Defaults to 0.0.
edge_kd (float) – Bending edge damping used when add_surface_mesh_edges is True. Defaults to 0.0.
particle_radius (float | None) – particle’s contact radius (controls rigidbody-particle contact distance)
color (list[float] | tuple[float, float, float] | vec3f | list[list[float] | tuple[float, float, float] | vec3f] | ndarray | None) – Display color in [0, 1] for the generated surface mesh. If a single RGB value, applied to all triangles. If array-like, RGB values are applied per triangle.
opacity (float | list[float] | ndarray | None) – Display opacity in [0, 1] for the generated surface mesh. If scalar, applied to all triangles. If array-like, values are applied per triangle.
label (str | None) – Optional name appended to volume_label for this soft body. If None, a generated volume_N label is used. Currently unused by mesh-quality diagnostics because the generated grid is degenerate-free by construction. See Deformable Objects.

Note

The generated surface triangles and optional edges are for collision purposes. Their stiffness and damping values default to zero so they do not introduce additional elastic forces. Set the triangle stiffness parameters above to non-zero values if you want the surface to behave like a thin skin.

add_soft_mesh(*, pos, rot, scale, vel, mesh=None, vertices=None, indices=None, density=None, k_mu=None, k_lambda=None, k_damp=None, tri_ke=0.0, tri_ka=0.0, tri_kd=0.0, tri_drag=0.0, tri_lift=0.0, add_surface_mesh_edges=True, edge_ke=0.0, edge_kd=0.0, particle_radius=None, color=None, opacity=None, validate_mesh=False, label=None)#

Helper to create a tetrahedral model from an input tetrahedral mesh.

Can be called with either a TetMesh object or raw vertices/indices arrays. When both are provided, explicit parameters override the values from the TetMesh.

Parameters:

pos (Vec3) – The position of the solid in world space.
rot (Quat) – The orientation of the solid in world space.
scale (float) – Uniform scale applied to vertex positions.
vel (Vec3) – The velocity of the solid in world space.
mesh (TetMesh | None) – A TetMesh object. When provided, its vertices, indices, material arrays, density, and pre-computed surface triangles are used directly.
vertices (list[Vec3] | None) – A list of vertex positions, array of 3D points. Required if mesh is not provided.
indices (list[int] | None) – A list of tetrahedron indices, 4 entries per-element, flattened array. Required if mesh is not provided.
density (float | None) – The density [kg/m^3] of the mesh. Overrides mesh.density if both are provided.
k_mu (float | np.ndarray | None) – The first elastic Lame parameter [Pa]. Scalar or per-element array. Overrides mesh.k_mu if both are provided.
k_lambda (float | np.ndarray | None) – The second elastic Lame parameter [Pa]. Scalar or per-element array. Overrides mesh.k_lambda if both are provided.
k_damp (float | np.ndarray | None) – The viscous damping coefficient [Pa·s]. Scalar or per-element array. Overrides mesh.k_damp if both are provided.
tri_ke (float) – Stiffness for surface mesh triangles. Defaults to 0.0.
tri_ka (float) – Area stiffness for surface mesh triangles. Defaults to 0.0.
tri_kd (float) – Damping for surface mesh triangles. Defaults to 0.0.
tri_drag (float) – Drag coefficient for surface mesh triangles. Defaults to 0.0.
tri_lift (float) – Lift coefficient for surface mesh triangles. Defaults to 0.0.
add_surface_mesh_edges (bool) – Whether to create zero-stiffness bending edges on the generated surface mesh. These edges improve collision robustness for VBD solver. Defaults to True.
edge_ke (float) – Bending edge stiffness used when add_surface_mesh_edges is True. Defaults to 0.0.
edge_kd (float) – Bending edge damping used when add_surface_mesh_edges is True. Defaults to 0.0.
particle_radius (float | None) – particle’s contact radius (controls rigidbody-particle contact distance).
color (Vec3 | list[Vec3] | np.ndarray | None) – Display color in [0, 1] for the generated surface mesh. If a single RGB value, applied to all triangles. If array-like, RGB values are applied per triangle.
opacity (float | list[float] | np.ndarray | None) – Display opacity in [0, 1] for the generated surface mesh. If scalar, applied to all triangles. If array-like, values are applied per triangle.
validate_mesh (bool) – If True, check for inverted or small-volume tetrahedra, sliver tetrahedra, and non-manifold faces, and emit warnings. See newton.utils.validate_tet_mesh().
label (str | None) – Optional name forwarded to newton.utils.validate_tet_mesh() so a mesh-quality warning emitted with validate_mesh=True can identify this soft body. The same name is appended to volume_label; if None, a generated volume_N label is used. See Deformable Objects.

Note

Parameter resolution order: explicit argument > TetMesh attribute > builder default (default_tet_density, default_tet_k_mu, default_tet_k_lambda, default_tet_k_damp).

The generated surface triangles and optional edges are for collision purposes. Their stiffness and damping values default to zero so they do not introduce additional elastic forces. Set the stiffness parameters above to non-zero values if you want the surface to behave like a thin skin.

add_spring(i, j, ke, kd, control, custom_attributes=None)#

Adds a spring between two particles in the system

Parameters:

i (int) – The index of the first particle
j (int) – The index of the second particle
ke (float) – The elastic stiffness of the spring
kd (float) – The damping coefficient of the spring [N·s/m].
control (float) – The actuation level of the spring
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

Note

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

add_tendon(route, *, label=None, custom_attributes=None)#

Add a complete experimental massless routed tendon atomically.

Each guide after the first owns the incoming span’s material parameters. All guides must belong to one simulation world. A guide with body=-1 is fixed in world space and belongs to current_world. Roller guides may be dynamic only when internal and not adjacent to another dynamic guide. The route is validated and copied before any tendon arrays are changed. Author world-attached routes in the source builder before add_world() or replicate(); those methods end outside the copied world contexts.

Experimental

This API represents an open, ordered route; it does not infer closed loops or change the guide order during simulation.

Parameters:

route (Sequence[TendonGuide]) – At least two ordered route guides.
label (str | None) – Tendon name; defaults to tendon_{index}.
custom_attributes (dict[str, Any] | None) – Values of declared TENDON-frequency attributes. Guide and incoming-span attributes are supplied on each TendonGuide.

Returns:

Tendon index. Its flattened guide range begins at tendon_start[index] and contains len(route) guides.

Raises:

TypeError – If a route entry is not a TendonGuide.
ValueError – If geometry, material parameters, body references, or dynamic-routing topology are invalid.

Return type:

int

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

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 viscous damping coefficient [Pa·s].
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

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, color=None, opacity=None, custom_attributes=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 tri_materials.

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.
tri_ke (float | None) – The elastic stiffness of the triangle. If None, the default value (default_tri_ke) is used.
tri_ka (float | None) – The area stiffness of the triangle. If None, the default value (default_tri_ka) is used.
tri_kd (float | None) – The damping coefficient of the triangle. If None, the default value (default_tri_kd) is used.
tri_drag (float | None) – The drag coefficient of the triangle. If None, the default value (default_tri_drag) is used.
tri_lift (float | None) – The lift coefficient of the triangle. If None, the default value (default_tri_lift) is used.
color (list[float] | tuple[float, float, float] | vec3f | None) – Display color in [0, 1]. If None, the default triangle color is used.
opacity (float | None) – Display opacity in [0, 1]. If None, the triangle is fully opaque.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

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, color=None, opacity=None, custom_attributes=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] | ndarray) – The indices of the first particle
j (list[int] | ndarray) – The indices of the second particle
k (list[int] | ndarray) – The indices of the third particle
tri_ke (list[float] | None) – The elastic stiffness of the triangles. If None, the default value (default_tri_ke) is used.
tri_ka (list[float] | None) – The area stiffness of the triangles. If None, the default value (default_tri_ka) is used.
tri_kd (list[float] | None) – The damping coefficient of the triangles. If None, the default value (default_tri_kd) is used.
tri_drag (list[float] | None) – The drag coefficient of the triangles. If None, the default value (default_tri_drag) is used.
tri_lift (list[float] | None) – The lift coefficient of the triangles. If None, the default value (default_tri_lift) is used.
color (list[float] | tuple[float, float, float] | vec3f | list[list[float] | tuple[float, float, float] | vec3f] | ndarray | None) – Display color in [0, 1]. If a single RGB value, applied to all triangles. If array-like, RGB values are applied per triangle.
opacity (float | list[float] | ndarray | None) – Display opacity in [0, 1]. If scalar, applied to all triangles. If array-like, values are applied per triangle.
custom_attributes (dict[str, Any] | None) – Dictionary of custom attribute names to values.

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=None, base_joint=None, parent_body=-1, 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=False, joint_ordering='dfs', bodies_follow_joint_ordering=True, collapse_fixed_joints=False, collapse_massless_fixed_root=False, mesh_maxhullvert=None, force_position_velocity_actuation=False, override_root_xform=False, joint_damping_mode='passive', package_dirs=None)#

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

Parameters:

source (str) – URDF filename, local file: URI, package:// or model:// URI, or XML content.
package_dirs (list[str] | None) – Extra package roots for source and asset URIs; for package://robot/..., supply the directory containing robot. Requires newton[importers]. Roots supplement environment paths without guaranteed precedence or restricting access. Plain relative paths use the URDF directory; file URIs require an absolute local path.
xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform to apply to the root body. If None, the transform is set to identity. If parent_body is set, xform is expressed in that body’s frame instead of the world frame.
override_root_xform (bool) – If True, the articulation root’s world-space transform is replaced by xform instead of being composed with it, preserving only the internal structure (relative body positions). Useful for cloning articulations at explicit positions. When a base_joint is specified, xform is applied as the full parent transform (including rotation) rather than splitting position/rotation. Not intended for sources containing multiple articulations, as all roots would be placed at the same xform. Defaults to False.
floating (bool | None) –
Controls the base joint type for the root body.
- None (default): Uses format-specific default (creates a FIXED joint for URDF).
- True: Creates a FREE joint with 6 DOF (3 translation + 3 rotation). Only valid when parent_body == -1 since FREE joints must connect to world frame.
- False: Creates a FIXED joint (0 DOF).
Cannot be specified together with base_joint.
base_joint (dict | None) –
Custom joint specification for connecting the root body to the world (or to parent_body if specified). This parameter enables hierarchical composition with custom mobility. Dictionary with joint parameters as accepted by ModelBuilder.add_joint() (e.g., joint type, axes, limits, stiffness).

Cannot be specified together with floating.

parent_body (int) –

Parent body index for hierarchical composition. If specified, attaches the imported root body to this existing body, making them part of the same kinematic articulation. The connection type is determined by floating or base_joint. If -1 (default), the root connects to the world frame. Restriction: Only the most recently added articulation can be used as parent; attempting to attach to an older articulation will raise a ValueError.

Note

Valid combinations of floating, base_joint, and parent_body:

floating	base_joint	parent_body	Result
`None`	`None`	`-1`	Format default (URDF: FIXED joint)
`True`	`None`	`-1`	FREE joint to world (6 DOF)
`False`	`None`	`-1`	FIXED joint to world (0 DOF)
`None`	`{dict}`	`-1`	Custom joint to world (e.g., D6)
`False`	`None`	`body_idx`	FIXED joint to parent body
`None`	`{dict}`	`body_idx`	Custom joint to parent body (e.g., D6)
explicitly set	explicitly set	any	❌ Error: mutually exclusive (cannot specify both)
`True`	`None`	`body_idx`	❌ Error: FREE joints require world frame

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 (Axis | Literal['X', 'Y', 'Z'] | ~typing.Literal[0, 1, 2] | int | str) – 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.
joint_ordering (Literal['bfs', 'dfs'] | None) – 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.
collapse_massless_fixed_root (bool) – If True, collapse only the massless fixed-joint chain below an imported free root body. Ignored when collapse_fixed_joints is True.
mesh_maxhullvert (int | None) – Maximum vertices for convex hull approximation of meshes.
force_position_velocity_actuation (bool) – If True and both position (stiffness) and velocity (damping) gains are non-zero, joints use POSITION_VELOCITY actuation mode. If False (default), actuator modes are inferred per joint via newton.JointTargetMode.from_gains(): POSITION if stiffness > 0, VELOCITY if only damping > 0, EFFORT if a drive is present but both gains are zero (direct torque control), or NONE if no drive/actuation is applied.
joint_damping_mode (Literal['passive', 'drive']) – How to interpret URDF <dynamics damping>. "passive" (default) imports it into joint_damping and keeps drive damping at default_joint_cfg.target_kd. "drive" imports it into joint_target_kd; absent values use default_joint_cfg.target_kd. In drive mode, passive damping uses default_joint_cfg.damping for revolute, prismatic, and planar joints. XPBD/VBD do not consume passive joint damping.

add_usd(source, *, xform=None, floating=None, base_joint=None, parent_body=-1, only_load_enabled_rigid_bodies=False, only_load_enabled_joints=True, joint_drive_gains_scaling=1.0, verbose=False, ignore_paths=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, load_static_visual_shapes=True, hide_collision_shapes=False, force_show_colliders=False, parse_mujoco_options=True, mesh_maxhullvert=None, schema_resolvers=None, force_position_velocity_actuation=False, convert_mjc_equality_constraints=True, override_root_xform=False, legacy_margin_gap=False, return_deformable_results=False, allow_unsafe_torch_checkpoints=False)#

Parses a Universal Scene Description (USD) stage and adds rigid bodies, particles, soft 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 | Any) – The file path to the USD file, or an existing USD stage instance.
xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – The transform to apply to the entire scene. If parent_body is set, imported bodies are placed relative to that body’s frame; static shapes still use xform in the world frame.
override_root_xform (bool) – If True, the articulation root’s world-space transform is replaced by xform instead of being composed with it, preserving only the internal structure (relative body positions). Useful for cloning articulations at explicit positions. Not intended for sources containing multiple articulations, as all roots would be placed at the same xform. Defaults to False.
floating (bool | None) –
Controls the base joint type for the root body (bodies not connected as a child to any joint).
- None (default): Uses format-specific default (creates a FREE joint for USD bodies without joints).
- True: Creates a FREE joint with 6 DOF (3 translation + 3 rotation). Only valid when parent_body == -1 since FREE joints must connect to world frame.
- False: Creates a FIXED joint (0 DOF).
Cannot be specified together with base_joint.
base_joint (dict | None) –
Custom joint specification for connecting the root body to the world (or to parent_body if specified). This parameter enables hierarchical composition with custom mobility. Dictionary with joint parameters as accepted by ModelBuilder.add_joint() (e.g., joint type, axes, limits, stiffness).

Cannot be specified together with floating.

parent_body (int) –

Parent body index for hierarchical composition. If specified, attaches the imported root body to this existing body, making them part of the same kinematic articulation. The connection type is determined by floating or base_joint. If -1 (default), the root connects to the world frame. Restriction: Only the most recently added articulation can be used as parent; attempting to attach to an older articulation will raise a ValueError.

Note

Valid combinations of floating, base_joint, and parent_body:

floating	base_joint	parent_body	Result
`None`	`None`	`-1`	Format default (USD: FREE joint for bodies without joints)
`True`	`None`	`-1`	FREE joint to world (6 DOF)
`False`	`None`	`-1`	FIXED joint to world (0 DOF)
`None`	`{dict}`	`-1`	Custom joint to world (e.g., D6)
`False`	`None`	`body_idx`	FIXED joint to parent body
`None`	`{dict}`	`body_idx`	Custom joint to parent body (e.g., D6)
explicitly set	explicitly set	any	❌ Error: mutually exclusive (cannot specify both)
`True`	`None`	`body_idx`	❌ Error: FREE joints require world frame

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, log additional information about the parsed USD file. Default is False.
ignore_paths (list[str] | None) – A list of regular expressions matching prim paths to ignore.
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) – Default for whether self-collisions are enabled for all shapes within an articulation. Resolved via the schema resolver from newton:selfCollisionEnabled (NewtonArticulationRootAPI) or physxArticulation:enabledSelfCollisions on the articulation root, or on the cable BasisCurves prim for cable-owned articulations; if neither is authored, this value 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 “/”. Bound physics materials outside this subtree are resolved without importing unrelated bodies or shapes.
joint_ordering (Literal['bfs', 'dfs'] | None) – 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), using the settings from default_mesh_approximation_cfg. Default is False.
load_sites (bool) – If True, sites (prims with NewtonSiteAPI or 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. Also imports experimental deformable visual meshes; see Importing deformable visual meshes.
load_static_visual_shapes (bool) – If True, supported visual-only geometry outside rigid-body hierarchies is loaded as static shapes when load_visual_shapes is also True. Default is True.
hide_collision_shapes (bool) – If True, collision shapes on bodies that already have visual-only geometry are hidden unconditionally, regardless of whether the collider has authored PBR material data. Default is False.
force_show_colliders (bool) – If True, collision shapes get the VISIBLE flag regardless of whether visual shapes exist on the same body. Note that hide_collision_shapes=True still suppresses the VISIBLE flag for colliders on bodies with visual-only geometry. Default is False.
parse_mujoco_options (bool) – Whether MuJoCo solver options from the PhysicsScene should be parsed. If False, solver options are not loaded and custom attributes retain their default values. Default is True.
convert_mjc_equality_constraints (bool) – Whether MuJoCo equality schemas should be converted to Newton loop joints or mimic constraints while preserving MuJoCo equality metadata for SolverMuJoCo. A weld becomes a FIXED loop joint, or a BALL loop joint when its torquescale is 0 (see “Link-break welds and MuJoCo welds” in the articulation docs). If False, equality constraints are preserved in the mujoco:equality_constraint custom-attribute namespace and finalize under model.mujoco.equality_constraint_*.
mesh_maxhullvert (int | None) – Maximum vertices for convex hull approximation of meshes. Note that an authored newton:maxHullVertices attribute on any shape with a NewtonMeshCollisionAPI will take priority over this value.
schema_resolvers (list[SchemaResolver] | None) –
Resolver instances in priority order. Default is to only parse Newton-specific attributes. Schema resolvers collect per-prim “solver-specific” attributes, see Schema Resolvers 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 result["schema_attrs"] returned from parse_usd().

Experimental

The schema_resolvers argument may change without prior notice.
force_position_velocity_actuation (bool) – If True and both stiffness (kp) and damping (kd) are non-zero, joints use POSITION_VELOCITY actuation mode. If False (default), actuator modes are inferred per joint via newton.JointTargetMode.from_gains(): POSITION if stiffness > 0, VELOCITY if only damping > 0, EFFORT if a drive is present but both gains are zero (direct torque control), or NONE if no drive/actuation is applied.
legacy_margin_gap (bool) – If True, restore pre-MuJoCo-3.9 import behavior where shape_margin is computed as mjc_margin - mjc_gap. Use for USD files authored against MuJoCo <= 3.8. Defaults to False (identity translation matching MuJoCo 3.9 semantics).
return_deformable_results (bool) – If True, include the experimental deformable entries in the returned mapping (path_cable_map / path_cloth_map / path_soft_map / path_deformable_visual_map / path_attachment_map and the matching path_*_attrs). Off by default, so the default return shape carries no deformable additions.
allow_unsafe_torch_checkpoints (bool) –
Allow USD neural actuators to reference Torch checkpoints. Only use this for trusted USD assets and checkpoints: loading a Torch checkpoint may execute code during newton.ModelBuilder.finalize(). Defaults to False.

Deprecated since version 1.8: Torch checkpoints are deprecated; export the network to ONNX.

Returns:

Experimental

return_deformable_results and its conditional result entries are experimental and may change or be removed without prior notice.

When return_deformable_results=True, imported deformable (cable/cloth/volume) element ranges are returned by prim path in the path_cable_map / path_cloth_map / path_soft_map entries below, and the material attributes as authored in the matching path_*_attrs entries. The map entries are build-time snapshots of the builder immediately after this call (already remapped when this call collapses fixed joints); they are not live selections, and a later replicate(), add_builder(), or other structural mutation is outside their contract. The path_*_attrs entries hold authored or resolved source values (material as authored, resolved_density as used), while the map entries and joint_indices inside path_attachment_attrs are realized builder indices; unsupported_reason is diagnostic text, not a stable code, and a prim absent from a realized map may still appear in the authored metadata.

path_particle_map is always returned. It maps each imported UsdGeom.Points prim carrying NewtonPointsDeformableSimAPI whose governing PhysicsDeformableBodyAPI resolves to a NewtonMPMSceneAPI owner to its half-open [start, end) builder particle range. These ranges are build-time snapshots and are not updated by later structural builder mutations. Each resolved whole-prim or point-GeomSubset physics material must apply NewtonMPMMaterialAPI, PhysicsMaterialAPI, or PhysicsVolumeDeformableMaterialAPI. MPM elasticity is read from newton:mpm:youngsModulus and newton:mpm:poissonsRatio. After unit conversion, Young’s modulus is in Pa and density is in kg/m^3. Unbound Points use Newton’s registered material defaults and ModelBuilder.default_shape_cfg density. All Points imported by one call must resolve to the same MPM scene; unrelated PhysicsScenes and particle systems are ignored. particle_scene_path contains the governing UsdPhysics.Scene prim path, or None when no particles are imported.

Particle widths are diameters. Newton converts each radius as width / 2 after applying stage units and the prim’s uniform world scale; converted widths and radii are in meters. Authored newton:masses take precedence over body mass or density, then material density. The deprecated physics:masses name is read, with a deprecation warning, when newton:masses is unauthored. Density-derived mass uses physics:density * width**3; converted masses are in kilograms. Without widths, it uses ModelBuilder.default_particle_radius and a support width of twice that radius. Non-uniform scale or shear is rejected because one scalar width cannot preserve a spherical particle under that transform.

Visual meshes load or generate normals through newton.usd.get_mesh(). Sharp shading can duplicate vertices in Model.shape_source, including for untextured meshes. Collision-only loads do not request normals, and visual expansion preserves source mass properties. Use newton.usd.get_mesh() with load_normals=False when source vertex sharing is required for geometry processing.

The returned mapping has 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_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_joint_map"`	Mapping from prim path (str) of a joint prim (e.g. that implements the PhysicsJointAPI) to the respective joint index in `ModelBuilder`
`"path_shape_map"`	Mapping from prim path (str) of the UsdGeom to the respective shape index in `ModelBuilder`
`"path_shape_scale"`	Mapping from prim path (str) of the UsdGeom to its respective 3D world scale
`"path_particle_map"`	Mapping from an imported particle-simulation `UsdGeom.Points` prim path to its half-open `(particle_start, particle_end)` builder range
`"path_cable_map"`	Mapping from prim path (str) of a curve deformable (cable) to its `(body_indices, joint_indices)` lists. Curves welded into a rod graph report empty joints (the joints belong to the shared graph articulation). Present only with `return_deformable_results=True`.
`"path_cloth_map"`	Mapping from prim path (str) of a surface deformable (cloth) to its `[start, end)` index ranges, keyed `"particle"` / `"tri"` / `"edge"`. Present only with `return_deformable_results=True`.
`"path_soft_map"`	Mapping from prim path (str) of a soft body (a volume deformable, or a legacy bare TetMesh) to its `[start, end)` index ranges, keyed `"particle"` / `"tet"`. Present only with `return_deformable_results=True`.
`"path_deformable_visual_map"`	Mapping from graphics Mesh prim path (str) to its index in `Model.deformable_visual_meshes`. Includes only successfully imported visual meshes. Present only with `return_deformable_results=True`. The indices describe this import, not copies created by later builder composition or replication.
`"path_cable_attrs"`	Mapping from prim path (str) of a curve deformable (cable) to its validated, solver-neutral cable import metadata (`material`, `resolved_density`, `closed`). `material` contains supported per-mode structural values before per-joint discretization: stretch/shear stiffness [N] and damping [N·s]; bend/twist stiffness [N·m²] and damping [N·m²·s]. `graph_component` is present only for curves successfully welded into the same rod graph; curves in one graph share the identifier. Present only with `return_deformable_results=True`.
`"path_cloth_attrs"`	Mapping from prim path (str) of a surface deformable (cloth) to its as-authored, solver-neutral attributes (`material` moduli, `resolved_density`). Present only with `return_deformable_results=True`.
`"path_soft_attrs"`	Mapping from prim path (str) of a soft body (a volume deformable, or a legacy bare TetMesh) to its as-authored, solver-neutral attributes (`resolved_density`). Present only with `return_deformable_results=True`.
`"path_attachment_map"`	Mapping from prim path (str) of a supported cable `PhysicsAttachment` prim to the created joint indices. Cloth/volume particle-body attachments are not joints and are listed only in `path_attachment_attrs`. Curve-to-curve `point`->``point`` junctions are consumed as rod-graph topology and are absent from this mapping. Present only with `return_deformable_results=True`.
`"path_attachment_attrs"`	Mapping from prim path (str) of a `PhysicsAttachment` prim to its parsed, solver-neutral attributes and any unsupported reason. Imported cloth/volume attachments list their particle-body attachment indices under `"attachment_particle_body_indices"`. Junctions consumed as rod-graph topology are absent here as well. Present only with `return_deformable_results=True`.
`"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
`"physics_scene_path"`	Prim path of the PhysicsScene selected during import, or `None` if no PhysicsScene was found
`"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)
`"particle_scene_path"`	Governing `UsdPhysics.Scene` prim path for imported particle simulation geometry, or `None` when no particles are imported
`"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`
`"actuator_count"`	Number of external actuators parsed from the USD stage

Return type:

dict[str, Any]

add_world(builder, xform=None, label_prefix=None)#

Add a builder as a new world.

This is a convenience method that combines begin_world(), add_builder(), and end_world() into a single call. It’s the recommended way to add homogeneous worlds (multiple instances of the same scene/robot).

Parameters:

builder (ModelBuilder) – The builder containing entities to add as a new world.
xform (tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf | None) – Optional transform to apply to all root bodies in the builder. Useful for spacing out worlds visually.
label_prefix (str | None) – Optional prefix prepended to all entity labels from the source builder. Useful for distinguishing multiple instances of the same model (e.g., "left_arm" vs "right_arm").

Raises:

RuntimeError – If called when already in a world context (via begin_world).

Example:

# Create a robot blueprint
robot = ModelBuilder()
robot.add_body(...)
robot.add_shape_box(...)

# Create main scene with multiple robot instances
scene = ModelBuilder()
scene.add_ground_plane()  # Global ground plane

# Add multiple robot worlds
for i in range(3):
    scene.add_world(robot)  # Each robot is a separate world

approximate_meshes(method='convex_hull', shape_indices=None, raise_on_failure=False, keep_visual_shapes=False, *, cache_dir=None, **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.utils.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. For coacd and vhacd, each geometrically connected component is decomposed separately and may produce one or more convex shapes, each limited to the source mesh’s maxhullvert vertices. CoACD decompositions repeat across runs; pass CoACD’s seed through remeshing_kwargs to change it.

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.

Important

Apply this method to a builder before passing it to replicate() or add_world(), not to the parent builder afterwards. Replication copies mesh references, not mesh data, so N worlds share one Mesh object. Approximating first simplifies each mesh once and shares the result across all replicated worlds; approximating afterwards produces the same shared result but processes every replicated shape.

Shapes that share one source Mesh object receive one shared replacement mesh, so copy a shape’s shape_source entry before modifying it for that shape alone.

Recommended:

arm = newton.ModelBuilder()
# ... populate arm ...
arm.approximate_meshes(method="convex_hull")

scene = newton.ModelBuilder()
scene.replicate(arm, copy_count=N)

Parameters:

method (Literal['coacd', 'vhacd', 'bounding_sphere', 'bounding_box'] | RemeshingMethod) – The method to use for approximating the mesh shapes.
shape_indices (list[int] | None) – The indices of the shapes to simplify. Entries that are not MESH or CONVEX_MESH shapes are ignored. 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.
keep_visual_shapes (bool) – If True, retain the original geometry as visual-only shapes.
cache_dir (str | os.PathLike[str] | None) – Directory for persistent coacd and vhacd decomposition caching. Created if missing; None uses newton.config.cache_dir_meshes, which defaults to None (no disk caching). Set that global setting to a directory to enable caching for subsequent calls, including USD imports. An explicit directory overrides the global setting. Entries are keyed by mesh geometry, effective backend settings, backend versions, and cache format version. Corrupt or incompatible entries are recomputed; cache I/O failures are logged and do not prevent approximation. Other methods ignore this option.
**remeshing_kwargs (dict[str, Any]) – Additional keyword arguments passed to the remeshing function.

Returns:

Indices of the shapes that were successfully remeshed.

Return type:

set[int]

begin_world(label=None, attributes=None, gravity=None)#

Begin a new world context for adding entities.

This method starts a new world scope where all subsequently added entities (bodies, shapes, joints, particles, etc.) will be assigned to this world. Use end_world() to close the world context and return to the global scope.

Important: Worlds cannot be nested. You must call end_world() before calling begin_world() again.

Parameters:

label (str | None) – Optional unique identifier for this world. If None, a default label “world_{index}” will be generated.
attributes (dict[str, Any] | None) – Optional custom attributes to associate with this world for later use.
gravity (list[float] | tuple[float, float, float] | vec3f | None) – Optional gravity vector [m/s^2] for this world. If None, the world uses the builder’s default gravity.

Raises:

RuntimeError – If called when already inside a world context (current_world is not -1).

Example:

builder = ModelBuilder()

# Add global ground plane
builder.add_ground_plane()  # Added to world -1 (global)

# Create world 0 with default gravity
builder.begin_world(label="robot_0")
builder.add_body(...)  # Added to world 0
builder.add_shape_box(...)  # Added to world 0
builder.end_world()

# Create world 1 with custom zero gravity
builder.begin_world(label="robot_1", gravity=(0.0, 0.0, 0.0))
builder.add_body(...)  # Added to world 1
builder.add_shape_box(...)  # Added to world 1
builder.end_world()

collapse_fixed_joints(verbose=False, joints_to_keep=None)#

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.

Parameters:

verbose (bool) – If True, log additional information about the collapsed joints.
joints_to_keep (Sequence[str | int] | None) – An optional sequence of joint labels or original joint indices to be excluded from the collapse process.

Note

Deformable labels do not change which fixed joints are collapsed. A curve’s record describes its surviving segment bodies and joints. It is omitted with a warning only when no segment bodies remain. Pass the relevant fixed joints through joints_to_keep to preserve the original segment layout. Curve-removal warnings are emitted after collapse completes.

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.

This populates both particle_color_groups (for particles) and body_color_groups (for rigid bodies) on the builder, which are consumed by newton.solvers.SolverVBD.

Call color() (or set_coloring()) before finalize when using newton.solvers.SolverVBD; finalize does not implicitly color the model.

Parameters:

include_bending (bool) – Whether to include bending edges in the coloring graph. Set to True if your model contains bending edges (added via add_edge()) that participate in bending constraints. When enabled, the coloring graph includes connections between opposite vertices of each edge (o1-o2), ensuring proper dependency handling for parallel bending computations. Leave as False if your model has no bending edges or if bending edges should not affect the coloring.
balance_colors (bool) – Whether to apply the color balancing algorithm to balance the size of each color
target_max_min_color_ratio (float) – the color balancing algorithm will stop when the ratio between the largest color and the smallest color reaches this value
coloring_algorithm (ColoringAlgorithm) – Coloring algorithm to use. ColoringAlgorithm.MCS uses maximum cardinality search (MCS), while ColoringAlgorithm.GREEDY uses degree-ordered greedy coloring. 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 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.

end_world()#

End the current world context and return to global scope.

After calling this method, subsequently added entities will be assigned to the global world (-1) until begin_world() is called again.

Raises:: RuntimeError – If called when not in a world context (current_world is -1).

Example:

builder = ModelBuilder()
builder.begin_world()
builder.add_body(...)  # Added to current world
builder.end_world()  # Return to global scope
builder.add_ground_plane()  # Added to world -1 (global)

finalize(device=None, *, requires_grad=False, skip_all_validations=False, skip_validation_worlds=False, skip_validation_joints=False, skip_validation_shapes=False, skip_validation_inertia=False, skip_validation_structure=False, skip_validation_joint_ordering=True)#

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).
skip_all_validations (bool) – If True, skips all validation checks. Use for maximum performance when you are confident the model is valid. Also skips mass/inertia correction, including bounds and balancing. Use individual skip flags to retain these corrections. Default is False.
skip_validation_worlds (bool) – If True, skips validation of world ordering and contiguity. Default is False.
skip_validation_joints (bool) – If True, skips articulation-topology and membership validation. By default, joints cannot connect separate articulations, and non-root joints must belong to an articulation or close a loop; standalone world-root joints are allowed.
skip_validation_shapes (bool) – If True, skips validation of finite contact materials, contact gaps, and hydroelastic SDF padding on colliding shapes. Default is False.
skip_validation_inertia (bool) – If True, skips all rigid body mass/inertia validation and correction, preserving the builder’s mass and inertia. Derived inverses are always recomputed. Skipped checks include finiteness, symmetry, positive-definiteness, bounds, and triangle-inequality checks. Does not undo earlier importer processing, shape mass computation, or fixed-joint merging. Default is False.
skip_validation_structure (bool) – If True, skips validation of structural invariants (body/joint references, particle topology, array lengths, monotonicity). Default is False.
skip_validation_joint_ordering (bool) – If True, skips validation of DFS topological joint ordering within articulations. Default is True (opt-in) because this check has O(n log n) complexity.

Returns:

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

Raises:

ValueError – If an enabled validation fails, including non-finite contact material values on colliding shapes.

Return type:

Model

Notes

Validates and corrects rigid body inertia and mass unless skip_validation_inertia or skip_all_validations is True.
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.
Python’s cyclic garbage collector is temporarily disabled during this operation. Its previous state is restored before returning or propagating an exception.

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[Model.AttributeFrequency | str]) – The frequencies to get custom attributes for.
Returns:: Custom attributes matching the requested frequencies.
Return type:: list[CustomAttribute]

get_custom_frequency_keys()#

Return set of custom frequency keys (string frequencies) defined in this builder.

has_custom_attribute(key)#

Check if a custom attribute is defined.

plot_articulation(show_body_labels=True, show_joint_labels=True, show_joint_types=True, plot_shapes=True, show_shape_labels=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_labels (bool) – Whether to show the body labels or indices
show_joint_labels (bool) – Whether to show the joint labels 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_labels (bool) – Whether to show the shape labels or indices
show_shape_types (bool) – Whether to show the shape geometry types
show_legend (bool) – Whether to show a legend

replicate(builder, copy_count=None, spacing=(0.0, 0.0, 0.0), *, separate_worlds=True, xforms=None, label_prefixes=None, world_count=None)#

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. By default, all entities from each copy are assigned to a new world, so copies do not collide with each other. With separate_worlds=False, all copies are added to the current world context instead, as repeated add_builder() calls would add them, and copies collide with each other.

All copies are merged in a single batched pass, which is much faster than calling add_world() or add_builder() once per copy; subclass overrides of those methods are not invoked during replication. Merged entries may share objects with builder and across the copies; see add_builder() for the supported life-cycle.

Deprecated since version 1.8: world_count is deprecated. Use copy_count instead.

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. With separate_worlds=False, this does not apply: copies share one world, so place them apart with spacing or xforms to keep them from starting in contact.

Python’s cyclic garbage collector is temporarily disabled during this operation. Its previous state is restored before returning or propagating an exception.

Important

Replication may replace the backing lists of attributes on this builder. References to list-valued attributes obtained before calling this method may become stale: they do not receive the replicated data, and mutations through them are not reflected by the builder. Reacquire attribute references from the builder after calling this method.

Important

To approximate mesh shapes, call approximate_meshes() on builder before passing it here. Replication copies mesh references, so approximating first simplifies each mesh once and shares the result across all copies; approximating afterwards produces the same shared result but processes every replicated shape.

Parameters:

builder (ModelBuilder) – The builder to replicate. All entities from this builder will be copied.
copy_count (int | None) – The number of copies to add.
spacing (tuple[float, float, float]) – The spacing between each copy along each axis. Ignored when xforms is provided. 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).
separate_worlds (bool) – Whether to assign each copy to a new world. If False, add all copies to the current world context (see current_world) instead. Like add_builder(), this then also replaces the current world’s gravity, or this builder’s gravity outside a world context, with the gravity of builder.
xforms (Sequence[tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf] | None) – Optional sequence of transforms, one per copy. When provided, its length must equal copy_count.
label_prefixes (Sequence[str | None] | None) – Optional prefix prepended to all labels from the source builder, one per copy, applied as add_builder() applies its label_prefix. Labels are joined with /. A None entry leaves that copy’s labels as they are in builder; an empty source label remains unlabeled.
world_count (int | None) – Deprecated alias for copy_count.

Raises:

TypeError – Neither or both of copy_count and world_count are supplied.
RuntimeError – separate_worlds is True inside a world context.
ValueError – xforms or label_prefixes does not have copy_count entries.

request_contact_attributes(*attributes)#

Request optional contact attributes on the finalized model.

Deprecated since version 1.7: Request newton.solvers.SolverBase.ObservableKind.CONTACT_F from the solver instead.

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

request_state_attributes(*attributes)#

Request optional solver-produced attributes on the finalized model.

Deprecated since version 1.7: Request newton.solvers.SolverBase.Observables from the solver instead.

See Solver Observables for migration details.

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

set_coloring(particle_color_groups)#

Sets coloring information with user-provided coloring.

Parameters:: particle_color_groups (Iterable[Iterable[int] | ndarray]) – 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.

set_joint_mimic(joint, reference_joint, *, coeffs=(0.0, 1.0))#

Configure a PRISMATIC, REVOLUTE, or D6 joint to mimic another with matching dimensions.

The relationship is applied componentwise to every position and velocity coordinate. The follower coordinates are defined by q[joint] = coeffs[0] + coeffs[1] * q[reference_joint] and qd[joint] = coeffs[1] * qd[reference_joint]. Passing None as reference_joint clears the relationship.

Quaternion joints (BALL, FREE, DISTANCE, and ROD) cannot be followers or references because the componentwise relationship does not preserve unit quaternions. FIXED joints have no coordinates to mimic and are also not supported.

Mimic chains are not supported: the reference joint must be independent, and a joint referenced by another mimic joint cannot become a follower. When both joints belong to articulations, they must share an articulation. This is checked again during finalization after articulation assignment.

Parameters:

joint (int) – Index of the follower joint.
reference_joint (int | None) – Index of the reference joint, or None to make joint independent.
coeffs (list[float] | tuple[float, float] | vec2f) – Offset and multiplier applied componentwise to the reference coordinates [m or rad, dimensionless].

Raises:

ValueError – If an index is invalid, either joint type is unsupported, the joint dimensions differ, the joints belong to different worlds or articulations, the coefficients are not finite, or the relationship creates a mimic chain.

validate_joint_ordering()#

Validate that joints within articulations follow DFS topological ordering.

This check ensures that joints are ordered such that parent bodies are processed before child bodies within each articulation. This ordering is required by some solvers (e.g., MuJoCo) for correct kinematic computations.

This method is public and opt-in because the check has O(n log n) complexity due to topological sorting. It is skipped by default in finalize.

Warns:: UserWarning – If joints are not in DFS topological order.
Returns:: Whether joints are correctly ordered.
Return type:: bool

actuator_count: int#: Total actuator count propagated to Model.actuator_count.

actuator_entries: dict[tuple, ActuatorEntry]#: Actuator entry groups accumulated from add_actuator(), keyed by drive class and shared params.

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

articulation_end: list[int]#: Exclusive end indices of regular tree joints accumulated for Model.articulation_end.

articulation_label: list[str]#: Articulation labels accumulated for Model.articulation_label.

articulation_start: list[int]#: Articulation start indices accumulated for Model.articulation_start.

articulation_world: list[int]#: World indices accumulated for Model.articulation_world.

articulation_world_start: list[int]#: Per-world articulation starts accumulated for Model.articulation_world_start.

attachment_particle_body_body: list[int]#: Rigid body indices accumulated for Model.attachment_particle_body_body.

attachment_particle_body_body_point: list[list[float] | tuple[float, float, float] | vec3f]#: Body-local attachment points [m] accumulated for Model.attachment_particle_body_body_point.

property attachment_particle_body_count: int#: The number of particle-body attachments in the model.

attachment_particle_body_damping: list[float]#: Attachment damping values [N·s/m] accumulated for Model.attachment_particle_body_damping.

attachment_particle_body_enabled: list[bool]#: Attachment enabled states accumulated for Model.attachment_particle_body_enabled.

attachment_particle_body_particle: list[int]#: Particle indices accumulated for Model.attachment_particle_body_particle.

attachment_particle_body_stiffness: list[float]#: Attachment stiffness values [N/m] accumulated for Model.attachment_particle_body_stiffness.

attachment_particle_body_world: list[int]#: World indices accumulated for Model.attachment_particle_body_world.

balance_inertia: bool#: 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.

battery_entries: dict[type, BatteryEntry]#: Battery entry groups accumulated from add_battery(), keyed by battery class.

body_color_groups: list[Any]#: Rigid-body color groups accumulated for Model.body_color_groups.

body_com: list[list[float] | tuple[float, float, float] | vec3f]#: Body centers of mass [m] accumulated for Model.body_com.

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

body_flags: list[int]#: Body flags accumulated for Model.body_flags.

body_inertia: list[list[float] | mat33f]#: Body inertia tensors accumulated for Model.body_inertia.

body_inv_inertia: list[list[float] | mat33f]#: Inverse body inertia tensors accumulated for Model.body_inv_inertia.

body_inv_mass: list[float]#: Inverse body masses accumulated for Model.body_inv_mass.

body_label: list[str]#: Body labels accumulated for Model.body_label.

body_lock_inertia: list[bool]#: Per-body inertia-lock flags retained while composing bodies in the builder.

body_mass: list[float]#: Body masses [kg] accumulated for Model.body_mass.

body_q: list[tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf]#: Body poses accumulated for Model.body_q.

body_qd: list[list[float] | tuple[float, float, float, float, float, float] | spatial_vectorf]#: Body spatial velocities accumulated for Model.body_qd.

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

body_world: list[int]#: World indices accumulated for Model.body_world.

body_world_start: list[int]#: Per-world body starts accumulated for Model.body_world_start.

bound_inertia: float | None#: Minimum allowed eigenvalue for rigid body inertia tensors [kg*m^2]. 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: float | None#: Minimum allowed mass value for rigid bodies [kg]. If set, any body mass below this value will be clamped to this minimum. Set to None to disable mass clamping. Default: None.

constraint_mimic_coef0: list[float]#: Offset coefficients accumulated for Model.constraint_mimic_coef0.

constraint_mimic_coef1: list[float]#: Scale coefficients accumulated for Model.constraint_mimic_coef1.

constraint_mimic_enabled: list[bool]#: Enabled flags accumulated for Model.constraint_mimic_enabled.

constraint_mimic_joint0: list[int]#: Follower joint indices accumulated for Model.constraint_mimic_joint0.

constraint_mimic_joint1: list[int]#: Leader joint indices accumulated for Model.constraint_mimic_joint1.

constraint_mimic_label: list[str]#: Mimic constraint labels accumulated for Model.constraint_mimic_label.

constraint_mimic_world: list[int]#: World indices accumulated for Model.constraint_mimic_world.

property current_world: int#

Returns the builder-managed world context for subsequently added entities.

A value of -1 means newly added entities are global. Use begin_world(), end_world(), add_world(), or replicate() to manage world assignment.

Returns:: The current world index for newly added entities.

curve_label: list[str]#

Labels of rod-backed deformable objects, aligned with curve_world.

Native add_rod() calls each append one entry. USD cable imports record one entry per simulation prim, except that curves welded into a graph share one entry for the complete graph. A prim containing several disconnected curves also has one entry. See Deformable Objects for graph labels and builder-time identity updates.

Experimental

Builder-time deformable object identities may change without notice.

curve_world: list[int]#

World index corresponding to each entry in curve_label.

Assigned by the builder during construction and cloning. Do not edit this list; use the world-assignment methods described in Deformable Objects.

Experimental

Builder-time deformable object identities may change without notice.

custom_attributes: dict[str, CustomAttribute]#: Registered custom attributes to materialize during finalize.

custom_frequencies: dict[str, CustomFrequency]#: Registered custom string frequencies keyed by namespace:name or bare name.

default_bvh_cfg#: Default BVH construction configuration used during model finalization.

default_edge_kd#: Default edge-bending damping.

default_edge_ke#: Default edge-bending elastic stiffness.

default_joint_cfg#: Default joint DoF configuration used when joint DoF configuration is omitted.

default_mesh_approximation_cfg#: Default mesh approximation settings used by approximate_meshes() when not passed explicitly, including USD-triggered approximation in add_usd().

default_particle_radius#: Default particle radius used when particle radius is not provided explicitly.

default_shape_cfg#: Default shape configuration used when shape-creation methods are called with cfg=None. Update this object before adding shapes to set default contact/material properties.

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.

default_spring_kd#: Default spring damping for distance constraints.

default_spring_ke#: Default spring elastic stiffness for distance constraints.

default_tet_density#: Default density [kg/m^3] for tetrahedral soft bodies.

default_tet_k_damp#: Default viscous damping coefficient [Pa·s] for tetrahedral elements.

default_tet_k_lambda#: Default second Lame parameter [Pa] for tetrahedral elements.

default_tet_k_mu#: Default first Lame parameter [Pa] for tetrahedral elements.

default_tri_drag#: Default aerodynamic drag coefficient for triangle elements.

default_tri_ka#: Default triangle area stiffness for cloth/soft-triangle constraints.

default_tri_kd#: Default triangle damping for cloth/soft-triangle constraints.

default_tri_ke#: Default triangle elastic stiffness for cloth/soft-triangle constraints.

default_tri_lift#: Default aerodynamic lift coefficient for triangle elements.

edge_bending_properties: list[tuple[float, float]]#: Bending stiffness/damping rows accumulated for Model.edge_bending_properties.

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

edge_indices: list[tuple[int, int, int, int]]#: Bending-edge connectivity accumulated for Model.edge_indices.

edge_rest_angle: list[float]#: Edge rest angles [rad] accumulated for Model.edge_rest_angle.

edge_rest_length: list[float]#: Edge rest lengths [m] accumulated for Model.edge_rest_length.

property gravity: vec3f#: Global/default gravity vector [m/s^2].

inertia_absolute_tolerance: float#: Positive absolute floor for eigenvalue and triangle-inequality tolerances [kg*m^2]. Lower this to preserve physically valid small tensors. Must be finite and positive in float32. Default: 1.0e-10.

inertia_correction: float#: Non-negative extra diagonal shift when repairing inertia [kg*m^2]. Added to the shift needed to meet the eigenvalue threshold or triangle inequality; does not affect tensors that pass validation. Zero disables the extra shift, not validation. Must be finite. Default: 1.0e-6.

inertia_relative_tolerance: float#: Non-negative relative eigenvalue tolerance (dimensionless). A principal moment below max(inertia_relative_tolerance * largest_moment, inertia_absolute_tolerance) triggers correction. Must be finite. Default: 1.0e-6.

joint_X_c: list[tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf]#: Child-frame joint transforms accumulated for Model.joint_X_c.

joint_X_p: list[tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf]#: Parent-frame joint transforms accumulated for Model.joint_X_p.

joint_act: list[float]#: Joint actuation inputs accumulated for Model.joint_act.

joint_armature: list[float]#: Joint armature values accumulated for Model.joint_armature.

joint_articulation: list[int]#: Articulation indices accumulated for Model.joint_articulation.

joint_axis: list[list[float] | tuple[float, float, float] | vec3f]#: Joint axes accumulated for Model.joint_axis.

joint_child: list[int]#: Child body indices accumulated for Model.joint_child.

joint_children: dict[int, list[tuple[int, int]]]#: Mapping from parent body index to (child_body, joint_idx) pairs (one per joint, no dedup).

joint_collision_filter_parent: list[bool]#: Per-joint resolved collision_filter_parent flag. Builder-only.

joint_constraint_count: int#: Total joint constraint count propagated to Model.joint_constraint_count.

joint_constraint_world_start: list[int]#: Per-world joint-constraint starts accumulated for Model.joint_constraint_world_start.

joint_coord_count: int#: Total joint coordinate count propagated to Model.joint_coord_count.

joint_coord_world_start: list[int]#: Per-world joint-coordinate starts accumulated for Model.joint_coord_world_start.

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

joint_cts: list[float]#: Per-joint constraint placeholders used to derive finalized joint-constraint counts.

joint_cts_start: list[int]#: Joint-constraint start indices retained while building per-joint constraint data.

joint_damping: list[float]#: Passive velocity damping values accumulated for Model.joint_damping.

joint_dof_count: int#: Total joint DoF count propagated to Model.joint_dof_count.

joint_dof_dim: list[tuple[int, int]]#: Per-joint linear/angular DoF dimensions accumulated for Model.joint_dof_dim.

joint_dof_world_start: list[int]#: Per-world joint DoF starts accumulated for Model.joint_dof_world_start.

joint_effort_limit: list[float]#: Joint effort limits accumulated for Model.joint_effort_limit.

joint_enabled: list[bool]#: Joint enabled flags accumulated for Model.joint_enabled.

joint_f: list[float]#: Joint forces accumulated for Model.joint_f.

joint_friction: list[float]#: Joint friction values accumulated for Model.joint_friction.

joint_label: list[str]#: Joint labels accumulated for Model.joint_label.

joint_limit_kd: list[float]#: Joint limit damping values accumulated for Model.joint_limit_kd.

joint_limit_ke: list[float]#: Joint limit stiffness values accumulated for Model.joint_limit_ke.

joint_limit_lower: list[float]#: Lower joint limits accumulated for Model.joint_limit_lower.

joint_limit_upper: list[float]#: Upper joint limits accumulated for Model.joint_limit_upper.

joint_mimic_coeffs: list[list[float] | tuple[float, float] | vec2f]#: Mimic offset and multiplier pairs accumulated for Model.joint_mimic_coeffs.

joint_mimic_joint: list[int]#: Reference joint indices accumulated for Model.joint_mimic_joint.

joint_parent: list[int]#: Parent body indices accumulated for Model.joint_parent.

joint_parents: dict[int, list[tuple[int, int]]]#: Mapping from child body index to (parent_body, joint_idx) pairs (one per joint, no dedup).

joint_q: list[float]#: Joint coordinates accumulated for Model.joint_q.

joint_q_start: list[int]#: Joint coordinate start indices accumulated for Model.joint_q_start.

joint_qd: list[float]#: Joint velocities accumulated for Model.joint_qd.

joint_qd_start: list[int]#: Joint DoF start indices accumulated for Model.joint_qd_start.

joint_rest_q: list[float]#: Spring rest configurations in joint coordinate layout, for Model.joint_rest_q.

joint_stiffness: list[float]#: Passive spring stiffness accumulated for Model.joint_stiffness.

joint_target_kd: list[float]#: Joint target damping values accumulated for Model.joint_target_kd.

joint_target_ke: list[float]#: Joint target stiffness values accumulated for Model.joint_target_ke.

joint_target_mode: list[int]#: Joint target modes accumulated for Model.joint_target_mode.

joint_target_pos#: Data descriptor that turns a removed attribute into a hard error naming its replacement.

joint_target_q: list[float]#: Joint position targets in joint_q (coord) layout, accumulated for Model.joint_target_q.

joint_target_qd: list[float]#: Joint velocity targets per DOF, accumulated for Model.joint_target_qd.

joint_target_vel#: Data descriptor that turns a removed attribute into a hard error naming its replacement.

property joint_twist_lower: list[float]#: Lower twist limits, never used by finalize() or any solver.

Deprecated since version 1.7: Limit joint rotations with the per-DOF limits of JointDofConfig instead.

property joint_twist_upper: list[float]#: Upper twist limits, never used by finalize() or any solver.

Deprecated since version 1.7: Limit joint rotations with the per-DOF limits of JointDofConfig instead.

joint_type: list[int]#: Joint type ids accumulated for Model.joint_type.

joint_velocity_limit: list[float]#: Joint velocity limits accumulated for Model.joint_velocity_limit.

joint_world: list[int]#: World indices accumulated for Model.joint_world.

joint_world_start: list[int]#: Per-world joint starts accumulated for Model.joint_world_start.

muscle_activations: list[float]#: Muscle activations accumulated for Model.muscle_activations.

Deprecated since version 1.9: Legacy muscles are deprecated; see add_muscle().

muscle_bodies: list[int]#: Muscle waypoint body indices accumulated for Model.muscle_bodies.

Deprecated since version 1.9: Legacy muscles are deprecated; see add_muscle().

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

Deprecated since version 1.9: Legacy muscles are deprecated; see add_muscle().

muscle_params: list[tuple[float, float, float, float, float]]#: Muscle parameter rows accumulated for Model.muscle_params.

Deprecated since version 1.9: Legacy muscles are deprecated; see add_muscle().

muscle_points: list[list[float] | tuple[float, float, float] | vec3f]#: Muscle waypoint local offsets accumulated for Model.muscle_points.

Deprecated since version 1.9: Legacy muscles are deprecated; see add_muscle().

muscle_start: list[int]#: Muscle waypoint start indices accumulated for Model.muscle_start.

Deprecated since version 1.9: Legacy muscles are deprecated; see add_muscle().

num_rigid_contacts_per_world: int | None#: Optional per-world rigid-contact allocation budget used to set Model.rigid_contact_max.

particle_color_groups: list[Any]#: Particle color groups accumulated for Model.particle_color_groups.

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

particle_flags: list[int | ParticleFlags]#: Particle flags accumulated for Model.particle_flags.

particle_mass: list[float]#: Particle masses [kg] accumulated for Model.particle_mass.

particle_max_velocity: float#: Maximum particle velocity [m/s] propagated to Model.particle_max_velocity.

particle_q: list[list[float] | tuple[float, float, float] | vec3f]#: Particle positions [m] accumulated for Model.particle_q.

particle_qd: list[list[float] | tuple[float, float, float] | vec3f]#: Particle velocities [m/s] accumulated for Model.particle_qd.

particle_radius: list[float]#: Particle radii [m] accumulated for Model.particle_radius.

particle_world: list[int]#: World indices accumulated for Model.particle_world.

particle_world_start: list[int]#: Per-world particle starts accumulated for Model.particle_world_start.

rigid_gap: float#: Default rigid contact gap [m] applied when adding a shape whose ModelBuilder.ShapeConfig.gap is None. The resolved per-shape values are later propagated to Model.shape_gap.

sdf_texture_paired_samples#: Whether generated SDF textures should store adjacent X samples together.

shape_body: list[int]#: Body indices accumulated for Model.shape_body.

property shape_collision_filter_pairs: list[tuple[int, int]]#: Shape collision filter pairs accumulated for Model.shape_collision_filter_pairs.

shape_collision_group: list[int]#: Collision groups accumulated for Model.shape_collision_group.

shape_collision_radius: list[float]#: Broadphase collision radii [m] accumulated for Model.shape_collision_radius.

shape_color: list[list[float] | tuple[float, float, float] | vec3f]#: Resolved display colors accumulated for Model.shape_color.

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

shape_flags: list[int]#: Shape flags accumulated for Model.shape_flags.

shape_force_sdf: list[bool]#: Per-shape ShapeConfig.force_sdf flags retained until finalize.

shape_gap: list[float]#: Contact gaps [m] accumulated for Model.shape_gap.

shape_is_solid: list[bool]#: Solid-vs-hollow flags accumulated for Model.shape_is_solid.

shape_label: list[str]#: Shape labels accumulated for Model.shape_label.

shape_margin: list[float]#: Shape margins [m] accumulated for Model.shape_margin.

shape_material_ka: list[float]#: Adhesion distances [m] accumulated for Model.shape_material_ka.

shape_material_kd: list[float]#: Contact damping values accumulated for Model.shape_material_kd.

shape_material_ke: list[float]#: Contact stiffness values [N/m] accumulated for Model.shape_material_ke.

shape_material_kf: list[float]#: Contact friction gains [N·s/m] accumulated for Model.shape_material_kf.

shape_material_kh: list[float]#: Hydroelastic stiffness values accumulated for Model.shape_material_kh.

shape_material_mu: list[float]#: Friction coefficients accumulated for Model.shape_material_mu.

shape_material_mu_rolling: list[float]#: Rolling friction coefficients accumulated for Model.shape_material_mu_rolling.

shape_material_mu_static: list[float | None]#: Static friction coefficients accumulated for Model.shape_material_mu_static. None means “same as mu” and is resolved in finalize(), so a direct edit of shape_material_mu keeps a single coefficient for such shapes; an explicit value is checked against the final mu there.

shape_material_mu_torsional: list[float]#: Torsional friction coefficients accumulated for Model.shape_material_mu_torsional.

shape_material_restitution: list[float]#: Restitution coefficients accumulated for Model.shape_material_restitution.

shape_opacity: list[float]#: Resolved display opacities accumulated for Model.shape_opacity.

shape_scale: list[list[float] | tuple[float, float, float] | vec3f]#: Shape scales accumulated for Model.shape_scale.

shape_sdf_max_resolution: list[int | None]#: Per-shape SDF maximum resolutions retained until finalize.

shape_sdf_narrow_band_range: list[tuple[float, float]]#: Per-shape SDF narrow-band ranges retained until finalize generates SDF data.

shape_sdf_padding: list[float | None]#: Per-shape SDF generation margins [m] retained until finalize. When None, shape_gap is used for primitive texture SDF generation.

shape_sdf_target_voxel_size: list[float | None]#: Per-shape target SDF voxel sizes retained until finalize.

shape_sdf_texture_format: list[str]#: Per-shape SDF texture format retained until finalize.

shape_source: list[Any]#: Source geometry objects accumulated for Model.shape_source.

shape_transform: list[tuple[list[float] | tuple[float, float, float] | vec3f, list[float] | tuple[float, float, float, float] | quatf] | transformf]#: Shape-to-body transforms accumulated for Model.shape_transform.

shape_type: list[int]#: Geometry type ids accumulated for Model.shape_type.

shape_world: list[int]#: World indices accumulated for Model.shape_world.

shape_world_start: list[int]#: Per-world shape starts accumulated for Model.shape_world_start.

spring_control: list[float]#: Spring control activations accumulated for Model.spring_control.

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

spring_damping: list[float]#: Spring damping values accumulated for Model.spring_damping.

spring_indices: list[int]#: Spring particle index pairs accumulated for Model.spring_indices.

spring_rest_length: list[float]#: Spring rest lengths [m] accumulated for Model.spring_rest_length.

spring_stiffness: list[float]#: Spring stiffness values [N/m] accumulated for Model.spring_stiffness.

surface_label: list[str]#

Labels of deformable objects represented by triangle surfaces, aligned with surface_world.

add_cloth_mesh() and add_cloth_grid() each record one cloth. USD cloth imports record one entry per simulation prim. See Deformable Objects for builder-time identity updates.

Experimental

Builder-time deformable object identities may change without notice.

surface_world: list[int]#

World index corresponding to each entry in surface_label.

Assigned by the builder during construction and cloning. Do not edit this list; use the world-assignment methods described in Deformable Objects.

Experimental

Builder-time deformable object identities may change without notice.

property tendon_count: int#: Number of authored tendon routes.

tendon_guide_axis: list[tuple[float, float, float]]#: Local-frame normal of the cable plane on each body.

tendon_guide_body: list[int]#: Body index for each tendon guide.

property tendon_guide_count: int#: Number of guides across all tendon routes.

tendon_guide_flags: list[int]#: Routing flags for each tendon guide.

tendon_guide_mu: list[float]#: Friction coefficient at each tendon guide.

tendon_guide_offset: list[tuple[float, float, float]]#: Local-frame offset of the cable plane center on each body [m].

tendon_guide_orientation: list[int]#: Winding direction (+1/-1) for each tendon guide.

tendon_guide_radius: list[float]#: Contact radius [m] for each tendon guide.

tendon_guide_type: list[int]#: Guide type (TendonGuideType enum) for each tendon guide.

tendon_label: list[str]#: Names of authored tendon routes.

tendon_segment_compliance: list[float]#: Compliance [m/N] for each tendon segment.

property tendon_segment_count: int#: Number of incoming straight spans across all tendon routes.

tendon_segment_damping: list[float]#: Damping coefficient [N·s/m] for each tendon segment.

tendon_segment_rest_length: list[float]#: Initial rest length [m] for each tendon segment.

tendon_start: list[int]#: Start index into guide arrays for each tendon.

tendon_world: list[int]#: Owning world of each tendon route.

tet_activations: list[float]#: Tetrahedral activations accumulated for Model.tet_activations.

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

tet_indices: list[tuple[int, int, int, int]]#: Tetrahedral connectivity accumulated for Model.tet_indices.

tet_materials: list[tuple[float, float, float]]#: Tetrahedral material rows accumulated for Model.tet_materials.

tet_poses: list[list[float] | mat33f]#: Tetrahedral rest-pose 3x3 matrices accumulated for Model.tet_poses.

tri_activations: list[float]#: Triangle activations accumulated for Model.tri_activations.

tri_areas: list[float]#: Triangle rest areas [m^2] accumulated for Model.tri_areas.

tri_color: list[list[float] | tuple[float, float, float] | vec3f]#: Triangle surface display colors accumulated for Model.tri_color.

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

tri_indices: list[tuple[int, int, int]]#: Triangle connectivity accumulated for Model.tri_indices.

tri_materials: list[tuple[float, float, float, float, float]]#: Triangle material rows accumulated for Model.tri_materials.

tri_opacity: list[float]#: Triangle surface display opacities accumulated for Model.tri_opacity.

tri_poses: list[list[float] | mat22f]#: Triangle rest-pose 2x2 matrices accumulated for Model.tri_poses.

up_axis: Axis#: Up axis used by geometry helpers and for resolving default gravity.

property up_vector: tuple[float, float, float]#

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.

validate_inertia_detailed: bool#: 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. When True, uses a CPU implementation that reports specific issues for each body. Both modes produce semantically identical corrected values on the returned Model. Neither mode modifies the builder’s internal state — corrected values live only on the Model. Default: False.

volume_label: list[str]#

Labels of deformable objects represented by tetrahedral volumes, aligned with volume_world.

add_soft_mesh() and add_soft_grid() each record one soft body. USD volume imports record one entry per simulation prim. See Deformable Objects for builder-time identity updates.

Experimental

Builder-time deformable object identities may change without notice.

volume_world: list[int]#

World index corresponding to each entry in volume_label.

Assigned by the builder during construction and cloning. Do not edit this list; use the world-assignment methods described in Deformable Objects.

Experimental

Builder-time deformable object identities may change without notice.

world_count: int#: Number of worlds accumulated for Model.world_count.

world_gravity: list[list[float] | tuple[float, float, float] | vec3f]#: Per-world gravity vectors [m/s^2] retained until finalize populates Model.gravity.