tvm.relay.dataflow_pattern

The Relay Pattern Language and tooling.

Classes:

`Expr`	alias of `RelayExpr`
`DFPattern`	Base class of all Patterns.
`ExprPattern`(expr)	A pattern which matches a constant expression.
`VarPattern`([name_hint])	A local variable in Relay.
`ConstantPattern`()	A pattern matching a Relay Constant.
`CallPattern`(op, args)	A pattern matching a function call node in Relay.
`FunctionPattern`(params, body)	A pattern matching a function node in Relay.
`IfPattern`(cond, true_branch, false_branch)	A patern matching a Relay If.
`LetPattern`(var, value, body)	A patern matching a Relay Let.
`TuplePattern`(fields)	A patern matching a Relay Tuple.
`TupleGetItemPattern`(tuple_value[, index])	Get index-th item from a TuplePattern.
`AltPattern`(left, right)	Create a Pattern that can match one of two conditions
`WildcardPattern`()	A pattern which matches anything.
`TypePattern`(pattern, ttype)	A pattern that matches another pattern with a certain type annotation.
`DataTypePattern`(pattern, dtype)	A pattern that matches another pattern with certain data type
`ShapePattern`(pattern, shape)	A pattern that matches another pattern with a certain tensor shape
`AttrPattern`(pattern, attrs)	Get match an expression with a certain attributes.
`DominatorPattern`(parent, path, child)	Match a domination graph.
`DFPatternCallback`([require_type, rewrite_once])	A Callback for Pattern Rewriting.

Functions:

`make_node`(type_key, **kwargs)	Make a new IR node by its type key and fields
`astext`(obj[, show_meta_data, annotate])	Get the text format of the expression.
`pretty_print`(obj)	Pretty print the object.
`get`(op_name)	Get the Op for a given name
`register_df_node`([type_key])	Register a Relay node type.
`is_var`([name])	Syntatic sugar for creating an optionally named VarPattern.
`is_constant`()	Syntatic sugar for creating a ConstantPattern.
`is_expr`(expr)	Syntatic sugar for creating an ExprPattern.
`is_op`(op_name)	Syntatic sugar for creating an operator ExprPattern.
`is_tuple`(fields)	Syntatic sugar for creating an ExprPattern.
`is_tuple_get_item`(tuple_value[, index])	Syntatic sugar for creating an ExprPattern.
`is_if`(cond, true_branch, false_branch)	Syntatic sugar for creating an IfPattern.
`is_let`(var, value, body)	Syntatic sugar for creating a LetPattern.
`wildcard`()	Syntatic sugar for creating a WildcardPattern.
`has_type`(ttype[, pattern])	Syntatic sugar for creating a TypePattern
`has_dtype`(dtype[, pattern])	Syntatic sugar for creating a DataTypePattern
`has_shape`(shape[, pattern])	Syntatic sugar for creating a ShapePattern
`has_attr`(attrs[, pattern])	Syntatic sugar for creating an AttrPattern
`dominates`(parent, path, child)	Syntatic sugar for creating an Dominator pattern
`match`(pattern, expr)	Match a pattern to an expression
`rewrite`(callbacks, expr[, mod])	Rewrite expression with the given callbacks.
`partition`(pattern, expr[, attrs, check])	Parition the expression into a series of functions that match the pattern

tvm.relay.dataflow_pattern.Expr: alias of RelayExpr

tvm.relay.dataflow_pattern.make_node(type_key, **kwargs)

Make a new IR node by its type key and fields

Parameters:

type_key (str) – The type key of the node.
**kwargs (dict) – The fields of the node.

Returns:

node – The corresponding IR Node

Return type:

Node

Note

If the created node is instance of AttrsNode, then the creator function will also run bound checks and default value setup as supported by Attrs.

Example

The following code constructs a IntImm object

x = tvm.ir.make_node("IntImm", dtype="int32", value=10, span=None)
assert isinstance(x, tvm.tir.IntImm)
assert x.value == 10

tvm.relay.dataflow_pattern.astext(obj: Object, show_meta_data=True, annotate=None)

Get the text format of the expression.

Parameters:

obj (Object) – The object to be printed.
show_meta_data (bool) – Whether to include meta data section in the text if there is meta data.
annotate (Optional[Object->str]) – Optionally annotate function to provide additional information in the comment block.

