[Doc] better documention

docs/atomic.rst

@@ -0,0 +1,92 @@
+.. _atomic:
+
+Atomic operations
+=================
+
+In taichi, ``x[i] += 1`` is atomic but ``x[i] = x[i] + 1`` is not.
+
+For example, to perform a reduction:
+::
+    @ti.kernel
+    def sum():
+        for i in x:
+            result[None] += x[i]
+
+Or use the function ``ti.atomic_add``, which is equivalent:
+::
+    @ti.kernel
+    def sum():
+        for i in x:
+            ti.atomic_add(result[None], x[i])
+
+See https://en.wikipedia.org/wiki/Fetch-and-add for more details.
+
+
+.. note::
+    Support of atomic operation on each backends:
+
+    +------+-----------+-----------+---------+
+    | type | LLVM      | OpenGL    | Metal   |
+    +======+===========+===========+=========+
+    | i32  |    OK     |    OK     |   OK    |
+    +------+-----------+-----------+---------+
+    | f32  |    OK     |    OK     |   OK    |
+    +------+-----------+-----------+---------+
+    | i64  |    OK     |   EXT     |  MISS   |
+    +------+-----------+-----------+---------+
+    | f64  |    OK     |   EXT     |  MISS   |
+    +------+-----------+-----------+---------+
+
+    (OK=supported, EXT=require extension, MISS=not supported)
+
+
+Functions
+---------
+
+.. function:: ti.atomic_add(x, y)
+
+    This is equivalent to ``x += y``.
+
+    :parameter x: (Expr, lvalue) the LHS of addition, also where the result is saved
+    :parameter y: (Expr) the RHS of addition
+    :return: (Expr) the original value stored in ``x``
+
+    e.g.:
+    ::
+        x = 3
+        y = 4
+        z = ti.atomic_add(x, y)
+        # now x = 7, y = 4, z = 3
+
+
+.. function:: ti.atomic_sub(x, y)
+
+    This is equivalent to ``x -= y``.
+
+
+.. function:: ti.atomic_max(x, y)
+
+    e.g.:
+    ::
+        x = 3
+        y = 4
+        z = ti.atomic_max(x, y)
+        # now x = 4, y = 4, z = 3
+
+
+.. function:: ti.atomic_min(x, y)
+
+
+.. function:: ti.atomic_or(x, y)
+
+    This is equivalent to ``x |= y``.
+
+
+.. function:: ti.atomic_and(x, y)
+
+    This is equivalent to ``x &= y``.
+
+
+.. function:: ti.atomic_xor(x, y)
+
+    This is equivalent to ``x ^= y``.

docs/cpp_style.rst

@@ -28,3 +28,7 @@ Don'ts
 - ``NULL``, use ``nullptr`` instead.
 - ``using namespace std;`` in global scope.
 - ``typedef``. Use ``using`` instead.
+
+Automatic code formatting
+--------------------------------------------------------------------------------
+- Please run ``ti format``

docs/global_settings.rst

@@ -3,4 +3,7 @@ Global Settings
 
 - Restart the Taichi runtime system (clear memory, destroy all variables and kernels): ``ti.reset()``
 - Eliminate verbose outputs: ``ti.get_runtime().set_verbose(False)``
-- To specify which GPU to use: ``export CUDA_VISIBLE_DEVICES=0``
+- Not to trigger GDB when crashes: ``ti.misc.util.set_gdb_trigger(False)``
+- Show more detailed log (TI_TRACE): ``ti.misc.util.set_logging_level(ti.TRACE)``
+- To specify which GPU to use for CUDA: ``export CUDA_VISIBLE_DEVICES=0``
+- To specify which Arch to use: ``export TI_ARCH=cuda``

docs/index.rst

@@ -25,6 +25,22 @@ The Taichi Programming Language
 
    external
 
+
+.. toctree::
+   :caption: Language
+   :maxdepth: 3
+
+   atomic
+
+
+.. toctree::
+   :caption: Structures
+   :maxdepth: 3
+
+   scalar_tensor
+   vector
+
+
 .. toctree::
    :caption: Advanced Programming
    :maxdepth: 3
@@ -52,6 +68,7 @@ The Taichi Programming Language
    dev_install
    contributor_guide
    cpp_style
+   performance
    internal
    faq
    acknowledgments

docs/internal.rst

@@ -7,6 +7,7 @@ Vector type system
 
 Intermediate representation
 ---------------------------------------
+Use ``ti.init(print_ir=True)`` to print IR on the console.
 
 
 Code generation

docs/linalg.rst

@@ -8,6 +8,7 @@ Matrices
 - ``ti.Matrix`` is for small matrices (e.g. `3x3`) only. If you have `64x64` matrices, you should consider using a 2D tensor of scalars.
 - ``ti.Vector`` is the same as ``ti.Matrix``, except that it has only one column.
 - Differentiate element-wise product ``*`` and matrix product ``@``.
