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)

Reply via email to