# tvm.ir¶

Common data structures across all IR variants.

Classes

 Array Array container of TVM. Attrs Attribute node, which is mainly use for defining attributes of relay operators. BaseExpr Base class of all the expressions. BaseFunc Base class of all functions. Constructor(name_hint, inputs, belong_to) Relay ADT constructor. DictAttrs Dictionary attributes. EnvFunc Environment function. FuncType(arg_types, ret_type[, type_params, …]) Function type. GlobalTypeVar(name_hint[, kind]) A global type variable that is used for defining new types or type aliases. GlobalVar(name_hint) A global variable in the IR. IRModule([functions, type_definitions]) IRModule that holds functions and type definitions. IncompleteType([kind]) Incomplete type during type inference. Map Map container of TVM. Node Base class of all IR Nodes, implements astext function. PointerType(element_type) PointerType used in the low-level TIR. PrimExpr Base class of all primitive expressions. PrimType(dtype) Primitive data type in the low level IR Range(begin[, end]) Represent a range in TVM. RelayExpr Base class of all non-primitive expressions. RelayRefType(value) Reference Type in relay. SourceName(name) A identifier for a source location. Span(source, lineno, col_offset) Specifies a location in a source program. TensorType(shape[, dtype]) A concrete TensorType in Relay. TupleType(fields) The type of tuple values. Type The base class of all types. TypeCall(func, args) Type function application. TypeConstraint Abstract class representing a type constraint. TypeData(header, type_vars, constructors) Stores the definition for an Algebraic Data Type (ADT) in Relay. TypeKind Possible kinds of TypeVars. TypeRelation(func, args, num_inputs, attrs) User defined type relation, it is an input-output relation on types. TypeVar(name_hint[, kind]) Type parameter in functions.

Functions

 assert_structural_equal(lhs, rhs[, …]) Assert lhs and rhs are structurally equal to each other. load_json(json_str) Load tvm object from json_str. make_node(type_key, **kwargs) Make a new IR node by its type key and fields save_json(node) Save tvm object as json string. structural_equal(lhs, rhs[, map_free_vars]) Check structural equality of lhs and rhs. structural_hash(node[, map_free_vars]) Compute structural hash of node
class tvm.ir.SourceName(name)

A identifier for a source location.

Parameters

name (str) – The name of the source.

class tvm.ir.Span(source, lineno, col_offset)

Specifies a location in a source program.

Parameters
• source (SourceName) – The source name.

• lineno (int) – The line number.

• col_offset (int) – The column offset of the location.

class tvm.ir.Node

Base class of all IR Nodes, implements astext function.

Methods

 astext([show_meta_data, annotate]) Get the text format of the expression.
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.

class tvm.ir.EnvFunc

Environment function.

This is a global function object that can be serialized by its name.

Methods

 get(name) Get a static env function
static get(name)

Get a static env function

Parameters

name (str) – The name of the function.

tvm.ir.load_json(json_str)

Load tvm object from json_str.

Parameters

json_str (str) – The json string

Returns

node – The loaded tvm node.

Return type

Object

tvm.ir.save_json(node)

Save tvm object as json string.

Parameters

node (Object) – A TVM object to be saved.

Returns

json_str – Saved json string.

Return type

str

tvm.ir.structural_equal(lhs, rhs, map_free_vars=False)

Check structural equality of lhs and rhs.

The structural equality is recursively defined in the DAG of IRNodes. There are two kinds of nodes:

• Graph node: a graph node in lhs can only be mapped as equal to one and only one graph node in rhs.

• Normal node: equality is recursively defined without the restriction of graph nodes.

Vars(tir::Var, TypeVar) and non-constant relay expression nodes are graph nodes. For example, it means that %1 = %x + %y; %1 + %1 is not structurally equal to %1 = %x + %y; %2 = %x + %y; %1 + %2 in relay.

A var-type node(e.g. tir::Var, TypeVar) can be mapped as equal to another var with the same type if one of the following condition holds:

