[doc] New FAQs (#6055)

Related issue = #  Co-authored-by: Yi Xu <xy_xuyi@foxmail.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
taichi-dev · Dec 18, 2022 · 88d1273 · 88d1273
1 parent 6467159
commit 88d1273
Showing 1 changed file with 172 additions and 0 deletions.
diff --git a/docs/lang/articles/faqs/faq.md b/docs/lang/articles/faqs/faq.md
@@ -167,3 +167,175 @@ def test(arr: ti.types.ndarray()):
         x[i] = arr[i]
 test(array)
 ```
+
+### Does the Taichi's GUI system support color mapping when rendering simulation results?
+
+Taichi's GUI system can display colors when the field it accepts is a 3D vector field where each vector represents the RGB values of a pixel.
+
+To enable color mapping, convert `ti.field` into a NumPy array and call Matplotlib's colormap (`cm`), as shown in the following example:
+
+```python
+gui = ti.GUI(f'Re = {un * lx / mu:4.0f} V_mag', (nx+1, ny+1)）
+step = 0
+while gui.running: # Main loop
+    print(f'>>> step : {step:<6d}, time : {step*dt:<6.3f} sec')
+    substep()
+    if step % 10 = 1:
+        V_np = V_mag.to_numpy()
+        V_img = cm.jet(V_np)
+        gui.set_image(V_img) # Plot the velocity magnitude contour
+        gui.show()
+    step += 1
+```
+
+### Why does inheritance fail? I created a parent class and a child class, both decorated with `@ti.data_oriented`, and placed fields under `@ti.kernel`.
+
+The problem does not lie with inheritance. All Taichi fields must be allocated/placed in the Python scope. In other words, you need to define a field before calling `@ti.kernel`.
+
+For example, the following code snippet cannot run properly:
+
+```python
+@ti.data_oriented
+class MyClass1():
+
+    def __init__(self):
+        self.testfield = ti.Vector.field(3, dtype=ti.f32)
+
+    @ti.kernel
+    def init_field(self):
+        ti.root.dense(ti.i, 10).place(self.testfield)
+```
+
+Instead, refrain from involving `@ti.kernel` when declaring a field via `ti.root().place()`:
+
+```python
+@ti.data_oriented
+class TriangleRasterizer:
+    def __init__(self, n):
+        self.n = n
+        self.A = ti.Vector.field(2, dtype=ti.f32)
+        self.B = ti.Vector.field(2, dtype=ti.f32)
+        self.C = ti.Vector.field(2, dtype=ti.f32)
+        self.c0 = ti.Vector.field(3, dtype=ti.f32)
+        self.c1 = ti.Vector.field(3, dtype=ti.f32)
+        self.c2 = ti.Vector.field(3, dtype=ti.f32)
+
+        self.vertices = ti.root.dense(ti.i, n).place(self.A, self.B, self.C)
+        self.colors = ti.root.dense(ti.i, n).place(self.c0, self.c1, self.c2)
+
+        # Tile-based culling
+        self.block_num_triangles = ti.field(dtype=ti.i32,
+                                            shape=(width // tile_size,
+                                                   height // tile_size))
+        self.block_indicies = ti.field(dtype=ti.i32,
+                                       shape=(width // tile_size,
+                                              height // tile_size, n))
+```
+
+### How can I write data in Taichi fields to files? `write()` does not work.
+
+You cannot save data in Taichi fields directly, but there is a workaround. Taichi allows interaction with external arrays. Use `to_numpy` to convert a Taichi field to a NumPy array, as explained in [this section](https://docs.taichi-lang.org/docs/master/external). Then write the Numpy array to files via `numpy.savetxt`.
+
+A simple example:
+
+```python
+import taichi as ti
+import numpy as np
+
+ti.init(arch=ti.cpu)
+
+x = ti.field(dtype=ti.f32, shape= 10)
+y = ti.Vector.field(n=2, dtype=ti.i32, shape=10)
+
+@ti.kernel
+def init():
+    for i in x:
+        x[i] = i * 0.5 + 1.0
+    for i in y:
+        y[i] = ti.Vector([i,i])
+
+init()
+np.savetxt('x.txt', x.to_numpy())
+np.savetxt('y.txt', y.to_numpy())
+```
+
+And data in fields `x` and `y` can be found in files **x.txt** and **y.txt**, respectively.
+
+### Why an image obtained using `field.to_numpy()` is rotated when displayed using `matplotlib`'s `plt.imshow()`?
+
+Taichi fields adopt a different coordinate system from NumPy's arrays for storing images. In a Taichi field, [0,0] denotes the pixel at the lower left corner of the image; the first axis extends to the right of the image; the second axis extends to the top.
+
+This is different from the usual convention taken by popular third-party libs like `matplotlib` or `opencv`, where [0, 0] denotes the pixel at the top left corner, the first axis extends down to the bottom of the image, and the second axis  extends to the right.
+
+Therefore, to display a NumPy array using `matplotlb`'s `imshow()`, you must rotate it 90 degrees clockwise.
+
+### How does Taichi compare with Python packages designed for data science or machine learning?
+
+Popular packages designed for data science or machine learning include NumPy, JAX, PyTorch, and TensorFlow. A major difference between them and Taichi lies in the granularity of math operations.
+
+A common feature shared by the other packages is that they treat a single data array as the smallest unit of operations. Take PyTorch as an example. PyTorch processes a tensor as a whole and thus prefers such operations as the addition/subtraction/multiplication/division of tensors and matrix multiplication. The operators are parallelized internally, but the implementation process is invisible to users. As a result, users have to combine operators in various ways if they want to manipulate elements in tensors.
+
+Unlike them, Taichi makes element-level operations transparent and directly manipulates each iteration of the loops. This is why Taichi outperforms the other packages in scientific computing. In this sense, it compares more to C++ and CUDA.
+
+### How does Taichi compare with Cython?
+
+Cython is a superset of the Python language for quickly generating C/C++ extensions. It is a frequently-used tool to improve Python code performance thanks to its support for C data types and static typing. In fact, many modules in the official NumPy and SciPy code are written and compiled in Cython.
+
+On the flip side, the mixture of Python and C values compromises Cython's readability. In addition, though Cython supports parallel computing to a certain degree (via multi-threading), it cannot offload computation to GPU backends.
+
+Compared with Cython, Taichi is more friendly to Non-C users because it can achieve significant performance improvement with pure valid Python code. Supporting a wide range of backends, Taichi is subject to much fewer limits when performing parallel programming. In addition, unlike Cython, Taichi does not require the OpenMP API or an extra parallelism module to accelerate your program. Just specify a backend and wrap the loop with the decorator `@ti.kernel`; then, you can leave the job to Taichi.
+
+### How does Taichi compare with Numba?
+
+As its name indicates, Numba is tailored for NumPy. Numba is recommended if your functions involve vectorization of NumPy arrays. Compared with Numba, Taichi enjoys the following advantages:
+
+- Taichi provides advanced features, including quantized data types, dataclasses and sparse data structures, and allows you to adjust memory layout flexibly. These features are especially helpful when a program handles massive amounts of data. However, Numba only performs best when dealing with dense NumPy arrays.
+- Taichi can run on different GPU backends, making large-scale parallel programming (such as particle simulation or rendering) much more efficient. But it would be hard even to imagine writing a renderer in Numba.
+
+### How does Taichi compare with ctypes?
+
+ctypes allows you to call C/C++ compiled code from Python and run C++/CUDA programs in Python through a C-compatible API. It is a convenient option to access a vast collection of libraries in Python while achieving some improvement in performance. However, ctypes elevates the usage barrier: To write a satisfactory program, you need to command C, Python, CMake, CUDA, and even more languages. Moreover, ctypes may not fit in well with some performance-critical scenarios where you try to call large C libraries in Python, given the runtime overhead it incurs.
+
+In contrast, it is much more reassuring to keep everything in Python. Taichi accelerates the performance of native Python code through automatic parallelization without involving the libraries out of the Python ecosystem. It also enables offline cache, which drastically reduces the launch overhead of Taichi kernels after the first call.
+
+### How does Taichi compare with PyPy?
+
+Similar to Taichi, PyPy also accelerates Python code via just-in-time (JIT) compilation. PyPy is attractive because users can keep Python scripts as they are without even moderate modification. On the other hand, its strict conformity with Python rules leaves limited room for optimization.
+
+If you expect a greater leap in performance, Taichi can achieve the end. But you need to familiarize yourself with Taichi's syntax and assumptions, which differ from Python's slightly.
+
+### How do I compute the minimum/maximum of a field?
+
+Use `ti.automic.min/max` instead of `ti.min/max`. For example:
+
+```python
+for i in x:
+   ret = ti.atomic_min(ret, x[i])
+```
+
+### Does Taichi provide a barrier synchronization function similar to `__syncthreads()` or `glMemoryBarrier()`?
+
+You can call `ti.sync()`, which is similar to CUDA's `cudaStreamSynchronize()`, in Taichi to synchronize the parallel for loops.
+
+`__syncthreads()` is a block-level synchronization barrier, and Taichi provides a synonymous API `ti.simt.block.sync()`, which for now supports CUDA and Vulkan backends only. However, all block-level APIs are still experimental, and you should use this API only when it relates to SIMT operation synchronization and `SharedArray` reads and writes.
+
+### How can I swap elements between two fields in the Taichi scope? `a,b = b,a` does not work.
+
+Direct value assignments lead to semantic ambiguity. For example, `a = b` can mean data copy if `a` is pre-defined, or otherwise can serve to define and initialize `a`.
+
+You can swap two fields in the Taichi scope using a struct for:
+
+```python
+@ti.func
+def field_copy(src: ti.template(), dst: ti.template()):
+    for I in ti.grouped(src):
+        dst[I] = src[I]
+
+@ti.kernel
+def test():
+    # copy b to a
+    field_copy(b, a)
+    print(a[0])
+
+test()
+```