newton.Model#

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

Bases: object

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

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

Key Features:

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

Note

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

class AttributeAssignment(*values)#

Bases: IntEnum

Enumeration of attribute assignment categories.

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

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

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

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

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

class AttributeFrequency(*values)#

Bases: IntEnum

Enumeration of attribute frequency categories.

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

ACTUATOR = 26#: Attribute frequency follows the number of actuators (see actuator_count).

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

ATTACHMENT_PARTICLE_BODY = 16#: Attribute frequency follows the number of particle-body attachments.

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

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

CONTACT = 17#

Packed rigid and soft-rigid contact slots, sized by the sum of their capacities.

The soft segment starts at rigid_contact_max, not the live rigid count. Experimental: currently supported for solver observables, not builder attributes.

CONTACT_RIGID = 18#

Rigid-rigid contact slots, sized by rigid_contact_max.

Experimental: currently supported for solver observables, not builder attributes.

CONTACT_SOFT = 19#

Soft-rigid contact slots, sized by soft_contact_max; excludes soft self-contact.

Experimental: currently supported for solver observables, not builder attributes.

CURVE = 23#: Experimental frequency for recorded deformable curves (see curve_count).

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

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

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

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

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

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

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

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

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

SURFACE = 24#: Experimental frequency for recorded deformable surfaces (see surface_count).

TENDON = 20#: Experimental massless routed tendons.

TENDON_GUIDE = 21#: Guides in flattened tendon routes.

TENDON_SEGMENT = 22#: Straight spans between consecutive tendon guides.

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

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

VOLUME = 25#: Experimental frequency for recorded deformable volumes (see volume_count).

WORLD = 15#

Attribute frequency follows the number of worlds plus the global world.

Arrays have shape (world_count + 1,) (see world_count): entries [0, world_count) belong to local worlds and the final entry to global world -1, matching per-world reset masks. Consumers without global-world semantics may ignore the final entry.

class AttributeNamespace(name)#

Bases: object

A container for namespaced custom attributes.

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

__init__(name)#

Initialize the namespace container.

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

add_deprecated_alias(name, getter, message)#

Add a deprecated attribute alias.

Deprecated since version 1.6: Define an explicit property on a custom namespace instead.

Parameters:

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

class AttributeSpec(frequency, assignment=None, references=None, row_width=1, requires_empty_sentinel=False, deprecated=False, alias_of=None, compaction_policy='generic', default=None)#

Bases: object

Semantic metadata for an indexed model attribute.

Experimental

compaction_policy and default are part of the experimental coupled-solver framework and may change without a deprecation period.

__init__(frequency, assignment=None, references=None, row_width=1, requires_empty_sentinel=False, deprecated=False, alias_of=None, compaction_policy='generic', default=None)#

alias_of: str | None = None#: Canonical name used when explicitly accessing this alias through a model view.

assignment: AttributeAssignment | None = None#: Object that owns the attribute, or None when it belongs to the Model.

compaction_policy: Literal['generic', 'end', 'start', 'range_start', 'world_start', 'color_groups', 'passthrough'] = 'generic'#

Experimental policy used by coupled model views.

"generic" selects and remaps rows using this spec; "end" remaps exclusive boundaries in the referenced domain; "range_start" remaps inclusive boundaries for independent ranges without a sentinel. Deformable *_start attributes use it with matching *_end attributes. "start", "world_start", and "color_groups" select their corresponding structured handling; and "passthrough" disables automatic count limiting. Non-generic policies may still be overridden by the coupled solver when constructing a compact view.

default: Any = None#

Experimental value of one row for entities without authored data, or None for the dtype’s zero.

ModelBuilder.finalize() sets it to ModelBuilder.CustomAttribute.default. Coupled model views use it for the rows they synthesize.

deprecated: bool = False#: Whether this is a deprecated compatibility alias that generic consumers should skip.

frequency: AttributeFrequency | str#: Entity domain that determines the attribute row count.

references: AttributeFrequency | str | None = None#: Entity domain referenced by integer values, or None when values are not entity indices.

requires_empty_sentinel: bool = False#: Whether empty compacted storage retains a sentinel value.

row_width: int = 1#: Number of flattened values stored for each entity row.

__init__(device=None)#

Initialize a Model object.

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

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

Add a custom attribute to the model.

Parameters:

