Skip to content

Commit

Permalink
[Doc] Update faq.md (#6921)
Browse files Browse the repository at this point in the history 
This PR makes the faq page more readable by grouping the questions into
subsections.
  • Loading branch information
@neozhaoliang
neozhaoliang authored Dec 19, 2022
1 parent 5a76150 commit 9ff43d8
Showing 1 changed file with 98 additions and 74 deletions.
172 changes: 98 additions & 74 deletions docs/lang/articles/faqs/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,13 @@ sidebar_position: 1

# Frequently Asked Questions

## Can I enable auto compeletion for Taichi?

Yes, Taichi's Python user-facing APIs should work natively with any language server for Python.

Take VSCode as an example, you can install `Python` or `Pylance` extensions to get language support like signature help with type information, code completion etc.

If it doesn't work out of box after installing the extension, please make sure the right Python interpreter is selected by:
- invoke command palette (`Shift + Command + P (Mac) / Ctrl + Shift + P (Windows/Linux)`)
- find `Python: Select Interpreter`
- make sure you select the path to the Python interpreter you're using with a `taichi` package installed
## Installation

### Why does my `pip` complain `package not found` when installing Taichi?

You may have a Python interpreter with an unsupported version. Currently, Taichi only supports Python 3.7/3.8/3.9/3.10 (64-bit) . For more information about installation-specific issues, please check [Installation Troubleshooting](./install.md).

### Does Taichi provide built-in constants such as `ti.pi`?

There is no built-in constant such as `pi`. We recommended using `math.pi` directly.
## Parallel programming

### Outer-most loops in Taichi kernels are by default parallel. How can I **serialize** one of them?

Expand All @@ -33,35 +22,14 @@ for _ in range(1): # This "ghost" loop will be "parallelized", but with only on
...
```

### What is the most convenient way to load images into Taichi fields?

One feasible solution is `field.from_numpy(ti.tools.imread('filename.png'))`.
### Does Taichi provide a barrier synchronization function similar to `__syncthreads()` or `glMemoryBarrier()`?

### Can Taichi interact with **other Python packages** such as `matplotlib`?
You can call `ti.sync()`, which is similar to CUDA's `cudaStreamSynchronize()`, in Taichi to synchronize the parallel for loops.

Yes, Taichi supports many popular Python packages. Taichi provides helper functions such as `from_numpy` and `to_numpy` to transfer data between Taichi fields and NumPy arrays, so that you can also use your favorite Python packages (e.g., `numpy`, `pytorch`, `matplotlib`) together with Taichi as below:
`__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.

```python
import taichi as ti
pixels = ti.field(ti.f32, (1024, 512))
import numpy as np
arr = np.random.rand(1024, 512)
pixels.from_numpy(arr) # load numpy data into taichi fields
import matplotlib.pyplot as plt
arr = pixels.to_numpy() # store taichi data into numpy arrays
plt.imshow(arr)
plt.show()
import matplotlib.cm as cm
cmap = cm.get_cmap('magma')
gui = ti.GUI('Color map')
while gui.running:
render_pixels()
arr = pixels.to_numpy()
gui.set_image(cmap(arr))
gui.show()
```

Besides, you can also pass numpy arrays or torch tensors into a Taichi kernel as arguments. See [Interacting with external arrays](../basic/external.md) for more details.
## Data structures

### How do I declare a field with a **dynamic length**?

Expand All @@ -74,10 +42,55 @@ SNodes may be less efficient than using `dense` SNodes, due to dynamic data stru
maintenance overheads.
:::

### 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()
```

### 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])
```


### How do I program on less structured data structures (such as graphs and tetrahedral meshes) in Taichi?

These structures have to be decomposed into 1D Taichi fields. For example, when representing a graph, you can allocate two fields, one for the vertices and the other for the edges. You can then traverse the elements using `for v in vertices` or `for v in range(n)`.


## Developement related

### Can I enable auto compeletion for Taichi?

Yes, Taichi's Python user-facing APIs should work natively with any language server for Python.

Take VSCode as an example, you can install `Python` or `Pylance` extensions to get language support like signature help with type information, code completion etc.

If it doesn't work out of box after installing the extension, please make sure the right Python interpreter is selected by:
- invoke command palette (`Shift + Command + P (Mac) / Ctrl + Shift + P (Windows/Linux)`)
- find `Python: Select Interpreter`
- make sure you select the path to the Python interpreter you're using with a `taichi` package installed

### How to install Taichi on a server without Internet access?

Follow these steps to install Taichi on a server without Internet access.
Expand All @@ -96,12 +109,49 @@ pip download taichi
python -m pip install xxxx.whl
```


## Integration with other libs/softwares

### What is the most convenient way to load images into Taichi fields?

One feasible solution is `field.from_numpy(ti.tools.imread('filename.png'))`.

### Can Taichi interact with **other Python packages** such as `matplotlib`?

Yes, Taichi supports many popular Python packages. Taichi provides helper functions such as `from_numpy` and `to_numpy` to transfer data between Taichi fields and NumPy arrays, so that you can also use your favorite Python packages (e.g., `numpy`, `pytorch`, `matplotlib`) together with Taichi as below:

```python
import taichi as ti
pixels = ti.field(ti.f32, (1024, 512))
import numpy as np
arr = np.random.rand(1024, 512)
pixels.from_numpy(arr) # load numpy data into taichi fields
import matplotlib.pyplot as plt
arr = pixels.to_numpy() # store taichi data into numpy arrays
plt.imshow(arr)
plt.show()
import matplotlib.cm as cm
cmap = cm.get_cmap('magma')
gui = ti.GUI('Color map')
while gui.running:
render_pixels()
arr = pixels.to_numpy()
gui.set_image(cmap(arr))
gui.show()
```

Besides, you can also pass numpy arrays or torch tensors into a Taichi kernel as arguments. See [Interacting with external arrays](../basic/external.md) for more details.


### Can I integrate Taichi and Houdini?

The answer is an unequivocal Yes! Our contributors managed to embed [taichi_elements](https://github.com/taichi-dev/taichi_elements), a multi-material continuum physics engine, into Houdini as an extension, combining Houdini's flexibility in preprocessing with Taichi's strength in high-performance computation.

You can follow the instructions provided [here](https://github.com/taichi-dev/taichi_houdini).


## Precision related

### How do I accurately initialize a vector or matrix with `f64` precision when my default floating-point precision (`default_fp`) is `f32`?

To better understand the question, look at the program below:
Expand Down Expand Up @@ -133,6 +183,8 @@ You may notice the value of `A` is slightly different from `[0.2, 0]`. This is b

Alternatively, if you can afford having all floating-point operations in `f64` precision, you can directly initialize Taichi with `ti.init(..., default_fp=ti.f64)`.

## From Python to Taichi

### Why does it always return an error when I pass a list from the Python scope to a Taichi kernel?

A Taichi kernel **cannot** take a Python list directly. You need to use NumPy arrays as a bridge.
Expand Down Expand Up @@ -168,6 +220,8 @@ def test(arr: ti.types.ndarray()):
test(array)
```

## Visualization

### 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.
Expand All @@ -188,6 +242,8 @@ while gui.running: # Main loop
step += 1
```

## Objective-oriented programming

### 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`.
Expand Down Expand Up @@ -232,6 +288,8 @@ class TriangleRasterizer:
height // tile_size, n))
```

## From Taichi to Python

### 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`.
Expand Down Expand Up @@ -269,6 +327,8 @@ This is different from the usual convention taken by popular third-party libs li

Therefore, to display a NumPy array using `matplotlb`'s `imshow()`, you must rotate it 90 degrees clockwise.

## Miscellaneous

### 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.
Expand Down Expand Up @@ -303,39 +363,3 @@ In contrast, it is much more reassuring to keep everything in Python. Taichi acc
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()
```

0 comments on commit 9ff43d8

Please sign in to comment.