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)