This is an automated email from the ASF dual-hosted git repository.
tlopex 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 4ed861002 [DOCS] Use format_tree for interactive IR walkthrough
examples (#126)
4ed861002 is described below
commit 4ed8610024d33892e2d5c4ee74f4853352f1bc0e
Author: Shushi Hong <[email protected]>
AuthorDate: Thu Oct 29 15:00:44 2026 -0400
[DOCS] Use format_tree for interactive IR walkthrough examples (#126)
This pr replaces hand-drawn program structure diagrams with runnable
ir.format_tree examples and actual output. Introduce the API in IR
Overview with a standalone expression and examples of expanding and
folding fields.
Use complete TVMScript functions for control-flow examples, explain how
to retrieve the relevant IR objects, and improve transitions between
source code, inspection code, and output.
---
docs/ir/functions_and_modules.rst | 59 +++++---
docs/ir/operators_and_calls.rst | 121 +++++++++++-----
docs/ir/overview.rst | 71 +++++++++
docs/ir/printing_and_parsing.rst | 22 +--
docs/ir/statements.rst | 295 +++++++++++++++++++++++++++-----------
docs/ir/types_and_expressions.rst | 136 +++++++++++++-----
6 files changed, 523 insertions(+), 181 deletions(-)
diff --git a/docs/ir/functions_and_modules.rst
b/docs/ir/functions_and_modules.rst
index af9811169..b77faa82e 100644
--- a/docs/ir/functions_and_modules.rst
+++ b/docs/ir/functions_and_modules.rst
@@ -45,12 +45,7 @@ and its ``body`` holds the loop.
:class:`ir.BaseFunc <tvm_tirx.ir.BaseFunc>`, the common base class for
IR function definitions. The base class provides ``attrs`` for named
function properties. ``tirx.Function`` adds the tensor program's
-parameters, return type, and statement body:
-
-.. code-block:: text
-
- ir.BaseFunc attrs
- └── tirx.Function params, ret_type, body
+parameters, return type, and statement body.
The main fields of ``tirx.Function`` are:
@@ -69,19 +64,32 @@ The main fields of ``tirx.Function`` are:
* - ``attrs``
- An ``ir.DictAttrs`` containing named function properties.
-The loop has its own body containing the tensor store. These nested
-bodies give ``add_one`` the following structure:
+The loop has its own body containing the tensor store. We can print
+these nested bodies and expand the function's return type:
+
+.. code-block:: python
+
+ from tvm_tirx import ir
+
+ print(ir.format_tree(add_one, expand=[(ir.BaseFunc, "ret_type")]))
+
+The output is:
.. code-block:: text
- add_one: tirx.Function
- ├── params[0]: ir.Var A
- ├── params[1]: ir.Var B
- ├── ret_type: ir.TupleType no return value
- └── body: ir.SeqStmt
- └── seq[0]: ir.For for i in range(n)
- └── body: ir.SeqStmt
- └── seq[0]: ir.TensorStore B[i] = A[i] + 1
+ Function
+ ├── params[0]: A = Var(ty=TensorType(shape=[n], dtype=float32))
+ ├── params[1]: B = Var(ty=TensorType(shape=[n], dtype=float32))
+ ├── ret_type: TupleType
+ │ └── fields: []
+ └── body: SeqStmt
+ └── seq[0]: For(begin=IntImm(value=0), end=n)
+ ├── var: i = Var(ty=int32)
+ └── body: SeqStmt
+ └── seq[0]: TensorStore(dest=B, indices=[i])
+ └── value: Add
+ ├── a: TensorLoad(source=A, indices=[i])
+ └── b: FloatImm(value=1.0)
``add_one.ty`` stores an ``ir.FuncType`` describing the function's
signature: its parameter types and return type. We can inspect these
@@ -172,13 +180,24 @@ and each value is a function definition whose class
inherits
``ir_function``. The constructor creates a ``GlobalVar`` named
``"add_one"`` from the string key and associates it with this function:
+.. code-block:: python
+
+ print(ir.format_tree(module.functions, max_depth=3))
+
+The output is:
+
.. code-block:: text
- module: ir.IRModule
- └── functions
- └── key: ir.GlobalVar ("add_one") → value: tirx.Function (ir_function)
+ Map
+ ├── [0][0]: GlobalVar(name_hint='add_one')
+ └── [0][1]: Function
+ ├── params: Array(...)
+ └── body: SeqStmt(...)
-The ``GlobalVar`` serves as a reference; the function body belongs to
+The map displays each entry as a key/value pair: ``[0][0]`` is the
+global reference and ``[0][1]`` is its function definition. ``max_depth``
+limits the display, so ``...`` marks fields left unexpanded. The
+``GlobalVar`` serves as a reference; the function body belongs to
the associated ``tirx.Function``. We can retrieve the reference by name,
then use it to look up the definition:
diff --git a/docs/ir/operators_and_calls.rst b/docs/ir/operators_and_calls.rst
index fd1a0f803..239e282a6 100644
--- a/docs/ir/operators_and_calls.rst
+++ b/docs/ir/operators_and_calls.rst
@@ -98,12 +98,21 @@ operator. We can construct it directly through the IR API:
creates an expression whose ``op`` refers to that definition and whose
``args`` contains the axis argument. Its ``ty`` records the int32 result:
+.. code-block:: python
+
+ print(ir.format_tree(
+ x_call,
+ expand=[(ir.Call, "ty")],
+ hide=["attrs", "ty_args"],
+ ))
+
+The output is:
+
.. code-block:: text
- x_call: ir.Call
- ├── op → shared ir.Op tirx.cuda.thread_idx
- ├── args[0]: ir.StringImm "x"
- └── ty: ir.PrimType int32
+ Call(op=tirx.cuda.thread_idx)
+ ├── ty: PrimType(dtype=int32)
+ └── args[0]: StringImm(value='x')
``op.args_info[0].name`` is the parameter name ``"axis"``;
``x_call.args[0]`` holds its argument value ``"x"``. The call describes
@@ -126,36 +135,56 @@ y axis with the same operator:
Both ``x_call.op`` and ``y_call.op`` reference the shared ``op``. Each
call has its own ``args`` array, containing ``"x"`` or ``"y"``, and
-both calls produce an int32 coordinate:
+both calls produce an int32 coordinate. We can check that their operator
+references identify the same object:
+
+.. code-block:: python
+
+ print(x_call.op.same_as(y_call.op))
+
+The output is:
.. code-block:: text
- x_call.op ──┐
- ├──> op: ir.Op tirx.cuda.thread_idx
- y_call.op ──┘
+ True
A call's result can be an operand in a larger expression. A kernel with
256 threads per block can combine the block and thread coordinates to
find the tensor element assigned to a thread:
-.. literalinclude:: ../../examples/quick_start/add_one_cuda.py
- :language: python
- :start-at: i = T.cuda.block_idx
- :end-at: i = T.cuda.block_idx
- :dedent: 4
+.. code-block:: python
+
+ n = T.dynamic("n")
+
+ @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 block-index call produces the block coordinate, and the thread-index
call produces the coordinate within that block. Each helper constructs
an ``ir.Call``. The multiplication and addition use the calls' results
as operands:
+.. code-block:: python
+
+ device_region = gpu_add_one.body.seq[0]
+ index_binding = device_region.body.seq[0] # The definition of i.
+ print(ir.format_tree(index_binding.value, hide=["attrs", "ty_args"]))
+
+The output is:
+
.. code-block:: text
- ir.prim.Add
- ├── a: ir.prim.Mul
- │ ├── a: ir.Call T.cuda.block_idx("x")
- │ └── b: ir.IntImm 256
- └── b: ir.Call T.cuda.thread_idx("x")
+ Add
+ ├── a: Mul
+ │ ├── a: Call(op=tirx.cuda.block_idx)
+ │ │ └── args[0]: StringImm(value='x')
+ │ └── b: IntImm(value=256)
+ └── b: Call(op=tirx.cuda.thread_idx)
+ └── args[0]: StringImm(value='x')
Expression Arguments
~~~~~~~~~~~~~~~~~~~~
@@ -182,14 +211,23 @@ explicitly:
In both forms, the call's ``op`` refers to the registered ``prim.sigmoid``
operator, and ``args[0]`` refers to the addition expression
``scalar_plus_one``:
+.. code-block:: python
+
+ print(ir.format_tree(
+ activated_plus_one,
+ expand=[(ir.Call, "ty")],
+ hide=["attrs", "ty_args"],
+ ))
+
+The output is:
+
.. code-block:: text
- activated_plus_one: ir.Call
- ├── op → shared ir.Op prim.sigmoid
- ├── args[0]: ir.prim.Add scalar_value + 1
- │ ├── a: ir.Var scalar_value
- │ └── b: ir.FloatImm 1.0
- └── ty: ir.PrimType float32
+ Call(op=prim.sigmoid)
+ ├── ty: PrimType(dtype=float32)
+ └── args[0]: Add
+ ├── a: scalar_value
+ └── b: FloatImm(value=1.0)
When the compiled program runs, sigmoid receives the result of the
addition. This expression therefore computes
@@ -253,15 +291,19 @@ The tensor store uses that call as its ``value``
expression:
.. code-block:: python
- activation_store = add_one_sigmoid.body[0].body[0]
+ activation_store = add_one_sigmoid.body.seq[0].body.seq[0]
activation_call = activation_store.value
+ print(ir.format_tree(activation_store, hide=["attrs", "ty_args"]))
+
+The output is:
.. code-block:: text
- activation_store: ir.TensorStore
- ├── dest: ir.Var B
- └── value: ir.Call prim.sigmoid
- └── args[0]: ir.prim.Add A[i] + 1
+ TensorStore(dest=B, indices=[i])
+ └── value: Call(op=prim.sigmoid)
+ └── args[0]: Add
+ ├── a: TensorLoad(source=A, indices=[i])
+ └── b: FloatImm(value=1.0)
When the function runs, the addition produces the sigmoid input and the
store writes its result to ``B[i]``.
@@ -296,19 +338,24 @@ an ``ir.Evaluate`` statement inside the loop body:
.. code-block:: python
- memory_loop = masked_add_one.body[0]
- write_statement = memory_loop.body[2]
+ memory_loop = masked_add_one.body.seq[0]
+ write_statement = memory_loop.body.seq[2]
write_call = write_statement.value
+ print(ir.format_tree(
+ write_statement,
+ hide=["args", "attrs", "ty_args"],
+ ))
+
+The output is:
.. code-block:: text
- memory_loop.body: ir.SeqStmt
- ├── seq[0]: ir.Bind indices
- ├── seq[1]: ir.Bind values
- └── seq[2]: ir.Evaluate
- └── value: ir.Call tirx.masked_store
- └── ty: ir.PrimType void
+ Evaluate
+ └── value: Call(op=tirx.masked_store)
+The loop body first binds ``indices`` and ``values``. Its third
+statement, ``write_statement``, evaluates the masked-store call.
+This view hides the call's arguments to focus on the ``Evaluate`` wrapper.
Through the IR API, ``ir.Evaluate(write_call)`` constructs the
corresponding statement. Even with a ``void`` result type, the call is
an expression; ``Evaluate`` gives it a place in the statement sequence.
diff --git a/docs/ir/overview.rst b/docs/ir/overview.rst
index aa7724b13..8642127bd 100644
--- a/docs/ir/overview.rst
+++ b/docs/ir/overview.rst
@@ -164,6 +164,77 @@ IR nodes can also carry source locations
``loc`` field records where it came from in the source, so a diagnostic
can point back to the original code.
+Inspecting the IR
+-----------------
+
+:py:func:`ir.format_tree <tvm_tirx.ir.format_tree>` displays an IR object's
+fields as a text tree. We can follow the GPU function's body to the
+addition in ``B[i] = A[i] + 1`` and print that expression:
+
+.. code-block:: python
+
+ from tvm_tirx import ir
+
+ region = add_one.body.seq[0] # The device region.
+ branch = region.body.seq[1] # The if statement after the index
binding.
+ store = branch.then_case.seq[0] # The write to B[i].
+ addition = store.value
+ print(ir.format_tree(addition))
+
+The output is:
+
+.. code-block:: text
+
+ Add
+ ├── a: TensorLoad(source=A, indices=[i])
+ └── b: FloatImm(value=1.0)
+
+The root is the addition. Its ``a`` field holds the tensor read, and
+its ``b`` field holds the constant. Names such as ``A`` and ``i`` refer
+to variables already defined in the function. The display uses short
+class names: ``Add``, for example, is ``ir.prim.Add``.
+
+The default view keeps common details compact and hides expression
+types. To show the type of each expression, we can expand ``ty`` for
+``ir.Expr`` objects:
+
+.. code-block:: python
+
+ print(ir.format_tree(addition, expand=[(ir.Expr, "ty")]))
+
+The output is:
+
+.. code-block:: text
+
+ Add
+ ├── ty: PrimType(dtype=float32)
+ ├── a: TensorLoad(source=A, indices=[i])
+ │ └── ty: PrimType(dtype=float32)
+ └── b: FloatImm(value=1.0)
+ └── ty: PrimType(dtype=float32)
+
+Each ``PrimType(dtype=float32)`` describes the value produced by the
+expression above it. Field selectors can be names, such as ``"a"``, or
+``(class, field)`` pairs that target a particular class. We use a class
+selector here to override the default rule that hides ``Expr.ty``.
+
+The ``fold`` option instead puts selected fields on the same line as
+their parent:
+
+.. code-block:: python
+
+ print(ir.format_tree(addition, fold=["a", "b"]))
+
+The output is:
+
+.. code-block:: text
+
+ Add(a=TensorLoad(source=A, indices=[i]), b=FloatImm(value=1.0))
+
+We will use ``format_tree`` throughout the walkthrough to inspect the
+objects in each example. Its API reference describes the remaining
+options for expanding, folding, and hiding fields.
+
.. _choose-a-chapter:
What to Read Next
diff --git a/docs/ir/printing_and_parsing.rst b/docs/ir/printing_and_parsing.rst
index 9440e97eb..75ad0e3c7 100644
--- a/docs/ir/printing_and_parsing.rst
+++ b/docs/ir/printing_and_parsing.rst
@@ -297,22 +297,26 @@ The parameter's ``loc`` points back to this declaration.
We can read
line = location.start_line
print(f"Parameter {parameter.name} is declared on line {line}.")
-The output is:
+For the CPU source file shown above, the output is:
.. code-block:: text
Parameter A is declared on line 29.
-``source_name.name`` also records the path to the CPU program's source
-file:
+The number follows the definition's position in its source file; it can
+change if you save the definition elsewhere.
-.. code-block:: text
+We can also retrieve the source filename through
+``location.source_name.name``. To inspect which fields a source location
+records without displaying its file path, we can print the location
+with ``source_name`` hidden:
+
+.. code-block:: python
+
+ print(ir.format_tree(location, hide=["source_name"]))
- parameter: ir.Var A
- └── loc: ir.SourceLoc
- ├── source_name: ir.SourceName
- │ └── name path to the source file
- └── start_line line of A's declaration
+The fields include ``start_line``, ``end_line``, ``start_column``, and
+``end_column``, which identify the declaration's range in the source.
Source locations are also useful when parsing fails. The following
source is missing the type annotation for parameter ``A``. We give the
diff --git a/docs/ir/statements.rst b/docs/ir/statements.rst
index 895645545..79138421f 100644
--- a/docs/ir/statements.rst
+++ b/docs/ir/statements.rst
@@ -105,14 +105,35 @@ The loop in ``add_one`` writes one output element in each
iteration:
The indented assignment ``B[i] = A[i] + 1`` becomes an
``ir.TensorStore`` statement describing a write to a tensor element.
-The loop body is a ``SeqStmt`` containing this statement. We can also
-construct this body through the IR API, using the parameter variables
-from ``add_one``:
+The loop body is a ``SeqStmt`` containing this statement. We can retrieve
+it from the parsed function and print its structure:
.. code-block:: python
from tvm_tirx import ir
+ parsed_loop = add_one.body.seq[0] # The for statement.
+ body = parsed_loop.body
+ print(ir.format_tree(body))
+
+The output is:
+
+.. code-block:: text
+
+ SeqStmt
+ └── seq[0]: TensorStore(dest=B, indices=[i])
+ └── value: Add
+ ├── a: TensorLoad(source=A, indices=[i])
+ └── b: FloatImm(value=1.0)
+
+When the compiled function runs, the store computes ``A[i] + 1`` and
+writes the result to element ``i`` of ``B``. We can retrieve this
+statement with ``body[0]``, which is shorthand for ``body.seq[0]``.
+
+We can also construct this body directly through the IR API:
+
+.. code-block:: python
+
A, B = add_one.params
n = A.ty.shape[0]
i = ir.Var("i", "int32")
@@ -122,34 +143,50 @@ from ``add_one``:
``ir.TensorStore`` takes the destination tensor ``B``, the index list
``[i]``, and the value expression ``A[i] + 1``. These arguments populate
its ``dest``, ``indices``, and ``value`` fields. ``ir.SeqStmt([store])``
-holds this store statement as its first entry:
-
-.. code-block:: text
-
- body: ir.SeqStmt
- └── seq[0]: ir.TensorStore B[i] = A[i] + 1
- ├── dest: ir.Var B
- ├── indices[0]: ir.Var i
- └── value: ir.prim.Add A[i] + 1
-
-When the compiled function runs, the store computes ``A[i] + 1`` and
-writes the result to element ``i`` of ``B``. We can retrieve this
-statement with ``body[0]``, which is shorthand for ``body.seq[0]``.
+puts the store in a sequence with the structure shown above.
A small extension of the CPU loop names the addition's result before
writing it to the output:
.. code-block:: python
- for i in range(n):
- value = A[i] + 1
- B[i] = value
+ @T.function
+ def add_one_bound(A: T.Tensor((n,), T.float32), B: T.Tensor((n,),
T.float32)):
+ for i in range(n):
+ value = A[i] + 1
+ B[i] = value
The assignment to ``value`` becomes an ``ir.Bind`` statement: its
``var`` field holds the variable, and its ``value`` field holds the
addition expression. The following ``TensorStore`` uses that variable
-as the value to write. We can construct these two statements and put
-them in a sequence:
+as the value to write. We can inspect the sequence in the loop body:
+
+.. code-block:: python
+
+ bound_loop = add_one_bound.body.seq[0]
+ bound_body = bound_loop.body
+ print(ir.format_tree(bound_body))
+
+The output is:
+
+.. code-block:: text
+
+ SeqStmt
+ ├── seq[0]: Bind
+ │ ├── var: value = Var(ty=float32)
+ │ └── value: Add
+ │ ├── a: TensorLoad(source=A, indices=[i])
+ │ └── b: FloatImm(value=1.0)
+ └── seq[1]: TensorStore(dest=B, indices=[i])
+ └── value: value
+
+This prints the body parsed from ``add_one_bound``. The first statement
+binds the addition to ``value``, and the second uses that same variable
+as the value to store. When the function runs, the binding computes the
+addition before the store writes it to ``B[i]``.
+
+The IR API can also construct a sequence with a binding followed by a
+store:
.. code-block:: python
@@ -158,17 +195,6 @@ them in a sequence:
store_from_value = ir.TensorStore(B, [i], value)
sequence = ir.SeqStmt([binding, store_from_value])
-.. code-block:: text
-
- sequence: ir.SeqStmt
- ├── seq[0]: ir.Bind value = A[i] + 1
- │ ├── var: ir.Var value
- │ └── value: ir.prim.Add A[i] + 1
- └── seq[1]: ir.TensorStore B[i] = value
- └── value → same ir.Var value
-
-When the function runs, the binding computes the addition and defines
-``value``, then the store writes this value to ``B[i]``.
The next section places the original single-store ``body`` inside the
CPU loop.
@@ -205,18 +231,26 @@ The arguments ``0``, ``n``, and ``1`` set the ``begin``,
``end``, and
``step`` fields. ``ForKind.DEFAULT`` selects execution in iteration
order. On each iteration, the loop executes the statements in ``body``:
-.. code-block:: text
+.. code-block:: python
+
+ parsed_loop = add_one.body.seq[0] # The for statement in the CPU
function.
+ print(ir.format_tree(parsed_loop))
- loop: ir.For
- ├── var: ir.Var i
- ├── begin: ir.IntImm 0
- ├── end: ir.Var n
- ├── step: ir.IntImm 1
- ├── kind: ir.ForKind.DEFAULT
- └── body: ir.SeqStmt
- └── seq[0]: ir.TensorStore B[i] = A[i] + 1
+The output is:
+
+.. code-block:: text
-The end bound is exclusive, so ``i`` runs from 0 through ``n - 1``.
+ For(begin=IntImm(value=0), end=n)
+ ├── var: i = Var(ty=int32)
+ └── body: SeqStmt
+ └── seq[0]: TensorStore(dest=B, indices=[i])
+ └── value: Add
+ ├── a: TensorLoad(source=A, indices=[i])
+ └── b: FloatImm(value=1.0)
+
+The default view puts ``begin`` and ``end`` on the loop's first line;
+its unit step and sequential kind are omitted because they match the
+defaults. The end bound is exclusive, so ``i`` runs from 0 through ``n - 1``.
Each iteration executes the store in ``body`` with that value of ``i``.
The loop defines ``i`` for use inside ``For.body``, which is its scope.
The ``For`` establishes this scope, and its ``SeqStmt`` body records
@@ -244,30 +278,66 @@ zero:
TVMScript represents the branch as an ``ir.If``. Its ``condition`` is
the boolean comparison ``A[i] > 0``. Its ``then_case`` and ``else_case``
each hold a ``SeqStmt`` containing one store. Only the sequence selected
-by the condition runs for each element.
+by the condition runs for each element. We can retrieve the branch
+from the loop body:
+
+.. code-block:: python
+
+ relu_loop = relu.body.seq[0]
+ relu_branch = relu_loop.body.seq[0] # The if/else statement.
+ print(ir.format_tree(relu_branch))
+
+The output is:
+
+.. code-block:: text
+
+ If
+ ├── condition: GT
+ │ ├── a: TensorLoad(source=A, indices=[i])
+ │ └── b: FloatImm(value=0.0)
+ ├── then_case: SeqStmt
+ │ └── seq[0]: TensorStore(dest=B, indices=[i])
+ │ └── value: TensorLoad(source=A, indices=[i])
+ └── else_case: SeqStmt
+ └── seq[0]: TensorStore(dest=B, indices=[i])
+ └── value: FloatImm(value=0.0)
A bounds check uses the same kind of statement. A GPU version of add-one
distributes the elements across threads, and each thread checks whether
-it has a valid element to process. These statements belong inside its
-function body:
+it has a valid element to process:
-.. literalinclude:: ../../examples/quick_start/add_one_cuda.py
- :language: python
- :start-at: T.device_entry(
- :end-at: B[i] = A[i] + 1
- :dedent: 4
+.. 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 ``if i < n`` becomes an ``ir.If``. Its ``condition`` field holds
the comparison, an ``ir.prim.LT`` expression. Its ``then_case`` field
holds a ``SeqStmt`` containing the tensor store:
+.. code-block:: python
+
+ device_region = gpu_add_one.body.seq[0]
+ branch = device_region.body.seq[1] # The if after the index definition.
+ print(ir.format_tree(branch))
+
+The output is:
+
.. code-block:: text
- ir.If
- ├── condition: ir.prim.LT i < n
- ├── then_case: ir.SeqStmt
- │ └── seq[0]: ir.TensorStore B[i] = A[i] + 1
- └── else_case: None
+ If(else_case=None)
+ ├── condition: LT
+ │ ├── a: i
+ │ └── b: n
+ └── then_case: SeqStmt
+ └── seq[0]: TensorStore(dest=B, indices=[i])
+ └── value: Add
+ ├── a: TensorLoad(source=A, indices=[i])
+ └── b: FloatImm(value=1.0)
The condition produces a boolean. When it is true, the thread executes
the store in ``then_case``. An else branch has its own ``SeqStmt`` in
@@ -282,19 +352,33 @@ the same function body into a device region. An
the IR. Its ``op`` identifies ``tirx.device_entry``, and its ``body`` is
a ``SeqStmt`` containing the index definition followed by the branch:
+.. code-block:: python
+
+ print(ir.format_tree(
+ device_region,
+ hide=["attrs", "args", "body_params", "result_vars", "value"],
+ ))
+
+The output is:
+
.. code-block:: text
- ir.RegionStmt
- ├── op → ir.Op tirx.device_entry
- └── body: ir.SeqStmt
- ├── seq[0]: ir.Bind i = ...
- └── seq[1]: ir.If if i < n
- └── then_case: ir.SeqStmt
- └── seq[0]: ir.TensorStore B[i] = A[i] + 1
-
-The ``Bind`` defines ``i`` before the ``If`` uses it. The variable is
-available to the condition and tensor store within the region. The
-:ref:`Printing and Parsing <tvmscript-region-syntax>` chapter explains
+ RegionStmt(op=tirx.device_entry)
+ └── body: SeqStmt
+ ├── seq[0]: Bind
+ │ └── var: i = Var(ty=int32)
+ └── seq[1]: If(else_case=None)
+ ├── condition: LT
+ │ ├── a: i
+ │ └── b: n
+ └── then_case: SeqStmt
+ └── seq[0]: TensorStore(dest=B, indices=[i])
+
+This view hides launch settings and value expressions to focus on the
+statements inside ``body``. The ``Bind`` defines ``i`` before the ``If``
+uses it. The variable is available to the condition and tensor store
+within the region. The :ref:`Printing and Parsing <tvmscript-region-syntax>`
+chapter explains
the grouping rule for this syntax and the equivalent ``with`` form.
While loops
@@ -321,17 +405,34 @@ TVMScript represents the loop as an ``ir.While``. Its
``condition``
holds the comparison, and its ``body`` contains both the output store
and the index update:
-.. code-block:: text
+.. code-block:: python
- ir.While
- ├── condition: ir.prim.LT i < n
- └── body: ir.SeqStmt
- ├── seq[0]: ir.TensorStore B[i] = A[i] + 1
- └── seq[1]: ir.TensorStore i += 1
+ while_loop = add_one_while.body.seq[2] # After i's allocation and
initialization.
+ print(ir.format_tree(while_loop, hide=["indices"]))
-The mutable scalar uses a one-element local tensor in IR. The second
-store writes its next value, which the condition reads before the next
-iteration.
+The output is:
+
+.. code-block:: text
+
+ While
+ ├── condition: LT
+ │ ├── a: TensorLoad(source=i)
+ │ └── b: n
+ └── body: SeqStmt
+ ├── seq[0]: TensorStore(dest=B)
+ │ └── value: Add
+ │ ├── a: TensorLoad(source=A)
+ │ └── b: FloatImm(value=1.0)
+ └── seq[1]: TensorStore(dest=i)
+ └── value: Add
+ ├── a: TensorLoad(source=i)
+ └── b: IntImm(value=1)
+
+This view hides index lists to focus on the condition and the two stores.
+The mutable scalar uses a one-element local tensor in IR, so reads of
+``i`` appear as ``TensorLoad(source=i)``.
+The first store in the loop writes to ``B``; the second writes the new
+index to ``i``. The condition reads that index before the next iteration.
Loop exits
~~~~~~~~~~
@@ -355,7 +456,28 @@ if no such element exists:
the element is positive, the store records its index and ``break`` ends
the loop. These statements become
``ir.Continue`` and ``ir.Break`` inside their enclosing loop; neither
-has operands or a nested body.
+has operands or a nested body. We can inspect the loop after the initial
+store to ``B[0]``:
+
+.. code-block:: python
+
+ search_loop = first_positive.body.seq[1] # The for loop after B[0] = -1.
+ print(ir.format_tree(search_loop.body))
+
+The output is:
+
+.. code-block:: text
+
+ SeqStmt
+ ├── seq[0]: If(else_case=None)
+ │ ├── condition: LE
+ │ │ ├── a: TensorLoad(source=A, indices=[i])
+ │ │ └── b: IntImm(value=0)
+ │ └── then_case: SeqStmt
+ │ └── seq[0]: Continue()
+ ├── seq[1]: TensorStore(dest=B, indices=[IntImm(value=0)])
+ │ └── value: i
+ └── seq[2]: Break()
Assertions and returns
~~~~~~~~~~~~~~~~~~~~~~
@@ -377,12 +499,25 @@ The ``assert`` becomes an ``ir.AssertStmt``. Its
``condition`` holds
error before the tensor read. Otherwise, execution reaches the
``ir.Return``, whose ``value`` is the addition expression:
+.. code-block:: python
+
+ print(ir.format_tree(first_plus_one.body))
+
+The output is:
+
.. code-block:: text
- first_plus_one.body: ir.SeqStmt
- ├── seq[0]: ir.AssertStmt assert n > 0, ...
- └── seq[1]: ir.Return
- └── value: ir.prim.Add A[0] + 1
+ SeqStmt
+ ├── seq[0]: AssertStmt
+ │ ├── condition: GT
+ │ │ ├── a: n
+ │ │ └── b: IntImm(value=0)
+ │ ├── error_kind: StringImm(value='RuntimeError')
+ │ └── message_parts[0]: StringImm(value='the input must contain at least
one element')
+ └── seq[1]: Return
+ └── value: Add
+ ├── a: TensorLoad(source=A, indices=[IntImm(value=0)])
+ └── b: FloatImm(value=1.0)
The return annotation ``-> T.float32`` declares the result type. For an
input starting with ``3.5``, the function returns ``4.5`` directly to its
diff --git a/docs/ir/types_and_expressions.rst
b/docs/ir/types_and_expressions.rst
index 73b2369d1..292be8acd 100644
--- a/docs/ir/types_and_expressions.rst
+++ b/docs/ir/types_and_expressions.rst
@@ -138,11 +138,18 @@ the parser represents it as a ``tirx.TensorType`` object.
Its ``shape``
field contains one dimension, ``n``, and its ``dtype`` field is
``ir.PrimType("float32")``:
+.. code-block:: python
+
+ input_type = add_one.params[0].ty
+ print(ir.format_tree(input_type))
+
+The output is:
+
.. code-block:: text
- tirx.TensorType T.Tensor((n,), T.float32)
- ├── shape[0]: ir.Var n
- └── dtype: ir.PrimType float32
+ 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
@@ -261,13 +268,26 @@ represents the read as an ``ir.TensorLoad`` node. Its
``source`` field
refers to ``A``, and ``indices`` contains ``i``, selecting the element
to read:
+.. 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"],
+ ))
+
+The output is:
+
.. code-block:: text
- ir.TensorLoad A[i]
- ├── ty: ir.PrimType float32
- ├── source: ir.Var A
- │ └── ty: tirx.TensorType (n,) of float32
- └── indices[0]: ir.Var i
+ 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.
**Vector expressions.** A primitive expression can also produce a vector
value. The earlier add-one result ``vector_plus_one`` has type
@@ -306,11 +326,17 @@ a call to a registered operator; the returned IR node is
an ``ir.Call``.
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``:
+.. code-block:: python
+
+ print(ir.format_tree(addition))
+
+The output is:
+
.. code-block:: text
- ir.prim.Add A[i] + 1
- ├── a: ir.TensorLoad A[i]
- └── b: ir.FloatImm 1.0
+ 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
@@ -320,26 +346,37 @@ 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. The following part of
-its body combines multiplication, addition, and comparison to compute
-and check that element's index:
+A GPU version assigns one element to each thread. Its index calculation
+combines multiplication and addition, and its bounds check uses a
+comparison:
-.. literalinclude:: ../../examples/quick_start/add_one_cuda.py
- :language: python
- :start-at: i = T.cuda.block_idx
- :end-at: B[i] = A[i] + 1
- :dedent: 4
+.. 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:
+.. 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))
+
+The output is:
+
.. code-block:: text
- ir.prim.LT i < n
- ├── a: ir.Var i
- └── b: ir.Var n
+ LT
+ ├── a: i
+ └── b: n
The comparison checks whether the thread has a valid element to process.
@@ -388,14 +425,24 @@ inspect their types through ``ty``:
output_type = B.ty
Each parameter is a ``Var`` with its own ``name`` and ``ty`` fields.
-For ``A``, these are:
+We can expand its type to inspect the shape and element type:
+
+.. code-block:: python
+
+ print(ir.format_tree(A, expand=[(ir.Var, "ty")]))
+
+The output is:
.. code-block:: text
- A: ir.Var
- ├── name: "A"
- └── ty: tirx.TensorType (n,) of float32
+ A = Var
+ └── ty: TensorType
+ ├── shape[0]: n = Var
+ │ └── ty: PrimType(dtype=int32)
+ └── dtype: PrimType(dtype=float32)
+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:
@@ -454,12 +501,21 @@ We can construct the thread-index call directly through
the IR API:
``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"],
+ ))
+
+The output is:
+
.. code-block:: text
- x_call: ir.Call
- ├── op → ir.Op tirx.cuda.thread_idx
- ├── args[0]: ir.StringImm "x"
- └── ty: ir.PrimType int32
+ 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
@@ -475,14 +531,24 @@ built-in ``prim.sigmoid`` operator:
sigmoid_op = ir.Op.get("prim.sigmoid")
activated_plus_one = ir.Call(sigmoid_op, [scalar_plus_one])
-The call's argument is now the addition expression:
+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:
+
+.. code-block:: python
+
+ print(ir.format_tree(
+ activated_plus_one,
+ fold=["args"],
+ expand=[(ir.Call, "ty")],
+ hide=["attrs", "ty_args"],
+ ))
+
+The output is:
.. code-block:: text
- activated_plus_one: ir.Call
- ├── op → ir.Op prim.sigmoid
- ├── args[0]: ir.prim.Add scalar_value + 1
- └── ty: ir.PrimType float32
+ Call(op=prim.sigmoid, args=[Add(a=scalar_value, b=FloatImm(value=1.0))])
+ └── ty: PrimType(dtype=float32)
``activated_plus_one.args[0]`` refers to ``scalar_plus_one``, so sigmoid
receives the addition's result. The expression computes