# Vectors¶

A vector in Taichi can have two forms:

• as a temporary local variable. An `n` component vector consists of `n` scalar values.
• as an element of a global field. In this case, the field is an N-dimensional array of `n` component vectors.

In fact, `Vector` is simply an alias of `Matrix`, just with `m = 1`. See Matrices and Fields and matrices for more details.

## Declaration¶

### As global vector fields¶

`ti.Vector.``field`(n, dtype, shape = None, offset = None)
Parameters: n – (scalar) the number of components in the vector dtype – (DataType) data type of the components shape – (optional, scalar or tuple) shape of the vector field, see Fields and matrices offset – (optional, scalar or tuple) see Coordinate offsets

For example, this creates a 3-D vector field of the shape of `5x4`:

```# Python-scope
a = ti.Vector.field(3, dtype=ti.f32, shape=(5, 4))
```

Note

In Python-scope, `ti.field` declares a scalar field (Scalar fields), while `ti.Vector.field` declares a vector field.

### As a temporary local variable¶

`ti.``Vector`([x, y, ...])
Parameters: x – (scalar) the first component of the vector y – (scalar) the second component of the vector

For example, this creates a 3D vector with components (2, 3, 4):

```# Taichi-scope
a = ti.Vector([2, 3, 4])
```

## Accessing components¶

### As global vector fields¶

`a[p, q, ...][i]`
Parameters: a – (ti.Vector.field) the vector p – (scalar) index of the first field dimension q – (scalar) index of the second field dimension i – (scalar) index of the vector component

This extracts the first component of vector `a[6, 3]`:

```x = a[6, 3]

# or
vec = a[6, 3]
x = vec
```

Note

Always use two pairs of square brackets to access scalar elements from vector fields.

• The indices in the first pair of brackets locate the vector inside the vector fields;
• The indices in the second pair of brackets locate the scalar element inside the vector.

For 0-D vector fields, indices in the first pair of brackets should be `[None]`.

### As a temporary local variable¶

`a[i]`
Parameters: a – (Vector) the vector i – (scalar) index of the component

For example, this extracts the first component of vector `a`:

```x = a
```

This sets the second component of `a` to 4:

```a = 4
```

TODO: add descriptions about `a(i, j)`

### XYZW vector component accessors¶

We also provide four handy accessors for the first four vector components:

`a.``x`

Same as `a`.

`a.``y`

Same as `a`.

`a.``z`

Same as `a`.

`a.``w`

Same as `a`.

Note

XYZW accessors can be used for both reading and writing:

```v = ti.Vector([2, 3, 4])
print(v.x)  # 2
print(v.y)  # 3
print(v.z)  # 4
v.y = 8
print(v.y)  # 8
```

XYZW accessors can be used in both Taichi-scope and Python-scope.

XYZW accessors don’t work for `ti.Matrix`.

For GLSL-alike shuffling accessors, consider using taichi_glsl:

```import taichi_glsl as tl

v = tl.vec(2, 3, 4)
print(v.xy)  # [2 3]
print(v._xYzX_z)  # [0 2 -3 4 -2 0 4]
```

## Methods¶

`a.``norm`(eps = 0)
Parameters: a – (ti.Vector) eps – (optional, scalar) a safe-guard value for `sqrt`, usually 0. See the note below. (scalar) the magnitude / length / norm of vector

For example,

```a = ti.Vector([3, 4])
a.norm() # sqrt(3*3 + 4*4 + 0) = 5
```

`a.norm(eps)` is equivalent to `ti.sqrt(a.dot(a) + eps)`

Note

To safeguard the operator’s gradient on zero vectors during differentiable programming, set `eps` to a small, positive value such as `1e-5`.

`a.``norm_sqr`()
Parameters: a – (ti.Vector) (scalar) the square of the magnitude / length / norm of vector

For example,

```a = ti.Vector([3, 4])
a.norm_sqr() # 3*3 + 4*4 = 25
```

`a.norm_sqr()` is equivalent to `a.dot(a)`

`a.``normalized`()
Parameters: a – (ti.Vector) (ti.Vector) the normalized / unit vector of `a`

For example,

```a = ti.Vector([3, 4])
a.normalized() # [3 / 5, 4 / 5]
```

`a.normalized()` is equivalent to `a / a.norm()`.

`a.``dot`(b)
Parameters: a – (ti.Vector) b – (ti.Vector) (scalar) the dot (inner) product of `a` and `b`

E.g.,

```a = ti.Vector([1, 3])
b = ti.Vector([2, 4])
a.dot(b) # 1*2 + 3*4 = 14
```
`a.``cross`(b)
Parameters: a – (ti.Vector, 2 or 3 components) b – (ti.Vector of the same size as a) (scalar (for 2D inputs), or 3D Vector (for 3D inputs)) the cross product of `a` and `b`

We use a right-handed coordinate system. E.g.,

```a = ti.Vector([1, 2, 3])
b = ti.Vector([4, 5, 6])
c = ti.cross(a, b)
# c = [2*6 - 5*3, 4*3 - 1*6, 1*5 - 4*2] = [-3, 6, -3]

p = ti.Vector([1, 2])
q = ti.Vector([4, 5])
r = ti.cross(a, b)
# r = 1*5 - 4*2 = -3
```
`a.``outer_product`(b)
Parameters: a – (ti.Vector) b – (ti.Vector) (ti.Matrix) the outer product of `a` and `b`

E.g.,

```a = ti.Vector([1, 2])
b = ti.Vector([4, 5, 6])
c = ti.outer_product(a, b) # NOTE: c[i, j] = a[i] * b[j]
# c = [[1*4, 1*5, 1*6], [2*4, 2*5, 2*6]]
```

Note

The outer product should not be confused with the cross product (`ti.cross`). For example, `a` and `b` do not have to be 2- or 3-component vectors for this function.

`a.``cast`(dt)
Parameters: a – (ti.Vector) dt – (DataType) (ti.Vector) vector with all components of `a` casted into type `dt`

E.g.,

```# Taichi-scope
a = ti.Vector([1.6, 2.3])
a.cast(ti.i32) # [2, 3]
```

See Type system for more details.

Note

Vectors are special matrices with only 1 column. In fact, `ti.Vector` is just an alias of `ti.Matrix`.

`a.``n`
Parameters: a – (ti.Vector or ti.Vector.field) (scalar) return the dimensionality of vector `a`

E.g.,

```# Taichi-scope
a = ti.Vector([1, 2, 3])
a.n  # 3
```
```    # Python-scope
a = ti.Vector.field(3, dtype=ti.f32, shape=(4, 5))
a.n  # 3

See :ref:`meta` for more details.
```

Note

When used as a global vector field, it will additionally contain all the metadata that a scalar field would have, E.g.:

```# Python-scope
a = ti.Vector.field(3, dtype=ti.f32, shape=(4, 5))
a.shape  # (4, 5)
a.dtype  # ti.f32
```

## Element-wise operations (WIP)¶

TODO: add element wise operations docs