Skip to content

Commit

Permalink
[doc] Update hello_world.md (#6889)
Browse files Browse the repository at this point in the history
Issue: #

### Brief Summary

Co-authored-by: Olinaaaloompa <[email protected]>
Co-authored-by: Zhao Liang <[email protected]>
  • Loading branch information
3 people authored Dec 15, 2022
1 parent 45f4045 commit 4ec7dff
Showing 1 changed file with 40 additions and 24 deletions.
64 changes: 40 additions & 24 deletions docs/lang/articles/get-started/hello_world.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ for i in range(1000000):

Save the code above to your local machine and run this program.


*You get the following animation:*

<center>
Expand All @@ -70,44 +71,57 @@ Save the code above to your local machine and run this program.

</center>

:::note

If you are *not* using an IDE for running code, you can simply run the code from your terminal by:

1. Go to the directory that contains your .py file
2. Type in `python3 *nameOfFile*.py` (replace *nameOfFile* with your programs name. Be sure to include the `.py` extension)

:::

Let's dive into this simple Taichi program.

### Import Taichi

```python
import taichi as ti
import taichi.math as tm
```
The first two lines import Taichi and its `math` module. The `math` module contains built-in vectors and matrices of small dimensions, such as `vec2` for 2D real vectors and `mat3` for 3&times;3 real matrices.

The first two lines import Taichi and its `math` module. The `math` module contains:
- Frequently-used math functions.
- Built-in vectors and matrices of small dimensions, such as `vec2` for 2D real vectors and `mat3` for 3&times;3 real matrices.
See the [Math Module](../math/math_module.md) for more information.

```python
ti.init(arch=ti.gpu)
```

This line calls `ti.init()` to customize your Taichi runtime depending on the arguments passed into it. For now, we only introduce the most important argument, namely, `arch`.
### Initialize Taichi

:::note
`ti.init(**kwargs)`- Initializes Taichi environment and allows you to customize your Taichi runtime depending on the optional arguments passed into it.
:::

For now, we only introduce the most important argument, namely, `arch`.

The argument `arch` specifies the *backend* that executes the compiled code. A backend can be either `ti.cpu` or `ti.gpu`. When `ti.gpu` is specified, Taichi moves down the backend list of `ti.cuda`, `ti.vulkan`, and `ti.opengl/ti.metal`. If no GPU architecture is available, Taichi falls back to your CPU device.

You can also directly specify which GPU backend to use. For example, set `arch=ti.cuda` to run your program on CUDA. Taichi raises an error if the target architecture is unavailable. See the [Global Settings](../reference/global_settings.md) for more information about `ti.init()`.

### Define a field
```python{4}
import taichi as ti
import taichi.math as tm
ti.init(arch=ti.gpu)
```

### Define a Taichi field

:::note
`ti.field(dtype, shape)` - Defines a Taichi field whose shape is of `shape` and whose elements are of type `dtype`.

Let's move on to the next two lines.
`ti.field` is the most important and frequently used data structure in Taichi. You can compare it to NumPy's `ndarray` or PyTorch's `tensor`. But Taichi's field is more flexible. For example, a Taichi field can be [spatially sparse](../basic/sparse.md) and easily [switched between different data layouts](../basic/layout.md).

We will introduce more advanced features of fields in other scenario-based tutorials. For now, it suffices to know that the field `pixels` is a dense 2D array.

```python
n = 320
pixels = ti.field(dtype=float, shape=(n * 2, n))
```

The code snippet defines a field whose shape is (640, 320) and whose elements are floating-point numbers.

*field* is the most important and frequently used data structure in Taichi. You can compare it to NumPy's `ndarray` or PyTorch's `tensor`. But Taichi's field is more flexible. For example, a Taichi field can be [spatially sparse](../basic/sparse.md) and easily [switched between different data layouts](../basic/layout.md).

We will introduce more advanced features of field in other scenario-based tutorials. For now, it suffices to know that the field `pixels` is a dense 2D array.

### Kernels and functions

Expand All @@ -130,18 +144,20 @@ For those who come from the world of OpenGL, `ti.func` corresponds to the usual

### Parallel for loops

The key to high performance lies in Line 15:

```python
for i, j in pixels:
```
The key to high performance lies in how you iterate in Taichi. In particular, we can use parallelized looping to parse through our data more efficiently.

This is a `for` loop at the outermost scope in a Taichi kernel and thus is *automatically parallelized*.
The following code snippet introduces a `for` loop at the outermost scope in a Taichi kernel and thus is *automatically parallelized*. Notice that the loop is also calling both `i` and `j` at the same time, and the program will run these iterations concurrently.

Taichi offers a handy syntax sugar: It parallelizes any `for` loop at the outermost scope in a kernel. This means that you can parallelize your tasks using one plain loop, without the need to know thread allocation/recycling or memory management.

Note that the field `pixels` is treated as an iterator. As the indices of the field elements, `i` and `j` are integers falling in the ranges `[0, 2*n-1]` and `[0, n-1]`, respectively. The pair `(i, j)` loops over the sets `(0, 0)`, `(0, 1)`, ..., `(0, n-1)`, `(1, n-1)`, ..., `(2*n-1, n-1)` in parallel.


```python
for i, j in pixels:
```


Keep in mind that the *for loops not at the outermost scope are not parallelized* but handled serially:

```python {3,7,14-15}
Expand Down

0 comments on commit 4ec7dff

Please sign in to comment.