From 52bdcb4dd2e0c8c0bf5d512f5a5de08c7d1bb790 Mon Sep 17 00:00:00 2001 From: archibate <1931127624@qq.com> Date: Fri, 31 Jul 2020 15:43:14 +0800 Subject: [PATCH 1/5] [skip ci] Revert "[skip ci] revert type.rst" This reverts commit a9866750d0c91991bc4511b0b238cf4f9b5ecf1a. --- docs/type.rst | 112 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 94 insertions(+), 18 deletions(-) diff --git a/docs/type.rst b/docs/type.rst index 0f01ec8745852..0173b74f2fda1 100644 --- a/docs/type.rst +++ b/docs/type.rst @@ -1,8 +1,33 @@ Type system =========== +Taichi supports many data types. The type name is recognized as +a *prefix character* + a *digital number*. + +The *prefix character* can be one of: + +- ``i`` for signed integers, e.g. 233, -666 +- ``u`` for unsigned integers, e.g. 233, 666 +- ``f`` for floating point numbers, e.g. 2.33, 1e-4 + +The *digital number* can be one of: + +- ``8`` +- ``16`` +- ``32`` +- ``64`` + +It represents how many **bits** are used in storing the data. +The larger the bit number, the higher the precision is. + +For example, the two most commonly used types: + +- ``i32`` represents a 32-bit signed integer. +- ``f32`` represents a 32-bit floating pointer number. + Supported types --------------- + Currently, supported basic types in Taichi are - int8 ``ti.i8`` @@ -46,13 +71,21 @@ Currently, supported basic types in Taichi are (OK: supported, EXT: require extension, N/A: not available) -Boolean types should be represented using ``ti.i32``. +.. note:: -Binary operations on different types will give you a promoted type, following the C programming language, e.g. + Boolean types are represented using ``ti.i32``. -- ``i32 + f32 = f32`` -- ``f32 + f64 = f64`` -- ``i32 + i64 = i64`` + + +Type promotion +-------------- + +Binary operations on different types will give you a promoted type, following the C programming language convention, e.g.: + +- ``i32 + f32 = f32`` (integer + float = float) +- ``i32 + i64 = i64`` (less-bits + more-bits = more-bits) + +Basically it will try to choose the more precise type to contain the result value. .. _default_precisions: @@ -62,6 +95,7 @@ Default precisions By default, numerical literals have 32-bit precisions. For example, ``42`` has type ``ti.i32`` and ``3.14`` has type ``ti.f32``. + Default integer and float-point precisions (``default_ip`` and ``default_fp``) can be specified when initializing Taichi: .. code-block:: python @@ -76,24 +110,66 @@ Default integer and float-point precisions (``default_ip`` and ``default_fp``) c Type casts ---------- -Use ``ti.cast`` to cast scalar values. +Implicit casts +************** + +WARNING: The type of a variable is **determinated on it's initialization**. + +When a *wide* variable is assigned with a *narrow* type, it will be +implicitly promoted to the *wide* type and no warning will be raised: .. code-block:: python - a = 1.4 - b = ti.cast(a, ti.i32) - c = ti.cast(b, ti.f32) + a = 1.7 + a = 1 + print(a) # 1.0 - # Equivalently, use ``int()`` and ``float()`` - # to convert values to default float-point/integer types - b = int(a) - c = float(b) +When a *narrow* variable is assigned with a *wide* type, it will be +implicitly casted into the *narrow* type and Taichi will raise a warning: - # Element-wise casts in matrices - mat = ti.Matrix([[3.0, 0.0], [0.3, 0.1]]) - mat_int = mat.cast(int) - mat_int2 = mat.cast(ti.i32) +.. code-block:: python + + a = 1 + a = 1.7 + print(a) # 1 + +Explicit casts +************** + +You may use ``ti.cast`` to explicitly cast scalar values between different types: + +.. code-block:: python + + a = 1.7 + b = ti.cast(a, ti.i32) # 1 + c = ti.cast(b, ti.f32) # 1.0 + +Equivalently, use ``int()`` and ``float()`` to convert values to default float-point/integer types: + +.. code-block:: python + + a = 1.7 + b = int(a) # 1 + c = float(a) # 1.0 + +Casting vector / matrix elements +******************************** + +Type casts applied to vectors/matrices are element-wise: + +.. code-block:: python + + u = ti.Vector([2.3, 4.7]) + v = int(u) # ti.Vector([2, 4]) + # equivalent to: + v = ti.cast(u, ti.i32) # ti.Vector([2, 4]) + +Bit casting +*********** Use ``ti.bit_cast`` to bit-cast a value into another data type. The underlying bits will be preserved in this cast. The new type must have the same width as the the old type. -For example, bit-casting ``i32`` to ``f64`` is not allowed. Use this operation with caution. + +.. code-block:: + + For people from C++, ``ti.bit_cast`` is equivalent to ``reinterpret_cast``. From d116dc06b1734960d7da1398256387c1ab10b9aa Mon Sep 17 00:00:00 2001 From: archibate <1931127624@qq.com> Date: Fri, 31 Jul 2020 15:50:29 +0800 Subject: [PATCH 2/5] [skip ci] [Doc] Improve type.rst readability --- docs/type.rst | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/docs/type.rst b/docs/type.rst index 0173b74f2fda1..71b6bed0a8de4 100644 --- a/docs/type.rst +++ b/docs/type.rst @@ -93,18 +93,40 @@ Basically it will try to choose the more precise type to contain the result valu Default precisions ------------------ -By default, numerical literals have 32-bit precisions. +By default, all numerical literals have 32-bit precisions. For example, ``42`` has type ``ti.i32`` and ``3.14`` has type ``ti.f32``. Default integer and float-point precisions (``default_ip`` and ``default_fp``) can be specified when initializing Taichi: .. code-block:: python - ti.init(..., default_fp=ti.f32) - ti.init(..., default_fp=ti.f64) + ti.init(default_fp=ti.f32) + ti.init(default_fp=ti.f64) + + ti.init(default_ip=ti.i32) + ti.init(default_ip=ti.i64) + + +Also note that you may use ``float`` or ``int`` in type definitions as aliases +for default precisions, e.g.: + +.. code-block:: python + + ti.init(default_ip=ti.i64, default_fp=ti.f32) + + x = ti.var(float, 5) + y = ti.var(int, 5) + # is equivalent to: + x = ti.var(ti.f32, 5) + y = ti.var(ti.i64, 5) + + def func(a: float) -> int: + ... + + # is equivalent to: + def func(a: ti.f32) -> ti.i64: + ... - ti.init(..., default_ip=ti.i32) - ti.init(..., default_ip=ti.i64) Type casts @@ -144,7 +166,8 @@ You may use ``ti.cast`` to explicitly cast scalar values between different types b = ti.cast(a, ti.i32) # 1 c = ti.cast(b, ti.f32) # 1.0 -Equivalently, use ``int()`` and ``float()`` to convert values to default float-point/integer types: +Equivalently, use ``int()`` and ``float()`` to convert values to float-point or +integer types of default precisions: .. code-block:: python @@ -160,7 +183,7 @@ Type casts applied to vectors/matrices are element-wise: .. code-block:: python u = ti.Vector([2.3, 4.7]) - v = int(u) # ti.Vector([2, 4]) + v = int(u) # ti.Vector([2, 4]) # equivalent to: v = ti.cast(u, ti.i32) # ti.Vector([2, 4]) From 8882a594472bb1cf8a6a09576cf762d830f1d431 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BD=AD=E4=BA=8E=E6=96=8C?= <1931127624@qq.com> Date: Sat, 1 Aug 2020 22:53:19 +0800 Subject: [PATCH 3/5] [skip ci] Apply suggestions from code review Co-authored-by: Yuanming Hu --- docs/type.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/type.rst b/docs/type.rst index 71b6bed0a8de4..f2f401b86bd4c 100644 --- a/docs/type.rst +++ b/docs/type.rst @@ -1,10 +1,10 @@ Type system =========== -Taichi supports many data types. The type name is recognized as -a *prefix character* + a *digital number*. +Taichi supports common numerical data types. Each type is denoted as +a character indicating its *category* and a number of *precision bits*, e.g., ``i32`` and ``f64``. -The *prefix character* can be one of: +The *category* can be one of: - ``i`` for signed integers, e.g. 233, -666 - ``u`` for unsigned integers, e.g. 233, 666 @@ -137,7 +137,7 @@ Implicit casts WARNING: The type of a variable is **determinated on it's initialization**. -When a *wide* variable is assigned with a *narrow* type, it will be +When a *low-precision* variable is assigned to a *high-precision* variable, it will be implicitly promoted to the *wide* type and no warning will be raised: .. code-block:: python @@ -146,8 +146,8 @@ implicitly promoted to the *wide* type and no warning will be raised: a = 1 print(a) # 1.0 -When a *narrow* variable is assigned with a *wide* type, it will be -implicitly casted into the *narrow* type and Taichi will raise a warning: +When a *high-precision* variable is assigned to a *low-precision* type, it will be +implicitly down-cast into the *low-precision* type and Taichi will raise a warning: .. code-block:: python @@ -175,8 +175,8 @@ integer types of default precisions: b = int(a) # 1 c = float(a) # 1.0 -Casting vector / matrix elements -******************************** +Casting vectors and matrices +**************************** Type casts applied to vectors/matrices are element-wise: @@ -184,7 +184,7 @@ Type casts applied to vectors/matrices are element-wise: u = ti.Vector([2.3, 4.7]) v = int(u) # ti.Vector([2, 4]) - # equivalent to: + # If you are using ti.i32 as default_ip, this is equivalent to: v = ti.cast(u, ti.i32) # ti.Vector([2, 4]) Bit casting @@ -192,6 +192,7 @@ Bit casting Use ``ti.bit_cast`` to bit-cast a value into another data type. The underlying bits will be preserved in this cast. The new type must have the same width as the the old type. +or example, bit-casting ``i32`` to ``f64`` is not allowed. Use this operation with caution. .. code-block:: From 6ab72970bc7da9822333ecb7a8426ea95d5a5a3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BD=AD=E4=BA=8E=E6=96=8C?= <1931127624@qq.com> Date: Sat, 1 Aug 2020 23:00:51 +0800 Subject: [PATCH 4/5] [skip ci] Apply suggestions from code review --- docs/type.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/type.rst b/docs/type.rst index f2f401b86bd4c..1985013fcd210 100644 --- a/docs/type.rst +++ b/docs/type.rst @@ -135,7 +135,9 @@ Type casts Implicit casts ************** -WARNING: The type of a variable is **determinated on it's initialization**. +.. warning:: + + The type of a variable is **determinated on it's initialization**. When a *low-precision* variable is assigned to a *high-precision* variable, it will be implicitly promoted to the *wide* type and no warning will be raised: @@ -192,6 +194,7 @@ Bit casting Use ``ti.bit_cast`` to bit-cast a value into another data type. The underlying bits will be preserved in this cast. The new type must have the same width as the the old type. +For example, bit-casting ``i32`` to ``f64`` is not allowed. Use this operation with caution. or example, bit-casting ``i32`` to ``f64`` is not allowed. Use this operation with caution. .. code-block:: From ead4e2ae87ac8fe2e177dd310d3bb940895fb984 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BD=AD=E4=BA=8E=E6=96=8C?= <1931127624@qq.com> Date: Sat, 1 Aug 2020 23:03:25 +0800 Subject: [PATCH 5/5] [skip ci] Apply suggestions from code review --- docs/type.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/type.rst b/docs/type.rst index 1985013fcd210..53263967ddcae 100644 --- a/docs/type.rst +++ b/docs/type.rst @@ -195,7 +195,6 @@ Bit casting Use ``ti.bit_cast`` to bit-cast a value into another data type. The underlying bits will be preserved in this cast. The new type must have the same width as the the old type. For example, bit-casting ``i32`` to ``f64`` is not allowed. Use this operation with caution. -or example, bit-casting ``i32`` to ``f64`` is not allowed. Use this operation with caution. .. code-block::