name (str) – Name of the attribute.
attrib (array | list[Any]) – The array to add as an attribute. Can be a wp.array for numeric types or a list for string attributes.
frequency (AttributeFrequency | str) – The frequency of the attribute. Can be a Model.AttributeFrequency enum value or a string for custom frequencies.
assignment (AttributeAssignment | None) – The assignment category using Model.AttributeAssignment enum. Determines which object will hold the attribute.
namespace (str | None) – Namespace for the attribute. If None, attribute is added directly to the assignment object (e.g., model.attr_name). If specified, attribute is added to a namespace object (e.g., model.namespace_name.attr_name).
references (AttributeFrequency | str | None) – Entity or custom-frequency domain indexed by the attribute values, or None when values are not references. Use a Model.AttributeFrequency enum for built-in domains or a string for custom frequencies. Existing built-in strings such as "body" and "world" are also supported. Use enums for CURVE, SURFACE, and VOLUME; their string names refer to custom frequencies.

Raises:

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

body_variant_labels(body)#

Labels of the shape variants of a body, indexed like body_variant.

Experimental

Body variants may change without a deprecation period.

Parameters:: body (int) – Body index.
Returns:: The labels, or an empty list for a body without variants.
Raises:: IndexError – If body is out of range.
Return type:: list[str]

bvh_build_particles(state, *, bvh_constructor=None)#

Build or rebuild the particle BVH stored on this model.

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

Parameters:

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

bvh_build_shapes(state, *, bvh_constructor=None, shape_flags=ShapeFlags.VISIBLE)#

Build or rebuild the shape BVH stored on this model.

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

Parameters:

state (newton.State) – Current simulation state with body transforms.
bvh_constructor (str | None) – Warp BVH construction algorithm. Valid choices are "sah", "median", "lbvh", or None to use Warp’s device-dependent default.
shape_flags (ShapeFlags) – Mask of ShapeFlags; a shape is included in the BVH if any of its flags are set in the mask.

bvh_refit_particles(state)#

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

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

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

bvh_refit_shapes(state)#

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

The shape BVH is built automatically by ModelBuilder.finalize(). Manually populated models must call bvh_build_shapes() first. Updates world-space shape transforms from state.body_q and refits the BVH in place, and marks the leaves of empty variant rows (see select_body_variants()) so that ray queries skip them.

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

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

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

Deprecated since version 1.5: Create a CollisionPipeline and call CollisionPipeline.collide() instead.

Parameters:

state (State) – The current simulation state.
contacts (Contacts | None) – The contacts buffer to populate (will be cleared first). If None, a new contacts buffer is allocated via contacts().
collision_pipeline (CollisionPipeline | None) – Optional collision pipeline override.
enable_rigid_soft_full_surface_contact (bool) – When True, additionally run the triangle-driven soft EDGE/FACE passes that detect soft edge / face vs rigid contacts the per-particle SDF path misses, written into the E/F ranges of Contacts.soft_contact_*. Default False reproduces the per-particle behaviour bit-for-bit. This flag is applied when the collision pipeline is allocated (its soft-contact buffer must be sized for the extra records), so it takes effect only on the first collide()/contacts() call that creates the pipeline. Passing True once a pipeline sized without it is cached raises ValueError. Participating mesh/convex shapes must also have volume SDFs provisioned via ModelBuilder.ShapeConfig.configure_sdf() (e.g. configure_sdf(force_sdf=True) on default_shape_cfg) before finalize, or pipeline construction raises.

contacts(collision_pipeline=None)#

Create and return a Contacts object for this model.

Deprecated since version 1.5: Create a CollisionPipeline and call CollisionPipeline.contacts() instead.

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

Note

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

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

control(requires_grad=None, clone_variables=True)#

Create and return a new Control object for this model.

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

Parameters:

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

Returns:

The initialized control object.

Return type:

Control

get_attribute_frequency(name)#

Get the frequency of an attribute.

Parameters:

name (str) – Name of the attribute.

Returns:

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

Raises:

KeyError – If the attribute frequency is not known.

Return type:

AttributeFrequency | str

get_custom_frequency_count(frequency)#

Get the count for a custom frequency.

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

get_requested_contact_attributes()#

Get the set of requested contact attribute names.

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

get_requested_state_attributes()#

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

See Solver Observables for details.

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

request_contact_attributes(*attributes)#

Request optional solver-produced contact attributes.

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 state attributes.

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

