This is an automated email from the ASF dual-hosted git repository.
tqchen pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-tirx.git
The following commit(s) were added to refs/heads/main by this push:
new ee3c8fc27 [DOCS] Restructure Types and Expressions around expression
types (#134)
ee3c8fc27 is described below
commit ee3c8fc27d9b4e87fdcbe53a541a3f26e33a4039
Author: Tianqi Chen <[email protected]>
AuthorDate: Fri Oct 30 20:34:43 2026 -0400
[DOCS] Restructure Types and Expressions around expression types (#134)
This PR restructures the Types and Expressions chapter around expression
types.
The chapter now leads with what an expression is and the type every
expression carries in its `ty` field. It then introduces types briefly,
with a `TensorType` subsection, followed by expressions (`Var`,
constants, primitive expressions, tensor reads, tuples, calls),
dependent types, and customization. Examples use `format_tree` and are
self-contained.
---
docs/ir/types_and_expressions.rst | 758 +++++++++++++++++++-------------------
1 file changed, 376 insertions(+), 382 deletions(-)
diff --git a/docs/ir/types_and_expressions.rst
b/docs/ir/types_and_expressions.rst
index 292be8acd..c03af3e1a 100644
--- a/docs/ir/types_and_expressions.rst
+++ b/docs/ir/types_and_expressions.rst
@@ -20,14 +20,42 @@
Types and Expressions
=====================
-In this chapter, we will introduce types and expressions. Expressions
-represent values and computations, and their types describe properties
-such as dtypes, tensor shapes, and function signatures. We will inspect
-the values in a small add-one function, then construct scalar and vector
-expressions through the IR API.
+An **expression** is an IR node that represents a value: a variable, a
+constant, an arithmetic operation, a tensor read, or a call. Expressions
+nest to form computations. In ``A[i] + 1``, the addition node holds the
+tensor read ``A[i]`` and the constant ``1`` as its operands.
-This CPU function reads each element of ``A``, adds one, and writes the
-result to ``B``. Both tensors have the same symbolic length ``n``:
+Every expression has a **type** attached to it in its ``ty`` field. The
+type describes the value the expression produces: a float32 scalar, a
+four-lane float32 vector, a tensor with shape ``(n,)``, and so on.
+
+.. code-block:: python
+
+ from tvm_tirx import ir
+ x = ir.Var("x", "float32")
+ y = x + 1
+ print(ir.format_tree(y, expand=[(ir.Expr, "ty")]))
+
+The output is:
+
+.. code-block:: text
+
+ Add
+ ├── ty: PrimType(dtype=float32)
+ ├── a: x
+ └── b: FloatImm(value=1.0)
+ └── ty: PrimType(dtype=float32)
+
+``y`` is an ``ir.prim.Add`` node. Its operands are the variable ``x`` and
+the constant ``1``, and each node carries its own ``ty``. The variable was
+given type float32 when it was created; the constant and the addition
+derive theirs from it.
+
+``ir.Expr`` is the base class of all expressions, and ``ir.Type`` is the
+base class of all types. The rest of this chapter introduces the main
+type classes, then the main expression classes, and finally how types
+can depend on expressions. It uses this add-one function as the running
+example:
.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
:language: python
@@ -39,8 +67,19 @@ result to ``B``. Both tensors have the same symbolic length
``n``:
Types
-----
-``ir.Type`` is the base class for all IR types, including primitive types
-for scalar and vector values, tensor types, and function types:
+``ir.Type`` is the base class of all types. A type describes a value:
+its dtype, its shape, or the values it is built from.
+
+``ir.PrimType`` describes a scalar or vector value by its dtype: the
+element kind, the bit width, and the number of lanes. ``float32`` is a
+single 32-bit floating-point value, and ``float32x4`` holds four of
+them in one vector. In TVMScript, ``T.float32`` is the object
+``ir.PrimType("float32")``.
+
+``tirx.TensorType`` describes a whole tensor, and the next subsection
+covers it in detail.
+
+The main type classes are:
.. list-table::
:header-rows: 1
@@ -50,513 +89,468 @@ for scalar and vector values, tensor types, and function
types:
- Describes
- Fields
* - ``ir.PrimType``
- - A scalar or vector dtype
+ - A scalar or vector value
- ``dtype``
- * - ``ir.PtrType``
- - A pointer's element type and memory scope
- - ``element_type``, ``scope``
+ * - ``tirx.TensorType``
+ - A tensor's shape, element type, and storage
+ - ``shape``, ``dtype``, ``scope``, ``data_alignment``, ``layout``
* - ``ir.TupleType``
- - Ordered tuple field types
+ - An ordered group of values
- ``fields``
+ * - ``ir.PtrType``
+ - A memory address and the element type it points to
+ - ``element_type``, ``scope``
* - ``ir.FuncType``
- - Function argument and return types
+ - A function's argument and result types
- ``arg_types``, ``ret_type``
- * - ``tirx.TensorType``
- - A tensor's shape, element type, and storage properties
- - ``shape``, ``dtype``, ``scope``, ``data_alignment``, ``layout``
-
-We will examine primitive and tensor types first, then look at the
-pointer type used for a tensor's data address.
-
-.. _user-ir-prim-type:
-
-PrimType
-~~~~~~~~
-
-:class:`ir.PrimType <tvm_tirx.ir.PrimType>` describes integer,
-floating-point, and boolean values, either as scalars or vectors. Its
-``dtype`` records the element kind, bit width, and number of lanes.
-
-In the program's tensor annotations, ``T.float32`` is an
-``ir.PrimType("float32")`` object.
-
-The tensor length ``n`` is an integer symbol:
-.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
- :language: python
- :start-at: from tvm_tirx.script import tirx as T
- :end-at: n = T.dynamic
+.. _user-tensor-type:
-The default dtype is int32, so ``n`` has type ``ir.PrimType("int32")``.
-The loop index ``i`` has the same primitive type.
+TensorType
+~~~~~~~~~~
-We can express the addition ``A[i] + 1`` directly through the IR API,
-with a scalar variable standing for the input element:
+``tirx.TensorType`` describes a whole tensor: its shape, its element
+type, and how it is stored. ``T.Tensor`` builds one:
.. code-block:: python
from tvm_tirx import ir
- scalar_value = ir.Var("scalar_value", "float32")
- scalar_plus_one = scalar_value + 1
-
-``scalar_value`` has type ``ir.PrimType("float32")``, so it represents a single
-32-bit floating-point value. The result ``scalar_plus_one`` has the
-same type, just like ``A[i] + 1`` in the program.
-
-.. _user-ir-vector-expression:
-
-``PrimType`` also supports vector values. We can extend the same addition
-to four float32 values at once:
-
-.. code-block:: python
-
- vector_value = ir.Var("vector_value", "float32x4")
- vector_plus_one = vector_value + 1
-
-The type of ``vector_value`` is ``ir.PrimType("float32x4")``. The ``x4`` suffix
-specifies four float32 lanes within one vector value. The addition adds
-one to each lane, and ``vector_plus_one`` has the same vector type.
+ from tvm_tirx.script import tirx as T
-.. _user-tensor-type:
+ tile_type = T.Tensor((16, 4), T.float16)
+ print(ir.format_tree(tile_type))
-TensorType
-~~~~~~~~~~
+The output is:
-:class:`tirx.TensorType <tvm_tirx.tirx.TensorType>` is an IR type object
-that describes a whole tensor. It records the tensor's dimensions and
-the type of each element.
+.. code-block:: text
-The program declares its input and output as:
+ TensorType
+ ├── shape[0]: IntImm(value=16)
+ ├── shape[1]: IntImm(value=4)
+ └── dtype: PrimType(dtype=float16)
-.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
- :language: python
- :start-at: def add_one(
- :end-at: def add_one(
+``shape`` lists one expression per dimension; here both are integer
+constants. ``dtype`` is the ``PrimType`` of each element.
-``T.Tensor((n,), T.float32)`` is the TVMScript notation for a tensor type;
-the parser represents it as a ``tirx.TensorType`` object. Its ``shape``
-field contains one dimension, ``n``, and its ``dtype`` field is
-``ir.PrimType("float32")``:
+A tensor type also records where its elements are stored. ``scope`` is
+the memory space that holds them, such as ``"global"`` (the default),
+``"shared"``, or ``"local"``:
.. code-block:: python
- input_type = add_one.params[0].ty
- print(ir.format_tree(input_type))
+ from tvm_tirx.script import tirx as T
+
+ shared_type = T.Tensor((16, 4), T.float16, scope="shared")
+ print(repr(shared_type.scope))
The output is:
.. code-block:: text
- TensorType
- ├── shape[0]: n = Var(ty=int32)
- └── dtype: PrimType(dtype=float32)
-
-The dimension ``n`` is symbolic: it is not fixed to a particular number
-when the function is compiled. Each call determines ``n`` from the length
-of ``A``. Since ``B`` uses the same symbol in its type, its length must
-match ``A``. The loop then uses ``n`` as its bound.
+ MemoryScope('shared')
-PtrType
-~~~~~~~
+We can optionally supply a tensor's ``layout``, which changes how its
+elements are placed in storage. The
+:doc:`Data Layout </programming_guides/data_layout>` guide covers
+layouts.
-Some low-level operations take a memory address. The ``data`` property
-of a tensor parameter constructs an expression for its data pointer:
-
-.. code-block:: python
-
- data_pointer = add_one.params[0].data
- pointer_type = data_pointer.ty
-
-``pointer_type`` is an ``ir.PtrType``. Its ``element_type`` is
-``ir.PrimType("float32")``, and its ``scope`` is ``"global"``, matching
-the tensor's storage. This type describes the elements addressed by the
-pointer. The tensor's ``TensorType`` also records their shape.
+.. _user-ir-expr:
Expressions
-----------
-``ir.Expr`` is the base class for expressions, which represent program
-values and computations. All expression classes inherit its ``ty`` field,
-which records the type of value they represent:
+Each expression class adds its own fields alongside ``ty``. When an
+expression is constructed, its ``ty`` is computed from its inputs, so a
+finished expression always carries a concrete type. While an expression
+is still being built and its type is not yet known, ``ty`` holds the
+placeholder ``ir.MissingType``.
-.. list-table::
- :header-rows: 1
- :widths: 15 25 60
+.. _user-ir-var:
+
+Var
+~~~
- * - Field
- - Value type
- - Meaning
- * - ``ty``
- - ``ir.Type``
- - The type of value represented by the expression.
+``ir.Var`` represents a named value. It has two fields: ``name``, a
+readable label, and ``ty``, the type of the value it stands for.
-We can inspect the types of ``scalar_value`` and ``scalar_plus_one``
-through ``ty``. Both are primitive types, so their ``dtype`` fields give
-the dtype names:
+In the add-one function, the parameters ``A`` and ``B`` are variables.
+Each one's ``ty`` is the annotation written in the signature:
.. code-block:: python
- print(scalar_value.ty.dtype)
- print(scalar_plus_one.ty.dtype)
+ A, B = add_one.params
+ print(ir.format_tree(A, expand=[(ir.Var, "ty")]))
The output is:
.. code-block:: text
- float32
- float32
-
-``ir.Var("scalar_value", "float32")`` sets the variable's type explicitly.
-The addition's constructor determines its result type from its operands;
-this process is called type inference.
-
-An expression under construction can also have an ``ir.MissingType``
-in ``ty`` while its type is undetermined. Once its inputs are ready,
-the appropriate type rule can determine a concrete result type.
-
-Each expression class adds fields for its value or operands, alongside
-the shared ``ty`` field:
-
-.. list-table::
- :header-rows: 1
- :widths: 30 35 35
+ A = Var
+ └── ty: TensorType
+ ├── shape[0]: n = Var
+ │ └── ty: PrimType(dtype=int32)
+ └── dtype: PrimType(dtype=float32)
- * - Classes (examples)
- - Represents
- - Additional fields
- * - ``ir.Var``
- - A variable
- - ``name``
- * - ``ir.IntImm``, ``ir.FloatImm``, ``ir.StringImm``
- - Literal constants
- - ``value``
- * - ``ir.prim.Add``, ``ir.prim.Sub``, ``ir.prim.Mul``
- - Binary arithmetic
- - ``a``, ``b``
- * - ``ir.prim.EQ``, ``ir.prim.LT``
- - Comparisons
- - ``a``, ``b``
- * - ``ir.Op``
- - A registered operator
- - ``name``, ``doc``, ``args_info``
- * - ``ir.Call``
- - A call to an operator or function
- - ``op``, ``args``, ``attrs``, ``ty_args``
- * - ``ir.TensorLoad``
- - A tensor element read
- - ``source``, ``indices``
+``T.Tensor((n,), T.float32)`` becomes a ``tirx.TensorType``. Its
+``shape`` holds the dimension expressions and its ``dtype`` holds the
+element type, ``ir.PrimType("float32")``.
+
+The function has two other kinds of variables. The symbolic dimension
+``n`` comes from ``n = T.dynamic("n")``. It is an int32 ``Var`` that
+stands for a size known only when the function is called, and it appears
+in ``A``'s shape above. The loop index ``i`` is defined by
+``for i in range(n)``. It is an int32 ``Var`` that the loop body uses to
+read ``A[i]`` and write ``B[i]``.
+
+In TIRx canonical form, each ``Var`` is defined at most once in a
+function. A variable is defined where it is introduced, such as a
+function parameter or a loop index, and it can then be used any number
+of times. Two loops cannot share the same ``Var`` object as their index,
+even when neither loop is nested in the other; each loop needs its own
+``Var``, even if the names are the same. This rule keeps analysis
+simple: every use of a variable refers to exactly one definition.
.. _user-ir-const:
-Primitive Expressions
-~~~~~~~~~~~~~~~~~~~~~
+Constants
+~~~~~~~~~
-A primitive expression is an expression whose ``ty`` is an ``ir.PrimType``.
-This term groups expressions by their result type. Variables, tensor
-reads, arithmetic nodes, and calls can all belong to this group when
-they produce primitive scalar or vector values.
-
-**Scalar expressions.** The CPU example uses the int32 expressions ``n``
-and ``i`` for the loop bound and index. The tensor read ``A[i]`` and the
-addition ``A[i] + 1`` both produce a single float32 value. A comparison
-such as ``i < n`` produces a boolean. These scalar result types are
-stored as ``PrimType`` objects in ``ty``.
-
-``A`` itself represents the whole tensor and has a ``TensorType``.
-The expression ``A[i]`` reads element ``i`` of this tensor. TVMScript
-represents the read as an ``ir.TensorLoad`` node. Its ``source`` field
-refers to ``A``, and ``indices`` contains ``i``, selecting the element
-to read:
+``ir.IntImm``, ``ir.FloatImm``, and ``ir.StringImm`` hold literal values
+in their ``value`` field. A constant's ``ty`` records its dtype:
.. code-block:: python
- loop = add_one.body.seq[0] # The for loop.
- addition = loop.body.seq[0].value # The value written by its store.
- element_read = addition.a
- print(ir.format_tree(
- element_read,
- expand=[(ir.Expr, "ty"), "source"],
- ))
+ from tvm_tirx import ir
+
+ print(ir.format_tree(ir.IntImm("int64", 3), expand=[(ir.Expr, "ty")]))
The output is:
.. code-block:: text
- TensorLoad(indices=[i])
- ├── ty: PrimType(dtype=float32)
- └── source: A = Var(ty=TensorType(shape=[n], dtype=float32))
-
-``expand`` shows the read's result type and the parameter referenced by
-``source``. The parameter's tensor type remains folded on one line.
+ IntImm(value=3)
+ └── ty: PrimType(dtype=int64)
-**Vector expressions.** A primitive expression can also produce a vector
-value. The earlier add-one result ``vector_plus_one`` has type
-``ir.PrimType("float32x4")``, representing four float32 lanes within
-one value.
+A Python number used in an operation becomes a constant with the dtype
+of the other operand, so ``x + 1`` with a float32 ``x`` contains a
+float32 ``FloatImm``.
-A call whose result type is a ``PrimType`` also belongs to this category.
-For example, the GPU expression ``T.cuda.thread_idx("x")`` is an
-``ir.Call`` with result type ``ir.PrimType("int32")``.
+.. _user-ir-prim-expr:
-.. _user-ir-prim-operations:
-
-Primitive Operations
-~~~~~~~~~~~~~~~~~~~~
-
-Arithmetic and comparisons combine variables, constants, and tensor
-reads into larger expressions. The ``ir.prim`` namespace provides node
-classes and Python helpers for these operations, as well as boolean
-logic, casts, and other primitive computations:
-
-.. list-table::
- :header-rows: 1
- :widths: 55 45
-
- * - Python expression
- - IR node constructed
- * - ``scalar_value + 1``
- - ``ir.prim.Add``
- * - ``ir.prim.sigmoid(scalar_value)``
- - ``ir.Call`` to ``prim.sigmoid``
-
-Python operators such as ``+``, ``*``, and ``<`` construct arithmetic
-and comparison nodes. The Python helper ``ir.prim.sigmoid`` constructs
-a call to a registered operator; the returned IR node is an ``ir.Call``.
+Primitive Expressions
+~~~~~~~~~~~~~~~~~~~~~
-In the CPU example, ``A[i] + 1`` becomes an ``ir.prim.Add``. A binary node
-stores its left operand in ``a`` and its right operand in ``b``:
+A primitive expression is an expression whose ``ty`` is an
+``ir.PrimType``. These expressions usually compute an index or an
+element value, and such computations occur in nearly every ML compiler
+scenario: tensor offsets, loop bounds, tiling and vectorization, and the
+scalar math inside each kernel. TIRx therefore gives them dedicated node
+classes in the ``ir.prim`` namespace, such as ``ir.prim.Add``,
+``ir.prim.LT``, and ``ir.prim.Cast``, rather than representing them as
+generic calls. The IR can refer to these common patterns directly, and
+analyses and transformations can recognize, reason about, and simplify
+them by their structure. Python operators on expressions construct
+these nodes.
+
+**Index expressions.** Index calculations combine integer variables and
+constants, such as a block offset plus a thread index. A binary node
+stores its operands in ``a`` and ``b``, and nodes nest to form larger
+computations.
.. code-block:: python
- print(ir.format_tree(addition))
+ from tvm_tirx import ir
+
+ bx = ir.Var("bx", "int32")
+ tx = ir.Var("tx", "int32")
+ print(ir.format_tree(bx * 256 + tx))
The output is:
.. code-block:: text
Add
- ├── a: TensorLoad(source=A, indices=[i])
- └── b: FloatImm(value=1.0)
-
-The arithmetic constructor derives the result type from its operands.
-Since ``A[i]`` is float32, it converts the source literal ``1`` to the
-float32 constant shown as ``ir.FloatImm``. The result is also float32.
-
-These constructors also support vector operands. In ``vector_value + 1``,
-the scalar constant is broadcast to all four lanes, producing the
-four-lane expression ``vector_plus_one``.
-
-A GPU version assigns one element to each thread. Its index calculation
-combines multiplication and addition, and its bounds check uses a
-comparison:
+ ├── a: Mul
+ │ ├── a: bx
+ │ └── b: IntImm(value=256)
+ └── b: tx
-.. code-block:: python
-
- @T.function
- def gpu_add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
- T.device_entry(launch=T.cuda.LaunchConfig(grid=T.ceildiv(n, 256),
block=256))
- i = T.cuda.block_idx("x") * 256 + T.cuda.thread_idx("x")
- if i < n:
- B[i] = A[i] + 1
-
-The GPU launch uses 256 threads per block. The multiplication by 256
-becomes an ``ir.prim.Mul``, and the sum becomes an ``ir.prim.Add``.
-The condition ``i < n`` is an ``ir.prim.LT`` whose ``a`` and ``b``
-operands are the index and tensor length:
+**Value computations.** Element values can combine operands of different
+dtypes. The constructor determines the result type from its operands and
+inserts an explicit ``ir.prim.Cast`` when they differ, so the conversion
+is visible to later passes and code generation.
.. code-block:: python
- device_region = gpu_add_one.body.seq[0]
- branch = device_region.body.seq[1] # The if statement.
- print(ir.format_tree(branch.condition))
+ i = ir.Var("i", "int32")
+ x = ir.Var("x", "float32")
+ print(ir.format_tree(i + x, expand=[(ir.Expr, "ty")]))
The output is:
.. code-block:: text
- LT
- ├── a: i
- └── b: n
-
-The comparison checks whether the thread has a valid element to process.
-
-Boolean operations combine comparisons into a single condition. For
-example, both checks must hold for a scalar to lie in the interval
-``[0, 1)``:
-
-.. code-block:: python
-
- in_unit_interval = ir.prim.And(scalar_value >= 0, scalar_value < 1)
-
-The ``And`` node holds the two comparisons in ``a`` and ``b``. Its result
-type is ``ir.PrimType("bool")``.
+ Add
+ ├── ty: PrimType(dtype=float32)
+ ├── a: Cast
+ │ ├── ty: PrimType(dtype=float32)
+ │ └── value: i
+ └── b: x
-An operation can also change the dtype of a value. To produce a float16
-version of the add-one result, we can use a cast:
+**Vector expressions.** A ``PrimType`` can hold several lanes, such as
+``float32x4`` for four float32 values, and arithmetic applies lane by
+lane. When one operand is a scalar, the constructor inserts an
+``ir.prim.Broadcast`` that repeats it across the lanes.
.. code-block:: python
- half_plus_one = ir.prim.Cast("float16", scalar_plus_one)
-
-The cast's ``value`` field refers to ``scalar_plus_one``. Its ``ty`` is
-``ir.PrimType("float16")``, which tells code generation to convert the
-float32 result to float16.
+ v = ir.Var("v", "float32x4")
+ print(ir.format_tree(v + 1, expand=[(ir.Expr, "ty")]))
-The :doc:`ir.prim </reference/python/ir.prim>` API reference lists other
-operations and their construction helpers.
-
-.. _user-ir-var:
+The output is:
-Var
-~~~
+.. code-block:: text
-``ir.Var`` represents a named value with a type. Variables can be
-function parameters, loop indices, or intermediate values defined by
-bindings.
+ Add
+ ├── ty: PrimType(dtype=float32x4)
+ ├── a: v
+ └── b: Broadcast
+ ├── ty: PrimType(dtype=float32x4)
+ ├── value: FloatImm(value=1.0)
+ │ └── ty: PrimType(dtype=float32)
+ └── lanes: IntImm(value=4)
+ └── ty: PrimType(dtype=int32)
+
+The following table lists the primitive expression node classes in
+``ir.prim``:
-The tensor parameters ``A`` and ``B`` in our CPU function are represented
-by ``ir.Var`` objects. We can retrieve them from ``add_one.params`` and
-inspect their types through ``ty``:
+.. list-table::
+ :header-rows: 1
+ :widths: 20 45 35
+
+ * - Category
+ - Node classes
+ - Python syntax
+ * - Arithmetic
+ - ``Add``, ``Sub``, ``Mul``, ``Div``, ``Mod``, ``FloorDiv``,
+ ``FloorMod``, ``Min``, ``Max``
+ - ``+``, ``-``, ``*``, ``/`` (float), ``//``, ``%`` (int)
+ * - Comparison
+ - ``EQ``, ``NE``, ``LT``, ``LE``, ``GT``, ``GE``
+ - ``<``, ``<=``, ``>``, ``>=``
+ * - Logical
+ - ``And``, ``Or``, ``Not``
+ - —
+ * - Bitwise
+ - ``BitwiseAnd``, ``BitwiseOr``, ``BitwiseXor``, ``BitwiseNot``,
+ ``LShift``, ``RShift``
+ - ``&``, ``|``, ``^``, ``~``, ``<<``, ``>>``
+ * - Conversion
+ - ``Cast``
+ - —
+ * - Selection
+ - ``Select``
+ - —
+ * - Vector
+ - ``Broadcast``, ``Ramp``, ``Shuffle``
+ - —
+ * - Binding
+ - ``Let``
+ - —
+
+Operations without dedicated node classes, such as ``ir.prim.exp`` and
+``ir.prim.sigmoid``, construct an ``ir.Call`` to a registered operator.
+Their results are still primitive expressions.
+
+The :doc:`ir.prim </reference/python/ir.prim>` API reference documents
+each node class, its construction helpers, and the available math
+functions.
+
+.. _user-ir-tensor-read:
+
+Tensor Reads
+~~~~~~~~~~~~
+
+Indexing a tensor variable reads one element. ``A[i]`` constructs an
+``ir.TensorLoad`` whose ``source`` is the tensor and whose ``indices``
+select the element. Its ``ty`` is the tensor's element type, so reading
+from a ``TensorType`` value produces a ``PrimType`` value:
.. code-block:: python
A, B = add_one.params
- input_type = A.ty
- output_type = B.ty
+ i = ir.Var("i", "int32")
+ print(ir.format_tree(A[i], expand=[(ir.Expr, "ty")]))
-Each parameter is a ``Var`` with its own ``name`` and ``ty`` fields.
-We can expand its type to inspect the shape and element type:
+The output is:
-.. code-block:: python
+.. code-block:: text
- print(ir.format_tree(A, expand=[(ir.Var, "ty")]))
+ TensorLoad(source=A, indices=[i])
+ └── ty: PrimType(dtype=float32)
-The output is:
+Low-level code sometimes needs the tensor's memory address instead.
+``A.data`` is a call to ``tirx.tensor_data_ptr`` whose type is an
+``ir.PtrType`` with element type float32.
-.. code-block:: text
+.. _user-ir-tuple:
- A = Var
- └── ty: TensorType
- ├── shape[0]: n = Var
- │ └── ty: PrimType(dtype=int32)
- └── dtype: PrimType(dtype=float32)
+Tuple
+~~~~~
-The variable's name appears before ``= Var``. The ``ty`` edge leads to
-its tensor type, whose shape contains the integer symbol ``n``.
-TVMScript creates these parameter variables when it parses the function.
-We can also create variables directly with ``ir.Var(name, ty)``. The
-scalar add-one example in PrimType uses this constructor:
+``ir.Tuple`` groups several expressions into one value, for example to
+return more than one result. Its ``fields`` hold the expressions, and
+its type is an ``ir.TupleType`` whose ``fields`` hold their types in the
+same order:
.. code-block:: python
from tvm_tirx import ir
- scalar_value = ir.Var("scalar_value", "float32")
- scalar_plus_one = scalar_value + 1
-``ir.Var("scalar_value", "float32")`` creates a variable whose ``name``
-is ``"scalar_value"`` and whose ``ty`` is ``ir.PrimType("float32")``.
+ i = ir.Var("i", "int32")
+ x = ir.Var("x", "float32")
+ pair = ir.Tuple([i, x])
+ print(ir.format_tree(pair, expand=[(ir.Expr, "ty")]))
-Tuples
-~~~~~~
-
-An expression can group several values into a tuple. For example, we can
-keep the original scalar and its add-one result together, then select
-the second value:
+The output is:
-.. code-block:: python
+.. code-block:: text
- paired_values = ir.Tuple([scalar_value, scalar_plus_one])
- second_value = ir.TupleGetItem(paired_values, 1)
+ Tuple
+ ├── ty: TupleType
+ │ ├── fields[0]: PrimType(dtype=int32)
+ │ └── fields[1]: PrimType(dtype=float32)
+ ├── fields[0]: i
+ └── fields[1]: x
-``paired_values.fields`` holds the two expressions. Its type is an
-``ir.TupleType`` whose ``fields`` holds their types: two
-``ir.PrimType("float32")`` objects. ``TupleGetItem`` records the tuple
-in ``tuple_value`` and the selected position in ``index``. Index 1
-selects ``scalar_plus_one``, so ``second_value`` has type
-``ir.PrimType("float32")``.
+``ir.TupleGetItem(pair, 1)`` selects one field by position. It records
+the tuple in ``tuple_value`` and the position in ``index``, and its type
+is the type of the selected field, ``PrimType("float32")``.
.. _user-ir-call:
Call
~~~~
-:class:`ir.Call <tvm_tirx.ir.Call>` represents a call to an operator or
-function. Its ``op`` field refers to the operator or function expression
-being called, and ``args`` holds the argument expressions. A registered
-operator is represented by ``ir.Op``.
+``ir.Call`` expresses a call to another function or to a specialized
+operation. Its ``op`` field is the callee, and ``args`` holds the
+argument expressions. A specialized operation is a registered operator,
+represented by ``ir.Op`` and looked up by name. Like every expression, a
+call has a ``ty``, computed from its arguments when the call is
+constructed.
-The GPU index calculation above uses ``T.cuda.block_idx("x")`` and
-``T.cuda.thread_idx("x")`` to read the block and thread coordinates.
-These TVMScript helpers construct calls to registered CUDA operators.
-We can construct the thread-index call directly through the IR API:
+For example, sigmoid is a registered operator rather than a dedicated
+``ir.prim`` node. A call to it takes a float32 argument and produces a
+float32 result:
.. code-block:: python
from tvm_tirx import ir
- op = ir.Op.get("tirx.cuda.thread_idx")
- x_call = ir.Call(op, [ir.StringImm("x")])
-
-``op`` is the ``ir.Op`` object for ``tirx.cuda.thread_idx``. The call's
-``op`` field refers to this object, and its ``args`` array contains the
-string expression ``"x"``. Its ``ty`` is ``ir.PrimType("int32")``:
-
-.. code-block:: python
-
- print(ir.format_tree(
- x_call,
- expand=[(ir.Call, "ty")],
- hide=["attrs", "ty_args"],
- ))
+ x = ir.Var("x", "float32")
+ sigmoid_op = ir.Op.get("prim.sigmoid")
+ y = ir.Call(sigmoid_op, [x + 1])
+ print(ir.format_tree(y, expand=[(ir.Expr, "ty")],
+ hide=["attrs", "ty_args"]))
The output is:
.. code-block:: text
- Call(op=tirx.cuda.thread_idx)
- ├── ty: PrimType(dtype=int32)
- └── args[0]: StringImm(value='x')
-
-The ``"x"`` argument selects the x axis. When the compiled GPU function
-runs, this call reads the current thread's x-axis coordinate within its
-block. The index arithmetic uses the coordinates returned by the
-thread-index and block-index calls to compute ``i``.
+ Call(op=prim.sigmoid)
+ ├── ty: PrimType(dtype=float32)
+ └── args[0]: Add
+ ├── ty: PrimType(dtype=float32)
+ ├── a: x
+ └── b: FloatImm(value=1.0)
+ └── ty: PrimType(dtype=float32)
-A common extension of add-one is an activation applied to its result.
-We can pass the earlier addition expression ``scalar_plus_one`` to the
-built-in ``prim.sigmoid`` operator:
+The example hides two other fields of ``ir.Call``: ``attrs``, which
+holds operator-specific attributes, and ``ty_args``, which holds
+explicit type arguments.
-.. code-block:: python
+.. _user-ir-dependent-type:
- sigmoid_op = ir.Op.get("prim.sigmoid")
- activated_plus_one = ir.Call(sigmoid_op, [scalar_plus_one])
+Dependent Types
+---------------
-The call's argument is now the addition expression. We fold ``args`` to
-keep the arithmetic on one line and expand the call's result type:
+A type can contain expressions. The shape of a ``tirx.TensorType`` is a
+list of expressions, so a tensor's dimensions can be symbolic values
+rather than fixed numbers:
.. code-block:: python
- print(ir.format_tree(
- activated_plus_one,
- fold=["args"],
- expand=[(ir.Call, "ty")],
- hide=["attrs", "ty_args"],
- ))
+ from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
+
+ n = T.dynamic("n")
+ matrix_type = T.Tensor((n, n * 2), T.float32)
+ print(ir.format_tree(matrix_type))
The output is:
.. code-block:: text
- Call(op=prim.sigmoid, args=[Add(a=scalar_value, b=FloatImm(value=1.0))])
- └── ty: PrimType(dtype=float32)
+ TensorType
+ ├── shape[0]: n = Var(ty=int32)
+ ├── shape[1]: Mul
+ │ ├── a: n
+ │ └── b: IntImm(value=2)
+ └── dtype: PrimType(dtype=float32)
+
+The first dimension is the int32 variable ``n``, and the second is the
+expression ``n * 2``. A type whose fields refer to expressions is called
+a dependent type: the concrete shape depends on the value of ``n``.
+
+In a function signature, dependent types relate parameters to each
+other. In the add-one function below, both tensors have type
+``T.Tensor((n,), T.float32)``:
-``activated_plus_one.args[0]`` refers to ``scalar_plus_one``, so sigmoid
-receives the addition's result. The expression computes
-``1 / (1 + exp(-(scalar_value + 1)))``. The operator's type rule gives
-the call the same type as its input, ``ir.PrimType("float32")``. This
-call is therefore also a primitive expression. The Python helper
-``ir.prim.sigmoid(scalar_plus_one)`` constructs the same call.
+.. code-block:: python
+
+ n = T.dynamic("n")
+
+ @T.function
+ def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ for i in range(n):
+ B[i] = A[i] + 1
-The :doc:`operators_and_calls` chapter also covers calls to IR functions
-and explains how registered operators provide result-type inference
-and argument validation.
+Both types refer to the same variable ``n``. The first appearance of
+``n``, in ``A``'s type, defines it; the appearance in ``B``'s type is a
+use. When the function is
+called, ``n`` takes the length of ``A``, and ``B`` must have the same
+length. The loop body can also use ``n`` as an ordinary int32 value,
+here as the loop bound.
+
+TIRx analysis and transformation utilities are designed with dependent
+types in mind. When a transformation replaces a variable, it updates
+every type that refers to that variable, not only the expressions. For
+example, replacing ``n`` with ``16`` in the add-one function changes the
+loop bound to ``16`` and also changes the types of ``A`` and ``B`` to
+``T.Tensor((16,), T.float32)``. Types and expressions therefore stay
+consistent after each rewrite.
+
+Customization
+-------------
+
+The type and expression system is open to extension. A library can
+define a new type, such as a complex number type with float32 real and
+imaginary parts, and register operators that construct and consume
+values of that type. Each operator provides a type rule, so a call to it
+gets the new type in its ``ty`` just like a built-in expression.
+
+TIRx provides a common foundation for all IR nodes, so new types and
+the calls that use them support structural traversal, transformation,
+equivalence checking, printing, and parsing out of the box. A library
+adds only what is specific to its extension, such as passes that lower
+the new operations to what the backend supports.
+
+What to Read Next
+-----------------
+
+- :doc:`statements` shows how expressions are used in loops, stores,
+ and other statements.
+- :doc:`operators_and_calls` covers calls to functions, operator
+ registration, and how operators define their result types.
+- :doc:`../advanced/defining_ir_extensions` walks through an extension
+ that defines a complex type, its operators, and a lowering pass.