• They appear in a same definition point(e.g. function argument).

• They points to the same VarNode via the same_as relation.

• They appear in a same usage point, and map_free_vars is set to be True.

The rules for var are used to remap variables occurs in function arguments and let-bindings.

Parameters
• lhs (Object) – The left operand.

• rhs (Object) – The left operand.

• map_free_vars (bool) – Whether or not shall we map free vars that does not bound to any definitions as equal to each other.

Returns

result – The comparison result.

Return type

bool

See also

structural_hash(), assert_strucural_equal()

tvm.ir.assert_structural_equal(lhs, rhs, map_free_vars=False)

Assert lhs and rhs are structurally equal to each other.

Parameters
• lhs (Object) – The left operand.

• rhs (Object) – The left operand.

• map_free_vars (bool) – Whether or not shall we map free vars that does not bound to any definitions as equal to each other.

:raises ValueError : if assertion does not hold.:

tvm.ir.structural_hash(node, map_free_vars=False)

Compute structural hash of node

The structural hash value is recursively defined in the DAG of IRNodes. There are two kinds of nodes:

• Normal node: the hash value is defined by its content and type only.

• Graph node: each graph node will be assigned a unique index ordered by the first occurence during the visit. The hash value of a graph node is combined from the hash values of its contents and the index.

structural_hash is made to be concistent with structural_equal. If two nodes are structurally equal to each other, then their structural hash (with the same map_free_vars option) should be equal to each other as well.

If the structural hash of two nodes equals to each other, then it is highly likely(except for rare hash value collison cases) that the two nodes are structurally equal to each other.

Parameters
• node (Object) – The input to be hashed.

• map_free_vars (bool) – If map_free_vars is set to true, we will hash free variables by the order of their occurences. Otherwise, we will hash by their in-memory pointer address.

Returns

result – The hash result

Return type

int

See also

structrual_equal()

class tvm.ir.Type

The base class of all types.

Methods

 same_as(other) Compares two Relay types by referential equality.
same_as(other)

Compares two Relay types by referential equality.

class tvm.ir.TypeKind

Possible kinds of TypeVars.

class tvm.ir.PrimType(dtype)

Primitive data type in the low level IR

Parameters

dtype (str) – The runtime data type relates to the primtype.

class tvm.ir.PointerType(element_type)

PointerType used in the low-level TIR.

Parameters

element_type (tvm.ir.Type) – The type of pointer’s element.

class tvm.ir.TypeVar(name_hint, kind=<TypeKind.Type: 0>)

Type parameter in functions.

A type variable represents a type placeholder which will be filled in later on. This allows the user to write functions which are generic over types.

Parameters
• name_hint (str) – The name of the type variable. This name only acts as a hint, and is not used for equality.

• kind (Optional[TypeKind]) – The kind of the type parameter.

class tvm.ir.GlobalTypeVar(name_hint, kind=<TypeKind.AdtHandle: 5>)

A global type variable that is used for defining new types or type aliases.

Parameters
• name_hint (str) – The name of the type variable. This name only acts as a hint, and is not used for equality.

• kind (Optional[TypeKind]) – The kind of the type parameter.

class tvm.ir.TupleType(fields)

The type of tuple values.

Parameters

fields (List[Type]) – The fields in the tuple

class tvm.ir.TypeConstraint

Abstract class representing a type constraint.

class tvm.ir.FuncType(arg_types, ret_type, type_params=None, type_constraints=None)

Function type.

A function type consists of a list of type parameters to enable the definition of generic functions, a set of type constraints which we omit for the time being, a sequence of argument types, and a return type.

We can informally write them as: forall (type_params), (arg_types) -> ret_type where type_constraints

Parameters
• arg_types (List[tvm.relay.Type]) – The argument types

• ret_type (tvm.relay.Type) – The return type.

• type_params (Optional[List[tvm.relay.TypeVar]]) – The type parameters

• type_constraints (Optional[List[tvm.relay.TypeConstraint]]) – The type constraints.