select_body_variants(variants, *, bodies=None)#

Select the shape variant of bodies declared with ModelBuilder.add_body_variants.

The variant’s shapes are copied into the body’s variant rows: geometry, the collision data derived from it in ModelBuilder.finalize(), flags, color, materials, and shape custom attributes. Rows the variant does not use are emptied: their collision and visibility flags are cleared, so they neither collide in CollisionPipeline nor render, and sensors and ray casts skip them after the next bvh_refit_shapes(). The body’s mass, center of mass, and inertia, including their inverses, become those of the body as built plus the variant. Edits to the copied arrays, such as shape_scale or materials, last until the next selection, so apply randomization after selecting.

Each body may appear at most once per call. Entries whose variant is out of range, such as -1, leave their body unchanged. The selection runs without host synchronization, so it can be captured in a CUDA graph. Notify solvers and viewers with the returned flags:

flags = model.select_body_variants(variants, bodies=bodies)
solver.notify_model_changed(flags)
viewer.notify_model_changed(flags)

Experimental

Body variants may change without a deprecation period.

Parameters:

variants (wp.array[wp.int32]) – Variant index per entry, a position in the variant list of its body.
bodies (wp.array[wp.int32] | None) – Body index per entry of variants. If None, variants must have one entry per body.

Returns:

The ModelFlags bit-mask to pass to notify_model_changed.

Return type:

int

set_gravity(gravity, world=None)#

Set gravity for runtime modification.

Parameters:

gravity (tuple[float, float, float] | list | vec3f | ndarray) – A single gravity vector [m/s²], one vector per local world, or one vector per local world plus a final global vector. A single vector updates every local world and the global world. Local-world-only inputs preserve a distinct global gravity entry.
world (int | None) – If provided, set gravity only for this world. Use -1 for the global world.

Note

Call solver.notify_model_changed(ModelFlags.MODEL_PROPERTIES) after.

shape_collision_filter_contains(shape_a, shape_b)#

Return whether a canonicalized shape pair is collision-filtered.

This queries the canonical filter-pair array without copying it.

Parameters:

shape_a (SupportsIndex) – First shape index.
shape_b (SupportsIndex) – Second shape index.

Returns:

Whether the pair is present in the collision filter.

Raises:

TypeError – If either shape index is not an integer.

Return type:

bool

shape_collision_filter_mask(pairs)#

Return a boolean mask of which shape pairs are collision-filtered.

Bulk counterpart to shape_collision_filter_contains(): one vectorized query against the canonical filter-pair array instead of a Python-level membership test per pair.

Parameters:

pairs (ndarray) – Shape index pairs in any order, shape [pair_count, 2].

Returns:

Boolean mask of filtered pairs, shape [pair_count].

Raises:

TypeError – If pairs does not have an integer dtype.
OverflowError – If an unsigned shape index exceeds the signed 64-bit range.

Return type:

ndarray

shape_collision_filter_pairs_array()#

Return the collision-filter pairs as an array.

Array counterpart to shape_collision_filter_pairs that returns the canonical filter-pair array without copying the public set. Consumers that need every excluded pair — such as the "nxn" and "sap" broad-phase exclusion arrays — should prefer this form.

Returns:: Canonical shape index pairs sorted lexicographically, shape [pair_count, 2].
Return type:: ndarray

state(requires_grad=None)#

Create and return a new State object for this model.

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

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

actuator_count: int#: Total number of actuators added with ModelBuilder.add_actuator().

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

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

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

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

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

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

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

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

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

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

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

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

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

The total number of global articulations can be computed as:

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

attachment_particle_body_body: wp.array[wp.int32] | None#: Rigid body indices, shape [attachment_particle_body_count], int.

attachment_particle_body_body_point: wp.array[wp.vec3] | None#: Attachment points in body-local coordinates [m], shape [attachment_particle_body_count, 3].

attachment_particle_body_count: int#: Total number of rigid-body-to-particle attachments in the system.

attachment_particle_body_damping: wp.array[wp.float32] | None#: Attachment damping [N·s/m], ignored for hard constraints, shape [attachment_particle_body_count].

attachment_particle_body_enabled: wp.array[wp.bool] | None#: Whether each attachment is active, shape [attachment_particle_body_count].

attachment_particle_body_particle: wp.array[wp.int32] | None#: Particle indices, shape [attachment_particle_body_count], int.

