一、Taichi计算核（Kernel）

在函数定义上一行加上 @ti.kernel 装饰器，该函数会被编译为高性能 Taichi 计算核。

• 只能在 Python 域调用 Kernel，不能在 Kernel 内再调用另一个 Kernel。

1、正确示例

1
@ti.kernel
2
def foo():
3
    print("foo")      # 输出 "foo"
4

5
@ti.kernel
6
def bar():
7
    print("bar")      # 输出 "bar"
8

9
foo()                 # 在 Python 域调用
10
bar()                 # 在 Python 域调用

2、错误示例

1
@ti.kernel
2
def foo():
3
    print("foo")
4
    bar()             # 错误！不能在 Kernel 内调用另一个 Kernel
5

6
@ti.kernel
7
def bar():
8
    print("bar")
9

10
foo()

二、为什么要使用太极运算核？

1、太极运算核的并行调用

通过 @ti.kernel 装饰器，用户可以将计算密集型任务交由 Taichi 的 JIT 编译器处理，从而在多核 CPU 或 GPU 上实现显著的性能提升。

@ti.kernel 装饰的函数会自动并行化 Taichi 域最外层的 for 循环，从而充分利用硬件资源。例如：

1
@ti.kernel
2
def fill():
3

4
    for i in range(10):
5
        x[i]+=1
6
        s=0
7

8
        for j in range(5):
9
            s+=j
10
        y[i]=s
11

12
    for k in range(20):
13
        z[k]=k

2、for循环的并行性要求

只有最外层 for 循环会被并行化，内层循环不会。

1
@ti.kernel
2
def foo():
3
    if k > 42:
4
        for i in range(10):   # 不是最外层，不会并行
5
            ...

3、控制并行与串行的技巧

在下面的程序中，如果不想并行运行第一个循环，而想并行运行第二个循环，你可以这么写：

1
@ti.kernel
2
def my_loop():
3
    for i in range(10):
4
        for j in range(20):
5
            ...
6
def my_loop():
7
    for i in range(10):
8
        loop()
9

10
@ti.kernel
11
def loop()
12
    for j in range(20):
13
        ...
14

15
my_loop()

4、并行循环下的限制

在并行的最外层 for 循环中，不能使用 break 语句。

1
@ti.kernel
2
def loop():
3
    for i in range(10):
4
        ...
5
        break

但在串行（如内层循环）可以使用 break：

1
@ti.kernel
2
def loop():
3
    for i in range(10):
4
        ...
5
        for j in range(20):
6
            ...
7
            break  # 合法，内层串行循环可以 break

三、条件竞争（Race Condition）

由于Taichi程序会并行运行最外层内容，当并行的两处程序同时对一个变量进行操作时会产生条件竞争。条件竞争下，使用+=运算符会保证操作的原子性，但是x=x+y的写法不保证操作能被原子化保护，可能出现并行情况下for循环中两个分支同时写入它的情况。例如：

1
def sum():
2
    for i in range(10):
3

4
    A[None] += x[i]
5
    ti.atomic_add(A[None],x[i])
6

7
    A[None] = a[None] + x[i]

四、struct-for语法（场的遍历）

对于场（field）的数据类型，存在一种更简单的循环方法，例如下面一份代码：

1
import taichi as ti
2

3
ti.init(arch=ti.cpu)
4

5
N = 10
6
x = ti.Vector.field(2, dtype=ti.i32, shape=(N, N))
7

8
@ti.kernel
9
def foo():
10
    for i,j in x:
11
        x[i,j] = ti.Vector([i,j])
12

13
foo()

但是，struct-for的语法只对Taichi域的最外层循环有效，在内层循环不可以使用这种方法。

五、Kernel参数和返回值

1、参数

1. 目前最多是8个。
2. 且由Python作用域传到Taichi作用域。
3. 传递参数时必须把类型写出来（type-hinted），因为python本身是弱类型的一个解释性语言，所以从python里传进来的东西taichi并不知道它是什么东西。所以在@ti.kernel里函数定义传参的时候，我们需要把类型显式声明出来。
4. 只支持标量，如果要传矢量，要先把矢量拆开当标量传进来，再组装回矢量。
5. Taichi目前只支持值传递（与引用传递对立），也就是传参时发生一次数据拷贝，在函数内部对参数的修改不影响外部。

