From c2e2edbe07e712ad542519519ec3cbb669c66c60 Mon Sep 17 00:00:00 2001
From: archibate <1931127624@qq.com>
Date: Mon, 24 Aug 2020 13:04:47 +0800
Subject: [PATCH 1/4] [Doc] Separate arithmetics.rst from syntax.rst and fill
 it with more details

---
 docs/arithmetics.rst      | 165 ++++++++++++++++++++++++++++++++++++++
 docs/index.rst            |   3 +-
 docs/syntax.rst           |  83 +------------------
 docs/type.rst             |   2 +
 python/taichi/lang/ops.py |   8 +-
 5 files changed, 174 insertions(+), 87 deletions(-)
 create mode 100644 docs/arithmetics.rst

diff --git a/docs/arithmetics.rst b/docs/arithmetics.rst
new file mode 100644
index 0000000000000..29756a718e900
--- /dev/null
+++ b/docs/arithmetics.rst
@@ -0,0 +1,165 @@
+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.:
+
+  .. 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``. 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.
+
+Logic operators
+***************
+
+- ``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``.
+
+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]
diff --git a/docs/index.rst b/docs/index.rst
index f1cdef727c283..3f36d7f5052c6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,7 +18,6 @@ The Taichi Programming Language
    type
    tensor_matrix
    external
-   atomic
 
 
 .. toctree::
@@ -28,6 +27,8 @@ The Taichi Programming Language
    scalar_tensor
    vector
    matrix
+   arithmetics
+   atomic
    snode
 
 
diff --git a/docs/syntax.rst b/docs/syntax.rst
index 584722e442a50..f4418cd9a5e91 100644
--- a/docs/syntax.rst
+++ b/docs/syntax.rst
@@ -1,5 +1,5 @@
-Syntax
-======
+Kernels and functions
+=====================
 
 Taichi-scope vs Python-scope
 ----------------------------
@@ -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]
diff --git a/docs/type.rst b/docs/type.rst
index 7c23b7cc46da5..dcff98c72cd03 100644
--- a/docs/type.rst
+++ b/docs/type.rst
@@ -1,3 +1,5 @@
+.. _type:
+
 Type system
 ===========
 
diff --git a/python/taichi/lang/ops.py b/python/taichi/lang/ops.py
index fa21bbd20aa52..6de8c04387546 100644
--- a/python/taichi/lang/ops.py
+++ b/python/taichi/lang/ops.py
@@ -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)
 
 

From a369b1a36dd148d82d657fe14b99f592e9e1678b Mon Sep 17 00:00:00 2001
From: archibate <1931127624@qq.com>
Date: Mon, 24 Aug 2020 13:34:32 +0800
Subject: [PATCH 2/4] [skip ci] missing

---
 docs/arithmetics.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/arithmetics.rst b/docs/arithmetics.rst
index 29756a718e900..7a62c50ef61c6 100644
--- a/docs/arithmetics.rst
+++ b/docs/arithmetics.rst
@@ -47,6 +47,7 @@ Arithmetic operators
 Logic operators
 ***************
 
+- ``~a``
 - ``a == b``
 - ``a != b``
 - ``a > b``

From a2e95c500d7da8a6d87290973b09b70de067cba8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BD=AD=E4=BA=8E=E6=96=8C?= <1931127624@qq.com>
Date: Wed, 26 Aug 2020 10:16:32 +0800
Subject: [PATCH 3/4] [skip ci] Update docs/arithmetics.rst

---
 docs/arithmetics.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/arithmetics.rst b/docs/arithmetics.rst
index 7a62c50ef61c6..8a70c80a44575 100644
--- a/docs/arithmetics.rst
+++ b/docs/arithmetics.rst
@@ -36,7 +36,7 @@ Arithmetic operators
 .. 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:
+  ``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.

From f74bf53174d584034941716bc7eed33923ceb008 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BD=AD=E4=BA=8E=E6=96=8C?= <1931127624@qq.com>
Date: Wed, 26 Aug 2020 15:12:59 +0800
Subject: [PATCH 4/4] [skip ci] Apply suggestions from code review

---
 docs/arithmetics.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/arithmetics.rst b/docs/arithmetics.rst
index 8a70c80a44575..cfdd31985eadf 100644
--- a/docs/arithmetics.rst
+++ b/docs/arithmetics.rst
@@ -18,7 +18,7 @@ Arithmetic operators
 
 .. note::
 
-  The ``%`` operator in Taichi follows the Python-style instead of C-style, e.g.:
+  The ``%`` operator in Taichi follows the Python style instead of C style, e.g.:
 
   .. code-block:: python