class tvm.ir.IncompleteType(kind=<TypeKind.Type: 0>)

Incomplete type during type inference.

kindOptional[TypeKind]

The kind of the incomplete type.

class tvm.ir.RelayRefType(value)

Reference Type in relay.

Parameters

value (Type) – The value type.

class tvm.ir.TensorType(shape, dtype='float32')

A concrete TensorType in Relay.

This is the type assigned to tensors with a known dtype and shape. For example, a tensor of float32 and (5, 5).

Parameters
• shape (List[tvm.ir.PrimExpr]) – The shape of the Tensor

• dtype (Optional[str]) – The content data type.

Attributes

 concrete_shape Get shape of the type as concrete tuple of int.
property concrete_shape

Get shape of the type as concrete tuple of int.

Returns

shape – The concrete shape of the Type.

Return type

List[int]

:raises TypeError : If the shape is symbolic:

class tvm.ir.TypeCall(func, args)

Type function application.

Parameters
Returns

type_call – The type function application.

Return type

TypeCall

class tvm.ir.TypeRelation(func, args, num_inputs, attrs)

User defined type relation, it is an input-output relation on types.

TypeRelation is more generalized than TypeCall as it allows inference

of both inputs and outputs.

Parameters
• func (EnvFunc) – User defined relation function.

• args ([tvm.ir.Type]) – List of types to the func.

• num_inputs (int) – Number of input arguments in args, this act as a hint for type inference.

• attrs (Attrs) – The attribute attached to the relation information

Returns

type_relation – The type relation.

Return type

tvm.ir.TypeRelation

class tvm.ir.BaseExpr

Base class of all the expressions.

class tvm.ir.PrimExpr

Base class of all primitive expressions.

PrimExpr is used in the low-level code optimizations and integer analysis.

class tvm.ir.RelayExpr

Base class of all non-primitive expressions.

Attributes

 checked_type Get the checked type of tvm.relay.Expr.
property checked_type

Get the checked type of tvm.relay.Expr.

Returns

checked_type – The checked type.

Return type

tvm.relay.Type

class tvm.ir.GlobalVar(name_hint)

A global variable in the IR.

GlobalVar is used to refer to the global functions stored in the IRModule.

Parameters

name_hint (str) – The name of the variable.

class tvm.ir.Range(begin, end=None)

Represent a range in TVM.

You do not need to create a Range explicitly. Python lists and tuples will be converted automatically to a Range in API functions.

Parameters
• begin (PrimExpr) – The begin value of the range when end is None. Otherwise it is the length of the range.

• end (Optional[PrimExpr]) – The end value of the range.

Methods

 make_by_min_extent(min_value, extent) Construct a Range by min and extent.

Note

The constructor creates the range [begin, end) if the end argument is not None. Otherwise, it creates [0, begin).

static make_by_min_extent(min_value, extent)

Construct a Range by min and extent.

This constructs a range in [min_value, min_value + extent)

Parameters
• min_value (PrimExpr) – The minimum value of the range.

• extent (PrimExpr) – The extent of the range.

Returns

rng – The constructed range.

Return type

Range

class tvm.ir.BaseFunc

Base class of all functions.

Attributes

 attrs Return the attrs member of the function.
property attrs

Return the attrs member of the function.

class tvm.ir.Constructor(name_hint, inputs, belong_to)

Relay ADT constructor.

Parameters
• name_hint (str) – Name of constructor (only a hint).

• inputs (List[Type]) – Input types.

• belong_to (GlobalTypeVar) – Denotes which ADT the constructor belongs to.

class tvm.ir.TypeData(header, type_vars, constructors)

Stores the definition for an Algebraic Data Type (ADT) in Relay.

Note that ADT definitions are treated as type-level functions because the type parameters need to be given for an instance of the ADT. Thus, any global type var that is an ADT header needs to be wrapped in a type call that passes in the type params.

Parameters
• header (GlobalTypeVar) – The name of the ADT. ADTs with the same constructors but different names are treated as different types.

