diff --git a/docs/tensor_matrix.rst b/docs/tensor_matrix.rst index c1b1f814937fa..e7e2acf22be00 100644 --- a/docs/tensor_matrix.rst +++ b/docs/tensor_matrix.rst @@ -1,41 +1,41 @@ .. _tensor: -Tensors and matrices -==================== +Fields and matrices +=================== -Tensors are global variables provided by Taichi. Tensors can be either sparse or dense. -An element of a tensor can be either a scalar or a vector/matrix. +Fields are global variables provided by Taichi. Fields can be either sparse or dense. +An element of a field can be either a scalar or a vector/matrix. .. note:: - Although mathematically matrices are treated as 2D tensors, in Taichi, **tensor** and **matrix** are two completely different concepts. - Matrices can be used as tensor elements, so you can have tensors with each element being a matrix. + Although mathematically matrices are treated as 2D fields, in Taichi, **field** and **matrix** are two completely different concepts. + Matrices can be used as field elements, so you can have fields with each element being a matrix. -Tensors of scalars ------------------- -* Every global variable is an N-dimensional tensor. +Fields of scalars +----------------- +* Every global variable is an N-dimensional field. - - Global ``scalars`` are treated as 0-D tensors of scalars. + - Global ``scalars`` are treated as 0-D fields of scalars. -* Tensors are always accessed using indices +* Fields are always accessed using indices - - E.g. ``x[i, j, k]`` if ``x`` is a scalar 3D tensor. - - Even when accessing 0-D tensor ``x``, use ``x[None] = 0`` instead of ``x = 0``. Please **always** use indexing to access entries in tensors. + - E.g. ``x[i, j, k]`` if ``x`` is a scalar 3D field. + - Even when accessing 0-D field ``x``, use ``x[None] = 0`` instead of ``x = 0``. Please **always** use indexing to access entries in fields. -* Tensor values are initially zero. -* Sparse tensors are initially inactive. +* Field values are initially zero. +* Sparse fields are initially inactive. * See :ref:`scalar_tensor` for more details. -Tensors of matrices -------------------- -Tensor elements can also be matrices. +Fields of matrices +------------------ +Field elements can also be matrices. -Suppose you have a ``128 x 64`` tensor called ``A``, each element containing a ``3 x 2`` matrix. To allocate a ``128 x 64`` tensor of ``3 x 2`` matrix, use the statement ``A = ti.Matrix.field(3, 2, dtype=ti.f32, shape=(128, 64))``. +Suppose you have a ``128 x 64`` field called ``A``, each element containing a ``3 x 2`` matrix. To allocate a ``128 x 64`` field of ``3 x 2`` matrix, use the statement ``A = ti.Matrix.field(3, 2, dtype=ti.f32, shape=(128, 64))``. * If you want to get the matrix of grid node ``i, j``, please use ``mat = A[i, j]``. ``mat`` is simply a ``3 x 2`` matrix * To get the element on the first row and second column of that matrix, use ``mat[0, 1]`` or ``A[i, j][0, 1]``. -* As you may have noticed, there are **two** indexing operators ``[]`` when you load an matrix element from a global tensor of matrices: the first is for tensor indexing, the second for matrix indexing. +* As you may have noticed, there are **two** indexing operators ``[]`` when you load an matrix element from a global field of matrices: the first is for field indexing, the second for matrix indexing. * ``ti.Vector`` is simply an alias of ``ti.Matrix``. * See :ref:`matrix` for more on matrices. @@ -49,6 +49,6 @@ For example, ``2x1``, ``3x3``, ``4x4`` matrices are fine, yet ``32x6`` is probab Due to the unrolling mechanisms, operating on large matrices (e.g. ``32x128``) can lead to very long compilation time and low performance. -If you have a dimension that is too large (e.g. ``64``), it's better to declare a tensor of size ``64``. +If you have a dimension that is too large (e.g. ``64``), it's better to declare a field of size ``64``. E.g., instead of declaring ``ti.Matrix.field(64, 32, dtype=ti.f32, shape=(3, 2))``, declare ``ti.Matrix.field(3, 2, dtype=ti.f32, shape=(64, 32))``. -Try to put large dimensions to tensors instead of matrices. +Try to put large dimensions to fields instead of matrices. diff --git a/docs/vector.rst b/docs/vector.rst index 1f00d208fa8f8..401b38f3720f8 100644 --- a/docs/vector.rst +++ b/docs/vector.rst @@ -6,24 +6,24 @@ Vectors A vector in Taichi can have two forms: - as a temporary local variable. An ``n`` component vector consists of ``n`` scalar values. - - as an element of a global tensor. In this case, the tensor is an N-dimensional array of ``n`` component vectors. + - as an element of a global field. In this case, the field is an N-dimensional array of ``n`` component vectors. In fact, ``Vector`` is simply an alias of ``Matrix``, just with ``m = 1``. See :ref:`matrix` and :ref:`tensor` for more details. Declaration ----------- -As global tensors of vectors -++++++++++++++++++++++++++++ +As global fields of vectors ++++++++++++++++++++++++++++ .. function:: ti.Vector.field(n, dtype, shape = None, offset = None) :parameter n: (scalar) the number of components in the vector :parameter dtype: (DataType) data type of the components - :parameter shape: (optional, scalar or tuple) shape the tensor of vectors, see :ref:`tensor` + :parameter shape: (optional, scalar or tuple) shape the field of vectors, see :ref:`tensor` :parameter offset: (optional, scalar or tuple) see :ref:`offset` - For example, this creates a 5x4 tensor of 3 component vectors: + For example, this creates a 5x4 field of 3 component vectors: :: # Python-scope @@ -31,7 +31,7 @@ As global tensors of vectors .. note:: - In Python-scope, ``ti.field`` declares :ref:`scalar_tensor`, while ``ti.Vector.field`` declares tensors of vectors. + In Python-scope, ``ti.field`` declares :ref:`scalar_tensor`, while ``ti.Vector.field`` declares fields of vectors. As a temporary local variable @@ -52,13 +52,13 @@ As a temporary local variable Accessing components -------------------- -As global tensors of vectors -++++++++++++++++++++++++++++ +As global fields of vectors ++++++++++++++++++++++++++++ .. attribute:: a[p, q, ...][i] - :parameter a: (tensor of Vector) the vector - :parameter p: (scalar) index of the first tensor dimension - :parameter q: (scalar) index of the second tensor dimension + :parameter a: (field of Vector) the vector + :parameter p: (scalar) index of the first field dimension + :parameter q: (scalar) index of the second field dimension :parameter i: (scalar) index of the vector component This extracts the first component of vector ``a[6, 3]``: @@ -72,12 +72,12 @@ As global tensors of vectors .. note:: - **Always** use two pairs of square brackets to access scalar elements from tensors of vectors. + **Always** use two pairs of square brackets to access scalar elements from fields of vectors. - - The indices in the first pair of brackets locate the vector inside the tensor of vectors; + - The indices in the first pair of brackets locate the vector inside the field of vectors; - The indices in the second pair of brackets locate the scalar element inside the vector. - For 0-D tensors of vectors, indices in the first pair of brackets should be ``[None]``. + For 0-D fields of vectors, indices in the first pair of brackets should be ``[None]``. @@ -224,7 +224,7 @@ Metadata .. attribute:: a.n - :parameter a: (Vector or tensor of Vector) + :parameter a: (Vector or field of Vector) :return: (scalar) return the dimensionality of vector ``a`` E.g.,