tvm_ffi.structural

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 for more details.

See also

tvm_tirx.tirx.structural provides variants of these utilities that also track constraint information, such as loop ranges and branch conditions, at each node.

Functions

structural_walk(root[, callbacks, ...])	Walk a value structurally and invoke the first matching typed callback.
structural_map(root[, callbacks, ...])	Structurally map a value using typed replacement callbacks.
structural_visit(root[, callbacks])	Visit a value structurally with callbacks that own child traversal.
structural_mutate(root[, callbacks])	Mutate a value with callbacks that own recursive mutation.
structural_equal(lhs, rhs[, map_free_vars, ...])	Check structural equality between two values.
structural_hash(value[, map_free_vars, ...])	Compute structural hash of a value.
get_first_structural_mismatch(lhs, rhs[, ...])	Like structural_equal(), but returns the AccessPath pair of the first detected mismatch.

Classes

StructuralVisitor(*args, **kwargs)	Low-level structural traversal visitor.
StructuralMutator(*args, **kwargs)	Low-level structural mutator.
StructuralKey(key)	Hash-cached structural key wrapper.
WalkResult(*values)	Control signal for structural walks.
WalkOrder(*values)	Callback placement before or after recursively traversing children.
VisitInterrupt([value])	Payload-carrying signal that stops a structural visit.
DefRegionKind(*values)	Def-region state active during structural visiting.
InplaceMode(*values)	Permission to mutate a value in place along its ownership path.

Structural Hooks

An object type tells these utilities how to handle it through structural hooks, which it can register from C++ or Python:

Hook	Purpose
__s_visit__	Visits the object’s children and marks which fields define variables.
__s_mutate__	Rewrites the object’s children.
__s_maybe_inplace_mutate__	Optional. Reuses the object’s storage when it is safe to do so.
__s_equal__ and __s_hash__	Define structural equality and hashing.

Every TIRx IR node registers compiled hooks; other objects fall back to their reflected fields.

TIRx marks loop and Bind variables as DEF_SIMPLE; it marks function parameters, including the variables in their types, as DEF_PATTERN.

See Custom Visit and Mutation Hooks in the TVM-FFI documentation for how to write hooks.