`taichi.lang.matrix`¶

Module Contents¶

Classes¶

`Matrix`	The matrix class.
`MatrixField`	Taichi matrix field with SNode implementation.
`MatrixType`
`MatrixNdarray`	Taichi ndarray with matrix elements.
`VectorNdarray`	Taichi ndarray with vector elements.

Functions¶

Vector(n, dt=None, **kwargs)

Construct a Vector instance i.e. 1-D Matrix.

Attributes¶

`field`
`ndarray`
`zero`
`one`
`dot`
`cross`
`outer_product`
`unit`
`normalized`

class taichi.lang.matrix.Matrix(n=1, m=1, dt=None, suppress_warning=False)¶

Bases: taichi.lang.common_ops.TaichiOperations

The matrix class.

Parameters

n (Union[int, list, tuple, np.ndarray]) – the first dimension of a matrix.
m (int) – the second dimension of a matrix.
dt (DataType) – the element data type.

is_taichi_class = True¶

element_wise_binary(self, foo, other)¶

broadcast_copy(self, other)¶

element_wise_ternary(self, foo, other, extra)¶

element_wise_writeback_binary(self, foo, other)¶

element_wise_unary(self, foo)¶

linearize_entry_id(self, *args)¶

set_entry(self, i, j, e)¶

subscript(self, *indices)¶

property x(self)¶: Get the first element of a matrix.

property y(self)¶: Get the second element of a matrix.

property z(self)¶: Get the third element of a matrix.

property w(self)¶: Get the fourth element of a matrix.

property value(self)¶

to_list(self)¶

set_entries(self, value)¶

cast(self, dtype)¶

Cast the matrix element data type.

Parameters: dtype (DataType) – the data type of the casted matrix element.
Returns: A new matrix with each element’s type is dtype.

trace(self)¶

The sum of a matrix diagonal elements.

Returns: The sum of a matrix diagonal elements.

inverse(self)¶

The inverse of a matrix.

Note

The matrix dimension should be less than or equal to 4.

Returns: The inverse of a matrix.
Raises: Exception – Inversions of matrices with sizes >= 5 are not supported.

normalized(self, eps=0)¶

Normalize a vector.

Parameters: eps (Number) – a safe-guard value for sqrt, usually 0.

Examples:

a = ti.Vector([3, 4])
a.normalized() # [3 / 5, 4 / 5]
# `a.normalized()` is equivalent to `a / a.norm()`.

Note

Only vector normalization is supported.

transpose(self)¶

Get the transpose of a matrix.

Returns: Get the transpose of a matrix.

determinant(a)¶

Get the determinant of a matrix.

Note

The matrix dimension should be less than or equal to 4.

Returns: The determinant of a matrix.
Raises: Exception – Determinants of matrices with sizes >= 5 are not supported.

static diag(dim, val)¶

Construct a diagonal square matrix.

Parameters

dim (int) – the dimension of a square matrix.
val (TypeVar) – the diagonal element value.

Returns

The constructed diagonal square matrix.

sum(self)¶: Return the sum of all elements.

norm(self, eps=0)¶

Return the square root of the sum of the absolute squares of its elements.

Parameters: eps (Number) – a safe-guard value for sqrt, usually 0.

Examples:

a = ti.Vector([3, 4])
a.norm() # sqrt(3*3 + 4*4 + 0) = 5
# `a.norm(eps)` is equivalent to `ti.sqrt(a.dot(a) + eps).`

Returns: The square root of the sum of the absolute squares of its elements.

norm_inv(self, eps=0)¶

Return the inverse of the matrix/vector norm. For norm: please see norm().

Parameters: eps (Number) – a safe-guard value for sqrt, usually 0.
Returns: The inverse of the matrix/vector norm.

norm_sqr(self)¶: Return the sum of the absolute squares of its elements.

max(self)¶: Return the maximum element value.

min(self)¶: Return the minimum element value.

any(self)¶

Test whether any element not equal zero.

Returns: True if any element is not equal zero, False otherwise.
Return type: bool

all(self)¶

Test whether all element not equal zero.

Returns: True if all elements are not equal zero, False otherwise.
Return type: bool

fill(self, val)¶

