Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Doc] Separate arithmetics.rst from syntax.rst and fill it with more details #1761

Merged
merged 4 commits into from
Aug 26, 2020
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 166 additions & 0 deletions docs/arithmetics.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
Scalar operations
=================

Operators
---------

Arithmetic operators
********************

- ``-a``
- ``a + b``
- ``a - b``
- ``a * b``
- ``a / b``
- ``a // b``
- ``a % b``
- ``a ** b``

.. note::

The ``%`` operator in Taichi follows the Python-style instead of C-style, e.g.:
archibate marked this conversation as resolved.
Show resolved Hide resolved

.. code-block:: python

# no matter Taichi-scope or Python-scope:
print(2 % 3) # 2
print(-2 % 3) # 1

For C-style mod, please use ``ti.raw_mod``:

.. code-block:: python

print(ti.raw_mod(2, 3)) # 2
print(ti.raw_mod(-2, 3)) # -2

.. note::

Python 3 distinguishes ``/`` (true division) and ``//`` (floor division). For example, ``1.0 / 2.0 = 0.5``,
``1 / 2 = 0.5``, ``1 // 2 = 0``, ``4.2 // 2 = 2``. And Taichi follows the same design:

- **true divisions** on integral types will first cast their operands to the default float point type.
- **floor divisions** on float-point types will first cast their operands to the default integer type.

To avoid such implicit casting, you can manually cast your operands to desired types, using ``ti.cast``.
See :ref:`default_precisions` for more details on default numerical types.

Logic operators
***************

- ``~a``
- ``a == b``
- ``a != b``
- ``a > b``
- ``a < b``
- ``a >= b``
- ``a <= b``
- ``not a``
- ``a or b``
- ``a and b``
- ``a if cond else b``

Bitwise operators
*****************

- ``a & b``
- ``a ^ b``
- ``a | b``

Functions
---------

Trigonometric functions
***********************

.. function:: ti.sin(x)
.. function:: ti.cos(x)
.. function:: ti.tan(x)
.. function:: ti.asin(x)
.. function:: ti.acos(x)
.. function:: ti.atan2(x, y)
.. function:: ti.tanh(x)

Other arithmetic functions
**************************

.. function:: ti.sqrt(x)
.. function:: ti.rsqrt(x)

A fast version for ``1 / ti.sqrt(x)``.

.. function:: ti.exp(x)
.. function:: ti.log(x)
.. function:: ti.floor(x)
.. function:: ti.ceil(x)

Casting types
*************

.. function:: ti.cast(x, dtype)

See :ref:`type` for more details.

.. function:: int(x)

A shortcut for ``ti.cast(x, int)``.

.. function:: float(x)

A shortcut for ``ti.cast(x, float)``.

Builtin-alike functions
***********************

.. function:: abs(x)
.. function:: max(x, y, ...)
.. function:: min(x, y, ...)
.. function:: pow(x, y)

Same as ``x ** y``.
Comment on lines +111 to +119
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm kinda confused here. What does "Builtin-alike" mean? 🤔 Would just "built-in" be enough?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since abs and max are builtin functions, but they are replaced by ti.ti_abs and ti.ti_max by @ti.kernel, which is our functions. They just share the same interface with the Python built-in ones.


Random number generator
***********************

.. function:: ti.random(dtype = float)


Element-wise arithmetics for vectors and matrices
-------------------------------------------------

When these scalar functions are applied on :ref:`matrix` and :ref:`vector`, they are applied in an element-wise manner.
For example:

.. code-block:: python

