This is an automated email from the ASF dual-hosted git repository.

Seven-Streams 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 436f2a720 [DOCS][RUST] Add a tvm-tirx extension tutorial (#122)
436f2a720 is described below

commit 436f2a720d8f19a66a92a47b111888416d70ef53
Author: Linzhang Li <[email protected]>
AuthorDate: Thu Oct 29 17:48:46 2026 -0400

    [DOCS][RUST] Add a tvm-tirx extension tutorial (#122)
    
    ## Summary
    
    This PR adds a tutorial on extending TIRx from Rust, in a new
    documentation section, "Extending
    TIRx: everything is a plugin". One running example, complex numbers,
    covers the whole path:
    
    - **Rust.** A Rust library defines a complex IR type, four operators,
    and a pass that lowers them to
      scalar arithmetic.
    - **Python.** Python loads the library and writes a kernel with the new
    type in TVMScript. It
    compiles the kernel with LLVM through a pipeline that runs the pass, and
    checks the result
      against NumPy.
    
    This PR is based on #121, which lets an `rs_class` type be constructed
    without a `Placeholder`.
    Until #121 merges, its commit also shows in this PR's diff.
    
    ### Chapters
    
    - **Getting Started with Rust Extensions**
    (`docs/advanced/extending_ir_in_rust.rst`)
    - **Why Rust.** The C++ core stays stable, and an extension iterates on
    its own. The extension
    is a separate Rust library built on the `tvm-tirx` crate. It defines
    types, operators and
    passes on the same IR objects as C++ and Python, and loads without
    rebuilding TIRx.
    - **Setting up the project.** A `cdylib` crate that depends on
    `tvm-tirx` by path, built with
        `uv run --no-sync cargo build`.
    - **The case study.** The kernel that multiplies two arrays of complex
    numbers.
    - **Defining Types, Operators, and Passes**
    (`docs/advanced/defining_ir_extensions.rst`)
    - **The type.** `ComplexType`, an `rs_class` type registered with
    `register_type`.
    - **The operators.** `complex`, `cmul`, `real` and `imag`, defined as
    `OpDef` chains with Rust
        type inference and validators.
      - **The pass.** `LowerComplex`, built from three parts:
    - a `#[dispatch(map)]` rewriter that `structural_map` runs over the
    function;
        - a second walk that rejects any complex value left over;
        - `FunctionPass::new`, which wraps the function as a pass.
    - **Using and Compiling the Extension**
    (`docs/advanced/using_ir_extensions.rst`)
    - **Loading.** The script loads the library and declares the `my_ext`
    module for the builders.
    - **Compiling.** The script registers a pipeline that runs the pass
    before the default
    lowering. Compiling with the default pipeline instead fails in LLVM code
    generation.
      - **Checking the result.** The script compares the outputs with NumPy.
---
 docs/advanced/defining_ir_extensions.rst     | 230 ++++++++++++++++++++
 docs/advanced/extending_ir_in_rust.rst       | 123 +++++++++++
 docs/advanced/using_ir_extensions.rst        | 112 ++++++++++
 docs/index.rst                               |   9 +
 docs/reference/rust/index.rst                |  16 +-
 examples/extension/.gitignore                |  20 ++
 examples/extension/CMakeLists.txt            |  30 +++
 examples/extension/Cargo.toml                |  33 +++
 examples/extension/README.md                 |  43 ++++
 examples/extension/pyproject.toml            |  33 +++
 examples/extension/python/my_ext/__init__.py |  46 ++++
 examples/extension/run_example.py            |  65 ++++++
 examples/extension/rustfmt.toml              |  21 ++
 examples/extension/src/lib.rs                | 302 +++++++++++++++++++++++++++
 tests/python/ir/test_op_rust.py              | 186 +++++++++++++++--
 15 files changed, 1250 insertions(+), 19 deletions(-)

diff --git a/docs/advanced/defining_ir_extensions.rst 
b/docs/advanced/defining_ir_extensions.rst
new file mode 100644
index 000000000..1ba916634
--- /dev/null
+++ b/docs/advanced/defining_ir_extensions.rst
@@ -0,0 +1,230 @@
+..  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.
+
+Defining Types, Operators, and Passes
+=====================================
+
+In this chapter, we walk through the Rust library of the package set up in
+:doc:`extending_ir_in_rust`: a complex type, four operators, and a pass that
+lowers them to scalar arithmetic. The excerpts come from
+:download:`src/lib.rs <../../examples/extension/src/lib.rs>`, which also 
contains
+the validation and traversal helpers they use.
+
+Defining a Type
+---------------
+
+``ComplexType`` has one field, ``elem``, the scalar type shared by the real and
+imaginary parts:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+   :language: rust
+   :start-after: // begin type
+   :end-before: // end type
+
+As in C++, the type is defined in two parts: ``ComplexTypeObj`` is the object
+that holds the fields, and ``ComplexType`` is a reference-counted reference to
+it, which IR nodes store and functions pass around. ``base: TypeObj`` makes the
+object an IR type, and ``rs_class`` registers its fields for reflection, 
through
+which Python and IR JSON loading construct the type as they construct a C++ 
one.
+
+``def_object_ref!(pub ComplexType, Type, ComplexTypeObj)`` defines the
+reference. Its arguments are:
+
+- ``pub ComplexType``: the name and visibility of the reference.
+- ``Type``: the reference to the parent object, ``TypeObj``. A ``ComplexType``
+  converts into a ``Type`` with ``into()`` wherever a ``Type`` is expected, 
such
+  as the result of type inference.
+- ``ComplexTypeObj``: the object it refers to. A ``ComplexTypeObj`` converts
+  into a ``ComplexType`` with ``into()``, and a ``ComplexType`` dereferences to
+  it, so ``ty.elem`` reads the field.
+
+``infer_complex`` in the next section uses both conversions: it builds a
+``ComplexTypeObj``, turns it into a ``ComplexType``, and returns it as a
+``Type``.
+
+The ``static_init_block!`` runs ``register_type`` when the library loads, as a
+``TVM_FFI_STATIC_INIT_BLOCK`` does for C++, and Python then sees the type as
+``my_ext.Complex``.
+
+A ``ComplexType`` records the scalar type of the two parts, and a
+``complex(re, im)`` call supplies their values as its operands. ``elem`` can be
+any scalar float type, such as ``float32``, ``float64`` or ``bfloat16``; this
+tutorial uses ``float32``.
+
+Defining Operators
+------------------
+
+To support operations on the new type, we need to define new operators. In our
+case, complex arithmetic needs four: one builds a complex value from two
+scalars, one multiplies complex values, and two read the parts back as scalars
+so that results can be stored in ordinary ``float32`` buffers. Like the type,
+they are registered under the ``my_ext`` namespace:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 40 30
+
+   * - Operator
+     - Meaning
+     - Result type (``float32`` parts)
+   * - ``complex(re, im)``
+     - Construct a complex value
+     - ``my_ext.Complex(T.float32)``
+   * - ``cmul(z, w)``
+     - Multiply two complex values
+     - ``my_ext.Complex(T.float32)``
+   * - ``real(z)``
+     - Extract the real part
+     - ``T.float32``
+   * - ``imag(z)``
+     - Extract the imaginary part
+     - ``T.float32``
+
+The constructor is registered as an ``OpDef`` chain in a
+``static_init_block!``. Each step updates the operator registry, and the chain
+completes when its statement ends:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+   :language: rust
+   :start-after: // begin constructor
+   :end-before: // end constructor
+
+``signature`` declares the arguments of the operator and of its Python and
+TVMScript builder. ``set_infer_type`` attaches a named Rust function that
+checks the arguments and computes the result type:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+   :language: rust
+   :start-after: // begin inference
+   :end-before: // end inference
+
+``set_validator`` repeats these checks for a call whose result type is given
+explicitly rather than inferred. ``Pure`` marks the operator as computing a
+value without writing memory.
+
+``infer_complex`` requires both parts to be scalar floats of the same type, and
+converts neither. The other three operators follow the same pattern. ``cmul``
+requires two complex arguments of the same type and returns it; ``real`` and
+``imag`` require one and return its ``elem``. Passing an ordinary scalar to 
``cmul`` therefore fails
+with ``TypeError: my_ext.cmul expects a complex value``.
+
+Writing a Pass
+--------------
+
+Although the new type and operators can be used like built-in ones when writing
+programs, the existing passes know nothing about them: they can neither
+optimize them further nor lower them to what the backend supports. We therefore
+add a pass of our own to handle them. In our case, ``LowerComplex`` applies
+three rewrite rules:
+
+.. code-block:: text
+
+   cmul(complex(a, b), complex(c, d))  ->  complex(a*c - b*d, a*d + b*c)
+   real(complex(a, b))                 ->  a
+   imag(complex(a, b))                 ->  b
+
+A complex local variable ``z = complex(a, b)`` is split into two scalar
+variables, ``z_re = a`` and ``z_im = b``, and later uses of ``z`` resolve to
+that pair. This lets the rules apply to the step-by-step function from
+:doc:`extending_ir_in_rust`, whose loop body becomes:
+
+.. code-block:: python
+
+   z_re: T.let[T.float32] = A[i]
+   z_im: T.let[T.float32] = B[i]
+   w_re: T.let[T.float32] = C[i]
+   w_im: T.let[T.float32] = D[i]
+   product_re: T.let[T.float32] = z_re * w_re - z_im * w_im
+   product_im: T.let[T.float32] = z_re * w_im + z_im * w_re
+   R[i] = product_re
+   Im[i] = product_im
+
+Only scalar arithmetic remains. The pass refers to the four operators through
+handles:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+   :language: rust
+   :start-after: // begin handles
+   :end-before: // end handles
+
+A handle names a registered operator and looks it up on first use.
+``CMUL.is(&call.op)`` tests whether a call's ``op`` is ``my_ext.cmul``, and
+``COMPLEX.get()?`` returns ``my_ext.complex`` to build a new call. ``Lowering``
+implements these rewrites with them:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+   :language: rust
+   :start-after: // begin lowering
+   :end-before: // end lowering
+   :prepend: #[derive(Default)]
+      struct Lowering {
+          bindings: Vec<(Var, Var, Var)>,
+      }
+      impl Lowering {
+          fn parts(&self, expr: &Expr) -> Result<(Expr, Expr)> { ... }
+      }
+      #[dispatch(map)]
+      impl Lowering {
+          fn map_sequence(&mut self, seq: SeqStmt) -> SeqStmt { ... }
+   :append: }
+
+``bindings`` records each complex variable with its two scalar replacements,
+and ``parts`` reads the real and imaginary parts of an operand, either a
+``complex(re, im)`` call or a variable already split. ``#[dispatch(map)]``
+sends each node to the ``map_`` method of its type, and leaves other nodes
+unchanged: ``map_call`` applies the three rules, ``map_bind`` splits a complex
+binding, and ``map_sequence`` flattens the sequence that a split binding leaves
+inside another.
+
+The pass is built from an ordinary named function:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+   :language: rust
+   :start-after: // begin function callback
+   :end-before: // end function callback
+
+It receives a function, its module, and the pass context, and returns the
+rewritten function; ``Some`` replaces the original. The first 
``structural_map``
+walks the function with ``Lowering``. ``PostOrder`` visits children before 
their
+parent, so the operands of ``cmul`` are lowered before ``cmul`` itself. The
+second ``structural_map`` only checks the result. It takes a tuple of three
+functions, and calls each on the nodes of its parameter type:
+
+.. code-block:: rust
+
+   /// Reject a complex type, wherever it appears: on a variable, a parameter 
or an expression.
+   fn check_type(ty: Type) -> Result<Type> { ... }
+
+   /// Reject an expression whose type is complex.
+   fn check_expr(expr: Expr) -> Result<Expr> { ... }
+
+   /// Reject a call to one of the four complex operators that the rewrite did 
not consume.
+   fn check_call_lowered(call: Call) -> Result<Call> { ... }
+
+Each returns its node unchanged and raises a ``ValueError`` on an unsupported
+use, such as a complex function parameter, so the pass reports such a use
+before code generation.
+
+Finally, ``FunctionPass::new`` wraps the function as a pass, and the factory is
+exported so that Python can call it as ``lib.lower_complex()``:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+   :language: rust
+   :start-after: // begin pass
+   :end-before: // end pass
+
+Next, :doc:`using_ir_extensions` loads the library and compiles the function.
diff --git a/docs/advanced/extending_ir_in_rust.rst 
b/docs/advanced/extending_ir_in_rust.rst
new file mode 100644
index 000000000..b637140e3
--- /dev/null
+++ b/docs/advanced/extending_ir_in_rust.rst
@@ -0,0 +1,123 @@
+..  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.
+
+Getting Started with Rust Extensions
+====================================
+
+.. note::
+
+   All the code in this tutorial is in the repository, as the Python package
+   `examples/extension 
<https://github.com/apache/tvm-tirx/tree/main/examples/extension>`_.
+
+This tutorial shows how to extend TIRx from Rust: define new IR types and
+operators, write a pass that lowers them, and use them from Python like
+built-in features.
+
+In this chapter, we will first look at why extensions are written in Rust, then
+get ready for the rest of the tutorial: a Python package for the extension and
+the example program it will compile.
+
+Why Rust
+--------
+
+TIRx is built on a stable C++ library for its IR, analysis, transformations,
+and code generation. In most cases, you work with it from Python: tensor
+programs are written as Python functions in TVMScript, then compiled and run
+directly.
+
+With agents, compiler development iterates quickly. Along the way, a project 
may
+need new types and operators to describe its own concepts, such as a new number
+format or a hardware feature, and passes that lower them to what the backend
+supports. To support this, TIRx provides Rust bindings, the ``tvm-tirx`` crate,
+which let you define new types, operators, and passes on the same IR objects as
+C++ and Python. An extension is a separate Rust library that builds and loads 
on
+its own, without changing the C++ library, so the C++ core stays stable while
+the extension iterates quickly. Once loaded, its types and operators can be
+written in TVMScript and its passes can run in Python compilation pipelines,
+just like built-in ones.
+
+Setting Up the Project
+----------------------
+
+An extension is shipped as a Python package that contains its Rust library, so
+it is installed and imported like any other package. The example package,
+``my-ext``, has this layout:
+
+.. code-block:: text
+
+   examples/extension/
+   ├── Cargo.toml        # the Rust library, which depends on tvm-tirx
+   ├── src/lib.rs        # the type, operators, and pass
+   ├── CMakeLists.txt    # builds the library with cargo and installs it into 
my_ext
+   ├── pyproject.toml    # the Python package, built with scikit-build-core
+   ├── python/my_ext/    # loads the library and registers a compilation 
pipeline
+   └── run_example.py    # compiles and runs a function that uses the extension
+
+The Rust library is an ordinary crate that builds a shared library:
+
+.. literalinclude:: ../../examples/extension/Cargo.toml
+   :language: toml
+   :start-at: [lib]
+   :end-before: # Standalone crate
+
+``tvm-tirx`` re-exports TVM FFI as ``tvm_tirx::tvm_ffi``, so it is the only
+dependency.
+
+To build and install the package, follow :doc:`../dev/source_build` to install
+TIRx with LLVM enabled, and use Rust 1.84 or newer; the build looks for cargo
+in ``~/.cargo/bin``, where rustup installs it, and then on ``PATH``. Then, from
+the TIRx repository root:
+
+.. code-block:: bash
+
+   uv pip install scikit-build-core
+   uv pip install --no-build-isolation examples/extension
+
+``--no-build-isolation`` builds the package against the TIRx in the project
+environment: the cargo build runs its ``tvm-tirx-config`` and
+``tvm-ffi-config`` tools to find the native libraries, so the extension links
+the TIRx it runs with.
+
+Case Study: Complex Numbers
+---------------------------
+
+To show how to define new types, operators, and passes, we will use complex
+numbers as a running example throughout this tutorial: a complex type, 
operators
+that build and multiply complex values, and a pass that expands complex
+multiplication into real arithmetic:
+
+.. math::
+
+   (a + bi)(c + di) = (ac - bd) + (ad + bc)i.
+
+The following function multiplies two arrays of complex numbers element by
+element. ``A`` and ``B`` hold the real and imaginary parts of the first 
operand,
+``C`` and ``D`` those of the second:
+
+.. literalinclude:: ../../examples/extension/run_example.py
+   :language: python
+   :start-after: # begin kernel
+   :end-before: # end kernel
+
+``my_ext`` is the extension's Python package, which holds the builders of its
+type and operators; :doc:`using_ir_extensions` shows how it provides them. 
``z``, ``w``, and ``product`` are complex
+values that exist only in the IR.
+The function's inputs and outputs are ordinary ``float32`` arrays, so no
+runtime storage format for complex numbers is needed.
+
+Next, :doc:`defining_ir_extensions` defines the type, operators, and pass this
+function uses, and :doc:`using_ir_extensions` compiles and runs it.
diff --git a/docs/advanced/using_ir_extensions.rst 
b/docs/advanced/using_ir_extensions.rst
new file mode 100644
index 000000000..95b0454c3
--- /dev/null
+++ b/docs/advanced/using_ir_extensions.rst
@@ -0,0 +1,112 @@
+..  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.
+
+Using and Compiling the Extension
+=================================
+
+In this chapter, we look at the Python package that loads the library defined
+in :doc:`defining_ir_extensions`, then use it to compile the complex
+multiplication function and check the result against NumPy.
+
+The Python Package
+------------------
+
+In :doc:`defining_ir_extensions`, the type and operators were registered in
+static init blocks, which run as soon as the library loads. To write them in
+TVMScript, Python also needs a module that holds their builders. Definitions
+under ``tirx.`` go to ``T``, but an extension namespace such as ``my_ext`` is
+published only into a module that the extension declares. The package's
+:download:`__init__.py <../../examples/extension/python/my_ext/__init__.py>`
+therefore declares itself as that module before it loads the library:
+
+.. literalinclude:: ../../examples/extension/python/my_ext/__init__.py
+   :language: python
+   :start-after: # begin load
+   :end-before: # end load
+
+The two ``_init_exposed_*_api`` calls, internal to ``tvm_tirx.ir`` for now,
+publish the operators and the type into ``my_ext``; ``auto_emit_void_call``
+gives its builders the TVMScript behavior of the ``T`` builders.
+``load_lib_module`` finds the library that the package installs next to
+``__init__.py``. To parse printed IR that uses the extension, pass the package
+as well, as in ``extra_vars={"T": T, "my_ext": my_ext}``.
+
+The registered type and operators let the IR express complex values;
+``LowerComplex`` turns them into a form the backend can compile. The default
+pipeline does not know about the pass, so the package registers a pipeline,
+also named ``my_ext``, that runs it first:
+
+.. literalinclude:: ../../examples/extension/python/my_ext/__init__.py
+   :language: python
+   :start-after: # begin pipeline
+   :end-before: # end pipeline
+
+``lower_complex`` returns the pass that the library exports.
+
+Compile the Function
+--------------------
+
+:download:`run_example.py <../../examples/extension/run_example.py>` imports
+``my_ext``, which loads the library and registers the pipeline, and compiles
+the function from :doc:`extending_ir_in_rust` with it:
+
+.. literalinclude:: ../../examples/extension/run_example.py
+   :language: python
+   :start-after: # begin compile
+   :end-before: # end compile
+
+Compiling with the default pipeline instead fails in LLVM code generation,
+which has no complex type.
+
+Check the Result
+----------------
+
+A successful compilation shows that ``LowerComplex`` left no complex values for
+the backend. To check that its rewrite also computes the right numbers, the
+script runs the compiled function on random ``float32`` inputs and compares
+both outputs with NumPy's complex multiplication:
+
+.. literalinclude:: ../../examples/extension/run_example.py
+   :language: python
+   :start-after: # begin comparison
+   :end-before: # end comparison
+
+With the package installed as in :doc:`extending_ir_in_rust`, run the script:
+
+.. code-block:: bash
+
+   uv run --no-sync python examples/extension/run_example.py
+
+A successful run prints:
+
+.. code-block:: text
+
+   Complex multiplication matches NumPy.
+
+``tests/python/ir/test_op_rust.py`` runs the script too, and also checks
+printing and parsing, invalid calls, chained products, and that lowering leaves
+no complex types or operators.
+
+Next Steps
+----------
+
+Complex addition or conjugation needs one more operator and one more rewrite
+rule in ``LowerComplex``, registered and written the same way. The example
+keeps complex values inside a function: parameters and outputs are ordinary
+arrays, and complex numbers have no runtime storage format or calling
+convention. See the :doc:`Rust API reference <../reference/rust/index>` for
+the full Rust API.
diff --git a/docs/index.rst b/docs/index.rst
index 9a018804e..51071bd6d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -77,6 +77,15 @@ Table of Contents
 
    compiler/symbolic_integer_analysis
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Extending TIRx: everything is a plugin
+   :titlesonly:
+
+   advanced/extending_ir_in_rust
+   advanced/defining_ir_extensions
+   advanced/using_ir_extensions
+
 .. toctree::
    :maxdepth: 1
    :caption: Reference
diff --git a/docs/reference/rust/index.rst b/docs/reference/rust/index.rst
index bd88642ad..1ca675b7a 100644
--- a/docs/reference/rust/index.rst
+++ b/docs/reference/rust/index.rst
@@ -21,8 +21,14 @@ Rust API
 The ``tvm-tirx`` crate in ``rust/`` binds the TIRx compiler objects over TVM 
FFI.
 Its modules follow the Python package: ``tvm_tirx::ir`` is :doc:`tvm_tirx.ir
 <../python/ir>`, ``tvm_tirx::tirx`` is :doc:`tvm_tirx.tirx <../python/tirx>`, 
and so
-on. Operators can also be defined from Rust with its ``register_ops!`` macro, 
as
-:doc:`tvm_tirx.backend.rust <../python/backend.rust>` loads them.
+on. Operators and types can also be defined from Rust in 
``tvm_ffi::static_init_block!``
+blocks, which run when :doc:`tvm_tirx.backend.rust <../python/backend.rust>` 
loads the
+library.
+
+The crate is built on the ``tvm-ffi`` crate, which provides the objects, 
functions,
+containers and macros its API is written in. This site therefore also hosts the
+``tvm-ffi`` reference, so links between the two crates resolve here, against 
the version
+TIRx is built with.
 
 The reference is generated by ``cargo doc`` when the documentation is built 
with
 ``BUILD_RUST_DOCS=1`` (see :doc:`../../dev/doc_build`).
@@ -38,7 +44,7 @@ Crates
      - Description
    * - 📦 `tvm-tirx <generated/tvm_tirx/index.html>`_
      - The IR, TIRx, symbolic analysis, target, backend, runtime, codegen and 
script
-       bindings, the Rust IR constructors and operators, and ``register_ops!``.
+       bindings, and the Rust IR constructors and operators.
    * - 📦 `tvm-ffi <generated/tvm_ffi/index.html>`_
-     - The TVM FFI objects, functions and containers the bindings are built on,
-       re-exported as ``tvm_tirx::tvm_ffi``.
+     - The TVM FFI objects, functions, containers and ``static_init_block!`` 
the
+       bindings are built on, re-exported as ``tvm_tirx::tvm_ffi``.
diff --git a/examples/extension/.gitignore b/examples/extension/.gitignore
new file mode 100644
index 000000000..7137982ad
--- /dev/null
+++ b/examples/extension/.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/extension/CMakeLists.txt 
b/examples/extension/CMakeLists.txt
new file mode 100644
index 000000000..0be8356fe
--- /dev/null
+++ b/examples/extension/CMakeLists.txt
@@ -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.
+
+# scikit-build-core runs this to build the Rust library with cargo and install 
it into my_ext.
+cmake_minimum_required(VERSION 3.18)
+project(my_ext LANGUAGES NONE)
+
+# rustup's cargo is preferred over an older one on PATH.
+find_program(CARGO cargo HINTS "$ENV{HOME}/.cargo/bin" REQUIRED)
+set(cargo_target_dir "${CMAKE_BINARY_DIR}/cargo")
+set(lib_name 
"${CMAKE_SHARED_LIBRARY_PREFIX}my_ext${CMAKE_SHARED_LIBRARY_SUFFIX}")
+add_custom_target(my_ext ALL
+  COMMAND "${CMAKE_COMMAND}" -E env "CARGO_TARGET_DIR=${cargo_target_dir}"
+    "${CARGO}" build --release --manifest-path 
"${CMAKE_CURRENT_SOURCE_DIR}/Cargo.toml"
+  USES_TERMINAL VERBATIM)
+install(FILES "${cargo_target_dir}/release/${lib_name}" DESTINATION my_ext)
diff --git a/examples/extension/Cargo.toml b/examples/extension/Cargo.toml
new file mode 100644
index 000000000..aa004ed92
--- /dev/null
+++ b/examples/extension/Cargo.toml
@@ -0,0 +1,33 @@
+# 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 = "my-ext"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+# The shared library that the Python package loads.
+crate-type = ["cdylib"]
+
+[dependencies]
+# The tvm-tirx crate is not published yet, so the extension depends on it by 
path.
+tvm-tirx = { path = "../../rust" }
+
+# Standalone crate: not a member of any enclosing workspace.
+[workspace]
diff --git a/examples/extension/README.md b/examples/extension/README.md
new file mode 100644
index 000000000..df9a945d6
--- /dev/null
+++ b/examples/extension/README.md
@@ -0,0 +1,43 @@
+<!--- 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. -->
+
+# TIRx Extension Example
+
+A Python package, `my-ext`, that extends TIRx from Rust: a complex-number type,
+operators that build and multiply complex values, and a pass that lowers them 
to
+scalar arithmetic. Importing `my_ext` loads the Rust library, provides the
+`my_ext.*` builders for TVMScript, and registers the `my_ext` compilation
+pipeline. The tutorial in `docs/advanced/` walks through the code.
+
+- `src/lib.rs`: the type, operators, and pass, built by cargo as a shared 
library
+- `CMakeLists.txt`, `pyproject.toml`: build the library and install it into 
the package
+- `python/my_ext/`: loads the library and registers the pipeline
+- `run_example.py`: compiles a function that uses the extension and checks it 
against NumPy
+
+## Install and Run
+
+Install TIRx from source with LLVM enabled, and Rust 1.84 or newer. From the
+repository root:
+
+```bash
+uv pip install scikit-build-core
+uv pip install --no-build-isolation examples/extension
+uv run --no-sync python examples/extension/run_example.py
+```
+
+`--no-build-isolation` builds against the TIRx in the project environment,
+whose `tvm-tirx-config` and `tvm-ffi-config` the cargo build runs.
diff --git a/examples/extension/pyproject.toml 
b/examples/extension/pyproject.toml
new file mode 100644
index 000000000..36a9f3e26
--- /dev/null
+++ b/examples/extension/pyproject.toml
@@ -0,0 +1,33 @@
+# 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 = "my-ext"
+version = "0.1.0"
+description = "A TIRx extension written in Rust: a complex type, its 
operators, and a lowering pass"
+requires-python = ">=3.10"
+dependencies = ["apache-tvm-tirx"]
+
+[build-system]
+# apache-tvm-tirx provides tvm-tirx-config and tvm-ffi-config, which the cargo 
build 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/my_ext"]
+cmake.build-type = "Release"
diff --git a/examples/extension/python/my_ext/__init__.py 
b/examples/extension/python/my_ext/__init__.py
new file mode 100644
index 000000000..07ce41bb0
--- /dev/null
+++ b/examples/extension/python/my_ext/__init__.py
@@ -0,0 +1,46 @@
+# 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 complex type and operators of the Rust library, and a pipeline that 
lowers them."""
+
+from pathlib import Path
+
+from tvm_ffi.libinfo import load_lib_module
+
+from tvm_tirx import ir, tirx
+from tvm_tirx.ir._expose_api import _init_exposed_op_api, 
_init_exposed_type_api
+from tvm_tirx.script.ir_builder.base import auto_emit_void_call
+
+# begin load
+_init_exposed_op_api("my_ext", __name__, wrapper=auto_emit_void_call)
+_init_exposed_type_api("my_ext", __name__)
+_LIB = load_lib_module("my-ext", "my_ext", 
extra_lib_paths=[Path(__file__).parent])
+# end load
+
+
+def lower_complex() -> ir.transform.Pass:
+    """The pass that lowers complex values to scalar arithmetic."""
+    return _LIB.lower_complex()
+
+
+# begin pipeline
+def _pipeline(*, target=None):
+    lower, finalize_host, finalize_device = tirx.get_tir_pipeline("default", 
target=target)
+    return ir.transform.Sequential([lower_complex(), lower]), finalize_host, 
finalize_device
+
+
+tirx.register_tir_pipeline("my_ext", _pipeline)
+# end pipeline
diff --git a/examples/extension/run_example.py 
b/examples/extension/run_example.py
new file mode 100644
index 000000000..4aa4a4648
--- /dev/null
+++ b/examples/extension/run_example.py
@@ -0,0 +1,65 @@
+# 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.
+"""Compile a function that multiplies complex numbers with my_ext, and check 
it against NumPy."""
+
+import my_ext
+import numpy as np
+
+import tvm_tirx
+from tvm_tirx import runtime
+from tvm_tirx.script import tirx as T
+
+# begin kernel
+N = 16
+
+
[email protected]
+def complex_product(
+    A: T.Tensor((N,), "float32"),
+    B: T.Tensor((N,), "float32"),
+    C: T.Tensor((N,), "float32"),
+    D: T.Tensor((N,), "float32"),
+    R: T.Tensor((N,), "float32"),
+    Im: T.Tensor((N,), "float32"),
+):
+    for i in range(N):
+        z = my_ext.complex(A[i], B[i])
+        w = my_ext.complex(C[i], D[i])
+        product = my_ext.cmul(z, w)
+        R[i] = my_ext.real(product)
+        Im[i] = my_ext.imag(product)
+
+
+# end kernel
+
+# begin compile
+compiled = tvm_tirx.compile(complex_product, target="llvm", pipeline="my_ext")
+# end compile
+
+# begin comparison
+rng = np.random.default_rng(0)
+a, b, c, d = rng.standard_normal((4, N)).astype("float32")
+inputs = [runtime.tensor(x) for x in (a, b, c, d)]
+real_out = runtime.empty((N,), "float32")
+imag_out = runtime.empty((N,), "float32")
+compiled(*inputs, real_out, imag_out)
+
+expected = (a + 1j * b) * (c + 1j * d)
+np.testing.assert_allclose(real_out.numpy(), expected.real, rtol=1e-5, 
atol=1e-6)
+np.testing.assert_allclose(imag_out.numpy(), expected.imag, rtol=1e-5, 
atol=1e-6)
+# end comparison
+print("Complex multiplication matches NumPy.")
diff --git a/examples/extension/rustfmt.toml b/examples/extension/rustfmt.toml
new file mode 100644
index 000000000..59604833f
--- /dev/null
+++ b/examples/extension/rustfmt.toml
@@ -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.
+
+# Match the layout `tvm-ffi-stubgen --target rust` emits, so `cargo fmt` leaves
+# the generated blocks byte-identical and `tvm-ffi-stubgen --check` stays 
clean.
+use_small_heuristics = "Max"
+reorder_imports = false
diff --git a/examples/extension/src/lib.rs b/examples/extension/src/lib.rs
new file mode 100644
index 000000000..e50168731
--- /dev/null
+++ b/examples/extension/src/lib.rs
@@ -0,0 +1,302 @@
+/*
+ * 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.
+ */
+
+//! Complex values in the IR, lowered to ordinary scalar arithmetic.
+//! See docs/advanced/extending_ir_in_rust.rst; the my_ext Python package 
loads this library.
+
+use tvm_tirx::ir::op_attr::CALL_EFFECT_KIND;
+use tvm_tirx::ir::prim::ex;
+use tvm_tirx::ir::sig::{self, PrimExpr};
+use tvm_tirx::ir::transform::{Pass, PassContext, PassInfo};
+use tvm_tirx::ir::{
+    dtype, register_type, Bind, Call, CallEffectKind, CallObj, Expr, IRModule, 
Op, OpDef, OpHandle,
+    PrimType, SeqStmt, Stmt, Type, TypeObj, Var,
+};
+use tvm_tirx::tirx::transform::FunctionPass;
+use tvm_tirx::tirx::Function;
+use tvm_tirx::tvm_ffi::{
+    self, def_object_ref, dispatch, rs_class, Error, ObjectRefCast, 
ObjectRefCore, Result,
+    WalkOrder,
+};
+
+// begin type
+/// A complex number whose real and imaginary parts share a scalar type.
+#[rs_class("my_ext.ComplexType", final)]
+pub struct ComplexTypeObj {
+    base: TypeObj,
+    pub elem: PrimType,
+}
+def_object_ref!(pub ComplexType, Type, ComplexTypeObj);
+
+tvm_ffi::static_init_block! {
+    register_type::<ComplexType>()?;
+}
+// end type
+
+fn type_error(message: &str) -> Error {
+    Error::new(tvm_ffi::TYPE_ERROR, message, "")
+}
+
+fn require(condition: bool, message: &str) -> Result<()> {
+    if condition {
+        Ok(())
+    } else {
+        Err(type_error(message))
+    }
+}
+
+fn check_call(call: &CallObj, count: usize) -> Result<()> {
+    require(call.args.len() == count, &format!("expected {count} value 
arguments"))?;
+    require(call.ty_args.is_empty(), "type arguments are not supported")?;
+    require(call.attrs.is_none(), "call attributes are not supported")
+}
+
+/// The type of a part of a complex number: a scalar float, such as `float32`, 
`float64` or
+/// `bfloat16`.
+fn float_part(ty: &Type) -> Result<PrimType> {
+    let elem: PrimType =
+        ty.clone().try_cast().map_err(|_| type_error("expected a scalar 
float"))?;
+    let bits = elem.dtype.bits;
+    let float = elem.dtype == dtype::float(bits) || elem.dtype == 
dtype::bfloat(bits);
+    require(float, "expected a scalar float")?;
+    Ok(elem)
+}
+
+// begin inference
+fn infer_complex(call: &CallObj) -> Result<Type> {
+    check_call(call, 2)?;
+    let elem = float_part(&call.args.get(0)?.ty)?;
+    let im = float_part(&call.args.get(1)?.ty)?;
+    require(elem.dtype == im.dtype, "my_ext.complex expects parts of the same 
type")?;
+    let ty: ComplexType = ComplexTypeObj::new(TypeObj::new(call.loc.clone()), 
elem).into();
+    Ok(ty.into())
+}
+// end inference
+
+fn complex_arg(call: &CallObj, index: usize) -> Result<ComplexType> {
+    let op: Op = call.op.clone().try_cast()?;
+    let ty: ComplexType = call
+        .args
+        .get(index)?
+        .ty
+        .clone()
+        .try_cast()
+        .map_err(|_| type_error(&format!("{} expects a complex value", 
op.name.as_str())))?;
+    float_part(&ty.elem.clone().into())?;
+    Ok(ty)
+}
+
+fn infer_cmul(call: &CallObj) -> Result<Type> {
+    check_call(call, 2)?;
+    let (a, b) = (complex_arg(call, 0)?, complex_arg(call, 1)?);
+    require(a.elem.dtype == b.elem.dtype, "my_ext.cmul expects complex values 
of the same type")?;
+    Ok(a.into())
+}
+
+fn infer_part(call: &CallObj) -> Result<Type> {
+    check_call(call, 1)?;
+    Ok(complex_arg(call, 0)?.elem.clone().into())
+}
+
+// Explicit result types bypass inference, so validation checks the inputs and 
result again.
+fn validate_call(call: &CallObj) -> Result<()> {
+    let expected = if COMPLEX.is(&call.op) {
+        infer_complex(call)?
+    } else if CMUL.is(&call.op) {
+        infer_cmul(call)?
+    } else {
+        infer_part(call)?
+    };
+    let matches: bool = tvm_ffi::cached_global_func!("ffi.StructuralEqual")
+        .call_tuple((&expected, &call.ty, false, false))?
+        .try_into()?;
+    require(matches, "incorrect result type for complex operator")
+}
+
+// begin constructor
+tvm_ffi::static_init_block! {
+    OpDef::new("my_ext.complex", "Construct the complex number re + im * i.")
+        .signature((
+            sig::arg::<PrimExpr>("re", "The real part."),
+            sig::arg::<PrimExpr>("im", "The imaginary part."),
+        ))
+        .set_infer_type(infer_complex)
+        .set_validator(validate_call)
+        .set_attr(CALL_EFFECT_KIND, CallEffectKind::Pure);
+}
+// end constructor
+
+tvm_ffi::static_init_block! {
+    OpDef::new("my_ext.cmul", "Multiply two complex numbers.")
+        .signature((
+            sig::arg::<Expr>("a", "The first complex value."),
+            sig::arg::<Expr>("b", "The second complex value."),
+        ))
+        .set_infer_type(infer_cmul)
+        .set_validator(validate_call)
+        .set_attr(CALL_EFFECT_KIND, CallEffectKind::Pure);
+    OpDef::new("my_ext.real", "Extract the real part of a complex number.")
+        .signature(sig::arg::<Expr>("z", "The complex value."))
+        .set_infer_type(infer_part)
+        .set_validator(validate_call)
+        .set_attr(CALL_EFFECT_KIND, CallEffectKind::Pure);
+    OpDef::new("my_ext.imag", "Extract the imaginary part of a complex 
number.")
+        .signature(sig::arg::<Expr>("z", "The complex value."))
+        .set_infer_type(infer_part)
+        .set_validator(validate_call)
+        .set_attr(CALL_EFFECT_KIND, CallEffectKind::Pure);
+}
+
+// begin handles
+static COMPLEX: OpHandle = OpHandle::new("my_ext.complex");
+static CMUL: OpHandle = OpHandle::new("my_ext.cmul");
+static REAL: OpHandle = OpHandle::new("my_ext.real");
+static IMAG: OpHandle = OpHandle::new("my_ext.imag");
+// end handles
+
+#[derive(Default)]
+struct Lowering {
+    // Each complex local variable is replaced by two scalar local variables.
+    bindings: Vec<(Var, Var, Var)>,
+}
+
+impl Lowering {
+    fn parts(&self, expr: &Expr) -> Result<(Expr, Expr)> {
+        if let Some(call) = expr.as_node::<CallObj>() {
+            if COMPLEX.is(&call.op) {
+                return Ok((call.args.get(0)?, call.args.get(1)?));
+            }
+        }
+        for (var, re, im) in &self.bindings {
+            if var.same_as(expr) {
+                return Ok((re.clone().into(), im.clone().into()));
+            }
+        }
+        Err(Error::new(tvm_ffi::VALUE_ERROR, "LowerComplex cannot resolve 
complex operand", ""))
+    }
+}
+
+#[dispatch(map)]
+impl Lowering {
+    fn map_sequence(&mut self, seq: SeqStmt) -> SeqStmt {
+        SeqStmt::new(seq.seq.iter(), seq.loc.clone())
+    }
+
+    // begin lowering
+    fn map_call(&mut self, call: Call) -> Result<Expr> {
+        if COMPLEX.is(&call.op) || CMUL.is(&call.op) || REAL.is(&call.op) || 
IMAG.is(&call.op) {
+            validate_call(&call)?;
+        }
+        if CMUL.is(&call.op) {
+            let (a, b) = self.parts(&call.args.get(0)?)?;
+            let (c, d) = self.parts(&call.args.get(1)?)?;
+            // (a + bi)(c + di) = (ac - bd) + (ad + bc)i
+            let re = ex(&a) * ex(&c) - ex(&b) * ex(&d);
+            let im = ex(&a) * ex(&d) + ex(&b) * ex(&c);
+            return Ok(Call::new(
+                None,
+                COMPLEX.get()?,
+                [re, im],
+                None,
+                Vec::<Type>::new(),
+                call.loc.clone(),
+            )?
+            .into());
+        }
+        if REAL.is(&call.op) || IMAG.is(&call.op) {
+            let (re, im) = self.parts(&call.args.get(0)?)?;
+            return Ok(if REAL.is(&call.op) { re } else { im });
+        }
+        Ok(call.into())
+    }
+
+    fn map_bind(&mut self, bind: Bind) -> Result<Stmt> {
+        if let Some(ty) = bind.var.ty.as_node::<ComplexTypeObj>() {
+            let (re, im) = self.parts(&bind.value)?;
+            let name = bind.var.name.as_str();
+            let re_var = Var::new(&format!("{name}_re"), ty.elem.clone(), 
bind.var.loc.clone());
+            let im_var = Var::new(&format!("{name}_im"), ty.elem.clone(), 
bind.var.loc.clone());
+            self.bindings.push((bind.var.clone(), re_var.clone(), 
im_var.clone()));
+            let binds = [
+                Bind::new(re_var, re, bind.loc.clone())?,
+                Bind::new(im_var, im, bind.loc.clone())?,
+            ];
+            return Ok(SeqStmt::new(binds, bind.loc.clone()).into());
+        }
+        Ok(bind.into())
+    }
+    // end lowering
+}
+
+/// Reject a complex type, wherever it appears: on a variable, a parameter or 
an expression.
+fn check_type(ty: Type) -> Result<Type> {
+    if ty.as_node::<ComplexTypeObj>().is_some() {
+        return Err(Error::new(
+            tvm_ffi::VALUE_ERROR,
+            "LowerComplex left an unsupported complex type",
+            "",
+        ));
+    }
+    Ok(ty)
+}
+
+/// Reject an expression whose type is complex.
+fn check_expr(expr: Expr) -> Result<Expr> {
+    check_type(expr.ty.clone())?;
+    Ok(expr)
+}
+
+/// Reject a call to one of the four complex operators that the rewrite did 
not consume.
+fn check_call_lowered(call: Call) -> Result<Call> {
+    if COMPLEX.is(&call.op) || CMUL.is(&call.op) || REAL.is(&call.op) || 
IMAG.is(&call.op) {
+        return Err(Error::new(
+            tvm_ffi::VALUE_ERROR,
+            "LowerComplex left an unsupported complex call",
+            "",
+        ));
+    }
+    Ok(call)
+}
+
+// begin function callback
+fn lower_function(
+    func: Function,
+    _module: IRModule,
+    _ctx: PassContext,
+) -> Result<Option<Function>> {
+    let mut lowering = Lowering::default();
+    let rewritten = tvm_ffi::structural_map(func, &mut lowering, 
WalkOrder::PostOrder)?;
+    let checked = tvm_ffi::structural_map(
+        rewritten,
+        (check_type, check_call_lowered, check_expr),
+        WalkOrder::PostOrder,
+    )?;
+    let function: Function = checked.try_into()?;
+    Ok(Some(function))
+}
+// end function callback
+
+// begin pass
+fn lower_complex() -> Result<Pass> {
+    let pass = FunctionPass::new(lower_function, PassInfo::new(0, 
"my_ext.LowerComplex"));
+    Ok(Pass::from(&pass))
+}
+
+tvm_ffi::tvm_ffi_dll_export_typed_func!(lower_complex, lower_complex);
+// end pass
diff --git a/tests/python/ir/test_op_rust.py b/tests/python/ir/test_op_rust.py
index a72dd18b1..a3e5a1725 100644
--- a/tests/python/ir/test_op_rust.py
+++ b/tests/python/ir/test_op_rust.py
@@ -34,7 +34,10 @@ from pathlib import Path
 
 import pytest
 
+import tvm_tirx
+
 RUST_DIR = Path(__file__).resolve().parents[3] / "rust"
+EXTENSION_DIR = RUST_DIR.parent / "examples" / "extension"
 
 
 def find_cargo():
@@ -54,29 +57,51 @@ def find_cargo():
     return None
 
 
[email protected](scope="module")
-def define_ir_library():
-    """The example library of Rust operators and types, built by cargo."""
+def cargo_build(manifest, *args):
+    """Build with cargo in rust/'s target directory, shared with the crate, 
and return the
+    directory of the debug build."""
     cargo = find_cargo()
     if cargo is None or not shutil.which("tvm-ffi-config") or not 
shutil.which("tvm-tirx-config"):
         pytest.skip(
             "building rust/ needs a cargo as new as its rust-version, and 
tvm-ffi-config and "
             "tvm-tirx-config on PATH"
         )
-    manifest = RUST_DIR / "Cargo.toml"
-    subprocess.run(
-        [cargo, "build", "--manifest-path", str(manifest), "--example", 
"define_ir"], check=True
-    )
     target_dir = Path(os.environ.get("CARGO_TARGET_DIR", RUST_DIR / "target"))
-    name = {"darwin": "libdefine_ir.dylib", "win32": "define_ir.dll"}.get(
-        sys.platform, "libdefine_ir.so"
-    )
-    return target_dir / "debug" / "examples" / name
+    env = {**os.environ, "CARGO_TARGET_DIR": str(target_dir)}
+    subprocess.run([cargo, "build", "--manifest-path", str(manifest), *args], 
check=True, env=env)
+    return target_dir / "debug"
+
+
+def library_name(name):
+    """The file name of the shared library that cargo builds for `name`."""
+    return {"darwin": f"lib{name}.dylib", "win32": 
f"{name}.dll"}.get(sys.platform, f"lib{name}.so")
+
+
+def build_rust_example(example):
+    """Build an example library of Rust operators and types with cargo."""
+    debug_dir = cargo_build(RUST_DIR / "Cargo.toml", "--example", example)
+    return debug_dir / "examples" / library_name(example)
+
+
[email protected](scope="module")
+def define_ir_library():
+    """The example library of Rust operators and types, built by cargo."""
+    return build_rust_example("define_ir")
+
+
[email protected](scope="module")
+def extension_package(tmp_path_factory):
+    """The my_ext package of examples/extension, laid out as its wheel 
installs it."""
+    debug_dir = cargo_build(EXTENSION_DIR / "Cargo.toml")
+    root = tmp_path_factory.mktemp("extension")
+    package = shutil.copytree(EXTENSION_DIR / "python" / "my_ext", root / 
"my_ext")
+    shutil.copy(debug_dir / library_name("my_ext"), package)
+    return root
 
 
-def run_python(*code, libraries):
-    """Run `code` in a fresh interpreter, with the paths of `libraries` as its 
arguments, and
-    return its standard error.
+def run_python(*code, libraries=(), python_path=()):
+    """Run `code` in a fresh interpreter, with the paths of `libraries` as its 
arguments and
+    `python_path` before PYTHONPATH, and return its standard error.
 
     The code runs from a file: TVMScript reads the source of the functions it 
parses, which Python
     keeps for code passed with `-c` only from 3.13 on.
@@ -84,11 +109,13 @@ def run_python(*code, libraries):
     with tempfile.TemporaryDirectory() as tmp:
         script = Path(tmp) / "script.py"
         script.write_text("\n".join(textwrap.dedent(part) for part in code))
+        paths = [*map(str, python_path), *filter(None, 
[os.environ.get("PYTHONPATH")])]
         result = subprocess.run(
             [sys.executable, str(script), *map(str, libraries)],
             capture_output=True,
             text=True,
             check=False,
+            env={**os.environ, "PYTHONPATH": os.pathsep.join(paths)},
         )
     assert result.returncode == 0, result.stderr
     return result.stderr
@@ -138,6 +165,131 @@ ROUND_TRIP = """
 """
 
 
+# Checks of the extension beyond those of its example script: the type, 
printing and parsing,
+# invalid calls, chained products, float64 parts, and what the lowering 
rejects.
+EXTENSION_CHECKS = """
+    # Run after examples/extension/run_example.py, whose names it uses.
+    import tvm_ffi
+    from tvm_tirx import ir, tirx
+
+    # Inspect the registered type and round-trip the IR through text and JSON.
+    a_var, b_var = ir.Var("a", "float32"), ir.Var("b", "float32")
+    z = my_ext.complex(a_var, b_var)
+    assert isinstance(z.ty, my_ext.Complex)
+    assert tvm_ffi.structural_equal(z.ty.elem, ir.PrimType("float32"))
+    assert tvm_ffi.structural_equal(ir.load_json(ir.save_json(z.ty)), z.ty)
+    text = complex_product.script()
+    parsed = tvm_tirx.script.parse(text, extra_vars={"T": T, "my_ext": my_ext})
+    assert tvm_ffi.structural_equal(parsed, complex_product)
+    assert 
tvm_ffi.structural_equal(ir.load_json(ir.save_json(complex_product)), 
complex_product)
+    for name in ("complex", "cmul", "real", "imag"):
+        op = ir.Op.get(f"my_ext.{name}")
+        assert op.get_attr("TCallEffectKind") == ir.CallEffectKind.Pure
+        assert getattr(my_ext, name).__doc__ == op.doc
+
+    lower = my_ext.lower_complex()
+    lowered = lower(ir.IRModule({"main": complex_product}))
+    assert "my_ext." not in lowered["main"].script()
+
+
+    for original, tensor in zip((a, b, c, d), inputs):
+        np.testing.assert_array_equal(tensor.numpy(), original)
+
+
+    # Further checks stay out of the tutorial's code slices.
+    def expect_error(error_type, message, function, *args):
+        try:
+            function(*args)
+        except error_type as error:
+            assert message in str(error), str(error)
+        else:
+            raise AssertionError(f"expected {error_type.__name__}: {message}")
+
+
+    # The parts are scalar floats of one type; nothing is converted or 
promoted.
+    for dtype in ("int32", "float32x4"):
+        wrong = ir.Var("wrong", dtype)
+        expect_error(TypeError, "expected a scalar float", my_ext.complex, 
wrong, b_var)
+        expect_error(TypeError, "expected a scalar float", my_ext.complex, 
a_var, wrong)
+    wide = ir.Var("wide", "float64")
+    expect_error(TypeError, "parts of the same type", my_ext.complex, a_var, 
wide)
+    z64 = my_ext.complex(wide, wide)
+    assert tvm_ffi.structural_equal(z64.ty, my_ext.Complex(T.float64))
+    assert tvm_ffi.structural_equal(my_ext.real(z64).ty, T.float64)
+    expect_error(TypeError, "complex values of the same type", my_ext.cmul, z, 
z64)
+    brain = ir.Var("brain", "bfloat16")
+    assert tvm_ffi.structural_equal(my_ext.complex(brain, brain).ty, 
my_ext.Complex(T.bfloat16))
+    expect_error(TypeError, "cmul expects a complex value", my_ext.cmul, 
a_var, z)
+    expect_error(TypeError, "cmul expects a complex value", my_ext.cmul, z, 
a_var)
+    expect_error(TypeError, "real expects a complex value", my_ext.real, a_var)
+    expect_error(TypeError, "imag expects a complex value", my_ext.imag, a_var)
+
+    # Explicit result types must not let invalid calls escape validation.
+    for name, args in (("complex", [a_var, b_var]), ("cmul", [z, z]), ("real", 
[z]), ("imag", [z])):
+        invalid = ir.Call(f"my_ext.{name}", args, ty="int32")
+        expect_error(TypeError, "incorrect result type", invalid.validate)
+    invalid = ir.Call("my_ext.cmul", [a_var, z], ty=z.ty)
+    expect_error(TypeError, "expects a complex value", invalid.validate)
+    bad_type = my_ext.Complex(T.int32)
+    expect_error(TypeError, "expected a scalar float", my_ext.real, 
ir.Var("bad", bad_type))
+
+    # Complex function parameters and unconsumed complex values are outside 
this lowering.
+    unsupported = tirx.Function([ir.Var("z", z.ty)], 
ir.SeqStmt([ir.Evaluate(0)]))
+    expect_error(ValueError, "unsupported complex type", lower, 
ir.IRModule({"main": unsupported}))
+    unsupported = tirx.Function([a_var, b_var], ir.SeqStmt([ir.Evaluate(z)]))
+    expect_error(ValueError, "unsupported complex", lower, 
ir.IRModule({"main": unsupported}))
+
+
+    # Aliases, chained products and inline constructors take the same lowering 
path.
+    @T.function
+    def cube(
+        A: T.Tensor((N,), "float32"),
+        B: T.Tensor((N,), "float32"),
+        R: T.Tensor((N,), "float32"),
+        Im: T.Tensor((N,), "float32"),
+    ):
+        for i in range(N):
+            z = my_ext.complex(A[i], B[i])
+            alias = z
+            square = my_ext.cmul(alias, z)
+            R[i] = my_ext.real(my_ext.cmul(square, my_ext.complex(A[i], B[i])))
+            Im[i] = my_ext.imag(my_ext.cmul(square, z))
+
+
+    cube_lowered = lower(ir.IRModule({"main": cube}))
+    assert "my_ext." not in cube_lowered["main"].script()
+    cube_compiled = tvm_tirx.compile(cube, target="llvm", pipeline="my_ext")
+    cube_compiled(*inputs[:2], real_out, imag_out)
+    expected_cube = (a + 1j * b) ** 3
+    np.testing.assert_allclose(real_out.numpy(), expected_cube.real, 
rtol=1e-5, atol=1e-6)
+    np.testing.assert_allclose(imag_out.numpy(), expected_cube.imag, 
rtol=1e-5, atol=1e-6)
+
+
+    # The same lowering handles float64 parts.
+    @T.function
+    def product64(
+        A: T.Tensor((N,), "float64"),
+        B: T.Tensor((N,), "float64"),
+        R: T.Tensor((N,), "float64"),
+        Im: T.Tensor((N,), "float64"),
+    ):
+        for i in range(N):
+            z = my_ext.complex(A[i], B[i])
+            product = my_ext.cmul(z, z)
+            R[i] = my_ext.real(product)
+            Im[i] = my_ext.imag(product)
+
+
+    a64, b64 = rng.standard_normal((2, N))
+    real64, imag64 = runtime.empty((N,), "float64"), runtime.empty((N,), 
"float64")
+    product64_compiled = tvm_tirx.compile(product64, target="llvm", 
pipeline="my_ext")
+    product64_compiled(runtime.tensor(a64), runtime.tensor(b64), real64, 
imag64)
+    expected64 = (a64 + 1j * b64) ** 2
+    np.testing.assert_allclose(real64.numpy(), expected64.real, rtol=1e-12)
+    np.testing.assert_allclose(imag64.numpy(), expected64.imag, rtol=1e-12)
+"""
+
+
 def test_library_is_loaded_on_import():
     """``import tvm_tirx`` loads libtvm_tirx_rust, when the build has it, as a 
backend."""
     from tvm_ffi.libinfo import _find_library_by_basename  # pylint: 
disable=import-outside-toplevel
@@ -152,6 +304,12 @@ def test_library_is_loaded_on_import():
     assert "tvm_tirx_rust" in _LOADED_LIBS
 
 
[email protected](not tvm_tirx.runtime.enabled("llvm"), reason="LLVM is not 
enabled")
+def test_extension_example(extension_package):
+    script = EXTENSION_DIR / "run_example.py"
+    run_python(script.read_text(), EXTENSION_CHECKS, 
python_path=[extension_package])
+
+
 def test_rust_operators_are_registered_by_their_library(define_ir_library):
     run_python(
         """

Reply via email to