attachment_particle_body_stiffness: wp.array[wp.float32] | None#: Attachment stiffness [N/m], or positive infinity for a hard VBD constraint, shape [attachment_particle_body_count].

attachment_particle_body_world: wp.array[wp.int32] | None#: World index for each attachment, shape [attachment_particle_body_count], int.

attribute_assignment: dict[str, Model.AttributeAssignment]#: Compatibility map from custom attributes to their assignment categories.

attribute_frequency: dict[str, Model.AttributeFrequency | str]#: Compatibility map from attribute names to their indexing frequencies.

attribute_specs: dict[str, Model.AttributeSpec]#

Semantic metadata keyed by built-in or custom attribute name.

Attribute values remain normal Python attributes on the model. This registry describes their indexing, ownership, and reference semantics.

batteries: list[BatteryBase]#: List of battery instances for this model.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Selected shape variant of each body, an index into the body’s variants, or -1 for bodies without variants, shape [body_count], int.

Read-only: change it with select_body_variants(). See ModelBuilder.add_body_variants and body_variant_labels().

Experimental

Body variants may change without a deprecation period.

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

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

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

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

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

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

The total number of global bodies can be computed as:

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

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

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

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

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

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

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

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

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

constraint_mimic_coef0: wp.array[wp.float32] | None#: Offset coefficients for sparse mimic constraints, shape [constraint_mimic_count], float.

Deprecated since version 1.7: Use joint_mimic_coeffs and ModelBuilder.set_joint_mimic() instead.

constraint_mimic_coef1: wp.array[wp.float32] | None#: Multiplier coefficients for sparse mimic constraints, shape [constraint_mimic_count], float.

Deprecated since version 1.7: Use joint_mimic_coeffs and ModelBuilder.set_joint_mimic() instead.

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

Deprecated since version 1.7: Use joint_mimic_joint to identify joints with joint-owned mimic metadata instead.

constraint_mimic_enabled: wp.array[wp.bool] | None#: Active flags for sparse mimic constraints, shape [constraint_mimic_count], bool.

Deprecated since version 1.7: Use ModelBuilder.set_joint_mimic() to configure joint-owned mimic metadata instead.

constraint_mimic_joint0: wp.array[wp.int32] | None#: Follower indices for sparse mimic constraints, shape [constraint_mimic_count], int.

Deprecated since version 1.7: Use joint_mimic_joint and ModelBuilder.set_joint_mimic() instead.

constraint_mimic_joint1: wp.array[wp.int32] | None#: Reference indices for sparse mimic constraints, shape [constraint_mimic_count], int.

Deprecated since version 1.7: Use joint_mimic_joint and ModelBuilder.set_joint_mimic() instead.

constraint_mimic_label: list[str]#: Sparse mimic constraint labels, shape [constraint_mimic_count], str.

Deprecated since version 1.7: Use ModelBuilder.set_joint_mimic() to configure joint-owned mimic metadata instead.

constraint_mimic_world: wp.array[wp.int32] | None#: World indices for sparse mimic constraints, shape [constraint_mimic_count], int.

Deprecated since version 1.7: Use ModelBuilder.set_joint_mimic() to configure joint-owned mimic metadata instead.

property contact_max: int | None#

Combined rigid and soft-rigid contact buffer capacity, or None before collision setup.

This is the row count for AttributeFrequency.CONTACT, not the number of active contacts. It excludes soft self-contact.

curve_body_end: wp.array[wp.int32] | None#: Experimental exclusive end of each curve’s body range, shape [curve_count].

curve_body_start: wp.array[wp.int32] | None#: Experimental inclusive start of each curve’s body range, shape [curve_count].

curve_count: int#: Experimental number of recorded rod-backed deformable objects.

curve_joint_end: wp.array[wp.int32] | None#: Experimental exclusive end of each curve’s joint range, shape [curve_count].

curve_joint_start: wp.array[wp.int32] | None#: Experimental inclusive start of each curve’s joint range, shape [curve_count].

curve_label: list[str]#

Experimental labels of rod-backed deformable objects, shape [curve_count].

Copied from ModelBuilder.curve_label at finalization. Treat this list as read-only; edit labels on the builder.

curve_world: wp.array[wp.int32] | None#: Experimental world indices for curve_label, shape [curve_count]. -1 means global.