Returns:

text – The text format of the expression.

Return type:

str

Notes

The meta data section is necessary to fully parse the text format. However, it can contain dumps that are big (e.g constant weights), so it can be helpful to skip printing the meta data section.

tvm.relay.dataflow_pattern.pretty_print(obj: Object) → None: Pretty print the object.

tvm.relay.dataflow_pattern.get(op_name)

Get the Op for a given name

Parameters:: op_name (str) – The operator name
Returns:: op – The op of the corresponding name
Return type:: Op

tvm.relay.dataflow_pattern.register_df_node(type_key=None)

Register a Relay node type.

Parameters:: type_key (str or cls) – The type key of the node.

class tvm.relay.dataflow_pattern.DFPattern

Base class of all Patterns.

Methods:

`astext`([show_meta_data, annotate])	Get the text format of the expression.
`has_attr`(attrs)	Add an attribute constraint to this pattern
`has_type`(ttype)	Add a type constraint to this pattern
`has_dtype`(dtype)	Add a type constraint to this pattern
`has_shape`(shape)	Add a type constraint to this pattern
`match`(expr)	Match this pattern to an expression
`partition`(expr[, attrs, check])	Partition the expression into functions defined by this pattern
`dominates`(parent[, path])	Create a dominator for this pattern.
`optional`(option_constructor)	Create a optional user of this pattern.

astext(show_meta_data=True, annotate=None)

Get the text format of the expression.

Parameters:

show_meta_data (bool) – Whether to include meta data section in the text if there is meta data.
annotate (Optional[Object->str]) – Optionally annotate function to provide additional information in the comment block.

Returns:

text – The text format of the expression.

Return type:

str

Notes

The meta data section is necessary to fully parse the text format. However, it can contain dumps that are big (e.g constant weights), so it can be helpful to skip printing the meta data section.

has_attr(attrs: Dict[str, Object])

Add an attribute constraint to this pattern

Parameters:: attrs (Dict[str, Object])
Returns:: result – The resulting AttrPattern
Return type:: tvm.relay.dataflow_pattern.DFPattern

has_type(ttype: Type)

Add a type constraint to this pattern

Parameters:: ttype (tvm.ir.type.Type) – The type to match
Returns:: result – The resulting TypePattern
Return type:: tvm.relay.dataflow_pattern.DFPattern

has_dtype(dtype: str)

Add a type constraint to this pattern

Parameters:: dtype (str) – The dtype to match
Returns:: result – The resulting DataTypePattern
Return type:: tvm.relay.dataflow_pattern.DFPattern

has_shape(shape: List[PrimExpr])

Add a type constraint to this pattern

Parameters:: shape (List[tvm.ir.PrimExpr]) – The shape to match
Returns:: result – The resulting ShapePattern
Return type:: tvm.relay.dataflow_pattern.DFPattern

match(expr: RelayExpr) → bool

Match this pattern to an expression

Parameters:: expr (tvm.relay.Expr) – The expression to match.
Returns:: result – Whether or not the expression matches the pattern
Return type:: bool

partition(expr: ~tvm.ir.expr.RelayExpr, attrs: ~typing.Dict[str, ~tvm.runtime.object.Object] | None = None, check: ~typing.Callable[[~tvm.ir.expr.RelayExpr], bool] = <function DFPattern.<lambda>>) → RelayExpr

Partition the expression into functions defined by this pattern

Parameters:

expr (tvm.relay.Expr) – The expression to match.
attrs (Optional[Dict[str, Object]]) – A dictionary of Attribute name/values to add to the paritioned function
check (Callable[[Expr], bool]) – A function to perform more complicated checks on the matched expression. Returns true if partitioning should proceed, false otherwise.

Returns:

result – The Expression with matched subgraphs replaced by function calls to that subgraph

Return type:

tvm.relay.Expr

dominates(parent: DFPattern, path: DFPattern | None = None)

Create a dominator for this pattern.

Parameters:

parent (tvm.relay.dataflow_pattern.DFPattern) – The parent pattern this pattern dominates.
path (tvm.relay.dataflow_pattern.DFPattern) – The fuzzy path pattern.

Returns:

result – The resulting DominatorPattern.

Return type:

tvm.relay.dataflow_pattern.DFPattern

