Taichi: [Lang] [refactor] Use "field" to replace "var" in API, "tensor" in doc

[archibate]

@Rullec @yuanming-hu Continue our discussion in: https://github.com/taichi-dev/taichi/issues/1156#issuecomment-658532635

1. Introduction about our new allocating API

The new naming mechanism can be formulated in these 3 rules:

• use ti.field(dtype, ...) to allocate a global scalar field (tensors)
• use ti.Vector.field/ti.Matrix.field to allocate global vector/matrix fields (tensors)
• use ti.Vector and ti.Matrix for local variable

In one word, anything involved in the name field must be a global stuff, and all others must be some local things.
The difference between old and new names are exposed below, in the following working plan.

2. Working plan

2.1 Add new API

• [x] Support ti.field, ti.Vector.field, ti.Matrix.field

Simply renaming ti.var to ti.field should work.
In fact we already have ti.Matrix.var, so please rename that too :)

• [x] Use dt -> dtype as arguement by-the-way

Btw, the argument dt should be renamed to dtype, i.e. ti.field(dtype=ti.f32, shape=()).

2.2 Deprecate old API

• [x] Deprecate ti.var, ti.Vector.var, ti.Matrix.var

We don't want to fully abandon ti.var support yet, so let's only raise a warning before the API-breaking v0.7.0.

Let's make a dummy ti.var with simply redirect to corresponding field function:

def var(...):
  return field(...)

And please use the @deprecated decorator, it will raise a warning when the decorated function is being called, see ti.Matrix.transposed for usage example.

• [x] Deprecate ti.Vector, ti.Matrix usage for declaring global matrix fields.

We may not use @deprecated since ti.Vector is already for local matrix variables... So please use ti.warning in if-elif's instead.

2.3 Update docs, tests, examples for API change

• [x] Update examples for "ti.var" -> "ti.field"
• [x] Update tests for "ti.var" -> "ti.field"
• [x] Update docs for "ti.var" -> "ti.field"

Simply s/\.var/\.field/g should works. Relative trivial, compare to the next one:

2.4 Update docs for term change

• [x] Update docs for "tensor" -> "field"

This could be the most heavy-mind task in this issue, note that you can't simply s/tensor/field/g because:

1. We want to rename these too:
2. tensors -> fields
3. Tensor -> Field

4. ...

5. We don't want to rename these:

6. TensorFlow -> FieldFlow
7. torch tensor -> torch field
8. ...

NOTE: "tensor" -> "field" should be put in a separate PR for easy-to-review.

If someone is super familiar with sed and awk on how this can be done, please go ahead :)

2.5 Future works

• [x] Claim that we once used "tensor" as term for "field"

So that new students don't get puzzled when looking into old posts on zhihu that using the term "Taichi tensor".

• [ ] Fully remove "ti.var" and other @deprecated functions in v0.7.0

[Rullec]

Let's use this #1500 and delete my #1501!
I personnaly have 2 advice

1. maybe using some titles like

2. Working plan

2.1 Support new interfaces

2.2 Deprecate old interfaces

2.3 Add test for new interfaces

2.4 update our code examples

2.5 update the document

so that the statement can be more clear?

1. given a whole-scope statement about our new naming API maybe similar to #1501

HDYT? I will delete #1501 after your response

[Rullec]

Please let me begin to explore a proper way for accomplishing part 2.3 and 2.4, when you are doing work on 2.1 - 2.2

[Rullec]

HDYT?

[archibate]

Yes, please go ahead with 2.4 first :) 2.3 depends on 2.1 and need to be done later.

[Rullec]

Update:
2.4 has been mostly finished. Though I'm still proofreading it till I can personnally confirm that here is not obvious error.

Is it worth to have a PR or draft PR now? Or maybe you have another schedule?

[archibate]

Update:
2.4 has been mostly finished. Though I'm still proofreading it till I can personnally confirm that here is not obvious error.

Is it worth to have a PR or draft PR now? Or maybe you have another schedule?

Great! Please open a draft PR now, I have time to review given that @yuanming-hu is still reviewing my stale PRs :)

[Rullec]

Hi all!

Is the only left stuff is fully deprecated ti.var, right? Is there anything We need to do on this issue?

[archibate]

Is the only left stuff

Yes, we can close this issue once we finally obsolete ti.var, i.e. calling ti.var() will result in an error after that point.
Now we need to discuss about when to do the obsolete point. v0.7.0? v0.7.5? v0.8.0? @yuanming-hu Thoughts?

[BlurryLight]

@archibate
Hey there. There is no warning about the "ti.var" is going to be deprecated when I call "ti.var".

import taichi as ti 
p = ti.var(ti.i32, shape=()) 

in [Taichi] version 0.6.28, llvm 10.0.0, commit a58a9af7, linux, python 3.7.7, it compiles and says nothing about the ti.var has been sneakily replaced by ti.field. I relized it only when I looked through the documents.

[archibate]

@archibate
Hey there. There is no warning about the "ti.var" is going to be deprecated when I calls "ti.var".

import taichi as ti 
p = ti.var(ti.i32, shape=()) 

in [Taichi] version 0.6.28, llvm 10.0.0, commit a58a9af7, linux, python 3.7.7, it compiles and says nothing about the ti.var has been sneakily replaced by ti.field. I relized it only when I looked through the documents.

Thank for reporting! But I can't reproduce this issue on my end:

[bate@archit ~]$ p a.py
[Taichi] mode=release
[Taichi] preparing sandbox at /tmp/taichi-4vpgcotz
[Taichi] version 0.6.29, llvm 10.0.0, commit b63f6663, linux, python 3.8.3
a.py:5: DeprecationWarning: ti.var is deprecated, please use ti.field instead
ti.var 已被废除，请使用 ti.field 来替换
  p = ti.var(ti.i32, shape=())

Does upgrading to 0.6.29 solve the issue?

[BlurryLight]

@archibate oops! Currently the taichi is still 0.6.28 in Douban source. The mirror has yet synced with the upstream. Thanks for you answer.