+- ``ti.Vector(n, dt=ti.f32)`` or ``ti.Matrix(n, m, dt=ti.f32)``.
 - ``ti.transposed(A)`` or simply ``A.T()``
 - ``ti.inverse(A)``
 - ``ti.Matrix.abs(A)``

docs/scalar_tensor.rst

@@ -0,0 +1,58 @@
+.. _scalar_tensor:
+
+Tensor of scalars
+=================
+
+
+Creation
+--------
+
+.. function:: ti.var(dt, shape = None)
+
+    :parameter dt: (DataType) type of the tensor element
+    :parameter shape: (optional, scalar or tuple) the shape of tensor
+
+    This creates a 4x3 tensor called ``x`` with ``float32`` elements in GPU memory:
+    ::
+        x = ti.var(ti.f32, shape=(4, 3))
+
+    If shape is ``()``, then a scalar is created:
+    ::
+        x = ti.var(ti.f32, shape=())
+
+    If ``shape`` is not provided then you must *place* the variable later yourself:
+    ::
+        x = ti.var(ti.f32)
+        ti.root.dense(ti.ij, (4, 3)).place(x)
+
+    The about two are equivalent.
+
+
+.. note::
+
+    All variables should be created and *placed* before any kernel invocation or any of them accessed from python-scope
+
+For example:
+
+.. code-block:: python
+
+    x = ti.var(ti.f32)
+    x[None] = 233 # ERROR: x not placed!
+
+.. code-block:: python
+
+    x = ti.var(ti.f32, shape=())
+    @ti.kernel
+    def func():
+        x[None] = 233
+
+    func()
+    y = ti.var(ti.f32, shape=())
+    # ERROR: cannot create tensor after kernel invocated!
+
+.. code-block:: python
+
+    x = ti.var(ti.f32, shape=())
+    x[None] = 233
+    y = ti.var(ti.f32, shape=())
+    # ERROR: cannot create tensor after accessed from python-scope!

docs/sparse.rst

@@ -1,6 +1,6 @@
 .. _sparse:
 
-Sparse computation
+Sparse computation (WIP)
 ===============================================
 
 .. warning::

docs/tensor_matrix.rst

@@ -1,3 +1,5 @@
+.. _tensor:
+
 Tensors and matrices
 ==========================
 

docs/type.rst

@@ -5,11 +5,47 @@ Supported types
 ---------------------------------------
 Currently, supported basic types in Taichi are
 
+- int8 ``ti.i8``
+- int16 ``ti.i16``
 - int32 ``ti.i32``
 - int64 ``ti.i64``
+- uint8 ``ti.u8``
+- uint16 ``ti.u16``
+- uint32 ``ti.u32``
+- uint64 ``ti.u64``
 - float32 ``ti.f32``
 - float64 ``ti.f64``
 
+.. note::
+    Supported types on each backends:
+
+    +------+-----------+-----------+---------+
+    | type | LLVM      | OpenGL    | Metal   |
+    +======+===========+===========+=========+
+    | i8   |    OK     |   MISS    |   OK    |
+    +------+-----------+-----------+---------+
+    | i16  |    OK     |   MISS    |   OK    |
+    +------+-----------+-----------+---------+
+    | i32  |    OK     |    OK     |   OK    |
+    +------+-----------+-----------+---------+
+    | i64  |    OK     |   EXT     |  MISS   |
+    +------+-----------+-----------+---------+
+    | u8   |    OK     |   MISS    |   OK    |
+    +------+-----------+-----------+---------+
+    | u16  |    OK     |   MISS    |   OK    |
+    +------+-----------+-----------+---------+
+    | u32  |    OK     |   MISS    |   OK    |
+    +------+-----------+-----------+---------+
+    | u64  |    OK     |   MISS    |  MISS   |
+    +------+-----------+-----------+---------+
+    | f32  |    OK     |    OK     |   OK    |
+    +------+-----------+-----------+---------+
+    | f64  |    OK     |   EXT     |  MISS   |
+    +------+-----------+-----------+---------+
+
+    (OK=supported, EXT=require extension, MISS=not supported)
+
+
 Boolean types are represented using ``ti.i32``.
 
 Binary operations on different types will give you a promoted type, following the C programming language, e.g.

docs/utilities.rst

@@ -3,6 +3,30 @@ Utilities
 
 TODO: update
 
+GUI system
+----------
+
+.. code-block:: python
+
+    gui = ti.GUI('Title', (640, 480))
+    while not gui.is_pressed(ti.GUI.ESCAPE):
+        gui.set_image(img)
+        gui.show()
+
+
+Also checkout https://github.com/taichi-dev/taichi/blob/master/examples/keyboard.py for more advanced event processing.
+
+
+Image I/O
+---------
+
+.. code-block:: python
+
+    img = ti.imread('hello.png')
+    ti.imshow(img, 'Window Title')
+    ti.imwrite(img, 'hello2.png')
+
+
 Logging
 -------