newton.selection.DeformableCurveView#

class newton.selection.DeformableCurveView(model, pattern, *, verbose=None)[source]#

Select curves by label and read or update their segment body state.

Experimental

This API may change while deformable selection is developed.

Currently supports rod-backed curves with body and joint ranges. The family describes geometry, not a solver: particle-based curves are not supported yet. Matching surfaces and volumes are excluded from the selection.

After fixed-joint collapse, the view describes the curve’s surviving segment bodies and joints. Curves with no remaining bodies are omitted. Use collapse_fixed_joints() with joints_to_keep to preserve the original segment layout.

See Deformable Selection for world layout, getter-result lifetime, masked writes, and CUDA graph capture.

Parameters:

model (Model) – Model containing the finalized deformable objects.
pattern (str | list[str] | re.Pattern[str] | list[int]) – Label glob, list of label globs, compiled regular expression, or unique ascending indices into curve_label.
verbose (bool | None) – If True, log a short selection summary. If None, follow Warp’s logging level.

Methods

`__init__`(model, pattern, *[, verbose])
`deformable_object_ranges`()	Return one range of selected deformable-object indices per world.
`element_count`(kind)	Elements of `kind` per selected deformable object, or `None` when counts differ.
`get_body_transforms`(source)	Body transforms, shape `(count, body_count)`.
`get_body_velocities`(source)	Body velocities, shape `(count, body_count)`.
`ranges`(kind)	`[start, end)` element ranges of the selected deformable objects, in selection order.
`set_body_transforms`(target, values, *[, mask])	Write body transforms for the masked deformable objects.
`set_body_velocities`(target, values, *[, mask])	Write body velocities for the masked deformable objects.
`set_mask_from_indices`(mask, ...)	Replace a caller-owned mask with the selected deformable objects.
`starts`(kind)	Device-side element-range starts of the selected deformable objects, shape `(count,)`.

Attributes

`body_count`	Bodies per selected deformable object, or `None` when counts differ.
`count`	Number of selected deformable objects across all worlds.
`count_per_world`	Selected deformable objects per model world, or None when the counts vary.
`family`	Geometric family selected by this view.
`labels`	Label of each selected deformable object, ordered world by world.
`worlds`	Read-only Python list of model world indices, one per selected deformable object.
`deformable_object_boundaries`	Device-side deformable-object boundaries by world.
`worlds_device`	Read-only device copy of `worlds`, shape `(count,)`.

__init__(model, pattern, *, verbose=None)#

deformable_object_ranges()#

Return one range of selected deformable-object indices per world.

Each (start, end) pair slices labels or rows of batched state returned by this view. Use deformable_object_ranges()[world_id] to look up a world. The end is excluded. Empty worlds have equal start and end values. These are selected deformable object indices, not the simulation element indices returned by ranges().

A global-only selection has one range, (0, count), and its worlds_device entries are all -1. This single range is not indexed by a model world ID.

Returns:: One range per model world, including empty worlds, or one range for a global-only selection.
Return type:: list[tuple[int, int]]

element_count(kind)#

Elements of kind per selected deformable object, or None when counts differ.

Current rods record body/joint ranges, triangle surfaces record particle/triangle/edge ranges, and tetrahedral volumes record particle/tetrahedron ranges. Batched reads and writes require a common count; ranges() remains available when counts differ. particle_count and body_count are convenience properties for this query on their corresponding state element kinds.

Parameters:

kind (AttributeFrequency | Literal['body', 'joint', 'particle', 'triangle', 'edge', 'tetrahedron']) – Element kind recorded by every selected deformable object: a AttributeFrequency member such as PARTICLE or its lowercase name.

Returns:

Common number of elements per selected deformable object, or None.

Raises:

TypeError – If kind is not an AttributeFrequency member or a string.
ValueError – If the selected deformable objects do not record kind.

Return type:

int | None

get_body_transforms(source)#

Body transforms, shape (count, body_count).

Each transform contains a world-space translation [m] and a unitless quaternion.

Parameters:: source (Model | State) – Model initial state or simulation state to read.
Returns:: Body transforms with shape (count, body_count).
Raises:: ValueError – If body counts differ or the source array’s rank, dtype, device, or length is incompatible with the selection.
Return type:: wp.array2d[wp.transform]

get_body_velocities(source)#

Body velocities, shape (count, body_count).

Each value follows (v_com_world, omega_world): linear velocity [m/s] followed by angular velocity [rad/s].

Parameters:: source (Model | State) – Model initial state or simulation state to read.
Returns:: Body velocities with shape (count, body_count).
Raises:: ValueError – If body counts differ or the source array’s rank, dtype, device, or length is incompatible with the selection.
Return type:: wp.array2d[wp.spatial_vector]

ranges(kind)#

[start, end) element ranges of the selected deformable objects, in selection order.

For consumers that need each deformable object’s raw slice of the flat model arrays, e.g. to hand per-instance offsets to a renderer sync or to custom kernels. See element_count() for the valid kind values.

Native and USD curves include their construction-time root joints. After fixed-joint collapse, only surviving bodies and joints are exposed. A welded USD graph is one deformable object with the whole graph’s body and joint ranges. Its per-curve import maps are separate and keep empty joint lists. See Rod graphs.

