Y YASPS
Docs menu
Getting started Scene Mesh Primitive Primitive union Connectivity Attribute Minimizer Solver Differentiator Matrix Jacobian Hessian Gradient Examples Dropping in a container Cubify Inverse simulation

API reference · 03

Primitive

A primitive represents a repeated element type, such as vertices, edges, triangles, tetrahedra, or contact pairs.

A primitive object is often created under the scene using mesh.addPrimitive. We normally never construct a primitive explicitly from the constructor.

model = world.addMesh("model")
vertices = model.addPrimitive("vertices", numInstances=positions.shape[0])

addAttribute

addAttribute(name, computed_attribute=None, rows=1, cols=1, through=None, source=None)

Create stored data, bind a computed expression, or join an attribute from another primitive through a connectivity.

Parameter Type Default Description
name str required Name stored in the primitive attribute dictionary.
computed_attribute attribute or None None Symbolic expression to bind to this primitive.
rows int 1 Per-instance row count for a new data attribute.
cols int 1 Per-instance column count for a new data attribute.
through connectivity or None None Connectivity from this primitive to the source primitive.
source attribute or None None Source attribute to join. When omitted with through, YASPS looks for the same name on the target primitive.

Example

# Data attributes whose value will be supported by user
position = vertices.addAttribute("position", rows=3, cols=1)

# Computed expression
speed_squared = vertices.addAttribute("speed_squared", computed_attribute=velocity * velocity)

# Attribute joined through connectivity
tet_positions = tetrahedra.addAttribute("positions", through=tetrahedra_to_vertices, source=position)

Only one creation mode should be used per call. When computed_attribute is supplied, it takes precedence; otherwise through performs a join; otherwise rows and cols create stored data.

Returns: attribute.

Raises: ValueError for a duplicate name or an incompatible connectivity or source.

addConstant

addConstant(name, rows=1, cols=1)

Create a constant attribute on the primitive. Its value can be updated, but YASPS treats it as constant during differentiation and excludes it from minimization targets.

Parameter Type Default Description
name str required Name stored in the primitive attribute dictionary.
rows int 1 Per-instance row count.
cols int 1 Per-instance column count.

Example

rest_position = vertices.addConstant("rest_position", rows=3, cols=1)
mass = vertices.addConstant("mass")

Returns: attribute.

Raises: ValueError for a duplicate name.

addConnectivity

addConnectivity(name, to, data, dimension)

Create a directed connectivity from this primitive to another primitive in the same mesh. The connectivity is also available on the source primitive by name.

Parameter Type Description
name str Nonempty connectivity identifier. Must be valid and unique within the primitive.
to primitive Target primitive in the same mesh.
data numpy.ndarray or list[list[int]] Target-instance indices for every source instance.
dimension int Number of target indices per source instance. The current examples use fixed positive dimensions.

Example

tetrahedra_to_vertices = tetrahedra.addConnectivity("to_vertices", to=vertices, data=tet_indices, dimension=4)

assert tetrahedra.to_vertices is tetrahedra_to_vertices

Returns: connectivity.

Raises: ValueError when the name already exists or is invalid, or when the target belongs to another mesh.

updateNumInstances

updateNumInstances(numInstances)

Change the instance count of a dynamic primitive created with isDynamic=True.

Parameter Type Description
numInstances int New nonnegative instance count.

Example

contact_pairs.updateNumInstances(contact_count)

Returns: None.

Raises: ValueError when the primitive is not dynamic or the new count is negative.

__getitem__

primitive[key]

Retrieve a named primitive attribute.

Key Result
str The named attribute.

Example

position = vertices["position"]

Raises: KeyError when the attribute is missing or the key is not a string.

Properties

Property Type Description
isDynamic bool Whether updateNumInstances may change the instance count.
name str Primitive identifier supplied to mesh.addPrimitive.
mesh mesh Mesh that owns this primitive.
scene scene Scene reached through the owning mesh.
primitive primitive This primitive itself.
connectivities dict[str, connectivity] Named outgoing connectivities.
type str Always "primitive".
numInstances int Current number of primitive instances.
attributes dict[str, attribute] Named attributes and constants owned by the primitive.
attributesNames list[str] Names currently stored in attributes.
numConnectivities int Number of entries in connectivities.
fullName str Scene- and mesh-qualified primitive identifier.