Fills the matrix with a specific value in Taichi scope.

Parameters: val (Union[int, float]) – Value to fill.

to_numpy(self, keep_dims=False)¶

Converts the Matrix to a numpy array.

Parameters: keep_dims (bool, optional) – Whether to keep the dimension after conversion. When keep_dims=False, the resulting numpy array should skip the matrix dims with size 1.
Returns: The result numpy array.
Return type: numpy.ndarray

static zero(dt, n, m=None)¶

Construct a Matrix filled with zeros.

Parameters

dt (DataType) – The desired data type.
n (int) – The first dimension (row) of the matrix.
m (int, optional) – The second dimension (column) of the matrix.

Returns

A Matrix instance filled with zeros.

Return type

Matrix

static one(dt, n, m=None)¶

Construct a Matrix filled with ones.

Parameters

dt (DataType) – The desired data type.
n (int) – The first dimension (row) of the matrix.
m (int, optional) – The second dimension (column) of the matrix.

Returns

A Matrix instance filled with ones.

Return type

Matrix

static unit(n, i, dt=None)¶

Construct an unit Vector (1-D matrix) i.e., a vector with only one entry filled with one and all other entries zeros.

Parameters

n (int) – The length of the vector.
i (int) – The index of the entry that will be filled with one.
dt (DataType, optional) – The desired data type.

Returns

An 1-D unit Matrix instance.

Return type

Matrix

static identity(dt, n)¶

Construct an identity Matrix with shape (n, n).

Parameters

dt (DataType) – The desired data type.
n (int) – The number of rows/columns.

Returns

A n x n identity Matrix instance.

Return type

Matrix

static rotation2d(alpha)¶

classmethod field(cls, n, m, dtype, shape=None, name='', offset=None, needs_grad=False, layout=Layout.AOS)¶

Construct a data container to hold all elements of the Matrix.

Parameters

n (int) – The desired number of rows of the Matrix.
m (int) – The desired number of columns of the Matrix.
dtype (DataType, optional) – The desired data type of the Matrix.
shape (Union[int, tuple of int], optional) – The desired shape of the Matrix.
name (string, optional) – The custom name of the field.
offset (Union[int, tuple of int], optional) – The coordinate offset of all elements in a field.
needs_grad (bool, optional) – Whether the Matrix need gradients.
layout (Layout, optional) – The field layout, i.e., Array Of Structure (AOS) or Structure Of Array (SOA).

Returns

A Matrix instance serves as the data container.

Return type

Matrix

classmethod ndarray(cls, n, m, dtype, shape, layout=Layout.AOS)¶

Defines a Taichi ndarray with matrix elements.

Parameters

n (int) – Number of rows of the matrix.
m (int) – Number of columns of the matrix.
dtype (DataType) – Data type of each value.
shape (Union[int, tuple[int]]) – Shape of the ndarray.
layout (Layout, optional) – Memory layout, AOS by default.

Example

The code below shows how a Taichi ndarray with matrix elements can be declared and defined:

>>> x = ti.Matrix.ndarray(4, 5, ti.f32, shape=(16, 8))

static rows(rows)¶

Construct a Matrix instance by concatenating Vectors/lists row by row.

Parameters: rows (List) – A list of Vector (1-D Matrix) or a list of list.
Returns: A Matrix instance filled with the Vectors/lists row by row.
Return type: Matrix

static cols(cols)¶

Construct a Matrix instance by concatenating Vectors/lists column by column.

Parameters: cols (List) – A list of Vector (1-D Matrix) or a list of list.
Returns: A Matrix instance filled with the Vectors/lists column by column.
Return type: Matrix

dot(self, other)¶

Perform the dot product with the input Vector (1-D Matrix).

Parameters: other (Matrix) – The input Vector (1-D Matrix) to perform the dot product.
Returns: The dot product result (scalar) of the two Vectors.
Return type: DataType

cross(self, other)¶

Perform the cross product with the input Vector (1-D Matrix).

Parameters: other (Matrix) – The input Vector (1-D Matrix) to perform the cross product.
Returns: The cross product result (1-D Matrix) of the two Vectors.
Return type: Matrix