• type_vars (List[TypeVar]) – Type variables that appear in constructors.

• constructors (List[Constructor]) – The constructors for the ADT.

class tvm.ir.IRModule(functions=None, type_definitions=None)

IRModule that holds functions and type definitions.

IRModule is the basic unit for all IR transformations across the stack.

Parameters

functions (Optional[dict]) – Map of global var to BaseFunc

Methods

 from_expr(expr[, functions, type_defs]) Construct a module from a standalone expression. Look up an ADT constructor by tag. Get a global type variable in the function by name. Collect all global type vars defined in this module. get_global_var(name) Get a global variable in the function by name. Collect all global vars defined in this module. update(other) Insert functions in another Module to current one.
update(other)

Insert functions in another Module to current one.

Parameters

other (IRModule) – The module to merge into the current Module.

get_global_var(name)

Get a global variable in the function by name.

Parameters

name (str) – The name of the global variable.

Returns

global_var – The global variable mapped to name.

Return type

GlobalVar

Raises

tvm.error.TVMError if we cannot find corresponding global var.

get_global_vars()

Collect all global vars defined in this module.

Returns

global_vars – An array of global vars.

Return type
get_global_type_vars()

Collect all global type vars defined in this module.

Returns

global_type_vars – An array of global type vars.

Return type
get_global_type_var(name)

Get a global type variable in the function by name.

Parameters

name (str) – The name of the global type variable.

Returns

global_type_var – The global variable mapped to name.

Return type

GlobalTypeVar

Raises

tvm.error.TVMError if we cannot find corresponding global type var.

get_constructor(tag)

Look up an ADT constructor by tag.

Parameters

tag (int) – The tag for a constructor.

Returns

constructor – The constructor associated with the given tag,

Return type

Constructor

Raises

tvm.error.TVMError if the corresponding constructor cannot be found.

static from_expr(expr, functions=None, type_defs=None)

Construct a module from a standalone expression.

Parameters
• expr (RelayExpr) – The starting expression

• global_funcs (Optional[dict]) – Map of global vars to function definitions

• type_defs (Optional[dict]) – Map of global type vars to type definitions

Returns

mod – A module containing the passed definitions, where expr is set as the entry point (wrapped in a function if necessary)

Return type

Module

class tvm.ir.Attrs

Attribute node, which is mainly use for defining attributes of relay operators.

Used by function registered in python side, such as compute, schedule and alter_layout. Attrs is passed as the first argument to these functions.

Methods

 get_int(key) Get a python int value of a key Get a python int tuple of a key get_str(key) Get a python int value of a key Get list of names in the attribute. Get fields information
list_field_info()

Get fields information

Returns

infos – List of field information

Return type

list of AttrFieldInfo

keys()

Get list of names in the attribute.

Returns

keys – List of keys

Return type

list of str

get_int_tuple(key)

Get a python int tuple of a key

Parameters

key (str) –

Returns

value

Return type

Tuple of int

get_int(key)

Get a python int value of a key

Parameters

key (str) –

Returns

value

Return type

int

get_str(key)

Get a python int value of a key

Parameters

key (str) –

Returns

value

Return type

int

class tvm.ir.DictAttrs

Dictionary attributes.

Methods

 Get items from the map. Get list of names in the attribute.
keys()

Get list of names in the attribute.

Returns

keys – List of keys

Return type

list of str

items()

Get items from the map.

tvm.ir.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)
assert isinstance(x, tvm.tir.IntImm)
assert x.value == 10

class tvm.ir.Array

Array container of TVM.

You do not need to create Array explicitly. Normally python list and tuple will be converted automatically to Array during tvm function call. You may get Array in return values of TVM function call.

class tvm.ir.Map

Map container of TVM.

You do not need to create Map explicitly. Normally python dict will be converted automaticall to Map during tvm function call. You can use convert to create a dict[Object-> Object] into a Map

Methods

 Get the items from the map
items()

Get the items from the map