This is an automated email from the ASF dual-hosted git repository.
spectrometerHBH 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 5ac16828f [DOCS] Introduce IR tree display before the class hierarchy
(#133)
5ac16828f is described below
commit 5ac16828f31b2f4687a1a30b8f1d8a914f7e7cda
Author: Tianqi Chen <[email protected]>
AuthorDate: Fri Oct 30 20:31:03 2026 -0400
[DOCS] Introduce IR tree display before the class hierarchy (#133)
---
docs/ir/overview.rst | 154 ++++++++++++++++++++++++++-------------------------
1 file changed, 79 insertions(+), 75 deletions(-)
diff --git a/docs/ir/overview.rst b/docs/ir/overview.rst
index 0f5759c1b..ec6877cdc 100644
--- a/docs/ir/overview.rst
+++ b/docs/ir/overview.rst
@@ -18,10 +18,10 @@
IR Overview
===========
-TIRx gives developers and agents direct access to the programs and
-transformations at each stage of compilation. They can inspect the
-intermediate program, apply an existing pass, or add their own compiler
-components.
+One primary design goal of TIRx is to give developers and agents easy access
+to every stage of compilation, not only its input and output. By providing
+a consistent way to inspect and modify programs at each stage, TIRx makes
+it easier to understand and customize the compiler.
TIRx represents a program as a tree of intermediate representation (IR)
nodes, such as functions, statements, and values. The tree is similar to the
@@ -55,6 +55,81 @@ contains the following elements:
- **Modules** (:py:class:`ir.IRModule <tvm_tirx.ir.IRModule>`) group named
functions into a complete program.
+Exploring the IR Tree
+---------------------
+
+To get a visual sense of the IR structure, we can use
+:py:func:`ir.format_tree <tvm_tirx.ir.format_tree>` to display an IR object
+and its fields as a text tree. Let's start with the GPU function's body,
+follow it down 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 ``ir.format_tree`` function provides options to control how the tree
+is displayed. For example, we can show expression types by expanding the
+``ty`` field 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)
+
+Here, each ``PrimType(dtype=float32)`` tells us that the expression it
+belongs to produces a ``float32`` value. 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``.
+
+We can also make the display more compact by folding selected fields onto
+the same line as their parent. For example, folding ``a`` and ``b`` displays
+this addition on a single line:
+
+.. 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))
+
+This guide uses ``format_tree`` to inspect the objects in each example.
+Its API reference describes the remaining options for expanding, folding,
+and hiding fields.
+
Class Hierarchy
---------------
@@ -164,77 +239,6 @@ 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