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 e2e48f3f8 [DOCS] Add Working with IR in C++ and Rust chapters (#152)
e2e48f3f8 is described below
commit e2e48f3f8fcb5dfd76c72712d7ff34c412b2f62f
Author: Tianqi Chen <[email protected]>
AuthorDate: Sun Nov 1 14:17:02 2026 -0500
[DOCS] Add Working with IR in C++ and Rust chapters (#152)
---
docs/conf.py | 16 +-
docs/dev/doc_build.rst | 7 +
docs/index.rst | 2 +
docs/ir_guides/overview.rst | 2 +
docs/ir_guides/working_with_ir_in_cpp.rst | 594 +++++++++++++++++++++
docs/ir_guides/working_with_ir_in_rust.rst | 534 ++++++++++++++++++
docs/reference/cpp/index.rst | 82 +++
examples/ir_guides/CMakeLists.txt | 66 +++
examples/ir_guides/cpp/working_with_ir.cc | 224 ++++++++
examples/ir_guides/pyproject.toml | 34 ++
.../python/tirx_ir_guide_examples/__init__.py | 21 +
.../ir_guides/python/tirx_ir_guide_examples/cpp.py | 30 ++
.../python/tirx_ir_guide_examples/rust.py | 38 ++
examples/ir_guides/rust/.gitignore | 20 +
examples/ir_guides/rust/Cargo.toml | 31 ++
examples/ir_guides/rust/rustfmt.toml | 19 +
examples/ir_guides/rust/src/lib.rs | 286 ++++++++++
examples/ir_guides/working_with_ir_in_cpp.py | 104 ++++
examples/ir_guides/working_with_ir_in_rust.py | 94 ++++
19 files changed, 2201 insertions(+), 3 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
index 5237b5aab..1a930c4fd 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -53,8 +53,14 @@ breathe_default_project = "tvm-tirx"
breathe_projects = {"tvm-tirx": "./_build/doxygen/xml"}
-exhaleDoxygenStdin = """
-INPUT = ../include
+# The C++ reference also documents the TVM-FFI structural utilities, which
TIRx uses directly.
+_ffi_structural_headers = " ".join(
+ f"../3rdparty/tvm-ffi/include/tvm/ffi/extra/structural_{name}.h"
+ for name in ("visit", "mutate", "equal", "hash", "key")
+)
+
+exhaleDoxygenStdin = f"""
+INPUT = ../include {_ffi_structural_headers}
INCLUDE_PATH = ../include ../3rdparty/tvm-ffi/include
PREDEFINED += TVM_TIRX_DLL= TVM_RUNTIME_DLL=
TVM_RUNTIME_DLL_EXPORT= \
TVM_FFI_DLL= TVM_FFI_DLL_EXPORT= TVM_FFI_INLINE= \
@@ -62,7 +68,11 @@ PREDEFINED += TVM_TIRX_DLL= TVM_RUNTIME_DLL=
TVM_RUNTIME_DLL_EXPORT=
TVM_FFI_COLD_CODE= \
TVM_FFI_PREDICT_FALSE(x)=x TVM_FFI_PREDICT_TRUE(x)=x
\
__cplusplus=202002
-EXCLUDE_SYMBOLS += *detail* *TypeTraits* std tvm::ffi tvm::ffi::* TVM_*
\
+# tvm::ffi symbols come only from the structural headers in INPUT; their
engines are internal.
+# The TVM_* patterns exclude every macro except TVM_FFI_S_*, which those
headers reference.
+EXCLUDE_SYMBOLS += *detail* *TypeTraits* std \
+ TVM_[A-EG-Z]* TVM_F[A-EG-Z]* TVM_FFI_[A-RTV-Z]*
TVM_FFI_S[A-Z]* \
+ TVM_FFI_U* *_IMPL_ *Engine *EngineBase UnsafeInit
tvm::ffi::type_attr \
*_type_* *use_default_type_traits_v*
*object_ref_contains_v* \
WithAttr MatchesOneOf MakeConst FInferType
TFixedReturnType \
FRegionGetBodyParams FRegionValidate FTileOpDispatch
diff --git a/docs/dev/doc_build.rst b/docs/dev/doc_build.rst
index 1435667fd..f41f21245 100644
--- a/docs/dev/doc_build.rst
+++ b/docs/dev/doc_build.rst
@@ -67,6 +67,13 @@ Generating the C++ reference takes longer and requires
Doxygen:
brew install doxygen # macOS
sudo apt install doxygen # Linux
+The C++ reference also documents the TVM-FFI structural utilities from the
+``3rdparty/tvm-ffi`` submodule, so check it out first:
+
+.. code-block:: bash
+
+ git submodule update --init 3rdparty/tvm-ffi
+
Set ``BUILD_CPP_DOCS=1`` on the desired build command to enable the extra step:
.. code-block:: bash
diff --git a/docs/index.rst b/docs/index.rst
index 32fba9cad..26055fff0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -55,6 +55,8 @@ Table of Contents
ir_guides/printing_and_parsing
ir_guides/structural_utilities
ir_guides/symbolic_integer_analysis
+ ir_guides/working_with_ir_in_cpp
+ ir_guides/working_with_ir_in_rust
.. toctree::
:maxdepth: 1
diff --git a/docs/ir_guides/overview.rst b/docs/ir_guides/overview.rst
index a8935fcbc..bca67b255 100644
--- a/docs/ir_guides/overview.rst
+++ b/docs/ir_guides/overview.rst
@@ -285,3 +285,5 @@ and the second covers the tools we use to inspect and
transform it.
- :doc:`symbolic_integer_analysis` covers symbolic analysis and simplification
of integer indices and bounds, which compiler analyses and transformations
can use.
+- :doc:`working_with_ir_in_cpp` and :doc:`working_with_ir_in_rust` show how to
+ access and transform the same IR from C++ and Rust.
diff --git a/docs/ir_guides/working_with_ir_in_cpp.rst
b/docs/ir_guides/working_with_ir_in_cpp.rst
new file mode 100644
index 000000000..f001bb42c
--- /dev/null
+++ b/docs/ir_guides/working_with_ir_in_cpp.rst
@@ -0,0 +1,594 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Working with IR in C++
+======================
+
+The IR objects we have used from Python are TVM-FFI objects implemented in
+C++. A C++ function can receive ``add_one`` from Python, inspect or rewrite
+it, and hand the result back, with no conversion in between. This lets us
+move a hot analysis or a large transformation to C++ while keeping the rest
+of the workflow in Python.
+
+This chapter assumes the concepts of the earlier chapters and shows their
+C++ form:
+
+- **Accessing and creating IR nodes**: read fields, check node types, and
+ build new nodes.
+- **Structural utilities**: walk, map, and compare programs, with callbacks
+ selected by their parameter types.
+- **Visitor and mutator classes**: C++ classes with one hook per node kind,
+ for passes that customize many kinds of node.
+
+.. note::
+
+ The runnable code in this chapter is under
+ `examples/ir_guides
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_guides>`_
+ in the repository.
+
+Setting Up
+----------
+
+Throughout this chapter, we use the ``add_one`` function from Quick Start:
+
+.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
+ :language: python
+ :start-at: from tvm_tirx.script import tirx as T
+ :end-at: B[i] = A[i] + 1
+
+The examples are packaged as ``tirx_ir_guide_examples`` under
+`examples/ir_guides
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_guides>`__.
+Installing the package builds the C++ source, ``cpp/working_with_ir.cc``,
+into a library; ``CMakeLists.txt`` and ``pyproject.toml`` in the same
+directory show how. Install TIRx from the same source tree to keep the IR
+APIs aligned. We install without build isolation to build against that
+installation instead of fetching one from PyPI:
+
+.. code-block:: bash
+
+ pip install scikit-build-core
+ pip install --no-build-isolation -e examples/ir_guides
+
+Each example is a C++ function that takes ``add_one`` as its argument. A
+``TVM_FFI_STATIC_INIT_BLOCK`` at the end of the source registers each one as
+a global function under ``tirx_ir_guide_examples.cpp``:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-at: refl::GlobalDef()
+ :end-at: .def("tirx_ir_guide_examples.cpp.inspect", Inspect)
+ :dedent: 2
+
+The package's ``tirx_ir_guide_examples.cpp`` module loads the library and
+exposes these functions, so Python calls them by name:
+
+.. code-block:: python
+
+ import tirx_ir_guide_examples.cpp
+
+ tirx_ir_guide_examples.cpp.inspect(add_one)
+
+The driver ``working_with_ir_in_cpp.py`` calls each example this way and
+prints the result.
+
+Accessing and Creating IR Nodes
+-------------------------------
+
+Before reading any IR, it helps to know where the classes live. The
+headers relevant to this chapter sit in five folders under ``tvm/``; see
+:ref:`cpp-header-organization` for the full list:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 18 47 35
+
+ * - Folder
+ - Contents
+ - Included by our examples
+ * - ``tvm/ffi/``
+ - From TVM-FFI: ``Object`` and ``ObjectRef``, containers, functions,
+ and the structural utilities.
+ - ``extra/structural_visit.h``, ``extra/structural_mutate.h``,
+ ``extra/structural_equal.h``, ``extra/structural_hash.h``,
+ ``reflection/registry.h``
+ * - ``tvm/ir/``
+ - Core IR nodes, such as ``Expr``, ``Var``, ``Stmt``, ``For``, and
+ ``TensorStore``, and the expression visitors in ``expr_functor.h``.
+ - (through ``tvm/tirx/function.h``)
+ * - ``tvm/sym/``
+ - Symbolic analysis, such as ``sym::Analyzer`` and
+ ``sym::ConstraintContext``.
+ - None
+ * - ``tvm/tirx/``
+ - Tensor programs: ``tirx::Function``, the statement visitors in
+ ``stmt_functor.h``, and the constraint-context variants.
+ - ``function.h``, ``stmt_functor.h``
+ * - ``tvm/script/``
+ - The IR builder and the TVMScript printer.
+ - None
+
+IR classes live in the ``tvm`` namespace, TIRx-specific ones such as
+:cpp:class:`tvm::tirx::Function` in ``tvm::tirx``, and the TVM-FFI classes
+in ``tvm::ffi``. The examples start with ``using namespace tvm;``, so these
+appear as ``Var``, ``tirx::Function``, and
+:cpp:func:`ffi::StructuralWalk <tvm::ffi::StructuralWalk>`.
+
+**Each IR node has two C++ classes.** The node class, named with an
+``Obj`` suffix such as :cpp:class:`tvm::ForObj`, holds the fields. The
+reference class without the suffix, such as :cpp:class:`tvm::For`, is a
+reference-counted handle to a node, and is what functions take and return.
+The ``->`` operator on a reference reaches the node's fields.
+
+Let's read ``add_one`` from its parameters down to the store in its loop:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [inspect.begin]
+ :end-before: // [inspect.end]
+
+The output is:
+
+.. code-block:: text
+
+ param A
+ param B
+ loop over i up to n
+ store to B: A[i] + T.float32(1.0)
+
+Fields have the types we know from Python, and writing an expression to a
+stream prints it in TVMScript. The elements of a ``SeqStmt`` are general
+``Stmt`` references, so we check the actual node type before reading a
+loop or a store. |ObjectRef::as|_ and its relatives offer three forms:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 35 65
+
+ * - Call
+ - Returns
+ * - ``stmt.as<ForObj>()``
+ - A pointer to the node, or ``nullptr`` if it is not a loop.
+ * - ``stmt.as<For>()``
+ - A ``std::optional<For>`` reference.
+ * - ``stmt.as_or_throw<For>()``
+ - The ``For`` reference, or raises an error.
+
+.. note::
+
+ A function's ``body`` is always a ``SeqStmt``. The loop variable is stored
+ as a ``PrimVar``, which views a ``Var`` as a ``PrimExpr``, so we read its
+ name through ``as<VarObj>()``.
+
+To create a node, we call the constructor of its reference class, and
+arithmetic operators on ``PrimExpr`` build new expressions. Let's build a
+store that writes twice the value of the store in ``add_one``:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [create.begin]
+ :end-before: // [create.end]
+
+The output is:
+
+.. code-block:: python
+
+ n = T.dynamic("n", dtype="int32")
+ B = T.Var("B", T.Tensor((n,), T.float32))
+ i = T.dynamic("i", dtype="int32")
+ A = T.Var("A", T.Tensor((n,), T.float32))
+ B[i] = (A[i] + T.float32(1.0)) * T.float32(2.0)
+
+The new store reuses the destination and indices of the old one, so the
+printer declares them as free variables first. ``store->value * 2`` turns
+the literal into a constant of the value's type, ``T.float32(2.0)``.
+Constructing nodes creates new objects; ``add_one`` itself is not modified.
+
+Structural Utilities in C++
+---------------------------
+
+The structural utilities from Python are available in C++ with the same
+behavior: :cpp:func:`ffi::StructuralWalk <tvm::ffi::StructuralWalk>`,
+:cpp:func:`ffi::StructuralMap <tvm::ffi::StructuralMap>`,
+:cpp:class:`ffi::StructuralEqual <tvm::ffi::StructuralEqual>`, and
+:cpp:class:`ffi::StructuralHash <tvm::ffi::StructuralHash>`. **What changes
+is how callbacks are written**:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 25 35 40
+
+ * - Aspect
+ - Python
+ - C++
+ * - Nodes a callback receives
+ - The type paired with it, such as ``(ir.TensorStore, f)``
+ - The type of the callback's first parameter
+ * - Walk callback result
+ - ``None``, ``WalkResult.SKIP``, or a ``VisitInterrupt``
+ - ``ffi::Expected<WalkResult>``
+ * - Traversal order
+ - ``order="pre"`` or the default post-order
+ - A required template argument, ``WalkOrder::kPreOrder`` or
+ ``kPostOrder``
+ * - Keep a node in a map
+ - Return the input node
+ - Return ``ffi::Unchanged()`` or the node
+ * - Result of a map
+ - The new value
+ - An ``ffi::Any``, cast back with ``cast<T>()``
+ * - Definition region kind
+ - Pass the callback through ``with_def_region_kind``
+ - A trailing ``TVMFFIDefRegionKind`` parameter
+
+Structural Walk
+~~~~~~~~~~~~~~~
+
+As in Python, a walk calls our callback on each node of the type it asks
+for. To find the tensors that ``add_one`` writes, the callback takes a
+``const TensorStore&``:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [walk.begin]
+ :end-before: // [walk.end]
+
+The output is:
+
+.. code-block:: text
+
+ ['B']
+
+Only the store reaches the callback, because its parameter is
+``const TensorStore&``.
+
+A walk callback returns an
+``ffi::Expected<``\ :cpp:class:`ffi::WalkResult <tvm::ffi::WalkResult>`\ ``>``.
+``WalkResult::Advance()`` continues the walk, ``WalkResult::Skip()`` skips
+the node's children in pre-order, and ``WalkResult::Interrupt(...)`` stops
+the walk.
+
+To handle several node kinds in one walk, we pass one callback per kind as
+extra arguments. They are tried in
+declaration order, and only the first one whose parameter type matches a
+node runs; a node that matches none is still traversed but not reported.
+This walk records the loops and stores in pre-order:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [dispatch.begin]
+ :end-before: // [dispatch.end]
+
+The output is:
+
+.. code-block:: text
+
+ ['loop i', 'store B']
+
+The loop and the store each reach their own callback, and pre-order
+reports the loop before the store inside it. Matching follows the class
+hierarchy, so a callback that takes a base class, such as
+``const Stmt&``, would also take loops and stores that no earlier callback
+claims.
+
+To stop at the first match and return it, a callback wraps the node in an
+:cpp:class:`ffi::VisitInterrupt <tvm::ffi::VisitInterrupt>`.
+``StructuralWalk`` returns that interrupt, or ``std::nullopt`` if the walk
+finished without one:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [stop.begin]
+ :end-before: // [stop.end]
+
+The output is:
+
+.. code-block:: text
+
+ B
+
+The interrupt's ``value`` field carries the payload as an ``ffi::Any``, and
+``cast<TensorStore>()`` converts it back to a store.
+
+Definitions and Uses
+~~~~~~~~~~~~~~~~~~~~
+
+A callback receives the definition region kind of each site when it takes
+a ``TVMFFIDefRegionKind`` as its last parameter. The kinds match Python's:
+``kTVMFFIDefRegionKindNone`` for a use, ``kTVMFFIDefRegionKindSimple`` for
+``DEF_SIMPLE``, and ``kTVMFFIDefRegionKindPattern`` for ``DEF_PATTERN``. Let's
list the definition sites in
+``add_one``:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [definitions.begin]
+ :end-before: // [definitions.end]
+
+The output is:
+
+.. code-block:: text
+
+ A pattern
+ n pattern
+ B pattern
+ n pattern
+ i simple
+
+These are the same sites as in Python: the parameters define ``A``, ``B``,
+and ``n`` by pattern, and the loop defines ``i``.
+
+Structural Map
+~~~~~~~~~~~~~~
+
+``ffi::StructuralMap`` takes the same callbacks, but each one returns a
+replacement for its node. Let's specialize ``add_one`` by replacing ``n``
+with 128, passing ``n`` in from Python:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [specialize.begin]
+ :end-before: // [specialize.end]
+
+The output is:
+
+.. code-block:: python
+
+ from __future__ import annotations
+
+ # from tvm_tirx.script import tirx as T
+
+ @T.function
+ def add_one(A: T.Tensor((128,), T.float32), B: T.Tensor((128,), T.float32)):
+ for i in range(128):
+ B[i] = A[i] + T.float32(1.0)
+
+For every other variable, the callback returns
+:cpp:struct:`ffi::Unchanged <tvm::ffi::Unchanged>`\ ``()``, which keeps the
+node as it is. The constant takes its type from the variable, ``var->ty``.
+As in Python, the mapper keeps definitions and uses consistent, so the new
+``A`` and ``B`` and every use of them carry the specialized shape.
+
+Equality and Hashing
+~~~~~~~~~~~~~~~~~~~~
+
+``ffi::StructuralEqual::Equal`` and ``ffi::StructuralHash::Hash`` compare
+and hash by structure. Let's compare two ``add_one`` functions built
+separately in Python by ``make_add(1)``, the helper from the structural
+utilities chapter:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [equal.begin]
+ :end-before: // [equal.end]
+
+The output is:
+
+.. code-block:: text
+
+ [False, True, True]
+
+The functions are different objects, yet structurally equal with equal
+hashes. ``Equal`` and ``Hash`` also take an optional ``map_free_vars``
+argument, which defaults to ``false`` as in Python.
+
+Visit and Mutate
+~~~~~~~~~~~~~~~~
+
+When a callback must decide which children to visit, we use
+:cpp:func:`ffi::StructuralVisit <tvm::ffi::StructuralVisit>` and
+:cpp:func:`ffi::StructuralMutate <tvm::ffi::StructuralMutate>`, as in
+Python. Their callbacks also receive
+the visitor or mutator, such as
+:cpp:class:`ffi::StructuralVisitorObj* <tvm::ffi::StructuralVisitorObj>`,
+and descend into a node's children with ``DefaultVisitExpected`` or
+``DefaultMutateExpected``.
+
+Visitor and Mutator Classes
+---------------------------
+
+Walk and map cover most tasks. A pass that handles many kinds of node,
+however, reads better as a class with one method per kind:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 35 35
+
+ * - Tool
+ - Covers
+ - Use it for
+ * - Structural utilities
+ - Any TVM-FFI object
+ - A few node kinds, written as callbacks
+ * - :cpp:class:`tirx::StmtExprVisitor <tvm::tirx::StmtExprVisitor>`,
+ :cpp:class:`tirx::StmtExprMutator <tvm::tirx::StmtExprMutator>`
+ - TIRx statements and expressions (``tvm/tirx/stmt_functor.h``)
+ - Passes that customize many node kinds
+ * - :cpp:class:`ExprVisitor <tvm::ExprVisitor>`,
+ :cpp:class:`ExprMutator <tvm::ExprMutator>`
+ - Expressions alone (``tvm/ir/expr_functor.h``)
+ - Expression analyses and rewrites
+ * - :cpp:class:`ExprFunctor <tvm::ExprFunctor>`,
+ :cpp:class:`tirx::StmtFunctor <tvm::tirx::StmtFunctor>`
+ - Dispatch on the node kind with a signature we choose, such as
+ ``int(const Expr&)``, without traversing children
+ - Computations where each hook decides which children to recurse into
+
+Each class declares a virtual hook for every node kind, named ``Visit_``
+for a visitor and ``Mutate_`` for a mutator, and a subclass overrides only
+the kinds it cares about.
+
+**These classes are built on the structural utilities.** A node kind
+without a hook, such as a function, falls back to its structural traversal,
+which hands each child back to our hooks.
+
+.. note::
+
+ ``ExprVisitor`` ultimately derives from
+ :cpp:class:`ffi::StructuralVisitorObj <tvm::ffi::StructuralVisitorObj>`,
+ and ``ExprMutator`` from the mutator base behind ``StructuralMap``. Any
+ hook can read the definition region kind with ``def_region_kind()``.
+
+Let's record the loops around each write, as the structural visit example
+in Python did:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [visit.begin]
+ :end-before: // [visit.end]
+
+The output is:
+
+.. code-block:: text
+
+ ['B in i']
+
+Our ``For`` hook pushes the loop variable, calls the base class hook to
+visit the loop's bounds and body, then pops the variable. Calling the base
+hook plays the role of ``default_visit`` in Python, and returning its
+result passes an interrupt from a child up to the caller. Visitors are
+objects, so we allocate them with ``ffi::make_object``.
+
+.. note::
+
+ The ``using tirx::StmtExprVisitor::Visit_;`` line keeps the hooks we did
+ not override visible, as usual for overloaded virtual functions in C++.
+
+A mutator works the same way, with hooks that return the replacement node.
+Let's reverse the loop by replacing each use of ``i`` with ``n - 1 - i``,
+built with arithmetic operators as before:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [mutate.begin]
+ :end-before: // [mutate.end]
+
+The output is:
+
+.. code-block:: python
+
+ from __future__ import annotations
+
+ # from tvm_tirx.script import tirx as T
+
+ @T.function
+ def add_one[n](A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ for i in range(n):
+ B[n - 1 - i] = A[n - 1 - i] + T.float32(1.0)
+
+A mutator hook returns an
+:cpp:class:`UnchangedOr <tvm::ffi::UnchangedOr>`\ ``<T>``: either a
+replacement node or ``ffi::Unchanged()``, which keeps the original and lets
+the parents above it stay unchanged too. Our ``For`` hook records the
+replacement before calling the base class hook, so it is ready before any
+use of ``i`` is reached.
+
+.. note::
+
+ ``StmtExprMutator``'s ``For`` hook rewrites the loop's bounds and body but
+ not the loop variable itself, so our ``Var`` hook sees only the uses of
+ ``i``, and the loop keeps its variable. The ``InplaceMode`` argument
+ tells a hook whether it may update a node that no one else references in
+ place; our hooks forward it to the base class unchanged.
+
+Constraint Contexts
+~~~~~~~~~~~~~~~~~~~
+
+TIRx adds variants of the structural utilities and the visitor and mutator
+classes that also pass the facts valid at each node, such as loop ranges
+and branch conditions:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 25 35
+
+ * - Utility
+ - Works like
+ - Facts reach the callback as
+ * - :cpp:func:`tirx::StructuralWalkWithConstraintContext
<tvm::tirx::StructuralWalkWithConstraintContext>`
+ - ``ffi::StructuralWalk``
+ - A ``const sym::ConstraintContext&`` after the node
+ * - :cpp:func:`tirx::StructuralMapWithConstraintContext
<tvm::tirx::StructuralMapWithConstraintContext>`
+ - ``ffi::StructuralMap``
+ - A ``const sym::ConstraintContext&`` after the node
+ * - :cpp:func:`tirx::StructuralVisitWithConstraintContext
<tvm::tirx::StructuralVisitWithConstraintContext>`
+ - ``ffi::StructuralVisit``
+ - The ``constraints`` member of the visitor the callback receives
+ * - :cpp:func:`tirx::StructuralMutateWithConstraintContext
<tvm::tirx::StructuralMutateWithConstraintContext>`
+ - ``ffi::StructuralMutate``
+ - The ``constraints`` member of the mutator the callback receives
+ * - :cpp:class:`tirx::StmtExprVisitorWithConstraintContext
<tvm::tirx::StmtExprVisitorWithConstraintContext>`,
+ :cpp:class:`tirx::StmtExprMutatorWithConstraintContext
<tvm::tirx::StmtExprMutatorWithConstraintContext>`
+ - ``tirx::StmtExprVisitor``, ``tirx::StmtExprMutator``
+ - The inherited ``constraints`` member
+
+The functions are in ``tvm/tirx/structural_visit_with_constraint_context.h``
+and ``tvm/tirx/structural_mutate_with_constraint_context.h``, and the classes
+in ``tvm/tirx/stmt_functor_with_constraint_context.h``.
+
+These tools follow the same rules as in Python: IR is immutable, rewrites
+return new programs that share unchanged parts, and every utility respects
+definitions and uses. Because C++ and Python share the same objects, we can
+prototype a pass in Python and move parts of it to C++ as needed.
+
+Quick Reference
+---------------
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 30 30
+
+ * - C++
+ - What it does
+ - Python equivalent
+ * - ``loop->var``, ``func->params``
+ - Reads a node's fields
+ - ``loop.var``, ``func.params``
+ * - ``stmt.as<ForObj>()``, ``stmt.as<For>()``,
+ ``stmt.as_or_throw<For>()``
+ - Checks the node type and downcasts
+ - ``isinstance(stmt, ir.For)``
+ * - ``TensorStore(dest, indices, value)``, ``store->value * 2``
+ - Creates a node; builds an expression with operators
+ - ``ir.TensorStore(dest, indices, value)``, ``store.value * 2``
+ * - :cpp:func:`ffi::StructuralWalk <tvm::ffi::StructuralWalk>`\
``<ffi::WalkOrder::kPreOrder>(func, ...)``
+ - Walks with typed callbacks that return
+ ``ffi::Expected<ffi::WalkResult>``
+ - ``tvm_ffi.structural_walk(func, callbacks, order="pre")``
+ * - :cpp:func:`ffi::StructuralMap <tvm::ffi::StructuralMap>`\
``<order>(func, ...)``,
+ ``ffi::Unchanged()``
+ - Rebuilds with replacements and returns an ``ffi::Any``
+ - ``tvm_ffi.structural_map(func, callbacks)``
+ * - A trailing ``TVMFFIDefRegionKind`` parameter
+ - Receives the definition region kind
+ - ``with_def_region_kind=``
+ * - :cpp:func:`ffi::StructuralEqual::Equal
<tvm::ffi::StructuralEqual::Equal>`,
+ :cpp:func:`ffi::StructuralHash::Hash <tvm::ffi::StructuralHash::Hash>`
+ - Compares and hashes by structure
+ - ``tvm_ffi.structural_equal``, ``tvm_ffi.structural_hash``
+ * - :cpp:class:`tirx::StmtExprVisitor <tvm::tirx::StmtExprVisitor>`,
+ :cpp:class:`tirx::StmtExprMutator <tvm::tirx::StmtExprMutator>`,
+ :cpp:class:`ExprVisitor <tvm::ExprVisitor>`,
+ :cpp:class:`ExprMutator <tvm::ExprMutator>`
+ - One ``Visit_`` or ``Mutate_`` hook per node kind
+ - ``tvm_ffi.structural_visit``, ``tvm_ffi.structural_mutate``
+ * - ``TVM_FFI_STATIC_INIT_BLOCK``, ``refl::GlobalDef().def(...)``
+ - Registers C++ functions as global functions
+ - ``tvm_ffi.register_global_func``
+
+.. TVM-FFI C++ API page for ObjectRef, which the C++ reference does not
include.
+
+.. |ObjectRef::as| replace:: ``ObjectRef::as``
+.. _`ObjectRef::as`:
https://tvm.apache.org/ffi/reference/cpp/generated/classtvm_1_1ffi_1_1ObjectRef.html
diff --git a/docs/ir_guides/working_with_ir_in_rust.rst
b/docs/ir_guides/working_with_ir_in_rust.rst
new file mode 100644
index 000000000..6f86a0cd5
--- /dev/null
+++ b/docs/ir_guides/working_with_ir_in_rust.rst
@@ -0,0 +1,534 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Working with IR in Rust
+=======================
+
+The IR objects we have used so far in Python are TVM-FFI objects, and the
+same objects are available in Rust through the
+`tvm-tirx <https://crates.io/crates/tvm-tirx>`_ crate. A Rust function can
+receive a function written in TVMScript, read and rewrite it, and return
+the result to Python. Nothing is converted or copied along the way: Python
+and Rust hold references to the same native objects.
+
+This chapter assumes the concepts of the earlier chapters and shows their
+Rust form:
+
+- **Accessing and creating IR nodes**: read fields, branch on node types,
+ and build new nodes.
+- **Structural utilities**: walk, map, and compare programs, with
+ callbacks selected by their Rust parameter types.
+- **Visitors and mutators**: keep state across callbacks and control the
+ traversal, with ``#[dispatch]`` structs and ``VisitCallbacks``.
+
+.. note::
+
+ The runnable code in this chapter is under
+ `examples/ir_guides
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_guides>`_
+ in the repository.
+
+Setting Up
+----------
+
+Throughout this chapter, we use the ``add_one`` function from Quick Start:
+
+.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
+ :language: python
+ :start-at: from tvm_tirx.script import tirx as T
+ :end-at: B[i] = A[i] + 1
+
+The examples are packaged as ``tirx_ir_guide_examples`` under
+`examples/ir_guides
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_guides>`__.
+When cargo is available, installing the package builds the Rust crate in
+``rust/`` into a library; ``CMakeLists.txt`` and ``pyproject.toml`` in the
+same directory show how. The crate uses the bindings from this checkout,
+so install TIRx from the same source tree. We install without build isolation
+to build against that installation instead of fetching one from PyPI:
+
+.. code-block:: bash
+
+ pip install scikit-build-core
+ pip install --no-build-isolation -e examples/ir_guides
+
+Each example is a Rust function that takes ``add_one`` as its argument. A
+|static_init_block!|_ at the end of the crate registers each one as a
+global function under ``tirx_ir_guide_examples.rust``:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-at: tvm_ffi::Function::register_global_typed(
+ :end-at: )?;
+ :dedent: 4
+
+The package's ``tirx_ir_guide_examples.rust`` module loads the library and
+exposes these functions, so Python calls them by name:
+
+.. code-block:: python
+
+ import tirx_ir_guide_examples.rust
+
+ tirx_ir_guide_examples.rust.inspect(add_one)
+
+The driver ``working_with_ir_in_rust.py`` calls each example this way and
+prints the result.
+
+Accessing and Creating IR Nodes
+-------------------------------
+
+**Every IR node has two Rust types**: a handle such as |For|_, a
+reference-counted pointer that is cheap to clone, and the object it points
+to, such as |ForObj|_, which holds the fields. A handle dereferences to its
+object, so we read fields as ordinary struct fields.
+
+Let's read ``add_one`` from its parameters down to the store in its loop.
+The statements of a body are general ``Stmt`` handles, and |match_any!|_
+branches on their actual node type, as ``match`` does on an enum:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [inspect.begin]
+ :end-before: // [inspect.end]
+
+The output is:
+
+.. code-block:: text
+
+ param A
+ param B
+ loop over i up to n
+ store to B: A[i] + T.float32(1.0)
+
+Each arm names a handle type and binds the matching node to it; the arms
+are tried in order, and ``_`` takes everything else. Fields have the types
+we know from Python: ``params`` is an ``Array<Var>``, and the body of a
+loop is a ``SeqStmt`` whose ``seq`` holds its statements. |script|_ prints
+any node as TVMScript.
+
+.. note::
+
+ A function's ``body`` is always a ``SeqStmt``. ``get`` on an array returns
+ an error for an index out of range, and ``?`` passes it on.
+
+To create a node, we call the constructor of its handle type, such as
+|TensorStore::new|_. |ex|_ wraps an expression so that the usual Rust
+operators build IR; constructors accept the result directly. Let's build a
store
+that writes twice the value of the store in ``add_one``:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [create.begin]
+ :end-before: // [create.end]
+
+The output is:
+
+.. code-block:: python
+
+ n = T.dynamic("n", dtype="int32")
+ B = T.Var("B", T.Tensor((n,), T.float32))
+ i = T.dynamic("i", dtype="int32")
+ A = T.Var("A", T.Tensor((n,), T.float32))
+ B[i] = (A[i] + T.float32(1.0)) * T.float32(2.0)
+
+The new store reuses the destination and indices of the old one, so the
+printer declares them as free variables first. Constructing nodes creates
+new objects; ``add_one`` itself is not modified. Here |try_cast|_ downcasts
+to a single known type instead of branching.
+
+Structural Utilities
+--------------------
+
+The structural utilities are part of TVM-FFI, and the ``tvm_ffi`` crate,
+re-exported as ``tvm_tirx::tvm_ffi``, provides them in Rust:
+|structural_walk|_, |structural_map|_, |structural_visit|_, and
+|structural_mutate|_. They run on the same structural hooks as in Python,
+so they reach the same nodes and keep definitions and uses consistent in
+the same way. **What changes is the Rust form of each piece**:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 25 35 40
+
+ * - Aspect
+ - Python
+ - Rust
+ * - Nodes a callback receives
+ - The type paired with it, such as ``(ir.TensorStore, f)``
+ - The type of the callback's parameter
+ * - Walk callback result
+ - ``None``, ``WalkResult.SKIP``, or a ``VisitInterrupt``
+ - ``WalkResult``, or ``Result<WalkResult>`` to use ``?``
+ * - Traversal order
+ - ``order="pre"`` or the default post-order
+ - A required argument, ``WalkOrder::PreOrder`` or ``PostOrder``
+ * - Result of a map
+ - The new value
+ - An ``Any``, converted back with ``try_into``
+ * - Definition region kind
+ - Pass the callback through ``with_def_region_kind``
+ - A trailing ``DefRegionKind`` parameter
+ * - Errors
+ - Exceptions
+ - ``Result`` values
+ * - Structural equality
+ - ``structural_equal``
+ - The global function ``ffi.StructuralEqual``
+
+Structural Walk
+~~~~~~~~~~~~~~~
+
+As in Python, a walk calls our callback on each node of the type it asks
+for. Let's find the tensors that ``add_one`` writes:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [walk.begin]
+ :end-before: // [walk.end]
+
+The output is:
+
+.. code-block:: text
+
+ ['B']
+
+``on_store`` takes a ``TensorStore``, so the walk calls it only on
+stores. ``Strings`` is our alias for ``Array<tvm_ffi::String>``, which
+Python receives as a list of strings.
+
+|WalkResult|_\ ``::Advance`` continues into the node's children, ``Skip``
+does not descend into them, and ``Interrupt`` stops the whole walk.
+
+The parameter list of a callback decides what it receives:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 50 50
+
+ * - Callback
+ - Receives
+ * - ``|store: TensorStore|``
+ - Each write, as a handle.
+ * - ``|store: &TensorStoreObj|``
+ - Each write, as a borrowed object, without changing its reference
+ count.
+ * - ``|value: &StructuralView|``
+ - Every value the walk reaches.
+ * - ``|var: Var, kind: DefRegionKind|``
+ - Each variable, with its definition region kind.
+ * - ``(on_loop, on_store)``
+ - A tuple of callbacks, tried in order; only the first one whose type
+ matches a node runs. Tuples hold up to 12 callbacks and can be
+ nested.
+
+``WalkResult::interrupt_with`` stops the walk and returns a value, which
+lets a walk search for a node:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [stop.begin]
+ :end-before: // [stop.end]
+
+Python prints the ``dest.name`` of the store it receives. The output is:
+
+.. code-block:: text
+
+ B
+
+``structural_walk`` returns ``Ok(Some(interrupt))`` when a callback stops
+it, with the payload in ``interrupt.value``, and ``Ok(None)`` otherwise.
+
+Definitions and Uses
+~~~~~~~~~~~~~~~~~~~~
+
+A callback receives the definition region kind when it takes a
+|DefRegionKind|_ as its last parameter. This walk lists the definition
+sites of ``add_one``:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [definitions.begin]
+ :end-before: // [definitions.end]
+
+The output is:
+
+.. code-block:: text
+
+ A Pattern
+ n Pattern
+ B Pattern
+ n Pattern
+ i Simple
+
+The kinds are the ones we saw in Python, under Rust names:
+``DefRegionKind::None`` for a use site, ``Pattern`` for ``DEF_PATTERN``,
+and ``Simple`` for ``DEF_SIMPLE``. ``structural_map`` callbacks take the
+same trailing parameter.
+
+Structural Map
+~~~~~~~~~~~~~~
+
+A map callback returns the replacement for its node. Let's specialize
+``add_one`` for ``n = 128``, with ``n`` passed in from Python:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [specialize.begin]
+ :end-before: // [specialize.end]
+
+The output is:
+
+.. code-block:: python
+
+ from __future__ import annotations
+
+ # from tvm_tirx.script import tirx as T
+
+ @T.function
+ def add_one(A: T.Tensor((128,), T.float32), B: T.Tensor((128,), T.float32)):
+ for i in range(128):
+ B[i] = A[i] + T.float32(1.0)
+
+This is the same result as in Python. |make_const|_ builds the constant
+``128`` with the type of ``n``, and every other variable is returned as it
+is. ``structural_map`` takes ownership of the handle we pass and returns
+the new root as an ``Any``; Python still holds ``add_one``, which is
+unchanged.
+
+Structural Equality
+~~~~~~~~~~~~~~~~~~~
+
+The crate has no Rust function for structural equality yet, so we call the
+global function that Python's ``structural_equal`` uses,
+``ffi.StructuralEqual``, with its four arguments: the two values,
+``map_free_vars``, and ``skip_tensor_content``. Let's specialize
+``add_one`` twice and compare the results:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [equal.begin]
+ :end-before: // [equal.end]
+
+The output is:
+
+.. code-block:: text
+
+ [False, True]
+
+The two functions are different objects, so ``same_as`` is false, but they
+are structurally equal.
+
+Visitors and Mutators in Rust
+-----------------------------
+
+Rust has no separate layer of visitor and mutator classes. Stateful and
+typed traversals use the same four structural utilities, and the crate
+provides two conveniences to build them: |dispatch|_ turns the methods
+of a struct into typed callbacks, and |VisitCallbacks|_ and
+|MutateCallbacks|_ attach state to a tuple of callbacks.
+
+Typed Dispatch on a Struct
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The closures in a callback tuple cannot borrow the same state mutably at
+the same time, so callbacks that share state are written as methods
+instead. ``#[dispatch(walk)]`` on an ``impl`` block turns its ``walk_*``
+methods into callbacks: each method receives the nodes of its parameter
+type, and the methods are tried in source order. The struct holds the
+state. Let's record the loops and writes of ``add_one`` in the order the
+walk reaches them:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [dispatch_walk.begin]
+ :end-before: // [dispatch_walk.end]
+
+Called with ``pre_order`` true and then false, the output is:
+
+.. code-block:: text
+
+ ['loop i', 'write B']
+ ['write B', 'loop i']
+
+Pre-order reports the loop before the write inside it, and post-order the
+reverse. A method may also take a trailing ``DefRegionKind``, as a closure
+can. ``#[dispatch(map)]``, ``#[dispatch(visit)]``, and
+``#[dispatch(mutate)]`` work the same way for ``map_*``, ``visit_*``, and
+``mutate_*`` methods.
+
+Visit and Mutate
+~~~~~~~~~~~~~~~~
+
+A visit or mutate callback takes control of its node's children, as in
+Python. Let's record the loops around each write. With ``VisitCallbacks``,
+each callback receives the node and a ``VisitContext``, which holds the
+shared state:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [visit.begin]
+ :end-before: // [visit.end]
+
+The output is:
+
+.. code-block:: text
+
+ ['B inside [i]']
+
+``visit_for`` pushes the loop variable, lets ``visit_children`` visit the
+loop's children with their usual traversal, then pops the variable. It
+returns the result of ``visit_children``, so that an interrupt from a child
+reaches the caller. The context also provides ``visit`` for a selected
+child and ``def_region_kind`` for the current node.
+
+For the mutation we use the struct form instead; either form works for
+both visits and mutations. A ``#[dispatch(mutate)]`` method that takes a
+trailing ``&mut Mutator`` gets the mutation counterpart of
+``VisitContext``, with ``default_mutate`` for the children and
+``def_region_kind()``. Let's reverse the loop
+by replacing each use of ``i`` with ``n - 1 - i``, built with ``ex`` as
+before:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [mutate.begin]
+ :end-before: // [mutate.end]
+
+The output is:
+
+.. code-block:: python
+
+ from __future__ import annotations
+
+ # from tvm_tirx.script import tirx as T
+
+ @T.function
+ def add_one[n](A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ for i in range(n):
+ B[n - 1 - i] = A[n - 1 - i] + T.float32(1.0)
+
+``mutate_for`` records the replacement, then ``default_mutate`` rewrites
+the loop's children through the same struct, so ``mutate_var`` sees the
+replacement before any use of ``i``.
+
+.. note::
+
+ ``mutate_var`` replaces ``i`` only where ``def_region_kind()`` is
+ ``None``, so the loop's own ``i`` stays a variable. |ObjectIdentity|_
+ keys the map by object identity, as the Python version keys its
+ dictionary by variable.
+
+.. note::
+
+ TIRx also has traversals that track the facts valid at each node, such
+ as loop ranges and branch conditions. In Rust they are
+ |StructuralVisitorWithConstraintContext|_ and
+ |StructuralMutatorWithConstraintContext|_; ``constraints()`` returns the
+ current facts.
+
+With fields, typed callbacks, and the structural utilities, a Rust function
+works with the same IR that Python builds and prints, so an analysis or a
+transformation can move between the two languages one function at a time.
+
+Quick Reference
+---------------
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 30 30
+
+ * - Rust
+ - What it does
+ - Python equivalent
+ * - |match_any!|_
+ - Branches on the node type; the first matching arm runs
+ - ``isinstance`` checks
+ * - |try_cast|_, |as_node|_
+ - Downcasts to one type, as a ``Result`` handle or a borrowed
+ ``Option``
+ - ``isinstance(stmt, ir.For)``
+ * - |TensorStore::new|_, |ex|_\ ``(...)``, ``.expr()``
+ - Creates a node; builds an expression with operators
+ - ``ir.TensorStore(dest, indices, value)``, ``store.value * 2``
+ * - |structural_walk|_\ ``(&func, callbacks, WalkOrder::PreOrder)``
+ - Walks with typed callbacks that return ``WalkResult``
+ - ``tvm_ffi.structural_walk(func, callbacks, order="pre")``
+ * - |structural_map|_\ ``(func, callbacks, order)``
+ - Rebuilds with replacements and returns an ``Any``
+ - ``tvm_ffi.structural_map(func, callbacks)``
+ * - A trailing |DefRegionKind|_ parameter
+ - Receives the definition region kind
+ - ``with_def_region_kind=``
+ * - ``Function::get_global("ffi.StructuralEqual")``
+ - Compares by structure
+ - ``tvm_ffi.structural_equal``
+ * - |dispatch|_\ ``(walk)``, ``(map)``, ``(visit)``, ``(mutate)``
+ - Turns the methods of a struct into typed callbacks
+ - A list of ``(type, callback)`` pairs
+ * - |VisitCallbacks|_, |MutateCallbacks|_
+ - Attach state to a tuple of visit or mutate callbacks
+ - ``tvm_ffi.structural_visit``, ``tvm_ffi.structural_mutate``
+ * - |static_init_block!|_, |register_global_typed|_
+ - Registers Rust functions as global functions
+ - ``tvm_ffi.register_global_func``
+
+.. API pages of the tvm-tirx and tvm-ffi crates for the names above.
+
+.. |static_init_block!| replace:: ``static_init_block!``
+.. _static_init_block!:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/macro.static_init_block.html
+.. |For| replace:: ``For``
+.. _For:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/ir/stmt/struct.For.html
+.. |ForObj| replace:: ``ForObj``
+.. _ForObj:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/ir/stmt/struct.ForObj.html
+.. |script| replace:: ``script``
+.. _script:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/script/fn.script.html
+.. |try_cast| replace:: ``try_cast``
+.. _try_cast:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/object/trait.ObjectRefCast.html
+.. |structural_walk| replace:: ``structural_walk``
+.. _structural_walk:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_visit/fn.structural_walk.html
+.. |structural_map| replace:: ``structural_map``
+.. _structural_map:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_mutate/fn.structural_map.html
+.. |structural_visit| replace:: ``structural_visit``
+.. _structural_visit:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_visit/fn.structural_visit.html
+.. |structural_mutate| replace:: ``structural_mutate``
+.. _structural_mutate:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_mutate/fn.structural_mutate.html
+.. |WalkResult| replace:: ``WalkResult``
+.. _WalkResult:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_visit/enum.WalkResult.html
+.. |DefRegionKind| replace:: ``DefRegionKind``
+.. _DefRegionKind:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_visit/enum.DefRegionKind.html
+.. |make_const| replace:: ``make_const``
+.. _make_const:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/ir/prim/op/fn.make_const.html
+.. |dispatch| replace:: ``#[dispatch]``
+.. _dispatch: https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/attr.dispatch.html
+.. |VisitCallbacks| replace:: ``VisitCallbacks``
+.. _VisitCallbacks:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_visit/struct.VisitCallbacks.html
+.. |MutateCallbacks| replace:: ``MutateCallbacks``
+.. _MutateCallbacks:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_mutate/struct.MutateCallbacks.html
+.. |ex| replace:: ``ex``
+.. _ex: https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/ir/prim/op/fn.ex.html
+.. |ObjectIdentity| replace:: ``ObjectIdentity``
+.. _ObjectIdentity:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/object/struct.ObjectIdentity.html
+.. |StructuralVisitorWithConstraintContext| replace::
``StructuralVisitorWithConstraintContext``
+.. _StructuralVisitorWithConstraintContext:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/tirx/struct.StructuralVisitorWithConstraintContext.html
+.. |StructuralMutatorWithConstraintContext| replace::
``StructuralMutatorWithConstraintContext``
+.. _StructuralMutatorWithConstraintContext:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/tirx/struct.StructuralMutatorWithConstraintContext.html
+.. |match_any!| replace:: ``match_any!``
+.. _match_any!:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/macro.match_any.html
+.. |TensorStore::new| replace:: ``TensorStore::new``
+.. _TensorStore::new:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/ir/stmt/struct.TensorStore.html#method.new
+.. |as_node| replace:: ``as_node``
+.. _as_node:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/object/trait.ObjectRefCore.html#method.as_node
+.. |register_global_typed| replace:: ``Function::register_global_typed``
+.. _register_global_typed:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/function/struct.Function.html#method.register_global_typed
diff --git a/docs/reference/cpp/index.rst b/docs/reference/cpp/index.rst
index b023b3f96..0b6cdb8ec 100644
--- a/docs/reference/cpp/index.rst
+++ b/docs/reference/cpp/index.rst
@@ -23,6 +23,7 @@ can be a bit dense, so we recommend the following tips first:
- The :ref:`cpp-key-classes` lists the key classes that are most commonly used.
- See :ref:`cpp-header-organization` for how the modules are organized.
+- :ref:`cpp-ffi-structural` lists the TVM-FFI utilities for walking and
rewriting IR.
- You can go to the Full API Index at the bottom of this page to access the
full list of APIs.
- We usually group the APIs by files. You can look at the file hierarchy in
the
@@ -42,6 +43,9 @@ each folder builds on those above it.
* - Folder
- Description
+ * - ``tvm/ffi/``
+ - From TVM-FFI: objects, containers, functions, and the structural
utilities
+ (see :ref:`cpp-ffi-structural`).
* - ``tvm/support/``
- Compiler-independent common utilities.
* - ``tvm/runtime/``
@@ -270,6 +274,84 @@ Tensor Program
* - :cpp:class:`tvm::tirx::Function`
- TIRx tensor-program function.
+.. _cpp-ffi-structural:
+
+TVM-FFI Structural Utilities
+----------------------------
+
+TIRx builds on TVM-FFI and supports it as a first-class foundation. Every
+TIRx IR node is a TVM-FFI object that is shared across languages, so TIRx
+uses the native TVM-FFI utilities for walking and rewriting IR directly. We
+list these utilities here for completeness. See the `TVM-FFI documentation
+<https://tvm.apache.org/ffi/concepts/structural_eq_hash.html>`_ for more
+details.
+
+.. seealso:: The headers
``tvm/tirx/structural_visit_with_constraint_context.h``
+ and ``tvm/tirx/structural_mutate_with_constraint_context.h`` provide
+ variants of these utilities that also track constraint information, such
+ as loop ranges and branch conditions, at each node:
+ :cpp:func:`tvm::tirx::StructuralWalkWithConstraintContext`,
+ :cpp:func:`tvm::tirx::StructuralVisitWithConstraintContext`,
+ :cpp:func:`tvm::tirx::StructuralMapWithConstraintContext`, and
+ :cpp:func:`tvm::tirx::StructuralMutateWithConstraintContext`.
+
+Functions
+^^^^^^^^^
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Function
+ - Description
+ * - :cpp:func:`tvm::ffi::StructuralWalk`
+ - Walk every occurrence in pre- or post-order with typed callbacks.
+ * - :cpp:func:`tvm::ffi::StructuralMap`
+ - Rebuild a value with typed callbacks that return replacements.
+ * - :cpp:func:`tvm::ffi::StructuralVisit`
+ - Visit a value with callbacks that own the descent into children.
+ * - :cpp:func:`tvm::ffi::StructuralMutate`
+ - Mutate a value with callbacks that own the descent into children.
+ * - :cpp:func:`tvm::ffi::StructuralEqual::Equal`
+ - Compare two values by structure.
+ * - :cpp:func:`tvm::ffi::StructuralHash::Hash`
+ - Hash a value by structure, consistently with structural equality.
+
+Each function has an ``Expected`` form, such as
+:cpp:func:`tvm::ffi::StructuralWalkExpected`, that returns errors instead
+of throwing.
+
+Classes
+^^^^^^^
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Class
+ - Description
+ * - :cpp:class:`tvm::ffi::StructuralVisitorObj`
+ - Base of structural visitors, including the visitor behind
``StructuralWalk``.
+ * - :cpp:class:`tvm::ffi::StructuralMutatorObj`
+ - Base of structural mutators, including the mutator behind
``StructuralMap``.
+ * - :cpp:class:`tvm::ffi::StructuralEqual`
+ - Structural equality comparators.
+ * - :cpp:class:`tvm::ffi::StructuralHash`
+ - Structural hash.
+ * - :cpp:class:`tvm::ffi::StructuralKey`
+ - A key that compares and hashes its value by structure.
+ * - :cpp:class:`tvm::ffi::WalkResult`
+ - Per-node control signal of a walk: advance, skip, or interrupt.
+ * - :cpp:enum:`tvm::ffi::WalkOrder`
+ - Callback order of a walk or map: pre-order or post-order.
+ * - :cpp:class:`tvm::ffi::VisitInterrupt`
+ - The interrupt that stops a traversal, with an optional payload.
+ * - :cpp:struct:`tvm::ffi::Unchanged`
+ - Tag that keeps the original value in a map or mutation.
+ * - :cpp:class:`tvm::ffi::UnchangedOr`
+ - A replacement value or ``Unchanged``.
+ * - :cpp:enum:`tvm::ffi::InplaceMode`
+ - Whether a mutation may update a value in place.
.. _cpp-full-api-index:
diff --git a/examples/ir_guides/CMakeLists.txt
b/examples/ir_guides/CMakeLists.txt
new file mode 100644
index 000000000..a488b66e8
--- /dev/null
+++ b/examples/ir_guides/CMakeLists.txt
@@ -0,0 +1,66 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# scikit-build-core runs this to build the example libraries and install them
into tirx_ir_guide_examples:
+# the C++ library always, and the Rust library when cargo is available.
+cmake_minimum_required(VERSION 3.20)
+project(tirx_ir_guide_examples LANGUAGES CXX)
+
+# Locate the CMake packages with the TIRx and TVM-FFI config tools.
+find_package(
+ Python
+ COMPONENTS Interpreter
+ REQUIRED
+)
+execute_process(
+ COMMAND "${Python_EXECUTABLE}" -m tvm_tirx.config --cmakedir
+ OUTPUT_STRIP_TRAILING_WHITESPACE
+ OUTPUT_VARIABLE tvm_tirx_ROOT
+ COMMAND_ERROR_IS_FATAL ANY
+)
+execute_process(
+ COMMAND "${Python_EXECUTABLE}" -m tvm_ffi.config --cmakedir
+ OUTPUT_STRIP_TRAILING_WHITESPACE
+ OUTPUT_VARIABLE tvm_ffi_ROOT
+ COMMAND_ERROR_IS_FATAL ANY
+)
+find_package(tvm_ffi CONFIG REQUIRED)
+find_package(tvm_tirx CONFIG REQUIRED)
+
+# The C++ examples, linked against the TIRx compiler library, which contains
the IR.
+add_library(tirx_ir_guide_examples_cpp SHARED cpp/working_with_ir.cc)
+target_link_libraries(tirx_ir_guide_examples_cpp PRIVATE
tvm_tirx_compiler::shared tvm_ffi::shared)
+install(TARGETS tirx_ir_guide_examples_cpp LIBRARY DESTINATION
tirx_ir_guide_examples)
+
+# The Rust examples, built with cargo when it is available. rustup's cargo is
preferred over an
+# older one on PATH.
+find_program(CARGO cargo HINTS "$ENV{HOME}/.cargo/bin")
+if(NOT CARGO)
+ message(STATUS "cargo not found: skipping the Rust examples")
+ return()
+endif()
+set(cargo_target_dir "${CMAKE_BINARY_DIR}/cargo")
+set(rust_lib_name
+
"${CMAKE_SHARED_LIBRARY_PREFIX}tirx_ir_guide_examples_rust${CMAKE_SHARED_LIBRARY_SUFFIX}"
+)
+add_custom_target(
+ tirx_ir_guide_examples_rust ALL
+ COMMAND "${CMAKE_COMMAND}" -E env "CARGO_TARGET_DIR=${cargo_target_dir}"
"${CARGO}" build
+ --release --manifest-path
"${CMAKE_CURRENT_SOURCE_DIR}/rust/Cargo.toml"
+ USES_TERMINAL VERBATIM
+)
+install(FILES "${cargo_target_dir}/release/${rust_lib_name}" DESTINATION
tirx_ir_guide_examples)
diff --git a/examples/ir_guides/cpp/working_with_ir.cc
b/examples/ir_guides/cpp/working_with_ir.cc
new file mode 100644
index 000000000..2cd25810c
--- /dev/null
+++ b/examples/ir_guides/cpp/working_with_ir.cc
@@ -0,0 +1,224 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/*!
+ * \file working_with_ir.cc
+ * \brief C++ fragments that inspect, traverse, and rewrite add_one.
+ *
+ * Each function receives IR objects from Python and is registered as the
+ * global function tirx_ir_guide_examples.cpp.<name>; working_with_ir_in_cpp.py
+ * calls each function on add_one.
+ */
+// [includes.begin]
+#include <tvm/ffi/extra/structural_equal.h>
+#include <tvm/ffi/extra/structural_hash.h>
+#include <tvm/ffi/extra/structural_mutate.h>
+#include <tvm/ffi/extra/structural_visit.h>
+#include <tvm/ffi/reflection/registry.h>
+#include <tvm/tirx/function.h>
+#include <tvm/tirx/stmt_functor.h>
+// [includes.end]
+
+#include <sstream>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace {
+
+using namespace tvm;
+
+// [inspect.begin]
+ffi::String Inspect(const tirx::Function& func) {
+ std::ostringstream os;
+ for (const Var& param : func->params) {
+ os << "param " << param->name << "\n";
+ }
+ SeqStmt body = func->body;
+ if (const ForObj* loop = body[0].as<ForObj>()) {
+ os << "loop over " << loop->var.as<VarObj>()->name << " up to " <<
loop->end << "\n";
+ if (const TensorStoreObj* store = loop->body[0].as<TensorStoreObj>()) {
+ os << " store to " << store->dest.as<VarObj>()->name << ": " <<
store->value;
+ }
+ }
+ return os.str();
+}
+// [inspect.end]
+
+// [create.begin]
+TensorStore DoubleStore(const tirx::Function& func) {
+ For loop = func->body[0].as_or_throw<For>();
+ TensorStore store = loop->body[0].as_or_throw<TensorStore>();
+ PrimExpr doubled = store->value * 2;
+ return TensorStore(store->dest, store->indices, doubled);
+}
+// [create.end]
+
+// [walk.begin]
+ffi::Array<ffi::String> TensorsWritten(const tirx::Function& func) {
+ ffi::Array<ffi::String> writes;
+ ffi::StructuralWalk<ffi::WalkOrder::kPostOrder>(
+ func, [&](const TensorStore& store) -> ffi::Expected<ffi::WalkResult> {
+ writes.push_back(store->dest.as<VarObj>()->name);
+ return ffi::WalkResult::Advance();
+ });
+ return writes;
+}
+// [walk.end]
+
+// [dispatch.begin]
+ffi::Array<ffi::String> TraceStatements(const tirx::Function& func) {
+ ffi::Array<ffi::String> trace;
+ ffi::StructuralWalk<ffi::WalkOrder::kPreOrder>(
+ func,
+ [&](const For& loop) -> ffi::Expected<ffi::WalkResult> {
+ trace.push_back("loop " + loop->var.as<VarObj>()->name);
+ return ffi::WalkResult::Advance();
+ },
+ [&](const TensorStore& store) -> ffi::Expected<ffi::WalkResult> {
+ trace.push_back("store " + store->dest.as<VarObj>()->name);
+ return ffi::WalkResult::Advance();
+ });
+ return trace;
+}
+// [dispatch.end]
+
+// [stop.begin]
+ffi::Optional<TensorStore> FindWrite(const tirx::Function& func) {
+ ffi::Optional<ffi::VisitInterrupt> found =
ffi::StructuralWalk<ffi::WalkOrder::kPreOrder>(
+ func, [](const TensorStore& store) -> ffi::Expected<ffi::WalkResult> {
+ return ffi::WalkResult::Interrupt(ffi::VisitInterrupt(store));
+ });
+ if (!found.has_value()) return std::nullopt;
+ return found.value()->value.cast<TensorStore>();
+}
+// [stop.end]
+
+// [definitions.begin]
+ffi::Array<ffi::String> Definitions(const tirx::Function& func) {
+ ffi::Array<ffi::String> sites;
+ ffi::StructuralWalk<ffi::WalkOrder::kPreOrder>(
+ func, [&](const Var& var, TVMFFIDefRegionKind kind) ->
ffi::Expected<ffi::WalkResult> {
+ if (kind == kTVMFFIDefRegionKindSimple) {
+ sites.push_back(var->name + " simple");
+ } else if (kind == kTVMFFIDefRegionKindPattern) {
+ sites.push_back(var->name + " pattern");
+ }
+ return ffi::WalkResult::Advance();
+ });
+ return sites;
+}
+// [definitions.end]
+
+// [specialize.begin]
+tirx::Function Specialize(const tirx::Function& func, const Var& n) {
+ ffi::Any result =
+ ffi::StructuralMap<ffi::WalkOrder::kPreOrder>(func, [&](const Var& var)
-> ffi::Any {
+ if (var.same_as(n)) {
+ return IntImm(var->ty.as_or_throw<PrimType>(), 128);
+ }
+ return ffi::Unchanged();
+ });
+ return result.cast<tirx::Function>();
+}
+// [specialize.end]
+
+// [equal.begin]
+ffi::Array<bool> Compare(const tirx::Function& first, const tirx::Function&
second) {
+ return {
+ first.same_as(second),
+ ffi::StructuralEqual::Equal(first, second),
+ ffi::StructuralHash::Hash(first) == ffi::StructuralHash::Hash(second),
+ };
+}
+// [equal.end]
+
+// [visit.begin]
+class LoopNestVisitor : public tirx::StmtExprVisitor {
+ public:
+ using tirx::StmtExprVisitor::Visit_;
+
+ ffi::Optional<ffi::VisitInterrupt> Visit_(const ForObj* loop) override {
+ loops_.push_back(loop->var.as<VarObj>()->name);
+ ffi::Optional<ffi::VisitInterrupt> result =
tirx::StmtExprVisitor::Visit_(loop);
+ loops_.pop_back();
+ return result;
+ }
+
+ ffi::Optional<ffi::VisitInterrupt> Visit_(const TensorStoreObj* store)
override {
+ std::string entry = std::string(store->dest.as<VarObj>()->name) + " in";
+ for (const std::string& loop : loops_) entry += " " + loop;
+ writes.push_back(entry);
+ return tirx::StmtExprVisitor::Visit_(store);
+ }
+
+ ffi::Array<ffi::String> writes;
+
+ private:
+ std::vector<std::string> loops_;
+};
+
+ffi::Array<ffi::String> LoopsAroundWrites(const tirx::Function& func) {
+ auto visitor = ffi::make_object<LoopNestVisitor>();
+ visitor->Visit(func);
+ return visitor->writes;
+}
+// [visit.end]
+
+// [mutate.begin]
+class ReverseLoopMutator : public tirx::StmtExprMutator {
+ public:
+ using tirx::StmtExprMutator::Mutate_;
+
+ UnchangedOr<Stmt> Mutate_(const ForObj* loop, InplaceMode mode) override {
+ reversed_.emplace(loop->var.as<VarObj>(), loop->end - 1 - loop->var);
+ return tirx::StmtExprMutator::Mutate_(loop, mode);
+ }
+
+ UnchangedOr<Expr> Mutate_(const VarObj* var, InplaceMode mode) override {
+ auto it = reversed_.find(var);
+ if (it != reversed_.end()) return it->second;
+ return tirx::StmtExprMutator::Mutate_(var, mode);
+ }
+
+ private:
+ std::unordered_map<const VarObj*, PrimExpr> reversed_;
+};
+
+tirx::Function ReverseLoop(const tirx::Function& func) {
+ auto mutator = ffi::make_object<ReverseLoopMutator>();
+ return
mutator->Mutate(func).ValueOrUnchanged(func).as_or_throw<tirx::Function>();
+}
+// [mutate.end]
+
+TVM_FFI_STATIC_INIT_BLOCK() {
+ namespace refl = tvm::ffi::reflection;
+ refl::GlobalDef()
+ .def("tirx_ir_guide_examples.cpp.inspect", Inspect)
+ .def("tirx_ir_guide_examples.cpp.double_store", DoubleStore)
+ .def("tirx_ir_guide_examples.cpp.tensors_written", TensorsWritten)
+ .def("tirx_ir_guide_examples.cpp.trace_statements", TraceStatements)
+ .def("tirx_ir_guide_examples.cpp.find_write", FindWrite)
+ .def("tirx_ir_guide_examples.cpp.definitions", Definitions)
+ .def("tirx_ir_guide_examples.cpp.specialize", Specialize)
+ .def("tirx_ir_guide_examples.cpp.compare", Compare)
+ .def("tirx_ir_guide_examples.cpp.loops_around_writes", LoopsAroundWrites)
+ .def("tirx_ir_guide_examples.cpp.reverse_loop", ReverseLoop);
+}
+
+} // namespace
diff --git a/examples/ir_guides/pyproject.toml
b/examples/ir_guides/pyproject.toml
new file mode 100644
index 000000000..214fc1d92
--- /dev/null
+++ b/examples/ir_guides/pyproject.toml
@@ -0,0 +1,34 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[project]
+name = "tirx-ir-guide-examples"
+version = "0.1.0"
+description = "The C++ and Rust examples of the IR Guides: functions that read
and rewrite TIRx IR"
+requires-python = ">=3.10"
+dependencies = ["apache-tvm-tirx"]
+
+[build-system]
+# apache-tvm-tirx provides the CMake packages for the C++ library, and
tvm-tirx-config and
+# tvm-ffi-config, which the cargo build of the Rust library runs.
+requires = ["scikit-build-core>=0.11", "apache-tvm-tirx"]
+build-backend = "scikit_build_core.build"
+
+[tool.scikit-build]
+wheel.py-api = "py3"
+wheel.packages = ["python/tirx_ir_guide_examples"]
+cmake.build-type = "Release"
diff --git a/examples/ir_guides/python/tirx_ir_guide_examples/__init__.py
b/examples/ir_guides/python/tirx_ir_guide_examples/__init__.py
new file mode 100644
index 000000000..7257cd054
--- /dev/null
+++ b/examples/ir_guides/python/tirx_ir_guide_examples/__init__.py
@@ -0,0 +1,21 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""The C++ and Rust examples of the IR Guides.
+
+Import tirx_ir_guide_examples.cpp or tirx_ir_guide_examples.rust to load a
library and call
+its functions.
+"""
diff --git a/examples/ir_guides/python/tirx_ir_guide_examples/cpp.py
b/examples/ir_guides/python/tirx_ir_guide_examples/cpp.py
new file mode 100644
index 000000000..f9d4ee564
--- /dev/null
+++ b/examples/ir_guides/python/tirx_ir_guide_examples/cpp.py
@@ -0,0 +1,30 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""The functions of the C++ library, registered as
tirx_ir_guide_examples.cpp.<name>."""
+
+from pathlib import Path
+
+import tvm_ffi
+from tvm_ffi.libinfo import load_lib_module
+
+import tvm_tirx # noqa: F401 # loads the TIRx compiler library that the C++
library links
+
+# The library registers its functions when it loads, so load it before
collecting them.
+_LIB = load_lib_module(
+ "tirx-ir-guide-examples", "tirx_ir_guide_examples_cpp",
extra_lib_paths=[Path(__file__).parent]
+)
+tvm_ffi.init_ffi_api("tirx_ir_guide_examples.cpp", __name__)
diff --git a/examples/ir_guides/python/tirx_ir_guide_examples/rust.py
b/examples/ir_guides/python/tirx_ir_guide_examples/rust.py
new file mode 100644
index 000000000..2cd37e77c
--- /dev/null
+++ b/examples/ir_guides/python/tirx_ir_guide_examples/rust.py
@@ -0,0 +1,38 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""The functions of the Rust library, registered as
tirx_ir_guide_examples.rust.<name>."""
+
+from pathlib import Path
+
+import tvm_ffi
+from tvm_ffi.libinfo import load_lib_module
+
+import tvm_tirx # noqa: F401 # loads the TIRx compiler library that the Rust
library links
+
+# The library registers its functions when it loads, so load it before
collecting them.
+try:
+ _LIB = load_lib_module(
+ "tirx-ir-guide-examples",
+ "tirx_ir_guide_examples_rust",
+ extra_lib_paths=[Path(__file__).parent],
+ )
+except RuntimeError as err:
+ raise ImportError(
+ "The Rust library of tirx_ir_guide_examples was not built: install
cargo and reinstall the "
+ "package with pip install --no-build-isolation -e examples/ir_guides"
+ ) from err
+tvm_ffi.init_ffi_api("tirx_ir_guide_examples.rust", __name__)
diff --git a/examples/ir_guides/rust/.gitignore
b/examples/ir_guides/rust/.gitignore
new file mode 100644
index 000000000..7137982ad
--- /dev/null
+++ b/examples/ir_guides/rust/.gitignore
@@ -0,0 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Cargo build output
+/target/
+/Cargo.lock
diff --git a/examples/ir_guides/rust/Cargo.toml
b/examples/ir_guides/rust/Cargo.toml
new file mode 100644
index 000000000..12fae240a
--- /dev/null
+++ b/examples/ir_guides/rust/Cargo.toml
@@ -0,0 +1,31 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[package]
+name = "tirx-ir-guide-examples"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+# The shared library that tirx_ir_guide_examples.rust loads.
+name = "tirx_ir_guide_examples_rust"
+crate-type = ["cdylib"]
+
+[dependencies]
+# Use the bindings from this checkout to match the current IR node fields.
+tvm-tirx = { path = "../../../rust" }
diff --git a/examples/ir_guides/rust/rustfmt.toml
b/examples/ir_guides/rust/rustfmt.toml
new file mode 100644
index 000000000..f5a5255a8
--- /dev/null
+++ b/examples/ir_guides/rust/rustfmt.toml
@@ -0,0 +1,19 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Keep calls and method chains on one line up to the 100-column limit.
+use_small_heuristics = "Max"
diff --git a/examples/ir_guides/rust/src/lib.rs
b/examples/ir_guides/rust/src/lib.rs
new file mode 100644
index 000000000..29fd682ab
--- /dev/null
+++ b/examples/ir_guides/rust/src/lib.rs
@@ -0,0 +1,286 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+//! Functions that read, traverse, and rewrite `add_one` from Rust.
+//! See docs/ir_guides/working_with_ir_in_rust.rst. Each function is
registered as the global
+//! function `tirx_ir_guide_examples.rust.<name>`; working_with_ir_in_rust.py
calls each on `add_one`.
+
+use std::collections::HashMap;
+
+use tvm_tirx::ir::prim::{ex, make_const};
+use tvm_tirx::ir::{
+ Expr, For, ForObj, PrimType, Stmt, TensorStore, TensorStoreObj, Var,
UNKNOWN_LOC,
+};
+use tvm_tirx::script::script;
+use tvm_tirx::tirx::Function;
+use tvm_tirx::tvm_ffi::{
+ self, dispatch, match_any, Any, Array, DefRegionKind, Mutator,
ObjectIdentity, ObjectRefCast,
+ ObjectRefCore, Result, VisitCallbacks, VisitContext, VisitInterrupt,
WalkOrder, WalkResult,
+};
+
+/// A Python list of strings.
+type Strings = Array<tvm_ffi::String>;
+
+// [inspect.begin]
+fn inspect(func: Function) -> Result<tvm_ffi::String> {
+ let mut lines = Vec::new();
+ for param in func.params.iter() {
+ lines.push(format!("param {}", param.name.as_str()));
+ }
+ let body = &func.body;
+ for stmt in body.seq.iter() {
+ describe(stmt, "", &mut lines)?;
+ }
+ Ok(lines.join("\n").into())
+}
+
+fn describe(stmt: Stmt, indent: &str, lines: &mut Vec<String>) -> Result<()> {
+ match_any! {
+ stmt {
+ For(loop_) => {
+ let (var, end) = (loop_.var.name.as_str(),
script(&loop_.end)?);
+ lines.push(format!("{indent}loop over {var} up to {}",
end.as_str()));
+ for child in loop_.body.seq.iter() {
+ describe(child, &format!("{indent} "), lines)?;
+ }
+ },
+ TensorStore(store) => {
+ let (dest, value) = (script(&store.dest)?,
script(&store.value)?);
+ lines.push(format!("{indent}store to {}: {}", dest.as_str(),
value.as_str()));
+ },
+ _ => lines.push(format!("{indent}other statement")),
+ }
+ }
+ Ok(())
+}
+// [inspect.end]
+
+// [create.begin]
+fn double_store(func: Function) -> Result<TensorStore> {
+ let body = &func.body;
+ let loop_: For = body.seq.get(0)?.try_cast()?;
+ let store: TensorStore = loop_.body.seq.get(0)?.try_cast()?;
+ let doubled = ex(&store.value) * 2;
+ TensorStore::new(&store.dest, store.indices.iter(), doubled, UNKNOWN_LOC)
+}
+// [create.end]
+
+// [walk.begin]
+fn written_tensors(func: Function) -> Result<Strings> {
+ let mut writes = Vec::new();
+ let on_store = |store: TensorStore| -> Result<WalkResult> {
+ let dest: Var = store.dest.clone().try_cast()?;
+ writes.push(dest.name.clone());
+ Ok(WalkResult::Advance)
+ };
+ tvm_ffi::structural_walk(&func, on_store, WalkOrder::PostOrder)?;
+ Ok(writes.into_iter().collect())
+}
+// [walk.end]
+
+// [stop.begin]
+fn first_write(func: Function) -> Result<Option<TensorStore>> {
+ let find_write = |store: TensorStore| WalkResult::interrupt_with(store);
+ let found = tvm_ffi::structural_walk(&func, find_write,
WalkOrder::PostOrder)?;
+ match found {
+ Some(interrupt) => Ok(Some(interrupt.value.try_into()?)),
+ None => Ok(None),
+ }
+}
+// [stop.end]
+
+// [specialize.begin]
+fn specialize(func: Function, n: Var, value: i64) -> Result<Function> {
+ let specialize_var = |var: Var| -> Result<Expr> {
+ if var.same_as(&n) {
+ let ty: PrimType = var.ty.clone().try_cast()?;
+ return make_const(ty, value);
+ }
+ Ok(var.into())
+ };
+ tvm_ffi::structural_map(func, specialize_var,
WalkOrder::PostOrder)?.try_into()
+}
+// [specialize.end]
+
+// [definitions.begin]
+fn definitions(func: Function) -> Result<Strings> {
+ let mut sites = Vec::new();
+ let show_definition = |var: Var, kind: DefRegionKind| {
+ if kind != DefRegionKind::None {
+ sites.push(format!("{} {:?}", var.name.as_str(), kind));
+ }
+ WalkResult::Advance
+ };
+ tvm_ffi::structural_walk(&func, show_definition, WalkOrder::PreOrder)?;
+ Ok(sites.iter().map(tvm_ffi::String::from).collect())
+}
+// [definitions.end]
+
+// [equal.begin]
+fn compare_specialized(func: Function, n: Var) -> Result<Array<bool>> {
+ let first = specialize(func.clone(), n.clone(), 128)?;
+ let second = specialize(func, n, 128)?;
+ let (map_free_vars, skip_tensor_content) = (false, false);
+ let equal: bool = tvm_ffi::Function::get_global("ffi.StructuralEqual")?
+ .call_tuple((&first, &second, map_free_vars, skip_tensor_content))?
+ .try_into()?;
+ Ok([first.same_as(&second), equal].into_iter().collect())
+}
+// [equal.end]
+
+// [dispatch_walk.begin]
+#[derive(Default)]
+struct StatementTrace {
+ events: Vec<String>,
+}
+
+#[dispatch(walk)]
+impl StatementTrace {
+ fn walk_for(&mut self, loop_: &ForObj) -> WalkResult {
+ self.events.push(format!("loop {}", loop_.var.name.as_str()));
+ WalkResult::Advance
+ }
+
+ fn walk_store(&mut self, store: &TensorStoreObj) -> Result<WalkResult> {
+ self.events.push(format!("write {}", script(&store.dest)?.as_str()));
+ Ok(WalkResult::Advance)
+ }
+}
+
+fn trace_statements(func: Function, pre_order: bool) -> Result<Strings> {
+ let order = if pre_order { WalkOrder::PreOrder } else {
WalkOrder::PostOrder };
+ let mut trace = StatementTrace::default();
+ tvm_ffi::structural_walk(&func, &mut trace, order)?;
+ Ok(trace.events.iter().map(tvm_ffi::String::from).collect())
+}
+// [dispatch_walk.end]
+
+// [visit.begin]
+#[derive(Default)]
+struct LoopNest {
+ loops: Vec<String>,
+ writes: Vec<String>,
+}
+
+fn visit_for(
+ loop_: &ForObj,
+ visitor: &mut VisitContext<'_, LoopNest>,
+) -> Result<Option<VisitInterrupt>> {
+ visitor.state_mut().loops.push(loop_.var.name.as_str().to_owned());
+ let result = visitor.visit_children()?;
+ visitor.state_mut().loops.pop();
+ Ok(result)
+}
+
+fn visit_store(store: &TensorStoreObj, visitor: &mut VisitContext<'_,
LoopNest>) -> Result<()> {
+ let loops = visitor.state().loops.join(", ");
+ let write = format!("{} inside [{}]", script(&store.dest)?.as_str(),
loops);
+ visitor.state_mut().writes.push(write);
+ Ok(())
+}
+
+fn loops_around_writes(func: Function) -> Result<Strings> {
+ let mut visitor = VisitCallbacks::new(LoopNest::default(), (visit_for,
visit_store));
+ tvm_ffi::structural_visit(&func, &mut visitor)?;
+ let state = visitor.into_state();
+ assert!(state.loops.is_empty());
+ Ok(state.writes.iter().map(tvm_ffi::String::from).collect())
+}
+// [visit.end]
+
+// [mutate.begin]
+#[derive(Default)]
+struct ReverseLoops {
+ reversed_index: HashMap<ObjectIdentity, Expr>,
+}
+
+#[dispatch(mutate)]
+impl ReverseLoops {
+ fn mutate_for(&mut self, loop_: For, mutator: &mut Mutator) -> Result<Any>
{
+ let index = (ex(&loop_.end) - 1 - &loop_.var).expr()?;
+ self.reversed_index.insert(ObjectIdentity::of(&loop_.var), index);
+ mutator.default_mutate(self, &loop_)
+ }
+
+ fn mutate_var(&mut self, var: Var, mutator: &mut Mutator) -> Expr {
+ let is_use = mutator.def_region_kind() == DefRegionKind::None;
+ match self.reversed_index.get(&ObjectIdentity::of(&var)) {
+ Some(index) if is_use => index.clone(),
+ _ => var.into(),
+ }
+ }
+}
+
+fn reverse_loops(func: Function) -> Result<Function> {
+ tvm_ffi::structural_mutate(func, ReverseLoops::default())?.try_into()
+}
+// [mutate.end]
+
+tvm_ffi::static_init_block! {
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.inspect",
+ inspect,
+ "Read the fields of a function.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.double_store",
+ double_store,
+ "Build a store that writes twice the value.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.written_tensors",
+ written_tensors,
+ "List the tensors a function writes.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.first_write",
+ first_write,
+ "Find the first write.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.specialize",
+ specialize,
+ "Replace a variable with a constant.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.definitions",
+ definitions,
+ "List the definition sites.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.compare_specialized",
+ compare_specialized,
+ "Compare two specializations.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.trace_statements",
+ trace_statements,
+ "Trace loops and writes.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.loops_around_writes",
+ loops_around_writes,
+ "List the loops around each write.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.reverse_loops",
+ reverse_loops,
+ "Reverse every loop.",
+ )?;
+}
diff --git a/examples/ir_guides/working_with_ir_in_cpp.py
b/examples/ir_guides/working_with_ir_in_cpp.py
new file mode 100644
index 000000000..9673f51fc
--- /dev/null
+++ b/examples/ir_guides/working_with_ir_in_cpp.py
@@ -0,0 +1,104 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Call the C++ functions of tirx_ir_guide_examples on add_one.
+
+Install the package first, building against the installed TIRx:
+
+ pip install scikit-build-core
+ pip install --no-build-isolation -e examples/ir_guides
+"""
+
+import tirx_ir_guide_examples.cpp
+
+from tvm_tirx import ir
+from tvm_tirx.script import tirx as T
+
+n = T.dynamic("n")
+
+
[email protected]
+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
+
+
+summary = tirx_ir_guide_examples.cpp.inspect(add_one)
+print(summary)
+assert summary.splitlines() == [
+ "param A",
+ "param B",
+ "loop over i up to n",
+ " store to B: A[i] + T.float32(1.0)",
+]
+
+doubled = tirx_ir_guide_examples.cpp.double_store(add_one)
+print(doubled.script())
+assert isinstance(doubled, ir.TensorStore)
+assert not doubled.same_as(add_one.body.seq[0].body.seq[0]) # add_one is
unchanged
+
+writes = tirx_ir_guide_examples.cpp.tensors_written(add_one)
+print(list(writes))
+assert list(writes) == ["B"]
+
+trace = tirx_ir_guide_examples.cpp.trace_statements(add_one)
+print(list(trace))
+assert list(trace) == ["loop i", "store B"]
+
+found = tirx_ir_guide_examples.cpp.find_write(add_one)
+print(found.dest.name)
+assert isinstance(found, ir.TensorStore)
+
+sites = tirx_ir_guide_examples.cpp.definitions(add_one)
+print("\n".join(sites))
+assert list(sites) == ["A pattern", "n pattern", "B pattern", "n pattern", "i
simple"]
+
+add_one_128 = tirx_ir_guide_examples.cpp.specialize(add_one, n)
+print(add_one_128.script())
+assert "for i in range(128):" in add_one_128.script()
+assert "for i in range(n):" in add_one.script() # the input is unchanged
+# The mapper creates new A and B with the specialized type and remaps their
uses.
+new_A, new_B = add_one_128.params
+new_store = add_one_128.body.seq[0].body.seq[0]
+assert not new_A.same_as(add_one.params[0])
+assert new_store.dest.same_as(new_B)
+assert new_store.value.a.source.same_as(new_A)
+
+
+def make_add(value):
+ n = T.dynamic("n")
+
+ @T.function
+ def add(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ for i in range(n):
+ B[i] = A[i] + value
+
+ return add
+
+
+comparison = tirx_ir_guide_examples.cpp.compare(make_add(1), make_add(1))
+print(list(comparison))
+assert list(comparison) == [False, True, True]
+assert list(tirx_ir_guide_examples.cpp.compare(make_add(1), make_add(2))) ==
[False, False, False]
+
+loops = tirx_ir_guide_examples.cpp.loops_around_writes(add_one)
+print(list(loops))
+assert list(loops) == ["B in i"]
+
+add_one_reversed = tirx_ir_guide_examples.cpp.reverse_loop(add_one)
+print(add_one_reversed.script())
+assert "B[n - 1 - i] = A[n - 1 - i] + T.float32(1.0)" in
add_one_reversed.script()
+assert add_one_reversed.body.seq[0].var.same_as(add_one.body.seq[0].var)
diff --git a/examples/ir_guides/working_with_ir_in_rust.py
b/examples/ir_guides/working_with_ir_in_rust.py
new file mode 100644
index 000000000..8c4d32982
--- /dev/null
+++ b/examples/ir_guides/working_with_ir_in_rust.py
@@ -0,0 +1,94 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Call the Rust functions of tirx_ir_guide_examples on add_one.
+
+Install the package with cargo available first, building against the installed
TIRx:
+
+ pip install scikit-build-core
+ pip install --no-build-isolation -e examples/ir_guides
+"""
+
+import tirx_ir_guide_examples.rust
+
+from tvm_tirx import ir
+from tvm_tirx.script import tirx as T
+
+n = T.dynamic("n")
+
+
[email protected]
+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
+
+
+summary = tirx_ir_guide_examples.rust.inspect(add_one)
+print(summary)
+assert summary.splitlines() == [
+ "param A",
+ "param B",
+ "loop over i up to n",
+ " store to B: A[i] + T.float32(1.0)",
+]
+
+doubled = tirx_ir_guide_examples.rust.double_store(add_one)
+print(doubled.script())
+assert isinstance(doubled, ir.TensorStore)
+assert not doubled.same_as(add_one.body.seq[0].body.seq[0]) # add_one is
unchanged
+
+print(list(tirx_ir_guide_examples.rust.written_tensors(add_one)))
+assert list(tirx_ir_guide_examples.rust.written_tensors(add_one)) == ["B"]
+
+found = tirx_ir_guide_examples.rust.first_write(add_one)
+print(found.dest.name)
+assert isinstance(found, ir.TensorStore)
+
+add_one_128 = tirx_ir_guide_examples.rust.specialize(add_one, n, 128)
+print(add_one_128.script())
+assert "for i in range(128):" in add_one_128.script()
+assert "for i in range(n):" in add_one.script() # the input is unchanged
+# Mapping n changes the type of A and B, so the mapper creates new variables
and remaps their uses.
+new_A, new_B = add_one_128.params
+new_store = add_one_128.body.seq[0].body.seq[0]
+assert not new_A.same_as(add_one.params[0])
+assert new_store.dest.same_as(new_B)
+assert new_store.value.a.source.same_as(new_A)
+
+print("\n".join(tirx_ir_guide_examples.rust.definitions(add_one)))
+assert list(tirx_ir_guide_examples.rust.definitions(add_one)) == [
+ "A Pattern",
+ "n Pattern",
+ "B Pattern",
+ "n Pattern",
+ "i Simple",
+]
+
+print(list(tirx_ir_guide_examples.rust.compare_specialized(add_one, n)))
+assert list(tirx_ir_guide_examples.rust.compare_specialized(add_one, n)) ==
[False, True]
+
+print(list(tirx_ir_guide_examples.rust.trace_statements(add_one, True)))
+print(list(tirx_ir_guide_examples.rust.trace_statements(add_one, False)))
+assert list(tirx_ir_guide_examples.rust.trace_statements(add_one, True)) ==
["loop i", "write B"]
+assert list(tirx_ir_guide_examples.rust.trace_statements(add_one, False)) ==
["write B", "loop i"]
+
+print(list(tirx_ir_guide_examples.rust.loops_around_writes(add_one)))
+assert list(tirx_ir_guide_examples.rust.loops_around_writes(add_one)) == ["B
inside [i]"]
+
+add_one_reversed = tirx_ir_guide_examples.rust.reverse_loops(add_one)
+print(add_one_reversed.script())
+assert "B[n - 1 - i] = A[n - 1 - i] + T.float32(1.0)" in
add_one_reversed.script()
+assert add_one_reversed.body.seq[0].var.same_as(add_one.body.seq[0].var)