custom_frequency_articulation: dict[str, wp.array[Any]]#: Per-row articulation owners for articulation-scoped custom frequencies.

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

custom_frequency_label_attributes: dict[str, str]#: Attribute keys containing labels for custom-frequency rows.

property deformable_visual_mesh_count: int#: Number of deformable visual meshes.

Experimental

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

property deformable_visual_meshes: tuple[DeformableVisualMesh, ...]#

Deformable visual meshes stored at finalization. Read-only.

The tuple is empty when no meshes were added. See DeformableVisualMesh.

Experimental

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

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

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

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

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

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

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

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

gaussians_count#: Number of gaussians.

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

gravity: wp.array[wp.vec3] | None#

Local-world and global gravity vectors [m/s²], shape [world_count + 1], dtype vec3.

Entries [0, world_count) are local-world gravities and the final entry is the gravity of global world -1, which is distinct from world 0 also in models built without explicit worlds.

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

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

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

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

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

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

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

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

Incoming joint of each joint’s parent body (-1 if none exists), shape [joint_count], int.

Articulated joints resolve ancestors only within their own articulation, terminating at external roots. For unarticulated joints, articulation tree joints take precedence over loop-closing joints.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

joint_mimic_coeffs: wp.array[wp.vec2] | None#: Mimic offset and multiplier applied componentwise [m or rad, dimensionless], shape [joint_count, 2], float.

joint_mimic_joint: wp.array[wp.int32] | None#: Independent reference joint index for each mimic joint, or -1 for an independent joint, shape [joint_count], int.

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

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

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

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

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

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

Joint rest configuration [m or rad; xyzw unit quaternion for rotations], shape [joint_coord_count].

Uses the layout of joint_q and indexing of joint_q_start. Scalar rest coordinates may lie outside the joint limits to produce preload. ROD joints store zero translation and their relative structural-rest rotation. SolverVBD reads only the quaternion entries, with material coefficients in joint_target_ke and joint_target_kd; see Rod joints.

joint_stiffness: wp.array[wp.float32] | None#: Passive spring stiffness [N/m or N·m/rad], shape [joint_dof_count]. Independent of drive gains.

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

Drive derivative gain [N·s/m or N·m·s/rad, depending on joint type], shape [joint_dof_count], float.

ROD joints use this array for material damping; see Rod joints.

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

Drive proportional gain [N/m or N·m/rad, depending on joint type], shape [joint_dof_count], float.

ROD joints use this array for material stiffness about joint_rest_q; see Rod joints.

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

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

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

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

Shape matches joint_q. Index via joint_target_q_start, which aliases joint_q_start. Ball and free joint rotations use unit quaternions.

ROD joints use joint_rest_q for structural rest and ignore drive targets; see Rod joints.

property joint_target_q_start: array | None#: Per-joint start index into joint_target_q, shape (joint_count + 1,). Aliases joint_q_start.

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

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

Matches the layout of joint_qd.

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

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

Deprecated since version 1.7: Limit joint rotations with the per-DOF joint_limit_lower instead.

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

Deprecated since version 1.7: Limit joint rotations with the per-DOF joint_limit_upper instead.

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

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

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

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

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

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

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

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

The total number of global joints can be computed as:

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

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

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

property mesh_edge_centers: wp.array[wp.vec4f] | None#

Packed collision-edge centers (xyz) and half-lengths (w), shape [total_edge_count, 4] [m].

Centers and half-lengths are in unscaled mesh coordinates.

Deprecated since version 1.8: This acceleration data is internal and the public alias will be removed in 1.9. Use CollisionPipeline; low-level geometry.NarrowPhase mesh-SDF collision relies on internal edge data without a stable public accessor.

property mesh_edge_halves: wp.array[wp.vec4f] | None#

Packed collision-edge half-vectors (xyz) [m] and unitless endpoint-ownership codes (w).

Shape [total_edge_count, 4]. Half-vectors are in unscaled mesh coordinates.

Deprecated since version 1.8: This acceleration data is internal and the public alias will be removed in 1.9. Use CollisionPipeline; low-level geometry.NarrowPhase mesh-SDF collision relies on internal edge data without a stable public accessor.

property mesh_edge_indices: wp.array[wp.vec2i] | None#: Packed collision-edge vertex pairs, shape [total_edge_count].