B = ti.Matrix([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
C = ti.Matrix([[3.0, 4.0, 5.0], [6.0, 7.0, 8.0]])

A = ti.sin(B)
# is equivalent to
for i in ti.static(range(2)):
for j in ti.static(range(3)):
A[i, j] = ti.sin(B[i, j])

A = B ** 2
# is equivalent to
for i in ti.static(range(2)):
for j in ti.static(range(3)):
A[i, j] = B[i, j] ** 2

A = B ** C
# is equivalent to
for i in ti.static(range(2)):
for j in ti.static(range(3)):
A[i, j] = B[i, j] ** C[i, j]

A += 2
# is equivalent to
for i in ti.static(range(2)):
for j in ti.static(range(3)):
A[i, j] += 2

A += B
# is equivalent to
for i in ti.static(range(2)):
for j in ti.static(range(3)):
A[i, j] += B[i, j]
3 changes: 2 additions & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ The Taichi Programming Language
type
tensor_matrix
external
atomic


.. toctree::
Expand All @@ -28,6 +27,8 @@ The Taichi Programming Language
scalar_tensor
vector
matrix
arithmetics
atomic
snode


Expand Down
83 changes: 2 additions & 81 deletions docs/syntax.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Syntax
======
Kernels and functions
=====================

Taichi-scope vs Python-scope
----------------------------
Expand Down Expand Up @@ -270,82 +270,3 @@ reference:
else:
ret = 0.0
return ret


Scalar arithmetics
------------------

Supported scalar functions:

.. function:: ti.sin(x)
.. function:: ti.cos(x)
.. function:: ti.asin(x)
.. function:: ti.acos(x)
.. function:: ti.atan2(x, y)
.. function:: ti.cast(x, data_type)
.. function:: ti.sqrt(x)
.. function:: ti.rsqrt(x)
.. function:: ti.floor(x)
.. function:: ti.ceil(x)
.. function:: ti.tan(x)
.. function:: ti.tanh(x)
.. function:: ti.exp(x)
.. function:: ti.log(x)
.. function:: ti.random(data_type)
.. function:: abs(x)
.. function:: int(x)
.. function:: float(x)
.. function:: max(x, y)
.. function:: min(x, y)
.. function:: pow(x, y)

.. note::

Python 3 distinguishes ``/`` (true division) and ``//`` (floor division). For example, ``1.0 / 2.0 = 0.5``,
``1 / 2 = 0.5``, ``1 // 2 = 0``, ``4.2 // 2 = 2``. Taichi follows this design:

- **true divisions** on integral types will first cast their operands to the default float point type.
- **floor divisions** on float-point types will first cast their operands to the default integer type.

To avoid such implicit casting, you can manually cast your operands to desired types, using ``ti.cast``.
See :ref:`default_precisions` for more details on default numerical types.

.. note::

When these scalar functions are applied on :ref:`matrix` and :ref:`vector`, they are applied in an element-wise manner.
For example:

.. code-block:: python

B = ti.Matrix([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
C = ti.Matrix([[3.0, 4.0, 5.0], [6.0, 7.0, 8.0]])

A = ti.sin(B)
# is equivalent to
for i in ti.static(range(2)):
for j in ti.static(range(3)):
A[i, j] = ti.sin(B[i, j])

A = ti.pow(B, 2)
# is equivalent to
for i in ti.static(range(2)):
for j in ti.static(range(3)):
A[i, j] = ti.pow(B[i, j], 2)

A = ti.pow(B, C)
# is equivalent to
for i in ti.static(range(2)):
for j in ti.static(range(3)):
A[i, j] = ti.pow(B[i, j], C[i, j])

A += 2
# is equivalent to
for i in ti.static(range(2)):
for j in ti.static(range(3)):
A[i, j] += 2

A += B
# is equivalent to
for i in ti.static(range(2)):
for j in ti.static(range(3)):
A[i, j] += B[i, j]
2 changes: 2 additions & 0 deletions docs/type.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _type:

Type system
===========

Expand Down
8 changes: 3 additions & 5 deletions python/taichi/lang/ops.py
Original file line number Diff line number Diff line change
Expand Up @@ -273,11 +273,9 @@ def logical_not(a):
return _unary_operation(ti_core.expr_logic_not, lambda x: int(not x), a)


def random(dt=None):
if dt is None:
import taichi
dt = taichi.get_runtime().default_fp
x = Expr(ti_core.make_rand_expr(dt))
def random(dtype=float):
dtype = cook_dtype(dtype)
x = Expr(ti_core.make_rand_expr(dtype))
return expr_init(x)


Expand Down