Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Doc] Update dataclass.md #6876

Merged
merged 5 commits into from
Dec 15, 2022
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 8 additions & 11 deletions docs/lang/articles/advanced/dataclass.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ sidebar_position: 4

Taichi provides custom [struct types](../type_system/type.md#compound-types) for developers to assemble pieces of data together. However, it would be more convenient to have:

- A Python representation of the struct type which is more object oriented.
- Functions associated with a struct type (C++-style structs).
- A Python representation of the struct type which is more Object-Oriented.
- Functions associated with a struct type.


To achieve the ends, Taichi enabled the `@ti.dataclass` decorator on a Python class. This is inspired by Python's [dataclass](https://docs.python.org/3/library/dataclasses.html) feature, which uses class fields with annotations to create data types.

## Create a struct from a Python class
## Create a Struct from a Python Class
vai9er marked this conversation as resolved.
Show resolved Hide resolved
Olinaaaloompa marked this conversation as resolved.
Show resolved Hide resolved

The following is an example of defining a Taichi struct type under a Python class:

Expand All @@ -22,19 +22,16 @@ class Sphere:
center: vec3
radius: ti.f32
```
This creates the *exact* same type as using `ti.types.struct()`:
This is the same equivalent as using `ti.types.struct()`:

```python
Sphere = ti.types.struct(center=vec3, radius=ti.f32)
```
The `@ti.dataclass` decorator converts the annotated members in the Python class to members in the resulting struct type. In both of the above examples, you end up with the same struct field.
The `@ti.dataclass` decorator converts the annotated members in the `Python class` to members in the resulting `Struct Type`. In both of the above examples, you end up with the same struct field.
Olinaaaloompa marked this conversation as resolved.
Show resolved Hide resolved
Olinaaaloompa marked this conversation as resolved.
Show resolved Hide resolved

```python
sphere_field = Sphere.field(shape=(n,))
```

## Associate functions with the struct type
Python classes can have functions attached to them, and so can Taichi struct types. Building from the above example, one can embed functions in the struct as follows:
## Associate Functions with the Struct Type
vai9er marked this conversation as resolved.
Show resolved Hide resolved
Olinaaaloompa marked this conversation as resolved.
Show resolved Hide resolved
Both Python classes and Taichi struct types can have functions attached to them. Building from the above example, one can embed functions in the struct as follows:

```python
@ti.dataclass
Expand All @@ -54,7 +51,7 @@ class Sphere:

Functions associated with structs follow the same scope rules as other functions. In other words, they can be placed in either the Taichi scope or the Python scope. Each instance of the `Sphere` struct type now have the above functions attached to them. The functions can be called in the following way:

```python
```python{3,10}
a_python_struct = Sphere(center=vec3(0.0), radius=1.0)
# calls a python scope function from python
a_python_struct.is_zero_sized() # False
Expand Down