Deprecated since version 1.8: This acceleration data is internal and the public alias will be removed in 1.9. Use CollisionPipeline; low-level geometry.NarrowPhase mesh-SDF collision relies on internal edge data without a stable public accessor.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The total number of global particles can be computed as:

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

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

property rigid_contact_max: int | None#

Rigid contact buffer capacity, or None before collision setup.

CollisionPipeline publishes its resolved capacity, which later pipelines reuse as their default. Zero is a valid capacity.

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

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

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

property shape_collision_filter_pairs: Set[tuple[int, int]]#: Read-only set of explicit canonical shape index pairs that should not collide.

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

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

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

property shape_contact_pair_count: int#: Number of shape pairs. Read-only; does not construct the full pair array.

property shape_contact_pairs: wp.array[wp.vec2i] | None#

Pairs of shape indices that may collide, shape [shape_contact_pair_count], vec2i.

Constructed on first access; access it before CUDA graph capture if needed.

Default pairs omit static-static pairs and retain static-kinematic and kinematic-kinematic pairs.

Assign a replacement array to change pairs, or None to remove the model’s pair array and set its count to zero. In-place edits are unsupported.

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

property shape_edge_range: wp.array[wp.vec2i] | None#

Per-shape (start, count) into packed collision-edge arrays, shape [shape_count].

A range of (-1, 0) means no edges.

Deprecated since version 1.8: This acceleration data is internal and the public alias will be removed in 1.9. Use CollisionPipeline; low-level geometry.NarrowPhase mesh-SDF collision relies on internal edge data without a stable public accessor.

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

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

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

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

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

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

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

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

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

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

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

shape_material_kh: wp.array[wp.float32] | None#: Shape hydroelastic stiffness coefficient [N/m^3], shape [shape_count], float. Under the default linear pressure law, contact force scales with contact area, kh, and penetration depth.

shape_material_mu: wp.array[wp.float32] | None#: Shape coefficient of friction [dimensionless], shape [shape_count], float. The dynamic (kinetic) coefficient for solvers that model stick-slip friction (see shape_material_mu_static).

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

shape_material_mu_static: wp.array[wp.float32] | None#: Shape coefficient of static friction [dimensionless], shape [shape_count], float. Always holds the effective coefficient: ModelBuilder.finalize() resolves an unset ModelBuilder.ShapeConfig.mu_static to the shape’s final mu (direct edits of the builder’s shape_material_mu included) and rejects a value below it, so no entry is below shape_material_mu at finalize. The two arrays are independent afterwards: code that edits shape_material_mu at runtime and wants a single coefficient updates this array as well. Set via ModelBuilder.ShapeConfig.mu_static or a USD physics:staticFriction above physics:dynamicFriction. No built-in solver models stick-slip friction yet: SolverKamino carries the value into its material tables but its contact model uses the dynamic coefficient, and the other solvers read only shape_material_mu.

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

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

shape_opacity: wp.array[wp.float32] | None#: Shape display opacity [0, 1], shape [shape_count], float.

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

shape_source: list[object | None]#

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

Body variant rows keep the source they were finalized with; select_body_variants() updates shape_type and shape_source_ptr on the device only.

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

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

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

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

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

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

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

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

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

The total number of global shapes can be computed as:

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

soft_contact_kd: float#: Damping of soft contacts [N·s/m] (used by SolverSemiImplicit and SolverFeatherstone).

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

soft_contact_kf: float#: Soft contact friction gain [N·s/m] (used by SolverSemiImplicit and SolverFeatherstone).

property soft_contact_max: int | None#

Soft contact buffer capacity, or None before collision setup.

CollisionPipeline publishes its resolved capacity, including any enabled edge/face contact passes. Zero disables soft contacts.

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

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

soft_mesh_adjacency: MeshAdjacency | None#: Soft mesh topology and solver adjacency, or None before finalization.

soft_mesh_adjacency_device: MeshAdjacencyData | None#: Device-uploaded soft_mesh_adjacency, built once at finalization and shared by all consumers (VBD solver, collision pipeline). None before finalization.

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

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

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

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

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

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

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

surface_count: int#: Experimental number of recorded triangle-surface deformable objects.

surface_edge_end: wp.array[wp.int32] | None#: Experimental exclusive end of each surface’s edge range, shape [surface_count].

surface_edge_start: wp.array[wp.int32] | None#: Experimental inclusive start of each surface’s edge range, shape [surface_count].

