Skip to content

Commit

Permalink
[Doc] Replace tensor by field for files beginning with t to z (#1579)
Browse files Browse the repository at this point in the history
* update

* update
  • Loading branch information
Rullec authored Jul 25, 2020
1 parent 505cfcf commit 728fd3b
Show file tree
Hide file tree
Showing 2 changed files with 37 additions and 37 deletions.
44 changes: 22 additions & 22 deletions docs/tensor_matrix.rst
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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.
30 changes: 15 additions & 15 deletions docs/vector.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,32 +6,32 @@ 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
a = ti.Vector.field(3, dtype=ti.f32, shape=(5, 4))

.. 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
Expand All @@ -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]``:
Expand All @@ -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]``.



Expand Down Expand Up @@ -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.,
Expand Down

0 comments on commit 728fd3b

Please sign in to comment.