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 · 06

Attribute

attribute is the YASPS value type for stored data, constants, and symbolic expressions.

Most attributes are created by addAttribute or addConstant on a scene, mesh, primitive, or primitive union. This is because most attributes need to know where they belong, which gives us the information about how many instances this attribute contains, and if an operation between two attributes should be allowed.

For example, the following operation is allowed since x and y belongs to the same primitive

y = primitiveA.addAttribute(rows = 3, cols = 1)
z = x + y

The following is also allowed since meshA is a direct ancestor of primitiveA, and the dimension of the operation also checks out:

primitiveA = meshA.addPrimitive(numInstances = ...)
u = meshA.addAttribute(rows = 1, cols = 1)
v = primitiveA.addAttribute(rows = 3, cols = 1)
t = u * v

But the following operation is not allowed since we cannot infer that primitiveA and primitiveB do not form direct ancestry:

x = primitiveA.addAttribute(rows = 3, cols = 1)
y = primitiveB.addAttribute(rows = 3, cols = 1)
z = x + y

attribute

attribute(float_value=value)

Create a literal scalar attribute for use inside a symbolic expression.

Parameter Type Description
float_value float Literal scalar value.

Example

zero = attribute(float_value=0.0)

Stored attributes should be created through an owning scene, mesh, primitive, or primitive union instead of by calling the full internal constructor.

Returns: attribute with shape 1 × 1.

updateValue

updateValue(value, deepCopy=False)

Set the GPU value of a stored or constant attribute.

Parameter Type Default Description
value numpy.ndarray, pycuda.gpuarray.GPUArray, or array-like required Values flattened in row-major order and stored as float64.
deepCopy bool False Copy GPU data into separate storage instead of retaining the supplied GPU array.

Example

position.updateValue(vertex_positions)
last_position.updateValue(position.value, deepCopy=True)

Returns: None.

Raises: ValueError when the value cannot be converted to an array.

compute

compute()

Compile and evaluate a symbolic attribute on the GPU. Stored and constant attributes return immediately because their values already exist.

Example

computed_position = position_expression.compute()
position_gpu = computed_position.value

Returns: the same attribute, with value populated.

to_array

attribute.to_array(children, rows, cols)

Assemble a list of scalar attributes (attributes with dimension of 1 by 1) into one matrix-shaped attribute.

Parameter Type Description
children list[attribute, float, int] Elements in row-major order. Numeric values become scalar attributes.
rows int Result row count.
cols int Result column count.

Example

x = meshA.addAttribute(rows = 3, cols = 2)
gravity = attribute.to_array([x[0], -9.8, x[1, 2]], rows=3, cols=1)

Returns: matrix-shaped attribute.

Raises: ValueError when rows * cols does not match the number of children.

identity

attribute.identity(rows)

Create a square identity-matrix attribute.

Parameter Type Description
rows int Number of rows and columns.

Example

rotation = attribute.identity(3)

Returns: rows × rows attribute containing literal zeros and ones.

__getitem__

attribute[index]

Extract one element. A single integer uses flattened row-major indexing.

Index Result
int Scalar attribute at the flattened index.

Example

position = mesh.addAttribute(rows = 3, cols = 1)
x = position[0]
deformation_gradient = mesh.addAttribute(rows = 3, cols = 3)
entry = deformation_gradient[1, 2]

Raises: ValueError for an unsupported index or an index outside the attribute shape.

row

row(index)

Extract one row as a 1 × cols attribute.

Parameter Type Description
index int Zero-based row index.

Example

first_vertex = tetrahedron_positions.row(0)

Returns: row attribute.

Raises: ValueError when the row is outside the attribute shape.

reshape

reshape(rows, cols)

Change this attribute’s stored row and column counts in place. This updates shape metadata only and does not create an operation for code generation.

Parameter Type Description
rows int New row count.
cols int New column count.

Example

joined_affine_values.reshape(3, 3)

Returns: None.

Raises: ValueError when the new shape has a different number of elements.

resize

resize(rows, cols)

Create a symbolic resize operation with the requested shape. The source attribute is unchanged, and the operation is preserved for code generation.

Parameter Type Description
rows int New row count.
cols int New column count.

Example

affine_matrix = joined_affine_values.resize(3, 3)

Returns: symbolic resized attribute.

Raises: ValueError when the new shape has a different number of elements.

Supported operations

In this table, a attribute is a scalar when its shape is 1 × 1, and a matrix includes row and column vectors. Dimension check still applies to all those operations, but only applies to the per instance shape (as opposed to the actual GPU data array shape).

Operation Syntax Level Behavior
Addition a + b Scalar and matrix If both a and b have equal shape, it adds up element-wise. Otherwise, this becomes a broadcast add
Subtraction a - b Scalar and matrix Same thing except it’s subtraction.
Negation -a Scalar and matrix Negates every element.
Multiplication a * b Scalar and matrix Multiplies by a scalar, or performs matrix multiplication for compatible non-scalar shapes.
Division a / b Scalar denominator Divides a scalar or matrix by a scalar attribute or Python float.
Power a.pow(b) Scalar Raises one scalar to a scalar power.
Square root a.sqrt() Scalar Returns the scalar square root.
Natural logarithm a.log() Scalar Returns the scalar natural logarithm.
Sine a.sin() Scalar Returns the scalar sine.
Cosine a.cos() Scalar Returns the scalar cosine.
Absolute value a.abs() Scalar and matrix Applies absolute value element-wise.
Two-argument arctangent a.atan2(b) Scalar Computes atan2(a, b) for two scalars.
Transpose a.transpose() Matrix Swaps rows and columns.
Resize a.resize(rows, cols) Scalar and matrix Creates a symbolic shape change while preserving the element count.
Trace a.trace() Square matrix Sums the diagonal and returns a scalar.
Positive-semidefinite projection a.spd(method) Square matrix Method 0 keeps eigenvalues, 1 takes their absolute values, and 2 clamps negative values to zero.
Norm a.norm() Scalar or vector Returns the vector norm. A scalar is returned unchanged.
Dot product a.dot(b) Vector Returns a scalar for two vectors with equal element counts.
Cross product a.cross(b) 3-element vector Returns a 3 × 1 vector.
Inverse a.inverse() Scalar or square matrix Returns a reciprocal for a scalar or the matrix inverse.
Determinant a.determinant() Scalar or square matrix Returns a scalar determinant.
Symbolic equality a.eq(b) Equal shapes Returns a scalar condition. Python a == b checks expression identity instead.
Symbolic inequality a.neq(b) Equal shapes Returns a scalar condition.
Ordering a > b, a >= b, a < b, a <= b Equal shapes Returns a scalar condition.
Selection attribute.select(condition, a, b) Scalar condition. Branches can be equal-shaped scalar or matrix attributes. Selects between equal-shaped branches and preserves their shape.

Example

edge = positions.row(1) - positions.row(0)
length = edge.norm()

deformation = current.transpose() * rest.inverse()
energy = attribute.select(length > threshold, length.pow(2.0), zero)

Each operation returns another symbolic attribute. Evaluation happens when compute() or the minimizer requests it.

Properties

Property Type Description
rows int Per-instance row count.
cols int Per-instance column count.
size int Number of elements per instance: rows * cols.
value pycuda.gpuarray.GPUArray Flattened GPU values. Call compute() first for a symbolic expression.
correspondance scene, mesh, primitive, or primitive union Object whose instances index this attribute. The spelling matches the public API.