outer_product(self, other)¶

Perform the outer product with the input Vector (1-D Matrix).

Parameters: other (Matrix) – The input Vector (1-D Matrix) to perform the outer product.
Returns: The outer product result (Matrix) of the two Vectors.
Return type: Matrix

taichi.lang.matrix.Vector(n, dt=None, **kwargs)¶

Construct a Vector instance i.e. 1-D Matrix.

Parameters

n (Union[int, list, tuple], np.ndarray) – The desired number of entries of the Vector.
dt (DataType, optional) – The desired data type of the Vector.

Returns

A Vector instance (1-D Matrix).

Return type

Matrix

taichi.lang.matrix.field¶

taichi.lang.matrix.ndarray¶

taichi.lang.matrix.zero¶

taichi.lang.matrix.one¶

taichi.lang.matrix.dot¶

taichi.lang.matrix.cross¶

taichi.lang.matrix.outer_product¶

taichi.lang.matrix.unit¶

taichi.lang.matrix.normalized¶

class taichi.lang.matrix.MatrixField(_vars, n, m)¶

Bases: taichi.lang.field.Field

Taichi matrix field with SNode implementation.

Parameters

vars (List[Expr]) – Field members.
n (Int) – Number of rows.
m (Int) – Number of columns.

get_scalar_field(self, *indices)¶

Creates a ScalarField using a specific field member. Only used for quant.

Parameters: indices (Tuple[Int]) – Specified indices of the field member.
Returns: The result ScalarField.
Return type: ScalarField

calc_dynamic_index_stride(self)¶

fill(self, val)¶

Fills self with specific values.

Parameters: val (Union[Number, List, Tuple, Matrix]) – Values to fill, which should have dimension consistent with self.

to_numpy(self, keep_dims=False, dtype=None)¶

Converts the field instance to a NumPy array.

Parameters

keep_dims (bool, optional) – Whether to keep the dimension after conversion. When keep_dims=True, on an n-D matrix field, the numpy array always has n+2 dims, even for 1x1, 1xn, nx1 matrix fields. When keep_dims=False, the resulting numpy array should skip the matrix dims with size 1. For example, a 4x1 or 1x4 matrix field with 5x6x7 elements results in an array of shape 5x6x7x4.
dtype (DataType, optional) – The desired data type of returned numpy array.

Returns

The result NumPy array.

Return type

numpy.ndarray

to_torch(self, device=None, keep_dims=False)¶

Converts the field instance to a PyTorch tensor.

Parameters

device (torch.device, optional) – The desired device of returned tensor.
keep_dims (bool, optional) – Whether to keep the dimension after conversion. See to_numpy() for more detailed explanation.

Returns

The result torch tensor.

Return type

torch.tensor

from_numpy(self, arr)¶

class taichi.lang.matrix.MatrixType(n, m, dtype)¶

Bases: taichi.types.CompoundType

cast(self, mat)¶

filled_with_scalar(self, value)¶

field(self, **kwargs)¶

class taichi.lang.matrix.MatrixNdarray(n, m, dtype, shape, layout)¶

Bases: taichi.lang._ndarray.Ndarray

Taichi ndarray with matrix elements.

Parameters

n (int) – Number of rows of the matrix.
m (int) – Number of columns of the matrix.
dtype (DataType) – Data type of each value.
shape (Union[int, tuple[int]]) – Shape of the ndarray.
layout (Layout) – Memory layout.

property element_shape(self)¶

to_numpy(self)¶

from_numpy(self, arr)¶

fill_by_kernel(self, val)¶

class taichi.lang.matrix.VectorNdarray(n, dtype, shape, layout)¶

Bases: taichi.lang._ndarray.Ndarray

Taichi ndarray with vector elements.

Parameters

n (int) – Size of the vector.
dtype (DataType) – Data type of each value.
shape (Tuple[int]) – Shape of the ndarray.
layout (Layout) – Memory layout.

property element_shape(self)¶

to_numpy(self)¶

from_numpy(self, arr)¶

fill_by_kernel(self, val)¶

taichi.lang.matrix¶

Module Contents¶

Classes¶

Functions¶

Attributes¶

`taichi.lang.matrix`¶