newton.selection.DeformableSurfaceView#

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

Select surfaces by label and read or update their particle state.

Experimental

This API may change while deformable selection is developed.

Currently supports triangle surfaces with particle, triangle, and edge ranges. Particle getters also read inverse masses and flags from the Model. The family describes geometry, not a solver. Matching curves and volumes are excluded from the selection.

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 surface_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_particle_flags`(source)	Return `ParticleFlags` bitmasks for the selected deformable objects.
`get_particle_inv_masses`(source)	Return particle inverse masses [1/kg] for the selected deformable objects.
`get_particle_positions`(source)	Return particle positions [m] for the selected deformable objects.
`get_particle_velocities`(source)	Return particle velocities [m/s] for the selected deformable objects.
`ranges`(kind)	`[start, end)` element ranges of the selected deformable objects, in selection order.
`set_mask_from_indices`(mask, ...)	Replace a caller-owned mask with the selected deformable objects.
`set_particle_positions`(target, values, *[, mask])	Write particle positions for the masked deformable objects.
`set_particle_velocities`(target, values, *[, ...])	Write particle velocities for the masked deformable objects.
`starts`(kind)	Device-side element-range starts of the selected deformable objects, shape `(count,)`.

Attributes

`particle_count`	Particles 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_particle_flags(source)#

Return ParticleFlags bitmasks for the selected deformable objects.

The result shares Model storage or uses a reusable read buffer. Use wp.clone() to save an independent snapshot; do not edit the result.

Parameters:

source (Model) – Model whose particle numbering matches this view. This property is not stored on State.

Returns:

Integer bitmasks with shape (count, particle_count).

Raises:

AttributeError – If the source does not provide particle flags.
ValueError – If particle counts differ or the source array’s rank, dtype, device, or length is incompatible with the selection.

Return type:

wp.array2d[wp.int32]

get_particle_inv_masses(source)#

Return particle inverse masses [1/kg] for the selected deformable objects.

The result shares Model storage or uses a reusable read buffer. Use wp.clone() to save an independent snapshot; do not edit the result.

Parameters:

source (Model) – Model whose particle numbering matches this view. This property is not stored on State.

Returns:

Inverse masses with shape (count, particle_count).

Raises:

AttributeError – If the source does not provide particle inverse masses.
ValueError – If particle counts differ or the source array’s rank, dtype, device, or length is incompatible with the selection.

Return type:

wp.array2d[wp.float32]

get_particle_positions(source)#

Return particle positions [m] for the selected deformable objects.

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

get_particle_velocities(source)#

Return particle velocities [m/s] for the selected deformable objects.

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

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

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

Write particle positions 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) – Particle positions [m], shape (count, particle_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 3. 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_particle_velocities(target, values, *, mask=None)#

Write particle 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) – Particle velocities [m/s], shape (count, particle_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 3. 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.

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]

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.

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

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.