surface_label: list[str]#

Experimental labels of triangle-surface deformable objects, shape [surface_count].

Copied from ModelBuilder.surface_label at finalization. Treat this list as read-only; edit labels on the builder.

surface_particle_end: wp.array[wp.int32] | None#: Experimental exclusive end of each surface’s particle range, shape [surface_count].

surface_particle_start: wp.array[wp.int32] | None#: Experimental inclusive start of each surface’s particle range, shape [surface_count].

surface_tri_end: wp.array[wp.int32] | None#: Experimental exclusive end of each surface’s triangle range, shape [surface_count].

surface_tri_start: wp.array[wp.int32] | None#: Experimental inclusive start of each surface’s triangle range, shape [surface_count].

surface_world: wp.array[wp.int32] | None#: Experimental world indices for surface_label, shape [surface_count]. -1 means global.

tendon_count: int#: Total number of tendons in the system.

tendon_guide_axis: wp.array[wp.vec3] | None#: Local-frame normal of the cable plane on each body [dimensionless], shape [tendon_guide_count], vec3.

tendon_guide_body: wp.array[wp.int32] | None#: Body index for each tendon guide, shape [tendon_guide_count], int.

tendon_guide_count: int#: Total number of tendon guides (waypoints) across all tendons.

tendon_guide_flags: wp.array[wp.int32] | None#: Routing flags for each tendon guide, shape [tendon_guide_count], int.

tendon_guide_mu: wp.array[wp.float32] | None#: Friction coefficient [dimensionless] at each tendon guide, shape [tendon_guide_count], float.

tendon_guide_offset: wp.array[wp.vec3] | None#: Local-frame offset of the cable plane center on each body [m], shape [tendon_guide_count], vec3.

tendon_guide_orientation: wp.array[wp.int32] | None#: Winding direction (+1 or -1) for each tendon guide, shape [tendon_guide_count], int.

tendon_guide_radius: wp.array[wp.float32] | None#: Contact radius [m] for each tendon guide, shape [tendon_guide_count], float.

tendon_guide_type: wp.array[wp.int32] | None#: Guide type for each tendon guide (TendonGuideType enum), shape [tendon_guide_count], int.

tendon_label: list[str]#: Tendon names, shape (tendon_count,).

tendon_segment_compliance: wp.array[wp.float32] | None#: Compliance [m/N] for each tendon segment, shape [tendon_segment_count], float.

tendon_segment_count: int#: Total number of tendon segments (= tendon_guide_count - tendon_count).

tendon_segment_damping: wp.array[wp.float32] | None#: Damping [N·s/m] for each tendon segment, shape [tendon_segment_count], float.

tendon_segment_rest_length: wp.array[wp.float32] | None#: Initial rest length [m] for each tendon segment, shape [tendon_segment_count], float.

tendon_start: wp.array[wp.int32] | None#: Start index into guide arrays for each tendon, shape [tendon_count + 1], int.

tendon_world: wp.array[int] | None#: Owning world for each tendon; -1 denotes the global world.

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

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

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

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

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

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

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

tri_color: wp.array[wp.vec3] | None#: Triangle surface display colors [0, 1], shape [tri_count], vec3.

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

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

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

tri_opacity: wp.array[wp.float32] | None#: Triangle surface display opacity [0, 1], shape [tri_count], float.

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

up_axis: int#

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

Type:: Up axis

volume_count: int#: Experimental number of recorded tetrahedral deformable objects.

volume_label: list[str]#

Experimental labels of tetrahedral deformable objects, shape [volume_count].

Copied from ModelBuilder.volume_label at finalization. Treat this list as read-only; edit labels on the builder.

volume_particle_end: wp.array[wp.int32] | None#: Experimental exclusive end of each volume’s particle range, shape [volume_count].

volume_particle_start: wp.array[wp.int32] | None#: Experimental inclusive start of each volume’s particle range, shape [volume_count].

volume_tet_end: wp.array[wp.int32] | None#: Experimental exclusive end of each volume’s tetrahedron range, shape [volume_count].

volume_tet_start: wp.array[wp.int32] | None#: Experimental inclusive start of each volume’s tetrahedron range, shape [volume_count].

volume_world: wp.array[wp.int32] | None#: Experimental world indices for volume_label, shape [volume_count]. -1 means global.

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