Proposal of defining types and constructing objects in a more consistent way

[strongoier]

Currently, there are two common ways in Taichi to construct a vector:

# directly construct a vector object of type vector<3, i32> by providing initial values
a = ti.Vector([0, 0, 0])

# first define type vector<3, i32>
i32vec3 = ti.types.vector(n=3, dtype=ti.i32)
# then construct a vector object of that type and fill in initial values
b = i32vec3([0, 0, 0])

They diverge in many aspects, and users can easily get confused. I think it is time for a unification.

Similar to discussions in #4085, we can consider ti.types.vector as a type with two template parameters (n and dtype). We need to first specialize it with 0, 1, or 2 of these parameters, and use the specialized type to construct an actual object:

vec = ti.types.vector()
vec3 = ti.types.vector(n=3)
i32vec = ti.types.vector(dtype=ti.i32)
i32vec3 = ti.types.vector(n=3, dtype=ti.i32)

c = vec([0, 0, 0])
d = vec3([0, 0, 0])
e = i32vec([0, 0, 0])
f = i32vec3([0, 0, 0])

With type inference, each of c, d, e, f should be of the same type vector<3, i32>. Then we can make ti.Vector([0, 0, 0]) simply as a shortcut for ti.types.vector()([0, 0, 0]) in order to keep the old yet sweet API unchanged.

In this way, all these things get linked together.

---

A remaining issue lies in the different use of lower/upper cases.

I suggest to consistently use the lower case (ti.vector, ti.types.vector) throughout the API, which is also consistent with field and ndarray. To avoid breaking existing user code immediately, we can mark ti.Vector as deprecated starting from a much later release in v1.x and remove it from v2.0.

To summarize the current situation, we will have these APIs under the ti.types package for parameter type annotation...

• ti.types.vector, ti.types.matrix
• ti.types.struct
• ti.types.ndarray

... and these APIs under the top-level ti package for constructing the instances:

• ti.vector (and ti.Vector for legacy reason), ti.matrix (and ti.Matrix for legacy reason)
• ti.struct
• ti.ndarray
• ti.field

Usage:

arrf2d = ti.types.ndarray(dim=2, dtype=ti.f32)

@ti.kernel
def run(inarr: arrf2d, outarr: arrf2d):
  ...

arr1 = arrf2d(shape=(128, 128))
# or equivalently
arr2 = ti.ndarray(dtype=ti.f32, shape=(128, 128))

[k-ye]

@strongoier I added a small use case, do we agree on this API?

[strongoier]

Looks good to me!