Parameters:

kind (AttributeFrequency | Literal['body', 'joint', 'particle', 'triangle', 'edge', 'tetrahedron']) – Element kind recorded by every selected deformable object: a AttributeFrequency member or its lowercase name.

Returns:

One [start, end) range per selected deformable object.

Raises:

TypeError – If kind is not an AttributeFrequency member or a string.
ValueError – If the selected deformable objects do not record kind.

Return type:

list[tuple[int, int]]

set_body_transforms(target, values, *, mask=None)#

Write body transforms for the masked deformable objects.

Values stay in view order, including rows that are masked off. Keep values and masks unchanged until backward completes when using a tape. Preallocated device inputs require no temporary arrays during capture.

Parameters:

target (Model | State) – Model initial state or simulation state to update.
values (Any) – Body transforms with world-space translation [m] and a unitless quaternion, shape (count, body_count). Must not share storage with the target array; clone live getter results before writing. Host inputs are reshaped with a final axis of length 7. None is invalid.
mask (Any) – Boolean array of shape (count,) on the view’s device, or a host Boolean sequence outside capture. True updates that selected deformable object. None updates the whole selection.

Raises:

ValueError – If element counts, array shapes/dtypes/devices, mask, target capacity, or non-overlap requirements are not satisfied.
RuntimeError – If host values or a host mask are passed during CUDA capture.

set_body_velocities(target, values, *, mask=None)#

Write body velocities for the masked deformable objects.

Values stay in view order, including rows that are masked off. Keep values and masks unchanged until backward completes when using a tape. Preallocated device inputs require no temporary arrays during capture.

Parameters:

target (Model | State) – Model initial state or simulation state to update.
values (Any) – Body velocities in (v_com_world, omega_world) order [m/s, rad/s], shape (count, body_count). Must not share storage with the target array; clone live getter results before writing. Host inputs are reshaped with a final axis of length 6. None is invalid.
mask (Any) – Boolean array of shape (count,) on the view’s device, or a host Boolean sequence outside capture. True updates that selected deformable object. None updates the whole selection.

Raises:

ValueError – If element counts, array shapes/dtypes/devices, mask, target capacity, or non-overlap requirements are not satisfied.
RuntimeError – If host values or a host mask are passed during CUDA capture.

set_mask_from_indices(mask, deformable_object_indices)#

Replace a caller-owned mask with the selected deformable objects.

Indices refer to rows of this view, not model-global IDs. Their order does not reorder values passed to setters. Repeats select an object once. An empty selector clears the mask. Device inputs need no host copy or temporary allocation and can change between CUDA graph replays.

Parameters:

mask (wp.array[wp.bool]) – Output Boolean array with shape (count,) on the view’s device. Non-overlapping strided arrays are supported.
deformable_object_indices (Any) – Host integer sequence outside capture, or a one-dimensional int32 Warp array on the view’s device. Invalid host indices raise; invalid device indices are ignored, so fixed-capacity device selectors may use -1 for unused entries.

Raises:

TypeError – If the output is not a Warp array or a host index is not an integer. Booleans are not indices.
ValueError – If shapes, dtypes, devices, host bounds, or output strides are invalid. Validation failures leave the output unchanged.
RuntimeError – If host indices are passed during CUDA capture.

starts(kind)#

Device-side element-range starts of the selected deformable objects, shape (count,).

Together with element_count() this drives custom kernels over the selection without a host round-trip; the view’s own gather/scatter kernels use the same array. Treat the returned internal array as read-only.

Parameters:

kind (AttributeFrequency | Literal['body', 'joint', 'particle', 'triangle', 'edge', 'tetrahedron']) – Element kind recorded by every selected deformable object: a AttributeFrequency member or its lowercase name.

Returns:

Device array containing one start index per selected deformable object.

Raises:

TypeError – If kind is not an AttributeFrequency member or a string.
ValueError – If the selected deformable objects do not record kind.

Return type:

wp.array[wp.int32]

property body_count: int | None#: Bodies per selected deformable object, or None when counts differ.

count#: Number of selected deformable objects across all worlds.

count_per_world#

Selected deformable objects per model world, or None when the counts vary.

Empty model worlds count as zero, so counts of [1, 0, 1] give None. A global-only selection has one partition and returns count.

deformable_object_boundaries: wp.array[wp.int32]#

Device-side deformable-object boundaries by world.

There is one boundary per model world plus a final end boundary. A global-only selection has two boundaries.

World i spans selected deformable object indices from deformable_object_boundaries[i] to deformable_object_boundaries[i + 1], excluding the end. The final entry is the selected deformable object count. Treat this array as read-only. See deformable_object_ranges() for the corresponding Python ranges and the global-only case.

family#: Geometric family selected by this view.

labels#: Label of each selected deformable object, ordered world by world.

worlds#

Read-only Python list of model world indices, one per selected deformable object.

worlds_device holds the same mapping on the model’s device. Both are created with the view; editing either does not update the other.

worlds_device: wp.array[wp.int32]#

Read-only device copy of worlds, shape (count,).

Created on the model’s device with the view. Each entry is the model world of that selected deformable object, or -1 for a global object.