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

Reply via email to