optional(option_constructor: Callable[[DFPattern], DFPattern])

Create a optional user of this pattern.

Parameters:: option_constructor (function) – A function that takes a single Pattern parameter and returns a constructed pattern matching the option
Returns:: result – The resulting Pattern
Return type:: tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.is_var(name: str = '') → DFPattern

Syntatic sugar for creating an optionally named VarPattern.

Parameters:: name (str) – The name of the input pattern to match.
Returns:: result – The resulting pattern.
Return type:: tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.is_constant() → DFPattern

Syntatic sugar for creating a ConstantPattern.

Parameters:: name (str) – The name of the input pattern to match.
Returns:: result – The resulting pattern.
Return type:: tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.is_expr(expr: RelayExpr) → DFPattern

Syntatic sugar for creating an ExprPattern.

Parameters:: expr (Expr) – The Relay expression to match.
Returns:: result – The resulting pattern.
Return type:: tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.is_op(op_name: str) → DFPattern

Syntatic sugar for creating an operator ExprPattern.

Parameters:: op_name (String) – The name of the relay op
Returns:: result – The resulting ExprPattern
Return type:: tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.is_tuple(fields: Array) → DFPattern

Syntatic sugar for creating an ExprPattern.

Parameters:: fields (Array[tvm.relay.dataflow_pattern.DFPattern]) – The fields in the tuple.
Returns:: result – The resulting pattern.
Return type:: tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.is_tuple_get_item(tuple_value: DFPattern, index: int | None = None) → DFPattern

Syntatic sugar for creating an ExprPattern.

Parameters:

tuple_value (tvm.relay.dataflow_pattern.DFPattern) – The input tuple expression.
index (Optional[int]) – The index to match; Default (None) to match a TupleGetItem with any index.

Returns:

result – The resulting pattern.

Return type:

tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.is_if(cond, true_branch, false_branch)

Syntatic sugar for creating an IfPattern.

Parameters:

cond (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the condition of If.
true_branch (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the true branch of If.
false_branch (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the false branch of If.

Returns:

result – The resulting pattern.

Return type:

tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.is_let(var, value, body)

Syntatic sugar for creating a LetPattern.

Parameters:

var (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the variable of Let.
value (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the value of Let.
body (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the body where the binding is in effect.

Returns:

result – The resulting pattern.

Return type:

tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.wildcard() → DFPattern

Syntatic sugar for creating a WildcardPattern.

Returns:: result – The resulting pattern.
Return type:: tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.has_type(ttype: Type, pattern: DFPattern | None = None) → DFPattern

Syntatic sugar for creating a TypePattern

Parameters:

ttype (tvm.ir.type.Type) – The type to match
pattern (tvm.relay.dataflow_pattern.DFPattern) – The pattern that needs type annotation

Returns:

result – The resulting TypePattern

Return type:

tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.has_dtype(dtype: str, pattern: DFPattern | None = None) → DFPattern

Syntatic sugar for creating a DataTypePattern

Parameters:

dtype (str) – The dtype to match
pattern (tvm.relay.dataflow_pattern.DFPattern) – The pattern that needs type annotation

Returns:

result – The resulting DataTypePattern

Return type:

tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.has_shape(shape: List[PrimExpr], pattern: DFPattern | None = None) → DFPattern

Syntatic sugar for creating a ShapePattern

Parameters:

shape (List[tvm.ir.PrimExpr]) – The shape to match
pattern (tvm.relay.dataflow_pattern.DFPattern) – The pattern that needs type annotation

Returns:

result – The resulting ShapePattern

Return type:

tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.has_attr(attrs, pattern=None) → DFPattern

Syntatic sugar for creating an AttrPattern

Parameters:

attrs (Dict[str, Object]) – The attributes to match
pattern (Optional[tvm.relay.dataflow_pattern.DFPattern]) – The input pattern.

Returns:

result – The resulting AttrPattern

Return type:

tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.dominates(parent: DFPattern, path: DFPattern, child: DFPattern) → DFPattern

Syntatic sugar for creating an Dominator pattern

Parameters:

parent (tvm.relay.dataflow_pattern.DFPattern) – The parent pattern.
path (tvm.relay.dataflow_pattern.DFPattern) – The fuzzy path pattern.
child (tvm.relay.dataflow_pattern.DFPattern) – The child pattern.

Returns:

result – The resulting DominatorPattern.

Return type:

tvm.relay.dataflow_pattern.DFPattern

tvm.relay.dataflow_pattern.match(pattern: DFPattern, expr: RelayExpr) → bool

Match a pattern to an expression

Parameters:

pattern (tvm.relay.dataflow_pattern.DFPattern) – The input pattern.
expr (tvm.relay.Expr) – The expression to match.

class tvm.relay.dataflow_pattern.ExprPattern(expr: RelayExpr)

A pattern which matches a constant expression.

Parameters:: expr (tvm.relay.Expr) – The expression to match.

class tvm.relay.dataflow_pattern.VarPattern(name_hint: str = '')

A local variable in Relay.

Local variable can be used to declare input arguments to a function, or intermediate variables.

Parameters:

name_hint (str) – The name of the variable. Optional, if not provided, the pattern will match any VarNode.
type_annotation (tvm.ir.type.Type, optional) – The type annotation on the variable.

class tvm.relay.dataflow_pattern.ConstantPattern: A pattern matching a Relay Constant.

class tvm.relay.dataflow_pattern.CallPattern(op: DFPattern, args: List[DFPattern])

A pattern matching a function call node in Relay.

Parameters:

op (relay.dataflow_pattern.DFPattern) – The operation to be called.
args (List[relay.dataflow_pattern.DFPattern]) – The arguments to the call or None to match any arguments.

class tvm.relay.dataflow_pattern.FunctionPattern(params: List[DFPattern], body: DFPattern)

A pattern matching a function node in Relay.

Parameters:

params (List[relay.dataflow_pattern.DFPattern]) – The parameters to the Function or None to match any parameters.
body (relay.dataflow_pattern.DFPattern) – The body fo the Function

class tvm.relay.dataflow_pattern.IfPattern(cond: DFPattern, true_branch: DFPattern, false_branch: DFPattern)

A patern matching a Relay If.

Parameters:

cond (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the condition of If.
true_branch (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the true branch of If.
false_branch (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the false branch of If.

class tvm.relay.dataflow_pattern.LetPattern(var: DFPattern, value: DFPattern, body: DFPattern)

A patern matching a Relay Let.

Parameters:

var (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the variable of Let.
value (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the value of Let.
body (tvm.relay.dataflow_pattern.DFPattern) – The pattern describing the body where the binding is in effect.

class tvm.relay.dataflow_pattern.TuplePattern(fields: Array)

A patern matching a Relay Tuple.

Parameters:: fields (Array[tvm.relay.dataflow_pattern.DFPattern]) – The fields in the tuple.

class tvm.relay.dataflow_pattern.TupleGetItemPattern(tuple_value: DFPattern, index: int | None = None)

Get index-th item from a TuplePattern.

Parameters:

tuple_value (tvm.relay.dataflow_pattern.DFPattern) – The input tuple expression.
index (Optional[int]) – The index to match; Default (None) to match a TupleGetItem with any index.

class tvm.relay.dataflow_pattern.AltPattern(left: DFPattern, right: DFPattern)

Create a Pattern that can match one of two conditions

Parameters:

left (tvm.relay.dataflow_pattern.DFPattern) – One possible matching pattern.
right (tvm.relay.dataflow_pattern.DFPattern) – One possible matching pattern.

class tvm.relay.dataflow_pattern.WildcardPattern

A pattern which matches anything.

Methods:

redirect_to(pat)

Redirect the WildcardPattern to another pattern

redirect_to(pat: DFPattern)

Redirect the WildcardPattern to another pattern

Parameters:: pat (relay.dataflow_pattern.DFPattern) – The pattern that wildcard is redirected to.

class tvm.relay.dataflow_pattern.TypePattern(pattern: DFPattern, ttype: Type)

A pattern that matches another pattern with a certain type annotation.

Parameters:

pattern (tvm.relay.dataflow_pattern.DFPattern) – The input pattern that needs type annotation.
ttype (tvm.ir.type.Type) – The type to match.

class tvm.relay.dataflow_pattern.DataTypePattern(pattern: DFPattern, dtype: str)

A pattern that matches another pattern with certain data type

Parameters:

pattern (tvm.relay.dataflow_pattern.DFPattern) – The input pattern that needs type annotation.
dtype (str) – The dtype to match.

class tvm.relay.dataflow_pattern.ShapePattern(pattern: DFPattern, shape: List[PrimExpr])

A pattern that matches another pattern with a certain tensor shape

Parameters:

pattern (tvm.relay.dataflow_pattern.DFPattern) – The input pattern that needs type annotation.
shape (List[tvm.ir.PrimExpr]) – The shape to match.

class tvm.relay.dataflow_pattern.AttrPattern(pattern: DFPattern, attrs: Attrs)

Get match an expression with a certain attributes. Currently only supports Op Attributes, not call Attributes.

Parameters:

pattern (tvm.relay.dataflow_pattern.DFPattern) – The input pattern.
attrs (tvm.ir.attrs.Attrs) – The attributes to match.

class tvm.relay.dataflow_pattern.DominatorPattern(parent: DFPattern, path: DFPattern, child: DFPattern)

Match a domination graph.

Parameters:

parent (tvm.relay.dataflow_pattern.DFPattern) – The parent, i.e., the single node which produces something, later aggregated by the child.
path (tvm.relay.dataflow_pattern.DFPattern) – The fuzzy path pattern between parent and child, typically matches elementwise ops.
child (tvm.relay.dataflow_pattern.DFPattern) – The last node in the domination which is the end user for all nodes in the path and the parent.

class tvm.relay.dataflow_pattern.DFPatternCallback(require_type=False, rewrite_once=False)

A Callback for Pattern Rewriting.

When rewrite is called on this DFPatternCallback, the backend will find matches for the pattern, call the callback function, and replace the matched expression with whatever the callback returns.

Users are expect to inherit from this class and provide a “self.pattern” to match

Parameters:

require_type (bool) – Whether InferType is required to be run before the callback.
rewrite_once (bool) – If True, run the callback only once.

Methods:

`rewrite`(expr)	Rewrite expression with this callback
`callback`(pre, post, node_map)	Callback function to use when we found a match to the pattern

rewrite(expr: RelayExpr) → RelayExpr

Rewrite expression with this callback

Parameters:: expr (tvm.relay.Expr) – The expression to rewrite.
Returns:: result – The Expression with matched subgraphs rewritten by the callbacks.
Return type:: tvm.relay.Expr

callback(pre: RelayExpr, post: RelayExpr, node_map: Map) → RelayExpr

Callback function to use when we found a match to the pattern

Parameters:

pre (tvm.relay.Expr) – The matching expression from the original graph.
post (tvm.relay.Expr) – The matching expression with rewritten inputs
node_map (tvm.ir.container.Map[DFPattern, List[Expr]]) – The map between patterns and matched expressions

Returns:

result – The Expression with matched subgraph rewritten by the callback

Return type:

tvm.relay.Expr

tvm.relay.dataflow_pattern.rewrite(callbacks, expr: RelayExpr, mod: IRModule | None = None) → RelayExpr

Rewrite expression with the given callbacks.

Parameters:

callbacks (tvm.relay.dataflow_pattern.DFPatternCallback) – The input callback or list of callbacks.
expr (tvm.relay.Expr) – The expression to rewrite.
mod (Optional[tvm.ir.IRModule]) – The module that associates with the expression.

Returns:

result – The Expression with matched subgraphs rewritten by the callbacks.

Return type:

tvm.relay.Expr

tvm.relay.dataflow_pattern.partition(pattern: ~tvm.relay.dataflow_pattern.DFPattern, expr: ~tvm.ir.expr.RelayExpr, attrs: ~typing.Dict[str, ~tvm.runtime.object.Object] | None = None, check: ~typing.Callable[[~tvm.ir.expr.RelayExpr], bool] = <function <lambda>>) → RelayExpr

Parition the expression into a series of functions that match the pattern

Parameters:

pattern (tvm.relay.dataflow_pattern.DFPattern) – The pattern to match
expr (tvm.relay.Expr) – The expression to split into functions
attrs (Optional[Dict[str, Object]]) – A dict of attributes to apply to the partitioned function
check (Callable[[Expr], bool]) – A function to perform more complicated checks on the matched expression. Returns true if partitioning should proceed, false otherwise.

Returns:

result – The Expression with matched subgraphs replaced by function calls to that subgraph

Return type:

tvm.relay.Expr