# Operators

Here we present the supported operators in Taichi for both primitive types and compound types such as matrices.

## Supported operators for primitive types

### Arithmetic operators

Operation | Result |
---|---|

`-a` | `a` negated |

`+a` | `a` unchanged |

`a + b` | sum of `a` and `b` |

`a - b` | difference of `a` and `b` |

`a * b` | product of `a` and `b` |

`a / b` | quotient of `a` and `b` |

`a // b` | floored quotient of `a` and `b` |

`a % b` | remainder of `a / b` |

`a ** b` | `a` to the power of `b` |

##### note

The `%`

operator in Taichi follows the Python style instead of C style,
e.g.,

`# In Taichi-scope or Python-scope:`

print(2 % 3) # 2

print(-2 % 3) # 1

For C-style mod (`%`

), please use `ti.raw_mod`

. This function also receives floating points as arguments.

`ti.raw_mod(a, b)`

returns `a - b * int(float(a) / b)`

.

`print(ti.raw_mod(2, 3)) # 2`

print(ti.raw_mod(-2, 3)) # -2

print(ti.raw_mod(3.5, 1.5)) # 0.5

##### note

Python3 distinguishes `/`

(true division) and `//`

(floor division), e.g., `1.0 / 2.0 = 0.5`

, `1 / 2 = 0.5`

, `1 // 2 = 0`

,
`4.2 // 2 = 2`

. Taichi follows the same design:

**True divisions**on integral types first cast their operands to the default floating point type.**Floor divisions**on floating point types first cast their operands to the default integral type.

To avoid such implicit casting, you can manually cast your operands to
desired types, using `ti.cast`

. Please see
Default precisions for more details on
default numerical types.

Taichi also provides `ti.raw_div`

function which performs true division if one of the operands is floating point type
and performs floor division if both operands are integral types.

`print(ti.raw_div(5, 2)) # 2`

print(ti.raw_div(5, 2.0)) # 2.5

### Comparison operators

Operation | Result |
---|---|

`a == b` | if `a` is equal to `b` , then True, else False |

`a != b` | if `a` is not equal to `b` , then True, else False |

`a > b` | if `a` is strictly greater than `b` , then True, else False |

`a < b` | if `a` is strictly less than `b` , then True, else False |

`a >= b` | if `a` is greater than or equal to `b` , then True, else False |

`a <= b` | if `a` is less than or equal to `b` , then True, else False |

### Logical operators

Operation | Result |
---|---|

`not a` | if `a` is False, then True, else False |

`a or b` | if `a` is False, then `b` , else `a` |

`a and b` | if `a` is False, then `a` , else `b` |

### Conditional operations

The result of conditional expression `a if cond else b`

is `a`

if `cond`

is True, or `b`

otherwise.
`a`

and `b`

must have a same type.

The conditional expression does short-circuit evaluation, which means the branch not chosen is not evaluated.

`a = ti.field(ti.i32, shape=(10,))`

for i in range(10):

a[i] = i

@ti.kernel

def cond_expr(ind: ti.i32) -> ti.i32:

return a[ind] if ind < 10 else 0

cond_expr(3) # returns 3

cond_expr(10) # returns 0, a[10] is not evaluated

For element-wise conditional operations on Taichi vectors and matrices,
Taichi provides `ti.select(cond, a, b)`

which **does not** do short-circuit evaluation.

`cond = ti.Vector([1, 0])`

a = ti.Vector([2, 3])

b = ti.Vector([4, 5])

ti.select(cond, a, b) # ti.Vector([2, 5])

### Bitwise operators

Operation | Result |
---|---|

`~a` | the bits of `a` inverted |

`a & b` | bitwise and of `a` and `b` |

`a ^ b` | bitwise exclusive or of `a` and `b` |

`a | b` | bitwise or of `a` and `b` |

`a << b` | left-shift `a` by `b` bits |

`a >> b` | right-shift `a` by `b` bits |

##### note

The `>>`

operation denotes the
Shift Arithmetic Right (SAR) operation.
For the Shift Logical Right (SHR) operation,
consider using `ti.bit_shr()`

. For left shift operations, SAL and SHL are the
same.

### Trigonometric functions

`ti.sin(x)`

ti.cos(x)

ti.tan(x)

ti.asin(x)

ti.acos(x)

ti.atan2(x, y)

ti.tanh(x)

### Other arithmetic functions

`ti.sqrt(x)`

ti.rsqrt(x) # A fast version for `1 / ti.sqrt(x)`.

ti.exp(x)

ti.log(x)

ti.round(x, dtype=None)

ti.floor(x, dtype=None)

ti.ceil(x, dtype=None)

ti.sum(x)

ti.max(x, y, ...)

ti.min(x, y, ...)

ti.abs(x) # Same as `abs(x)`