2、返回值

1. 可以有返回值，也可以无返回值。若有返回值，只能有一个返回值。
2. 返回值必须使用 -> 运算符标明数据类型，且只能是标量。例如:

   1
   @ti.kernel
   2
   def my_kernel() -> ti.i32
   3
       return 123.456
   4
   
   5
   print(my_kernel()) #输出123，123.456会隐式地 `cast` 成为一个 `ti.i32` 数据类型。

六、太极函数（Function）

在函数的上一行加上@ti.func修饰，可以使函数成为太极函数（Taichi Function），它只能在Taichi作用域中被调用。太极函数可以帮助你在太极计算核中重复调用某些功能。

1、正确示例

1
@ti.kernel
2
def foo():
3
    print("foo")
4
    bar()
5

6
@ti.func
7
def bar():
8
    print("bar")
9

10
foo()

2、错误示例

1
def foo():
2
    print("foo")
3
    bar()
4

5
@ti.func
6
def bar():
7
    print("bar")
8

9
foo()

七、太极函数的嵌套和参数

1. 太极函数传参时不需要表明参数的数据类型，因为太极函数的参数一定来自于太极作用域中，而太极作用域已经标明数据的类型。
2. 太极函数可以没有返回值，也可以有返回值。
3. 因为太极是内联实现的，所以返回值可以使任意类型，且可以使任意多个。例如下面这份代码：

   1
   import taichi as ti
   2
   
   3
   ti.init(arch=cpu)
   4
   
   5
   @ti.func
   6
   def foo(vec):
   7
       return vec[1], vec[2]
   8
   
   9
   @ti.kernel
   10
   def my_kernel():
   11
       x, y = foo(ti.Vector([2, 3.3]))
   12
       print(x, y) #输出2和3,3
   13
   
   14
   my_kernel()

4. 太极函数的内联并非简单内联，向其中传递的参数仍然是值传递，会将参数复制一份传递进去。

八、Taichi作用域的部分特点

1. 在Taichi作用域内，所有的数据都是静态的。当一个数据被赋值为int，哪怕再用浮点数赋值，也会转为int，用vector赋值则报错。
2. 在Taichi作用域内，所有的词法作用域都是静态的，在if、for中定义的数据只能在局部中奏效。例如：

   1
   @ti.kernel
   2
   def err_out_scope(x: float):
   3
       if x < 0:
   4
           y = -x
   5
       else:
   6
           y = x
   7
   
   8
       print(y)

3. 如果想要创建一个全局变量，请定义场（field），你可以通过下面代码的变化来感受这一点。

   1
   import taichi as ti
   2
   
   3
   ti.init(arch=ti.cpu)
   4
   
   5
   a = 42
   6
   a = ti.field(ti.i32, shape=())
   7
   a[None] = 42
   8
   
   9
   @ti.kernel
   10
   def print_a():
   11
       print("a =", a)
   12
       print("a =", a[None])
   13
   
   14
   print_a()
   15
   # 输出 a = 42
   16
   a = 53
   17
   a[None] = 53
   18
   print("a =", a)
   19
   # 输出 a = 53
   20
   print_a()
   21
   # 输出 a = 42
   22
   # 输出 a = 53

九、Taichi中的数学运算：

1
ti.sin(x)
2
ti.cos(x)
3
ti.tan(x)
4
ti.asin(x)
5
ti.acos(x)
6
ti.atan2(y, x)
7
ti.sqrt(x)
8
ti.floor(x)
9
ti.ceil(x)
10
ti.inv(x)
11
ti.tanh(x)
12
ti.exp(x)
13
ti.log(x)
14
ti.random(data_type)
15
abs(x)
16
int(x)
17
float(x)
18
max(x, y, ...)
19
min(x, y, ...)
20
x ** y
21
A.transpose()
22
A.inverse()
23
A.trace()
24
A.determinant()
25
A.normalized()
26
A + B
27
A * B
28
A @ B
29
R, S = ti.polar_decompose(A, ti.f32)
30
U, sigma, V = ti.svd(A, ti.f32)
31
lambda, V = ti.eig(A, ti.f32)
32
u.dot(v)            # 标量
33
u.cross(v)          # 向量
34
u.outer_product()   # 矩阵