Skip to content

Commit

Permalink
[Doc] Update the documentation about Dynamic SNode (taichi-dev#6752)
Browse files Browse the repository at this point in the history
Issue: taichi-dev#5420

### Brief Summary

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Zhao Liang <[email protected]>
Co-authored-by: Olinaaaloompa <[email protected]>
  • Loading branch information
4 people authored and quadpixels committed May 13, 2023
1 parent cbb0655 commit 9cbfdd1
Showing 1 changed file with 40 additions and 13 deletions.
53 changes: 40 additions & 13 deletions docs/lang/articles/basic/sparse.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,9 @@ In Taichi, programmers can compose data structures similar to VDB and SPGrid wit


:::note
**Backend compatibility**: The LLVM backends (CPU/CUDA) and the Metal backend offer the full functionality of computation on spatially sparse data structures.
**Backend compatibility**: The LLVM-based backends (CPU/CUDA) offer the full functionality for performing computations on spatially sparse data structures.
Using sparse data structures on the Metal backend is now deprecated. The support for Dynamic SNode has been removed in v1.3.0,
and the support for Pointer/Bitmasked SNode will be removed in v1.4.0.
:::


Expand Down Expand Up @@ -170,31 +172,56 @@ The bitmasked SNodes are like dense SNodes with auxiliary activity values.

### Dynamic SNode

To support variable-length fields, Taichi provides dynamic SNodes. The code snippet below first creates a 5x1 dense block (line 2). Then each cell of the dense block contains a variable-length dynamic container (line 3). The maximum length of the dynamic container is 5. In the `make_lists()` function, you can use `ti.append()` to add a value to the end of a dynamic SNode. `x.parent()` is the same as `pixel`. The dense field `l` stores the length of each dynamic SNode.
To support variable-length fields, Taichi provides dynamic SNodes.

```python {3} title=dynamic.py
x = ti.field(ti.i32)
block = ti.root.dense(ti.i, 5)
pixel = block.dynamic(ti.j, 5)
pixel.place(x)
The first argument of `dynamic` is the axis, the second argument is the maximum length,
and the third argument (optional) is the `chunk_size`.

The `chunk_size` specifies how much space the dynamic SNode allocates when the previously-allocated space runs out.
For example, with `chunk_size=4`, the dynamic SNode allocates the space for four elements when the first element is appended, and
allocates space for another four when the 5th (, 9th, 13th...) element is appended.

You can use `x[i].append(...)` to append an element,
use `x[i].length()` to get the length, and use `x[i].deactivate()` to clear the list.

The code snippet below creates a struct field that stores pairs of `(i16, i64)`.
The `i` axis is a dense SNode, and the `j` axis is a dynamic SNode.

```python {5,13,15,20} title=dynamic.py
pair = ti.types.struct(a=ti.i16, b=ti.i64)
pair_field = pair.field()

block = ti.root.dense(ti.i, 4)
pixel = block.dynamic(ti.j, 100, chunk_size=4)
pixel.place(pair_field)
l = ti.field(ti.i32)
ti.root.dense(ti.i, 5).place(l)

@ti.kernel
def make_lists():
for i in range(5):
for j in range(i):
ti.append(x.parent(), i, j * j) # ti.append(pixel, i, j * j)
l[i] = ti.length(x.parent(), i) # [0, 1, 2, 3, 4]
def dynamic_pair():
for i in range(4):
pair_field[i].deactivate()
for j in range(i * i):
pair_field[i].append(pair(i, j + 1))
# pair_field = [[],
# [(1, 1)],
# [(2, 1), (2, 2), (2, 3), (2, 4)],
# [(3, 1), (3, 2), ... , (3, 8), (3, 9)]]
l[i] = pair_field[i].length() # l = [0, 1, 4, 9]
```


<center>

![Dynamic](https://raw.githubusercontent.com/taichi-dev/public_files/master/taichi/doc/dynamic.png)

</center>

:::note
A dynamic SNode must have one axis only, and the axis must be the last axis.
No other SNodes can be placed under a dynamic SNode. In other words, a dynamic SNode must be directly placed with a field.
Along the path from a dynamic SNode to the root of the SNode tree, other SNodes *must not* have the same axis as the dynamic SNode.
:::

## Computation on spatially sparse data structures

### Sparse struct-fors
Expand Down

0 comments on commit 9cbfdd1

Please sign in to comment.