ti.pow(x, y) # Same as `pow(x, y)` and `x ** y`

The `dtype`

argument in `round`

, `floor`

and `ceil`

functions specifies the data type of the returned value. The default `None`

means the returned type is the same as input `x`

.

### Builtin-alike functions

`abs(x) # Same as `ti.abs(x, y)``

pow(x, y) # Same as `ti.pow(x, y)` and `x ** y`.

### Random number generator

`ti.random(dtype=float)`

##### note

`ti.random`

supports `u32`

, `i32`

, `u64`

, `i64`

, and all floating point types.
The range of the returned value is type-specific.

Type | Range |
---|---|

i32 | -2,147,483,648 to 2,147,483,647 |

u32 | 0 to 4,294,967,295 |

i64 | -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 |

u64 | 0 to 18,446,744,073,709,551,615 |

floating point | 0.0 to 1.0 |

### Supported atomic operations

In Taichi, augmented assignments (e.g., `x[i] += 1`

) are automatically
atomic.

##### caution

When modifying global variables in parallel, make sure you use atomic
operations. For example, to sum up all the elements in `x`

,

`@ti.kernel`

def sum():

for i in x:

# Approach 1: OK

total[None] += x[i]

# Approach 2: OK

ti.atomic_add(total[None], x[i])

# Approach 3: Wrong result since the operation is not atomic.

total[None] = total[None] + x[i]

##### note

When atomic operations are applied to local values, the Taichi compiler will try to demote these operations into their non-atomic counterparts.

Apart from the augmented assignments, explicit atomic operations, such
as `ti.atomic_add`

, also do read-modify-write atomically. These
operations additionally return the **old value** of the first argument.
For example,

`x[i] = 3`

y[i] = 4

z[i] = ti.atomic_add(x[i], y[i])

# now x[i] = 7, y[i] = 4, z[i] = 3

Below is a list of all explicit atomic operations:

Operation | Behavior |
---|---|

`ti.atomic_add(x, y)` | atomically compute `x + y` , store the result in `x` , and return the old value of `x` |

`ti.atomic_sub(x, y)` | atomically compute `x - y` , store the result in `x` , and return the old value of `x` |

`ti.atomic_and(x, y)` | atomically compute `x & y` , store the result in `x` , and return the old value of `x` |

`ti.atomic_or(x, y)` | atomically compute `x | y` , store the result in `x` , and return the old value of `x` |

`ti.atomic_xor(x, y)` | atomically compute `x ^ y` , store the result in `x` , and return the old value of `x` |

`ti.atomic_max(x, y)` | atomically compute `max(x, y)` , store the result in `x` , and return the old value of `x` |

`ti.atomic_min(x, y)` | atomically compute `min(x, y)` , store the result in `x` , and return the old value of `x` |

##### note

Supported atomic operations on each backend:

type | CPU | CUDA | OpenGL | Metal | C source |
---|---|---|---|---|---|

i32 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |

f32 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |

i64 | ✔️ | ✔️ | ⭕ | ❌ | ✔️ |

f64 | ✔️ | ✔️ | ⭕ | ❌ | ✔️ |

(⭕ Requiring extensions for the backend.)

## Supported operators for matrices

The previously mentioned operations on primitive types can also be applied on compound types such as matrices. In these cases, they are applied in an element-wise manner. For example:

`B = ti.Matrix([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])`

C = ti.Matrix([[3.0, 4.0, 5.0], [6.0, 7.0, 8.0]])

A = ti.sin(B)

# is equivalent to

for i in ti.static(range(2)):

for j in ti.static(range(3)):

A[i, j] = ti.sin(B[i, j])

A = B ** 2

# is equivalent to

for i in ti.static(range(2)):

for j in ti.static(range(3)):

A[i, j] = B[i, j] ** 2

A = B ** C

# is equivalent to

for i in ti.static(range(2)):

for j in ti.static(range(3)):

A[i, j] = B[i, j] ** C[i, j]

A += 2

# is equivalent to

for i in ti.static(range(2)):

for j in ti.static(range(3)):

A[i, j] += 2

A += B

# is equivalent to

for i in ti.static(range(2)):

for j in ti.static(range(3)):

A[i, j] += B[i, j]

In addition, the following methods are supported matrices operations:

`a = ti.Matrix([[2, 3], [4, 5]])`

a.transpose() # the transposed matrix of `a`, will not effect the data in `a`.

a.trace() # the trace of matrix `a`, the returned scalar value can be computed as `a[0, 0] + a[1, 1] + ...`.

a.determinant() # the determinant of matrix `a`.

a.inverse() # (ti.Matrix) the inverse of matrix `a`.

a@a # @ denotes matrix multiplication

##### note

For now, determinant() and inverse() only works in Taichi-scope, and the size of the matrix must be 1x1, 2x2, 3x3 or 4x4.