tvm
Namespaces | Classes | Typedefs | Enumerations | Functions
tvm::relax Namespace Reference

Namespaces

 attr
 
 distributed
 
 transform
 

Classes

struct  VarUsageInfo
 A utility struct returned by CollectVarUsage. More...
 
struct  AllReduceAttrs
 Attributes used in allreduce operators. More...
 
struct  ScatterCollectiveAttrs
 Attributes used in scatter operators. More...
 
struct  InitAttrs
 Attributes used in full/full_like, ones/ones_like, and zeros/zeros_like operators. More...
 
struct  TriluAttrs
 Attributes used in tril and triu operator. More...
 
struct  AstypeAttrs
 Attributes used in astype operator. More...
 
struct  WrapParamAttrs
 Attributes used in wrap_param operator. More...
 
struct  DistributionAttrs
 Attributes for redistribute and annotate_sharding operator. More...
 
struct  Resize2DAttrs
 Attributes used in image resize2d operator. More...
 
struct  TakeAttrs
 Attributes used in take operator. More...
 
struct  StridedSliceAttrs
 Attributes used in strided_slice operator. More...
 
struct  MatmulAttrs
 Attributes for matmul operator. More...
 
struct  EinsumAttrs
 Attributes used in einsum operator. More...
 
struct  ConcatAttrs
 Attributes used in concat operators. More...
 
struct  ExpandDimsAttrs
 Attributes used in expand_dims operators. More...
 
struct  LayoutTransformAttrs
 Attributes used in layout_transform operator. More...
 
struct  PermuteDimsAttrs
 Attributes used in permute_dims operator. More...
 
struct  SplitAttrs
 Attributes used in split operator. More...
 
struct  SqueezeAttrs
 Attributes used in squeeze operators. More...
 
struct  RepeatAttrs
 Attributes used in repeat operators. More...
 
struct  TileAttrs
 Attributes used in tile operators. More...
 
struct  FlipAttrs
 Attributes used in flip operators. More...
 
struct  ScatterElementsAttrs
 Attributes used in scatter_elements operators. More...
 
struct  Conv1DAttrs
 Attributes used in Conv1d operator. More...
 
struct  Conv2DAttrs
 Attributes used in Conv2d operator. More...
 
struct  Conv3DAttrs
 Attributes used in Conv3d operator. More...
 
struct  Conv1DTransposeAttrs
 Attributes used in Conv1DTranspose operator. More...
 
struct  Conv2DTransposeAttrs
 Attributes used in Conv2d operator. More...
 
struct  Pool1DAttrs
 Attributes used in max_pool1d and avg_pool1d operator. More...
 
struct  Pool2DAttrs
 Attributes used in max_pool2d and avg_pool2d operator. More...
 
struct  Pool3DAttrs
 Attributes used in max_pool3d and avg_pool3d operator. More...
 
struct  AdaptivePool1DAttrs
 Attributes for 1d adaptive pool operator. More...
 
struct  AdaptivePool2DAttrs
 Attributes for 2d adaptive pool operator. More...
 
struct  AdaptivePool3DAttrs
 Attributes for 3d adaptive pool operator. More...
 
struct  SoftmaxAttrs
 Attributes used in softmax operators. More...
 
struct  LeakyReluAttrs
 Attributes used in softmax operators. More...
 
struct  BatchNormAttrs
 Attributes used in batch_norm operator. More...
 
struct  LayerNormAttrs
 Attributes used in layer_norm operator. More...
 
struct  GroupNormAttrs
 Attributes used in group_norm operator. More...
 
struct  RMSNormAttrs
 Attributes used in rms_norm operator. More...
 
struct  NLLLossAttrs
 Attributes used in nll_loss operator. More...
 
struct  DropoutAttrs
 Attributes used in dropout operator. More...
 
struct  AttentionAttrs
 Attributes used in Attention operator. More...
 
struct  PadAttrs
 Attributes used for the padding operator. More...
 
struct  CallTIRWithGradAttrs
 Attributes used in call_tir_with_grad. More...
 
struct  CallTIRInplaceAttrs
 Attributes used in call_tir_inplace. More...
 
struct  CallInplacePackedAttrs
 Attributes used in call_inplace_packed. More...
 
struct  ToVDeviceAttrs
 Attributes used in to_vdevice. More...
 
struct  HintOnDeviceAttrs
 Attributes used in hint_on_device. More...
 
struct  QuantizeAttrs
 Attributes for relax.quantize/relax.dequantize operator. More...
 
struct  ArgmaxArgminAttrs
 Attributes for search operators. More...
 
struct  SortAttrs
 Attributes used in sort operator. More...
 
struct  ArgsortAttrs
 Attributes used in argsort operator. More...
 
struct  TopKAttrs
 Attributes used in topk operator. More...
 
struct  StatisticalAttrs
 Attributes for statistical operators. More...
 
struct  ScanopAttrs
 Attributes used in scan operators like cumsum, cumprod. More...
 
class  DataflowBlockRewriteNode
 Statement rewriter for relax.DataflowBlock. More...
 
class  DataflowBlockRewrite
 A statement rewriter for relax.DataflowBlock. More...
 
class  BlockBuilderNode
 A builder to build Relax binding blocks. More...
 
class  BlockBuilder
 
class  DFPatternNode
 Base type of all dataflow patterns. More...
 
class  DFPattern
 Managed reference to dataflow patterns. More...
 
struct  PairCons
 Constraint of a DFPattern edge (producer -> consumer) in graph-level matching. More...
 
class  DFConstraintNode
 Additional constraints on the graph. More...
 
class  DFConstraint
 
class  PatternSeqNode
 A sequence of DFPatterns that the previous DFPattern is connected to the next one. More...
 
class  PatternSeq
 Managed reference to pattern sequences. More...
 
class  PatternContextNode
 A context to manage the graph-level pattern matching. More...
 
class  PatternContext
 Managed reference to a pattern context. More...
 
class  ExprPatternNode
 Pattern for Relax Expression. More...
 
class  ExprPattern
 Managed reference to an ExprPattern. More...
 
class  VarPatternNode
 A Pattern to Match a Relax Variable. More...
 
class  VarPattern
 Managed reference to a VarPattern. More...
 
class  DataflowVarPatternNode
 A Pattern to Match a Relax Dataflow Variable. More...
 
class  DataflowVarPattern
 Managed reference to a DataflowVarPattern. More...
 
class  GlobalVarPatternNode
 A Pattern to Match a Relax Global Variable. More...
 
class  GlobalVarPattern
 Managed reference to a GlobalVarPattern. More...
 
class  ConstantPatternNode
 A Pattern to Match a Relax Constant. More...
 
class  ConstantPattern
 Managed reference to a ConstantPattern. More...
 
class  CallPatternNode
 A pattern to match a callable node in Relax. More...
 
class  CallPattern
 
class  PrimArrPatternNode
 A pattern to match an array of PrimExpr. More...
 
class  PrimArrPattern
 Managed reference to a PrimArrPattern. More...
 
class  FunctionPatternNode
 A pattern to match a Relax Function. More...
 
class  FunctionPattern
 Managed reference to FunctionPatternNode. More...
 
class  TuplePatternNode
 Pattern to match a tuple of ordered expressions. More...
 
class  TuplePattern
 Managed reference to TuplePatternNode. More...
 
class  UnorderedTuplePatternNode
 A pattern to match multiple expressions unorderedly. More...
 
class  UnorderedTuplePattern
 Managed reference to UnorderedTuplePatternNode. More...
 
class  TupleGetItemPatternNode
 A pattern to match n'th indexing to a tuple. More...
 
class  TupleGetItemPattern
 Managed reference to TupleGetItemPatternNode. More...
 
class  AndPatternNode
 Match a conjunction of other patterns. More...
 
class  AndPattern
 Managed reference to AndPatternNode. More...
 
class  OrPatternNode
 Match a disjunction of other patterns. More...
 
class  OrPattern
 Managed reference to OrPatternNode. More...
 
class  NotPatternNode
 Pattern for rejecting a certain pattern. More...
 
class  NotPattern
 Managed reference to NotPatternNode. More...
 
class  WildcardPatternNode
 Wildcard Pattern is a pattern that can match anything. More...
 
class  WildcardPattern
 Managed reference to WildcardPatternNode. More...
 
class  TypePatternNode
 Pattern for matching a certain type. More...
 
class  TypePattern
 Managed reference to TypePatternNode. More...
 
class  StructInfoPatternNode
 Pattern for matching a certain struct info. More...
 
class  StructInfoPattern
 
class  ShapePatternNode
 A pattern that asserting a root pattern has a certain shape. More...
 
class  ShapePattern
 Managed reference to ShapePatternNode. More...
 
class  SameShapeConstraintNode
 A pattern that asserting multiple root patterns have the same shape. More...
 
class  SameShapeConstraint
 Managed reference to SameShapePatternNode. More...
 
class  DataTypePatternNode
 A pattern that asserting a root pattern has a certain data type. More...
 
class  DataTypePattern
 Managed reference to DataTypePatternNode. More...
 
class  AttrPatternNode
 A pattern that asserting a root pattern has certain attributes. More...
 
class  AttrPattern
 Managed reference to AttrPatternNode. More...
 
class  ExternFuncPatternNode
 A pattern of external function. More...
 
class  ExternFuncPattern
 Managed reference to ExternFuncPatternNode. More...
 
class  DFPatternFunctor
 A dynamical functor that dispatches on in the first DFPattern argument. More...
 
class  DFPatternFunctor< R(const DFPattern &n, Args...)>
 
class  DFPatternVisitor
 A simple visitor wrapper around DFPatternFunctor. Recursively visit the content. More...
 
class  ExecBuilderNode
 A builder provides api to build VM executable with instructions. More...
 
class  ExecBuilder
 
class  IdNode
 The unique identifier of variables. More...
 
class  Id
 
class  StructInfoNode
 Base type of all structure information. More...
 
class  StructInfo
 Managed reference to StructInfoNode. More...
 
class  CallNode
 Call corresponds to callable invocation. Corresponds to operation in computational graph terminology. More...
 
class  Call
 
class  TupleNode
 Tuple container. More...
 
class  Tuple
 
class  TupleGetItemNode
 Get index-th field out of a tuple. More...
 
class  TupleGetItem
 
class  LeafExprNode
 Base type of all (non-function) leaf Exprs. More...
 
class  LeafExpr
 Managed reference to BaseExprNode. More...
 
class  ShapeExprNode
 A shape expression which allows users to construct a shape containing PrimExpr. More...
 
class  ShapeExpr
 
class  VarNode
 The variable class for all Relax bindings. More...
 
class  Var
 
class  DataflowVarNode
 A sub-type of the variable node used to mark dataflow variables from normal visible "function local" bindings. More...
 
class  DataflowVar
 
class  ConstantNode
 Constant tensor. More...
 
class  Constant
 
class  PrimValueNode
 PrimValue. More...
 
class  PrimValue
 Managed reference to PrimValueNode. More...
 
class  StringImmNode
 Represent a string literal constant. More...
 
class  StringImm
 Managed reference to StringImm. More...
 
class  DataTypeImmNode
 Represent a data type constant. More...
 
class  DataTypeImm
 Managed reference to DataTypeImm. More...
 
class  BindingNode
 The base class of a variable binding in Relax. More...
 
class  Binding
 
class  MatchCastNode
 Runtime-match the value to the struct info. More...
 
class  MatchCast
 Managed reference to MatchCastNode. More...
 
class  VarBindingNode
 
class  VarBinding
 
class  BindingBlockNode
 
class  BindingBlock
 
class  DataflowBlockNode
 
class  DataflowBlock
 
class  SeqExprNode
 A sequence of blocks followed by an expression. More...
 
class  SeqExpr
 
class  IfNode
 Condition expression. More...
 
class  If
 
class  FunctionNode
 A Relax function. More...
 
class  Function
 
class  ExternFuncNode
 The extern function, which can represent packed function. More...
 
class  ExternFunc
 
class  ExprFunctor
 A dynamical functor that dispatches on in the first Expr argument. You can use this as a more powerful Visitor, since it allows you to define function signatures of Visit Function. More...
 
class  ExprFunctor< R(const Expr &n, Args...)>
 
class  ExprVisitor
 A simple visitor wrapper around ExprFunctor. Recursively visit the content. More...
 
class  ExprMutatorBase
 A mutator works in unnormalized form. More...
 
class  ExprMutator
 A mutator works in normal form. More...
 
class  NestedMsg
 Container that stores possibly nested message with leaf message type T. More...
 
class  ObjectStructInfoNode
 Opaque object. More...
 
class  ObjectStructInfo
 Managed reference to ObjectStructInfoNode. More...
 
class  PrimStructInfoNode
 Primitive value. More...
 
class  PrimStructInfo
 Managed reference to PrimStructInfoNode. More...
 
class  ShapeStructInfoNode
 StructInfo of shape value. More...
 
class  ShapeStructInfo
 Managed reference to ShapeStructInfoNode. More...
 
class  TensorStructInfoNode
 StructInfo of Tensor. More...
 
class  TensorStructInfo
 Managed reference to TensorStructInfoNode. More...
 
class  TupleStructInfoNode
 StructInfo of Tuple. More...
 
class  TupleStructInfo
 Managed reference to TupleStructInfoNode. More...
 
class  FuncStructInfoNode
 Structure information about function. More...
 
class  FuncStructInfo
 Managed reference to FuncStructInfoNode. More...
 
class  StructInfoFunctor
 
class  StructInfoFunctor< R(const StructInfo &n, Args...)>
 
class  StructInfoVisitor
 A struct info visitor. More...
 
class  StructInfoMutator
 StructInfoMutator that mutates struct info. More...
 
class  MatchResultNode
 
class  MatchResult
 Managed reference to MatchResultNode. More...
 
class  ChoiceNode
 Choice manages a set of keys for transformation and constraint functions. More...
 
class  Choice
 Managed reference to ChoiceNode. More...
 
class  KnobNode
 Knob manages a set of valid choices for an optimization. More...
 
class  Knob
 Managed reference to KnobNode. More...
 
class  TraceNode
 Trace manages history of optimization decisions. More...
 
class  Trace
 Managed reference to TraceNode. More...
 
class  TuningRecordNode
 The class of tuning records. More...
 
class  TuningRecord
 The managed reference of TuningRecordNode. More...
 
struct  WorkloadEqual
 The equality check for Workload. More...
 
class  DatabaseNode
 
class  Database
 Managed reference to DatabaseNode. More...
 
class  ShapeTypeNode
 
class  ShapeType
 
class  ObjectTypeNode
 
class  ObjectType
 
class  DynTensorTypeNode
 
class  DynTensorType
 Managed reference to DynTensorTypeNode. More...
 
class  PackedFuncTypeNode
 
class  PackedFuncType
 

Typedefs

using Expr = RelayExpr
 
using ExprNode = RelayExprNode
 
using FInferStructInfo = runtime::TypedPackedFunc< StructInfo(const Call &call, const BlockBuilder &ctx)>
 Infer output struct info given the call. More...
 
using FCallPacked = String
 Packed function implementation for operators. The relax operator will be lowered to this packed function call during codegen. More...
 
using FNormalize = runtime::TypedPackedFunc< Expr(const BlockBuilder &bb, Call call)>
 The function type of a normalization function. More...
 
using FLegalize = runtime::TypedPackedFunc< Expr(const BlockBuilder &bb, const Call &call)>
 The function type of a legalization function. More...
 
using FPrimalGradient = runtime::TypedPackedFunc< tvm::Array< Expr >(const Var &orig_var, const Call &orig_call, const Var &output_grad, const BlockBuilder &ctx)>
 Gradient for a specific op. More...
 
using StructInfoDeriveFunc = TypedEnvFunc< StructInfo(const Call &call, const BlockBuilder &ctx)>
 custom-defined StructInfo derivation function. More...
 
using TIRPattern = tir::PrimFunc
 
using FCodegen = runtime::TypedPackedFunc< Array< ObjectRef >(Array< MatchResult > match_results)>
 

Enumerations

enum class  BaseCheckResult { kFailL0 = 0 , kFailL1 = 1 , kFailL2 = 2 , kPass = 3 }
 Fine grained result of base check. More...
 

Functions

bool CanProveShapeEqual (const Array< PrimExpr > &lhs, const Array< PrimExpr > &rhs, arith::Analyzer *ana)
 Can prove the two symbolic shape arrays equals to each other. More...
 
bool CanProveShapeEqual (const Expr &lhs, const Expr &rhs, arith::Analyzer *ana)
 Can prove the two symbolic shape expressions equals to each other. More...
 
Type GetStaticType (const StructInfo &info)
 Get the corresponding static type from a given struct info. More...
 
StructInfo StructInfoFromType (const Type &type)
 Get the corresponding struct info from static type. More...
 
StructInfo DeriveCallRetStructInfo (const FuncStructInfo &finfo, const Call &call, const BlockBuilder &ctx, arith::Analyzer *ana=nullptr)
 
StructInfo EraseToWellDefined (const StructInfo &info, std::function< Optional< PrimExpr >(const tir::Var &var)> f_shape_var_map=nullptr, std::function< Optional< Expr >(const Var &var)> f_var_map=nullptr, arith::Analyzer *ana=nullptr)
 Erase the info to a corresponding more coarse grained struct info that is still well-defined(with all the vars in scope). More...
 
StructInfo EraseToWellDefined (const StructInfo &info, Map< tir::Var, PrimExpr > shape_var_map, Map< Var, Expr > var_map, arith::Analyzer *ana=nullptr)
 EraseToWellDefined variant with map. More...
 
BaseCheckResult StructInfoBaseCheck (const StructInfo &base, const StructInfo &derived, arith::Analyzer *ana=nullptr)
 Run a base check to see if base subsumes derived. More...
 
bool IsBaseOf (const StructInfo &base, const StructInfo &derived, arith::Analyzer *ana=nullptr)
 Check the relation of two struct info to see if one subsumes another one. More...
 
PrimExpr StructInfoBaseCheckPrecondition (const StructInfo &base, const StructInfo &derived)
 Return the condition for which base is a superset of derived. More...
 
StructInfo StructInfoLCA (const StructInfo &lhs, const StructInfo &rhs, arith::Analyzer *ana=nullptr)
 Unify the two struct info to their least common ancestor. More...
 
Array< tir::VarTIRVarsInStructInfo (const StructInfo &sinfo)
 Get the TIR variables that appear in the input struct info. The returned list is deduplicated - each TIR variable will appear at most once. More...
 
Array< tir::VarDefinableTIRVarsInStructInfo (const StructInfo &sinfo)
 Get the TIR variables that appear in the input struct info. More...
 
Array< PrimExprCollectNonNegativeExpressions (const StructInfo &sinfo)
 Collect expressions whose usage requires them to be non-negative. More...
 
Array< tir::VarDefinedSymbolicVars (const Expr &expr)
 Get the TIR variables that defined in the input function. The returned list is deduplicated - each TIR variable will appear at most once. More...
 
Array< tir::VarFreeSymbolicVars (const Expr &expr)
 Get the TIR variables that are used but not defined in the input function. The returned list is deduplicated - each TIR variable will appear at most once. More...
 
tvm::Array< VarBoundVars (const Expr &expr)
 Get all bound variables from expression expr. More...
 
tvm::Array< VarFreeVars (const Expr &expr)
 Get free type parameters from expression expr. More...
 
tvm::Array< VarAllVars (const Expr &expr)
 Get all variables from expression expr. More...
 
tvm::Array< GlobalVarAllGlobalVars (const Expr &expr)
 Get all global variables from expression expr. More...
 
tvm::Array< tvm::Array< GlobalVar > > DetectRecursion (const IRModule &m)
 Find all sets of recursive or mutually recursive functions in the module. More...
 
Map< Var, ExprAnalyzeVar2Value (const IRModule &m)
 Analyze var -> value mapping from VarBindings. More...
 
Map< Var, ExprAnalyzeVar2Value (const Expr &expr)
 Analyze var -> value mapping from VarBindings. More...
 
Map< Var, ExprAnalyzeVar2Value (const DataflowBlock &dfb)
 Analyze var -> value mapping from VarBindings. More...
 
Map< String, Array< Binding > > NameToBinding (const Function &fn)
 Return a mapping from variable name to its Bindings. More...
 
Map< Var, Array< Var > > DataflowBlockUseDef (const DataflowBlock &dfb)
 Get the use-def chain of variables inside a dataflow block. More...
 
std::pair< Map< Var, Array< Var > >, Array< Var > > FunctionUseDef (const Expr &expr)
 Get the use-def chain of variables inside a function. More...
 
VarUsageInfo CollectVarUsage (const Expr &expr)
 Collect variable bindings and usage. More...
 
Expr RemoveAllUnused (Expr expr)
 Remove unused statements inside DataflowBlocks. More...
 
relay::OpPatternKind AnalyzeOpPatternKind (const tir::PrimFunc &func)
 Annotate Op Pattern Kind for PrimFunc, which is used in relax FuseOps. More...
 
bool HasReshapePattern (const tir::PrimFunc &func)
 Check if the given PrimFunc is essentially doing a reshape operation. The reshape operation also includes expand_dims, squeeze, flatten, etc. More...
 
Optional< ExprFindImpureCall (const Expr &expr, const Optional< Expr > &own_name=Optional< Expr >(nullptr))
 Check if the given expression (likely a function body) contains any impure calls. More...
 
bool ContainsImpureCall (const Expr &expr, const Optional< Expr > &own_name=Optional< Expr >(nullptr))
 Check if the given expression (likely a function body) contains any impure calls. More...
 
bool WellFormed (Variant< IRModule, Function > obj, bool check_struct_info=true)
 Check if the IRModule is well formed. More...
 
Map< tir::Block, Map< ObjectRef, tir::IndexMap > > SuggestLayoutTransforms (const Function &fn, Array< tir::IndexMap > write_buffer_transformations)
 Using the layout transforms on the outputs, suggest layout transformation on the blocks and buffers for the PrimFunc. More...
 
Array< VarComputableAtCompileTime (const Function &func)
 
bool MatchExpr (DFPattern pattern, Expr expr, Optional< runtime::Map< Var, Expr >> bindings=NullOpt)
 Determine if a pattern matches an expression. More...
 
Optional< Map< DFPattern, Expr > > ExtractMatchedExpr (DFPattern pattern, Expr expr, Optional< runtime::Map< Var, Expr >> bindings=NullOpt)
 
Optional< Map< DFPattern, Var > > MatchGraph (const PatternContext &ctx, const DataflowBlock &dfb)
 Match a sub-graph in a DataflowBlock with a graph of patterns and return the mapping. More...
 
Function RewriteBindings (const PatternContext &ctx, TypedPackedFunc< Map< Var, Expr >(Map< DFPattern, Var >, Map< Var, Expr >)> rewriter, Function f)
 Rewrite a function with the given pattern and the rewriter function. More...
 
Function RewriteCall (const DFPattern &pattern, TypedPackedFunc< Expr(Expr, Map< DFPattern, Expr >)> rewriter, Function func)
 Rewrite a function with the given pattern and the rewriter function. More...
 
PatternSeq UsedBy (const PatternSeq &lhs, const PatternSeq &rhs, int index=-1)
 Create used-by relationship between lhs[-1] and rhs[0], with [*lhs, *rhs] returned. More...
 
PatternSeq operator^ (const PatternSeq &lhs, const PatternSeq &rhs)
 Syntax sugar of UsedBy(lhs, rhs, -1). More...
 
PatternSeq OnlyUsedBy (const PatternSeq &lhs, const PatternSeq &rhs, int index=-1)
 Create only-used-by relationship between lhs[-1] and rhs[0], with [*lhs, *rhs] returned. More...
 
PatternSeq operator>> (const PatternSeq &lhs, const PatternSeq &rhs)
 Syntax sugar of OnlyUsedBy(lhs, rhs, -1). More...
 
VarPattern IsVar (const String &name)
 Syntatic Sugar for creating a VarPattern with a name. More...
 
ConstantPattern IsConst ()
 Syntatic Sugar for creating a ConstantPattern. More...
 
WildcardPattern Wildcard ()
 Syntatic Sugar for creating a WildcardPattern. More...
 
ExprPattern IsExpr (const Expr &expr)
 Syntatic Sugar for creating a ExprPattern. More...
 
ExprPattern IsOp (const String &op_name)
 Syntatic Sugar for creating a ExprPattern base on an Op. More...
 
CallPattern IsCallTIR (const String &name, Optional< TuplePattern > args=NullOpt)
 Syntatic Sugar for call_tir (return a tensor) More...
 
CallPattern IsCallTIR (const String &name, TuplePattern var_args)
 Syntatic Sugar for call_tir (return a tuple of tensor) More...
 
CallPattern IsCallDPSPacked (const String &name, Optional< TuplePattern > args=NullOpt)
 Syntatic Sugar for call_dps_packed (return a tensor) More...
 
CallPattern IsCallDPSPacked (const String &name, TuplePattern var_args)
 Syntatic Sugar for call_dps_packed (return a tuple of tensor) More...
 
DFPattern IsTuple (const Array< DFPattern > &fields, bool unordered=false)
 Syntatic Sugar for creating TuplePattern or UnorderedTuplePattern (unordered=true) More...
 
TupleGetItemPattern IsTupleGetItem (const DFPattern tuple, int index=-1)
 Syntatic Sugar for creating a TupleGetItemPattern. More...
 
Call WithFields (Call call, Optional< Expr > opt_op=Optional< Expr >(), Optional< Array< Expr >> opt_args=Optional< Array< Expr >>(), Optional< Attrs > opt_attrs=Optional< Attrs >(), Optional< Array< StructInfo >> opt_sinfo_args=Optional< Array< StructInfo >>(), Optional< Span > opt_span=Optional< Span >())
 Returns call with the given properties. A null property denotes 'no change'. Returns call if all properties are unchanged. Otherwise, returns a copy with the new fields. More...
 
Tuple WithFields (Tuple tuple, Optional< Array< Expr >> opt_fields=Optional< Array< Expr >>(), Optional< Span > opt_span=Optional< Span >())
 Returns tuple with the given properties. A null property denotes 'no change'. Returns tuple if all properties are unchanged. Otherwise, returns a copy with the new fields. More...
 
TupleGetItem WithFields (TupleGetItem tuple_get_item, Optional< Expr > opt_tuple=Optional< Expr >(), Optional< Integer > opt_index=Optional< Integer >(), Optional< Span > opt_span=Optional< Span >())
 Returns tuple_get_item with the given properties. A null property denotes 'no change'. Returns tuple_get_item if all properties are unchanged. Otherwise, returns a copy with the new fields. More...
 
If WithFields (If if_expr, Optional< Expr > opt_cond=Optional< Expr >(), Optional< Expr > opt_true_branch=Optional< Expr >(), Optional< Expr > opt_false_branch=Optional< Expr >(), Optional< Span > opt_span=Optional< Span >())
 Returns if_expr with the given properties. A null property denotes 'no change'. Returns if_expr if all properties are unchanged. Otherwise, returns a copy with the new fields. More...
 
Expr GetShapeOf (const Expr &expr)
 Get the shape of Expr. More...
 
void PostOrderVisit (const Expr &node, std::function< void(const Expr &)> fvisit)
 
template<typename T , typename FType >
void ForEachLeaf (const NestedMsg< T > &msg, FType fvisit)
 Apply fvisit for each leaf elements in the nested message. More...
 
template<typename T , typename FType >
bool Equal (const NestedMsg< T > &lhs, const NestedMsg< T > &rhs, FType fequal)
 Recursively compare two nested messages. More...
 
template<typename T , typename FType >
NestedMsg< T > MapToNestedMsg (Expr expr, FType fmapleaf)
 Map expr with possible nested-tuple to nested message. More...
 
template<typename T , typename FType >
NestedMsg< T > MapToNestedMsg (StructInfo sinfo, FType fmapleaf)
 Map structinfo with possible nested-sinfo to nested message. More...
 
template<typename T , typename FType >
NestedMsg< T > MapToNestedMsgBySInfo (Expr expr, FType fmapleaf)
 Map expr with possible nested-tuple to nested message. More...
 
template<typename TargetType , typename T , typename FMapLeaf , typename FCombine >
TargetType NestedMsgTo (NestedMsg< T > msg, FMapLeaf fmapleaf, FCombine fcombine)
 Map nested message back to TargetType. More...
 
template<typename T , typename FType >
Expr NestedMsgToExpr (NestedMsg< T > msg, FType fmapleaf)
 Map nested message back to the expr. More...
 
template<typename T , typename FType >
NestedMsg< T > CombineNestedMsg (NestedMsg< T > lhs, NestedMsg< T > rhs, FType fcombine)
 Recursively combine two nested message into one. More...
 
template<typename T , typename FType >
NestedMsg< T > MapNestedMsg (NestedMsg< T > msg, FType fmapleaf)
 Recursively map a nested message to another one, with leaf mapped by the input fmapleaf. More...
 
template<typename T , typename FType >
void DecomposeNestedMsg (Expr expr, NestedMsg< T > msg, FType fvisitleaf)
 Recursively decompose the tuple structure in expr and msg along with it. More...
 
template<typename T , std::size_t N, typename FType >
Expr TransformTupleLeaf (Expr expr, std::array< NestedMsg< T >, N > msgs, FType ftransleaf)
 Recursively transform the tuple structure in expr and msgs along with it. More...
 
template<typename T , std::size_t N, typename FType >
StructInfo TransformTupleLeaf (StructInfo sinfo, std::array< NestedMsg< T >, N > msgs, FType ftransleaf)
 Recursively transform the tuple structure in sinfo and msgs along with it. More...
 
template<typename T >
Optional< T > MatchStructInfo (const Expr &expr)
 Match and check if expr have StructInfo T and return it. More...
 
template<typename T >
const T * GetStructInfoAs (const Expr &expr)
 Get the structure info of a given expr and try to cast it as const T*. More...
 
StructInfo GetStructInfo (const Expr &expr)
 Get the underlying structure info of expr. More...
 
bool HasVoidStructInfo (const Expr &expr)
 Whether the expr has void struct info. More...
 
void UpdateStructInfo (Expr expr, StructInfo struct_info)
 Update the struct info of an Expr. More...
 
TVM_ALWAYS_INLINE TVMRetValue CallPackedWithArgsInArray (const runtime::PackedFunc f, const Array< ObjectRef > &args)
 Helper function to unpack arguments in the array as parameters for the given packed function. More...
 
Expr Bind (const Expr &expr, const tvm::Map< Var, Expr > &binds, const tvm::Map< tir::Var, PrimExpr > &symbolic_var_map={})
 Bind the variables to a Relax expression. This is a helper function usually called by other pass functions to help optimizations. If any free variables are introduced into a function, those are added to the function parameters. Additionally this may change the order of parameters if you map a variable to a variable. More...
 
StructInfo Bind (const StructInfo &sinfo, const tvm::Map< tir::Var, PrimExpr > &symbolic_var_map)
 Bind the symbolic variables to a StructInfo. This is a helper function usually called by other pass functions to help optimizations. More...
 
tvm::Map< tir::Var, PrimExprInferSymbolicVarMap (const tvm::Map< relax::Var, relax::Expr > &binds, arith::Analyzer *analyzer)
 Infer a binding map for symbolic variables. More...
 
bool IsBoolStructInfo (const StructInfo &sinfo, bool permit_unknown_rank=true, bool permit_unknown_dtype=true)
 Check if the given StructInfo is for a boolean scalar (tensor of rank 0 with a boolean dtype). More...
 
bool IsLeafOrTuple (const Expr &expr)
 Check if the given expression is a "leaf" node or tuple node for normalization purposes. More...
 
bool IsImpureCall (const Call &call)
 Check if the given Call node is an impure operation. If the callee is a general expression, this simply requires checking the purity field of the FuncStructInfo. If it is an Op, then this checks the fPurity field. More...
 
Function CopyWithNewVars (Function func)
 Copy the given function. All variables that are bound inside the original function would be copied to satisfy the restriction in the well-formed check: Variables in Relax must be bound exactly once. This also ensures that both the function and its copy can be inserted into the same IRModule, and be asserted on the structural equality agaisnt IRModule created by TVMScript. More...
 
Expr ToNonDataflow (const Expr &e)
 Transform all dataflow structure to non-dataflow version. More...
 
Expr GetBoundValue (const Binding &b)
 Get the value bound in the binding. More...
 

Typedef Documentation

◆ Expr

using tvm::relax::Expr = typedef RelayExpr

◆ ExprNode

◆ FCallPacked

Packed function implementation for operators. The relax operator will be lowered to this packed function call during codegen.

◆ FCodegen

◆ FInferStructInfo

Infer output struct info given the call.

Parameters
callThe call expression to be derived.
ctxThe builder context.

◆ FLegalize

using tvm::relax::FLegalize = typedef runtime::TypedPackedFunc<Expr(const BlockBuilder& bb, const Call& call)>

The function type of a legalization function.

A legalization function is used to replace a relax::Call with more concrete implementations. For example, the operation relax.op.add may be replaced with a call to a TIR function implementing addition of two tensors.

The purpose of FLegalize is to remove calls to the operator while lowering. Therefore, unlike FNormalize, the resulting expression may not contain the original operator.

Parameters
bbThe BlockBuilder context.
callThe call to be legalized.

◆ FNormalize

The function type of a normalization function.

A normalization function is used when a relax::Call may be expressed in multiple syntactically valid and semantically equivalent forms, to normalize to a single representation.

Parameters
bbThe BlockBuilder context.
callThe call to be normalized. It is provided by-value, to avoid copies for the common case where the call is already normalized.

◆ FPrimalGradient

using tvm::relax::FPrimalGradient = typedef runtime::TypedPackedFunc<tvm::Array<Expr>( const Var& orig_var, const Call& orig_call, const Var& output_grad, const BlockBuilder& ctx)>

Gradient for a specific op.

Parameters
orig_varthe original var corresponding to orig_call.
orig_callthe original Call(op) expr.
output_gradthe gradient of the Expr.
ctxthe current block builder context.
Returns
the gradient for each parameter.

◆ StructInfoDeriveFunc

using tvm::relax::StructInfoDeriveFunc = typedef TypedEnvFunc<StructInfo(const Call& call, const BlockBuilder& ctx)>

custom-defined StructInfo derivation function.

Parameters
callThe call expression to be derived.
ctxThe builder context.
Returns
The derived struct info of the call.

◆ TIRPattern

Enumeration Type Documentation

◆ BaseCheckResult

Fine grained result of base check.

This analysis comes with different levels of checking failures that can help to customize the compilation decisions.

For a given pair of lhs_struct_info, rhs_struct_info. We adopt the following terminology:

  • LSet = {value | value matches lhs_struct_info}
  • RSet = {value | value matches rhs_struct_info}

See the definition of each level below.

Enumerator
kFailL0 

The two value sets have no intersection at all: Interset(LSet, RSet) = empty.

kFailL1 

LSet is not superset of RSet by only looking at static information.

Note
This level will trigger static type checking error when lhs is param and rhs is arg.
kFailL2 

WLSet is not superset of RSet because of mismatch in value information.

L1-level mismatches in params of FuncStructInfo is categorized as If lhs is FuncStructInfo, then L1-level mismatch in its params is categorized as L2-level mismatch for lhs.

Design considerations for functions:

  • (a) We want to be able to erase type/value in function signature when we unify function struct info and preserve simpler representations.
  • (b) We automatically insert match_cast at function boundary, so we can erase (int)->int argument as (object)->int. The input shape/type mismatch will be detected by runtime checks at function boundary. This behavior is also consistent with the PackedFunc behavior.
Note
This level means there is no problem about static known information. It is OK for the checker to do best effort and return this value.
kPass 

LSet is superset of RSet.

Function Documentation

◆ AllGlobalVars()

tvm::Array<GlobalVar> tvm::relax::AllGlobalVars ( const Expr expr)

Get all global variables from expression expr.

AllVars is a superset of BoundVars and FreeVars. The union of BoundVars and FreeVars is Allvars.

Parameters
exprthe expression.
Returns
List of all global variables, in the PostDFS order in the expression.

◆ AllVars()

tvm::Array<Var> tvm::relax::AllVars ( const Expr expr)

Get all variables from expression expr.

Parameters
exprthe expression.
Returns
List of all vars, in the PostDFS order in the expression.

◆ AnalyzeOpPatternKind()

relay::OpPatternKind tvm::relax::AnalyzeOpPatternKind ( const tir::PrimFunc func)

Annotate Op Pattern Kind for PrimFunc, which is used in relax FuseOps.

Parameters
funcThe PrimFunc to be analyzed.
Returns
The Op Pattern Kind.
Note
This analysis applies on TIR function but is primarily used by relax passes. As a result we place it under the relax namespace.

◆ AnalyzeVar2Value() [1/3]

Map<Var, Expr> tvm::relax::AnalyzeVar2Value ( const DataflowBlock dfb)

Analyze var -> value mapping from VarBindings.

Parameters
dfbThe dataflow block to check.
Returns
Var -> Value (Expr)

◆ AnalyzeVar2Value() [2/3]

Map<Var, Expr> tvm::relax::AnalyzeVar2Value ( const Expr expr)

Analyze var -> value mapping from VarBindings.

Parameters
exprThe expression to check.
Returns
Var -> Value (Expr)

◆ AnalyzeVar2Value() [3/3]

Map<Var, Expr> tvm::relax::AnalyzeVar2Value ( const IRModule m)

Analyze var -> value mapping from VarBindings.

Parameters
mThe IRModule to check.
Returns
Var -> Value (Expr)

◆ Bind() [1/2]

Expr tvm::relax::Bind ( const Expr expr,
const tvm::Map< Var, Expr > &  binds,
const tvm::Map< tir::Var, PrimExpr > &  symbolic_var_map = {} 
)

Bind the variables to a Relax expression. This is a helper function usually called by other pass functions to help optimizations. If any free variables are introduced into a function, those are added to the function parameters. Additionally this may change the order of parameters if you map a variable to a variable.

Parameters
exprThe input expression.
bindsThe variable to expression map that will be used to help the binding.
symbolic_var_mapThe map from symbolic var to the expr it binds to.
Returns
The updated expression.

◆ Bind() [2/2]

StructInfo tvm::relax::Bind ( const StructInfo sinfo,
const tvm::Map< tir::Var, PrimExpr > &  symbolic_var_map 
)

Bind the symbolic variables to a StructInfo. This is a helper function usually called by other pass functions to help optimizations.

◆ BoundVars()

tvm::Array<Var> tvm::relax::BoundVars ( const Expr expr)

Get all bound variables from expression expr.

Bound variables are all variables that are declared in the expr. They only have meaning inside that expr, and can only be used in it.

Parameters
exprthe expression.
Returns
List of bound vars, in the PostDFS order in the expression.

◆ CallPackedWithArgsInArray()

TVM_ALWAYS_INLINE TVMRetValue tvm::relax::CallPackedWithArgsInArray ( const runtime::PackedFunc  f,
const Array< ObjectRef > &  args 
)

Helper function to unpack arguments in the array as parameters for the given packed function.

◆ CanProveShapeEqual() [1/2]

bool tvm::relax::CanProveShapeEqual ( const Array< PrimExpr > &  lhs,
const Array< PrimExpr > &  rhs,
arith::Analyzer ana 
)

Can prove the two symbolic shape arrays equals to each other.

Parameters
lhsThe left operand.
rhsThe right operand.
anaThe analyzer used for integer analysis.
Returns
The prove result.
Note
This function does best effort prove, which means if result is false, there is still possibility that two shapes equals to each other during runtime.

◆ CanProveShapeEqual() [2/2]

bool tvm::relax::CanProveShapeEqual ( const Expr lhs,
const Expr rhs,
arith::Analyzer ana 
)

Can prove the two symbolic shape expressions equals to each other.

Parameters
lhsThe left operand.
rhsThe right operand.
anaThe analyzer used for integer analysis.
Note
This function does best effort prove, which means if result is false, there is still possibility that two shapes equals to each other during runtime.

◆ CollectNonNegativeExpressions()

Array<PrimExpr> tvm::relax::CollectNonNegativeExpressions ( const StructInfo sinfo)

Collect expressions whose usage requires them to be non-negative.

Any PrimExpr that is used as a tensor shape, or as an element in a ShapeExpr, may not be negative. This utility function can be used to generate assertions prior to calling a kernel, or to provide assumptions within a kernel that may be useful for simplification.

Parameters
sinfoThe struct info to be analyzed
Returns
A list of non-negative expressions.

◆ CollectVarUsage()

VarUsageInfo tvm::relax::CollectVarUsage ( const Expr expr)

Collect variable bindings and usage.

This function is equivalent to calling both FunctionUseDef and AnalyzeVar2Value, but requires only a single traversal of the expression.

Parameters
exprThe expression to analyze
Returns
The collected information

◆ CombineNestedMsg()

template<typename T , typename FType >
NestedMsg<T> tvm::relax::CombineNestedMsg ( NestedMsg< T >  lhs,
NestedMsg< T >  rhs,
FType  fcombine 
)

Recursively combine two nested message into one.

This function requires the two messages to be compatible with each other. The combination rule is as follows:

  • combine(null, msg) => msg
  • combine(leaf1, leaf2) => fcombine(leaf1, leaf2)
  • combine(array1, array2) => [combine(x, y) for x, y in zip(array1, array2)]
  • This function will throw an error if array have different size
Parameters
lhsThe left operand.
rhsThe right operand.
fcombinewith signature T fcombine(T lhs, T rhs)
Template Parameters
Tthe content type of nested msg
FTypecombine function type.

◆ ComputableAtCompileTime()

Array<Var> tvm::relax::ComputableAtCompileTime ( const Function func)

◆ ContainsImpureCall()

bool tvm::relax::ContainsImpureCall ( const Expr expr,
const Optional< Expr > &  own_name = OptionalExpr >(nullptr) 
)

Check if the given expression (likely a function body) contains any impure calls.

Parameters
exprThe expression to be examined. If expr is a function, we check the body.
own_name(Optional.) If we are checking a recursive function body, the caller can pass the function's name so recursive calls can be ignored in the check (must be a Var or GlobalVar).
Returns
A boolean indicating if the expression contains any impure calls.
Note
Relies on StructInfo annotations, so ensure that the module has been normalized first. Also, an impure call in a nested function does not mean that the outer expression contains an impure call–it only does if the nested function is later called.

◆ CopyWithNewVars()

Function tvm::relax::CopyWithNewVars ( Function  func)

Copy the given function. All variables that are bound inside the original function would be copied to satisfy the restriction in the well-formed check: Variables in Relax must be bound exactly once. This also ensures that both the function and its copy can be inserted into the same IRModule, and be asserted on the structural equality agaisnt IRModule created by TVMScript.

Parameters
funcThe relax function to copy.
Returns
The copied function.

◆ DataflowBlockUseDef()

Map<Var, Array<Var> > tvm::relax::DataflowBlockUseDef ( const DataflowBlock dfb)

Get the use-def chain of variables inside a dataflow block.

Parameters
dfbThe dataflow block to be analyzed.
Returns
A map mapping variable definitions to a set of uses.

◆ DecomposeNestedMsg()

template<typename T , typename FType >
void tvm::relax::DecomposeNestedMsg ( Expr  expr,
NestedMsg< T >  msg,
FType  fvisitleaf 
)

Recursively decompose the tuple structure in expr and msg along with it.

This function will call fvisitleaf for each leaf expression in expr. This function will throw an error if the nesting structure in msg does not match the tuple nesting structure in expr.

Parameters
exprThe input expression to be decomposed.
msgThe input nested message.
fvisitleafwith signature fvisitleaf(Expr expr, NestedMsg<T> msg)
Template Parameters
Tthe content type of nested msg
FTypeThe visit function type.

◆ DefinableTIRVarsInStructInfo()

Array<tir::Var> tvm::relax::DefinableTIRVarsInStructInfo ( const StructInfo sinfo)

Get the TIR variables that appear in the input struct info.

Returns all symbolic variables that are definable based on, and used within, the StructInfo.

Parameters
sinfoThe struct info object to be analyzed.
Returns
A tuple of (definable,used) TIR variables. Both lists are deduplicated, each TIR variable will appear at most once, and in order of occurrence.

◆ DefinedSymbolicVars()

Array<tir::Var> tvm::relax::DefinedSymbolicVars ( const Expr expr)

Get the TIR variables that defined in the input function. The returned list is deduplicated - each TIR variable will appear at most once.

Parameters
exprThe relax expression (e.g. a Function) to be analyzed.
Returns
The list of TIR variables that are defined in the input function.

◆ DeriveCallRetStructInfo()

StructInfo tvm::relax::DeriveCallRetStructInfo ( const FuncStructInfo finfo,
const Call call,
const BlockBuilder ctx,
arith::Analyzer ana = nullptr 
)
Returns
Derive the call's ret value struct info from inputs.
Parameters
finfoThe function struct info.
callThe call expression to be derived.
ctxThe builder context.
anaOptional context analyzer to prove symbolic expression equality.
Returns
The derived struct info of the call.
Note
call->op field is ignored during derivation and we only rely on information presented by func_sinfo.

◆ DetectRecursion()

tvm::Array<tvm::Array<GlobalVar> > tvm::relax::DetectRecursion ( const IRModule m)

Find all sets of recursive or mutually recursive functions in the module.

Two or more functions are mutually recursive if there is some cycle of references among them. For example, if there are two functions A and B, they are mutually recursive if A calls B and B calls A. Another case would be with three functions A, B, and C, where A calls B, B calls C, and C calls A.

(Note that functions do not have to call each other to reference each other. For example, if a function returns another function, that is still a reference that could potentially be recursive, even without a call.)

If a function is simply recursive and not mutually recursive with any other, it will be reported as a group by itself.

Parameters
mThe module
Returns
List of all groups of mutually recursive functions. Each member of the result is a list of functions in the module that are all mutually recursive. If a function is simply recursive and not mutually recursive with any other, then it will be listed as a group by itself.

◆ Equal()

template<typename T , typename FType >
bool tvm::relax::Equal ( const NestedMsg< T > &  lhs,
const NestedMsg< T > &  rhs,
FType  fequal 
)

Recursively compare two nested messages.

Parameters
lhsThe left operand.
rhsThe right operand.
fequalThe equal functor with signature bool fequal(T, T)
Template Parameters
Tthe content type of nested msg
FTypethe equal comparator type

◆ EraseToWellDefined() [1/2]

StructInfo tvm::relax::EraseToWellDefined ( const StructInfo info,
Map< tir::Var, PrimExpr shape_var_map,
Map< Var, Expr var_map,
arith::Analyzer ana = nullptr 
)

EraseToWellDefined variant with map.

Parameters
infoThe struct info.
shape_var_mapmap to specify whether a symbolic shape var is defined and the value it maps to, return nullopt if var is undefined.
var_mapmap to specify whether a var is defined in the target scope and the value it maps to, return nullopt if var is undefined.
anaOptional context analyzer to prove symbolic expression equality.
Returns
the corresponding erased struct info.

◆ EraseToWellDefined() [2/2]

StructInfo tvm::relax::EraseToWellDefined ( const StructInfo info,
std::function< Optional< PrimExpr >(const tir::Var &var)>  f_shape_var_map = nullptr,
std::function< Optional< Expr >(const Var &var)>  f_var_map = nullptr,
arith::Analyzer ana = nullptr 
)

Erase the info to a corresponding more coarse grained struct info that is still well-defined(with all the vars in scope).

When we are returning a StructInfo to another scope, it is important to remember that StructInfo may carry dependencies on var that is not defined the other scope.

In such cases, it is important to call EraseToWellDefined to get another StructInfo that only contains the vars that are defined in the target scope.

For example, consider the following function

@R.function
def f(x: R.Tensor[(n, m)]):
k = tir.Var("k", "int64")
v0 = opaque_fn(x)
v1 = match_cast(v0, R.Tensor[(n, k)])
v2 : R.Tensor[(n + 1, k + 2)] = pad(v1)
return v2
tvm::te::Tensor pad(const tvm::te::Tensor &t, const tvm::Array< tvm::PrimExpr > &pad_before, tvm::Array< tvm::PrimExpr > pad_after=tvm::Array< tvm::PrimExpr >(), PrimExpr pad_value=PrimExpr(), std::string name="T_pad", std::string tag=kElementWise, std::string pad_mode="constant", const Array< PrimExpr > *dyn_output_shape=nullptr)
Creates an operation that performs padding.
Definition: nn.h:155

In the above code, the return value y have shape (n + 1, k + 2), However, at the level of function signature, only n, m are defined, k is undefined here.

When we call EraseToWellDefined(R.Tensor[(n + 1, k + 2)], fshape_var_map={n: n, m: m}), we will obtain R.Tensor(ndim=2), which is an erased info that does not depend on k(which is undefined from parameter signature).

However, if we call EraseToWellDefined(R.Tensor[(n + 1, m)], fshape_var_map={n: n, m: m}), Then the return value will be R.Tensor[(n + 1, m)], because both n and m are defined.

We can also make these var map to return a different expression. For example, EraseToWellDefined(R.Tensor[(n + 1, m)], fshape_var_map={n: 2, m: m}) will give us R.Tensor[(3, m)], where n get replaced by 2.

Use this function in the following scenarios:

  • Decide the struct_info of expr with sub-scopes, such as If, SeqExpr
  • Decide the deduced return struct_info of a function that can be fully decided by params.
Parameters
infoThe struct info.
f_shape_var_mapcallback function to specify whether a symbolic shape var is defined and the value it maps to, return nullopt if var is undefined.
f_var_mapcallback function to specify whether a var is defined in the target scope and the value it maps to, return nullopt if var is undefined.
anaOptional context analyzer to prove symbolic expression equality.
Returns
the corresponding erased struct info.

◆ ExtractMatchedExpr()

Optional<Map<DFPattern, Expr> > tvm::relax::ExtractMatchedExpr ( DFPattern  pattern,
Expr  expr,
Optional< runtime::Map< Var, Expr >>  bindings = NullOpt 
)

◆ FindImpureCall()

Optional<Expr> tvm::relax::FindImpureCall ( const Expr expr,
const Optional< Expr > &  own_name = OptionalExpr >(nullptr) 
)

Check if the given expression (likely a function body) contains any impure calls.

Parameters
exprThe expression to be examined. If expr is a function, we check the body.
own_name(Optional.) If we are checking a recursive function body, the caller can pass the function's name so recursive calls can be ignored in the check (must be a Var or GlobalVar).
Returns
The impure expression, if one exists within the given expression. Otherwise, NullOpt.
Note
Relies on StructInfo annotations, so ensure that the module has been normalized first. Also, an impure call in a nested function does not mean that the outer expression contains an impure call–it only does if the nested function is later called.

◆ ForEachLeaf()

template<typename T , typename FType >
void tvm::relax::ForEachLeaf ( const NestedMsg< T > &  msg,
FType  fvisit 
)

Apply fvisit for each leaf elements in the nested message.

Parameters
fvisitThe visit callback.
msgThe input nested message.
Template Parameters
Tthe content type of nested msg
FTypethe visitor type with signature void fvisit(T)

◆ FreeSymbolicVars()

Array<tir::Var> tvm::relax::FreeSymbolicVars ( const Expr expr)

Get the TIR variables that are used but not defined in the input function. The returned list is deduplicated - each TIR variable will appear at most once.

Parameters
exprThe relax expression (e.g. a Function) to be analyzed.
Returns
The list of TIR variables that are used but not defined in the input function.

◆ FreeVars()

tvm::Array<Var> tvm::relax::FreeVars ( const Expr expr)

Get free type parameters from expression expr.

Free variables are variables that are not bound by a varbinding or a function parameter in the context.

Parameters
exprthe expression.
Returns
List of free vars, in the PostDFS order in the expression.

◆ FunctionUseDef()

std::pair<Map<Var, Array<Var> >, Array<Var> > tvm::relax::FunctionUseDef ( const Expr expr)

Get the use-def chain of variables inside a function.

Parameters
exprThe expression to be analyzed.
Returns
A tuple of variable usage and variable outputs. The first element is a map from variable definitions to the set of downstream users of that definition. The second element is a list of variables whose usage occurs outside of any variable binding, typically the output body of a relax::Function or a relax::SeqExpr.

◆ GetBoundValue()

Expr tvm::relax::GetBoundValue ( const Binding b)

Get the value bound in the binding.

◆ GetShapeOf()

Expr tvm::relax::GetShapeOf ( const Expr expr)

Get the shape of Expr.

Parameters
exprThe input expr.
Returns
The corresonding shape.
Note
This function requires expr to be normalized. The function will report an error if expr's StructInfo is not TensorStructInfo. It will try to return symbolic function when possible. If the tensor do not have a compile-time symbolic shape, the function will then choose to return Call(relax.op.shape_of, [expr]).

◆ GetStaticType()

Type tvm::relax::GetStaticType ( const StructInfo info)

Get the corresponding static type from a given struct info.

Parameters
infoThe struct info.
Returns
the corresponding static type.

◆ GetStructInfo()

StructInfo tvm::relax::GetStructInfo ( const Expr expr)
inline

Get the underlying structure info of expr.

Parameters
exprThe input expression.
Returns
underlying struct info.

◆ GetStructInfoAs()

template<typename T >
const T* tvm::relax::GetStructInfoAs ( const Expr expr)
inline

Get the structure info of a given expr and try to cast it as const T*.

Parameters
exprThe input expression.
Returns
The pointer. Returns nullptr if the type does not match
Template Parameters
Tthe underlying structure info type

◆ HasReshapePattern()

bool tvm::relax::HasReshapePattern ( const tir::PrimFunc func)

Check if the given PrimFunc is essentially doing a reshape operation. The reshape operation also includes expand_dims, squeeze, flatten, etc.

Here the allowed reshape pattern is: for example, assume the operation is B[l_0, l_1, ..., l_b] = A[r_0, r_1, ..., r_a], we check if we can prove that the flattened index of l_0, ..., l_b under buffer B equals to the flattened index of r_0, ..., r_a under buffer A.

Parameters
funcThe function to be examined.
Returns
A boolean indicating if the given PrimFunc is doing a reshape.
Note
According to the description above, the returned result can only be false-negative and cannot be false-positive, since whenever we cannot prove the equality, we return false. This property guarantees the safety of this function.

◆ HasVoidStructInfo()

bool tvm::relax::HasVoidStructInfo ( const Expr expr)
inline

Whether the expr has void struct info.

Parameters
exprThe input expression.
Returns
Whether the expr has void struct info.

◆ InferSymbolicVarMap()

tvm::Map<tir::Var, PrimExpr> tvm::relax::InferSymbolicVarMap ( const tvm::Map< relax::Var, relax::Expr > &  binds,
arith::Analyzer analyzer 
)

Infer a binding map for symbolic variables.

If a set of relax variables are replaced within an expression, this may result in removal of the definition site of a symbolic variable. This utility function determines the symbolic variable replacements that can be inferred based on the replaced relax variables, and can be used alongside the Bind utility function to replace both the relax variables and the implied symbolic variables.

Parameters
bindsA map of relax variables to relax expressions
analyzerThe analyzer to use for simplifications
Returns
A map of TIR variables to TIR expressions

◆ IsBaseOf()

bool tvm::relax::IsBaseOf ( const StructInfo base,
const StructInfo derived,
arith::Analyzer ana = nullptr 
)

Check the relation of two struct info to see if one subsumes another one.

Parameters
baseThe base struct info.
derivedThe derived struct info.
anaOptional context analyzer to prove symbolic expression equality.
Returns
Whether the relation holds.

◆ IsBoolStructInfo()

bool tvm::relax::IsBoolStructInfo ( const StructInfo sinfo,
bool  permit_unknown_rank = true,
bool  permit_unknown_dtype = true 
)

Check if the given StructInfo is for a boolean scalar (tensor of rank 0 with a boolean dtype).

Parameters
sinfoThe input StructInfo.
permit_unknown_rankIf true, it will permit the input type to have unknown rank (ndim of -1), which will require a dynamic check.
permit_unknown_dtypeIf true, it will permit the input type to have an unknown dtype (namely, void), which will require a dynamic check.
Returns
True iff the input type is a boolean scalar type (or, depending on options, has unknown rank or dtype)

◆ IsCallDPSPacked() [1/2]

CallPattern tvm::relax::IsCallDPSPacked ( const String name,
Optional< TuplePattern args = NullOpt 
)

Syntatic Sugar for call_dps_packed (return a tensor)

◆ IsCallDPSPacked() [2/2]

CallPattern tvm::relax::IsCallDPSPacked ( const String name,
TuplePattern  var_args 
)

Syntatic Sugar for call_dps_packed (return a tuple of tensor)

◆ IsCallTIR() [1/2]

CallPattern tvm::relax::IsCallTIR ( const String name,
Optional< TuplePattern args = NullOpt 
)

Syntatic Sugar for call_tir (return a tensor)

◆ IsCallTIR() [2/2]

CallPattern tvm::relax::IsCallTIR ( const String name,
TuplePattern  var_args 
)

Syntatic Sugar for call_tir (return a tuple of tensor)

◆ IsConst()

ConstantPattern tvm::relax::IsConst ( )

Syntatic Sugar for creating a ConstantPattern.

◆ IsExpr()

ExprPattern tvm::relax::IsExpr ( const Expr expr)

Syntatic Sugar for creating a ExprPattern.

◆ IsImpureCall()

bool tvm::relax::IsImpureCall ( const Call call)

Check if the given Call node is an impure operation. If the callee is a general expression, this simply requires checking the purity field of the FuncStructInfo. If it is an Op, then this checks the fPurity field.

Parameters
callThe input call
Returns
True iff the call is impure (definitely or possibly results in a visible side effect). That is, a call is considered pure only if definitely does not result in a visible side effect.

◆ IsLeafOrTuple()

bool tvm::relax::IsLeafOrTuple ( const Expr expr)

Check if the given expression is a "leaf" node or tuple node for normalization purposes.

The following expressions are defined as leaf nodes: Var, Constant, ShapeExpr, GlobalVar, Op, ExternFunc.

Tuples are included in this list mainly for convenience in grouping operator arguments. Note: Since tuples can contain nested expressions, it is necessary to ensure that values nested inside them are also leaves.

Parameters
exprThe input expression
Returns
True iff the input expression is a "leaf" node (a value allowed to appear inline without being bound to a var during normalization).

◆ IsOp()

ExprPattern tvm::relax::IsOp ( const String op_name)

Syntatic Sugar for creating a ExprPattern base on an Op.

◆ IsTuple()

DFPattern tvm::relax::IsTuple ( const Array< DFPattern > &  fields,
bool  unordered = false 
)

Syntatic Sugar for creating TuplePattern or UnorderedTuplePattern (unordered=true)

◆ IsTupleGetItem()

TupleGetItemPattern tvm::relax::IsTupleGetItem ( const DFPattern  tuple,
int  index = -1 
)

Syntatic Sugar for creating a TupleGetItemPattern.

◆ IsVar()

VarPattern tvm::relax::IsVar ( const String name)

Syntatic Sugar for creating a VarPattern with a name.

◆ MapNestedMsg()

template<typename T , typename FType >
NestedMsg<T> tvm::relax::MapNestedMsg ( NestedMsg< T >  msg,
FType  fmapleaf 
)

Recursively map a nested message to another one, with leaf mapped by the input fmapleaf.

Parameters
msgThe nested message to be mapped.
fmapleafThe leaf map function, with signature NestedMsg<T> fmapleaf(T msg)
Template Parameters
TThe content type of nested message.
FTypeThe leaf map function type.
Returns
The new nested message.

◆ MapToNestedMsg() [1/2]

template<typename T , typename FType >
NestedMsg<T> tvm::relax::MapToNestedMsg ( Expr  expr,
FType  fmapleaf 
)

Map expr with possible nested-tuple to nested message.

This function will unpack recursive tuples and run fmapleaf for each leaf, then recursively combines the results together into a NestedMsg.

The nesting structure will corresponds to the tuple structure.

Parameters
exprThe input expression.
fmapleafThe mapping function for each leaf with signature NestedMsg<T> fmap(Expr)
Template Parameters
Tthe content type of nested msg
FTypeThe mapping function type

◆ MapToNestedMsg() [2/2]

template<typename T , typename FType >
NestedMsg<T> tvm::relax::MapToNestedMsg ( StructInfo  sinfo,
FType  fmapleaf 
)

Map structinfo with possible nested-sinfo to nested message.

This function will unpack recursive sinfo and run fmapleaf for each leaf, then recursively combines the results together into a NestedMsg.

The nesting structure will corresponds to the tuple structure.

Parameters
sinfoThe input struct info.
fmapleafThe mapping function for each leaf with signature NestedMsg<T> fmap(StructInfo)
Template Parameters
Tthe content type of nested msg
FTypeThe mapping function type

◆ MapToNestedMsgBySInfo()

template<typename T , typename FType >
NestedMsg<T> tvm::relax::MapToNestedMsgBySInfo ( Expr  expr,
FType  fmapleaf 
)

Map expr with possible nested-tuple to nested message.

This function will unpack recursive expr by its struct info and run fmapleaf for each leaf, then recursively combines the results together into a NestedMsg.

The nesting structure will corresponds to the struct info of expr.

Parameters
exprThe input expression which should have struct info.
fmapleafThe mapping function for each leaf with signature NestedMsg<T> fmapleaf(Expr)
Template Parameters
Tthe content type of nested msg
FTypeThe mapping function type

◆ MatchExpr()

bool tvm::relax::MatchExpr ( DFPattern  pattern,
Expr  expr,
Optional< runtime::Map< Var, Expr >>  bindings = NullOpt 
)

Determine if a pattern matches an expression.

Note
The behavior of MatchExpr is to match a relax.Expr (expr) syntactically through one given pattern (pattern).
Parameters
patternThe pattern to match
exprThe expression to match
bindingsThe mapping from relax.Var to relax.Expr
Returns
true if matched
false if unmatched

◆ MatchGraph()

Optional<Map<DFPattern, Var> > tvm::relax::MatchGraph ( const PatternContext ctx,
const DataflowBlock dfb 
)

Match a sub-graph in a DataflowBlock with a graph of patterns and return the mapping.

Parameters
ctxThe graph-wise patterns.
dfbThe function to match.
Returns
Matched patterns and corresponding bound variables

◆ MatchStructInfo()

template<typename T >
Optional<T> tvm::relax::MatchStructInfo ( const Expr expr)
inline

Match and check if expr have StructInfo T and return it.

Parameters
exprThe input expression.
Returns
The result of match.
Template Parameters
Tthe underlying structure info type

◆ NameToBinding()

Map<String, Array<Binding> > tvm::relax::NameToBinding ( const Function fn)

Return a mapping from variable name to its Bindings.

Parameters
fnThe function to be analyzed.
Returns
A mapping from variable name to its Bindings.

◆ NestedMsgTo()

template<typename TargetType , typename T , typename FMapLeaf , typename FCombine >
TargetType tvm::relax::NestedMsgTo ( NestedMsg< T >  msg,
FMapLeaf  fmapleaf,
FCombine  fcombine 
)

Map nested message back to TargetType.

This function will decompose the nested message and run fmapleaf for each leaf message and get the leaf value, then recursively combines the results by fcombine.

Parameters
msgThe input nested message.
fmapleafThe mapping function for each leaf with signature TargetType fmapleaf(Optional<T>).
fcombineThe function for combining all childs of a node into TargetType with signature TargetType fmapleaf(Array<TargetType>).
Template Parameters
TargetTypethe target type to map nested msg to.
Tthe content type of nested msg.
FMapLeafThe leaf mapping function type.
FCombineThe combining function type.

◆ NestedMsgToExpr()

template<typename T , typename FType >
Expr tvm::relax::NestedMsgToExpr ( NestedMsg< T >  msg,
FType  fmapleaf 
)

Map nested message back to the expr.

This function will decompose the nested message and run fmapleaf for each leaf message and get the leaf expr, then recursively combines the results as tuple expr.

Parameters
msgThe input nested message.
fmapleafThe mapping function for each leaf with signature Expr fmapleaf(Optional<T>).
Template Parameters
Tthe content type of nested msg.
FTypeThe mapping function type.

◆ OnlyUsedBy()

PatternSeq tvm::relax::OnlyUsedBy ( const PatternSeq lhs,
const PatternSeq rhs,
int  index = -1 
)

Create only-used-by relationship between lhs[-1] and rhs[0], with [*lhs, *rhs] returned.

Parameters
lhsLeft hand side of the used-by relationship.
rhsRight hand side of the used-by relationship.
indexlhs[-1] is used as the index'th argument of rhs[0].
Returns
PatternSeq The concatenated sequence of [*lhs, *rhs].

◆ operator>>()

PatternSeq tvm::relax::operator>> ( const PatternSeq lhs,
const PatternSeq rhs 
)

Syntax sugar of OnlyUsedBy(lhs, rhs, -1).

◆ operator^()

PatternSeq tvm::relax::operator^ ( const PatternSeq lhs,
const PatternSeq rhs 
)

Syntax sugar of UsedBy(lhs, rhs, -1).

◆ PostOrderVisit()

void tvm::relax::PostOrderVisit ( const Expr node,
std::function< void(const Expr &)>  fvisit 
)

◆ RemoveAllUnused()

Expr tvm::relax::RemoveAllUnused ( Expr  expr)

Remove unused statements inside DataflowBlocks.

Parameters
exprThe expression (typically a relax::Function) from which to remove unused statements.
Returns
The updated function with no unused statements in DataflowBlock.

◆ RewriteBindings()

Function tvm::relax::RewriteBindings ( const PatternContext ctx,
TypedPackedFunc< Map< Var, Expr >(Map< DFPattern, Var >, Map< Var, Expr >)>  rewriter,
Function  f 
)

Rewrite a function with the given pattern and the rewriter function.

Parameters
ctxThe pattern constraint context under which rewriting takes place.
rewriterThe function to be called on a successful matching for rewriting. Given the map of patterns and corresponding variables (bound variables or parameters), it should return a map that specifies new values for matched bound variables.
fThe function to rewrite
Returns
The rewritten or the input function, depending on the pattern matching result.

◆ RewriteCall()

Function tvm::relax::RewriteCall ( const DFPattern pattern,
TypedPackedFunc< Expr(Expr, Map< DFPattern, Expr >)>  rewriter,
Function  func 
)

Rewrite a function with the given pattern and the rewriter function.

Pattern match and replace at an expression level. This level of granularity does not allow simultaneous replacement cannot be performed. In addition, removal of bindings cannot be performed explicitly, and is only done implicitly through RemoveAllUnused. See also RewriteBindings, which performs replacement on a block-level, and does not have these restrictions.

Parameters
patternThe pattern to be replaced
rewriterThe function to be called on a successful pattern matching. Given the matched expression and a map of sub-matches, it should return the replacement expression. If the expression doesn't require updating (e.g. replacement required checks beyond those expressed in the pattern), it should return the expression unmodified.
funcThe function to rewrite
Returns
The updated function, if any updates were applied.

◆ StructInfoBaseCheck()

BaseCheckResult tvm::relax::StructInfoBaseCheck ( const StructInfo base,
const StructInfo derived,
arith::Analyzer ana = nullptr 
)

Run a base check to see if base subsumes derived.

This function returns fine-grained base-check result on reasons of failure.

Parameters
baseThe base struct info.
derivedThe derived struct info.
anaOptional context analyzer to prove symbolic expression equality.
Returns
Whether the relation holds.
See also
BaseCheckResult

◆ StructInfoBaseCheckPrecondition()

PrimExpr tvm::relax::StructInfoBaseCheckPrecondition ( const StructInfo base,
const StructInfo derived 
)

Return the condition for which base is a superset of derived.

This function returns finer-grained conditions for kFailL2 than StructInfoBaseCheck

If the returned expression is true, or simplifies to true, then base is a superset of derived. If the returned expression is false, or simplifies to false, then base is not a superset of derived.

If the returned expression is neither true nor false, it is an expression in terms of the symbolic variables available in base and derived.

Parameters
baseThe base struct info.
derivedThe derived struct info.
Returns
Whether base is a base of derived.
See also
BaseCheckResult

◆ StructInfoFromType()

StructInfo tvm::relax::StructInfoFromType ( const Type type)

Get the corresponding struct info from static type.

Parameters
typeThe input type
Returns
the corresponding struct info.

◆ StructInfoLCA()

StructInfo tvm::relax::StructInfoLCA ( const StructInfo lhs,
const StructInfo rhs,
arith::Analyzer ana = nullptr 
)

Unify the two struct info to their least common ancestor.

Parameters
lhsThe left operand.
rhsThe right operand.
anaOptional context analyzer to prove symbolic expression equality.
Returns
The unified information.

◆ SuggestLayoutTransforms()

Map<tir::Block, Map<ObjectRef, tir::IndexMap> > tvm::relax::SuggestLayoutTransforms ( const Function fn,
Array< tir::IndexMap write_buffer_transformations 
)

Using the layout transforms on the outputs, suggest layout transformation on the blocks and buffers for the PrimFunc.

Parameters
fnThe PrimFunc to be analyzed.
write_buffer_transformationsArray of IndexMap transformations on PrimFunc outputs.
Returns
Suggested transforms per block in fn. For each block the returned value is a map from the object (block or buffer) to it's index map transformation.

◆ TIRVarsInStructInfo()

Array<tir::Var> tvm::relax::TIRVarsInStructInfo ( const StructInfo sinfo)

Get the TIR variables that appear in the input struct info. The returned list is deduplicated - each TIR variable will appear at most once.

Parameters
sinfoThe struct info object to be analyzed.
Returns
The list of TIR variables that appear in the input struct info.

◆ ToNonDataflow()

Expr tvm::relax::ToNonDataflow ( const Expr e)

Transform all dataflow structure to non-dataflow version.

◆ TransformTupleLeaf() [1/2]

template<typename T , std::size_t N, typename FType >
Expr tvm::relax::TransformTupleLeaf ( Expr  expr,
std::array< NestedMsg< T >, N >  msgs,
FType  ftransleaf 
)

Recursively transform the tuple structure in expr and msgs along with it.

This function will call ftransleaf for each leaf expression in expr. This function will throw an error if the nesting structure in msg does not match the tuple nesting structure in expr.

Parameters
exprThe input expression to be transform. 
msgsThe input messages to guide the transformation.
ftransleafwith signature ftransleaf(Expr, Array<NestedMsg<T>>)->Expr
Template Parameters
Tthe content type of nested msg
Nthe number of messages
FTypeThe visit function type.

◆ TransformTupleLeaf() [2/2]

template<typename T , std::size_t N, typename FType >
StructInfo tvm::relax::TransformTupleLeaf ( StructInfo  sinfo,
std::array< NestedMsg< T >, N >  msgs,
FType  ftransleaf 
)

Recursively transform the tuple structure in sinfo and msgs along with it.

This function will call ftransleaf for each leaf sinfo in sinfo. This function will throw an error if the nesting structure in msg does not match the tuple nesting structure in sinfo.

Parameters
sinfoThe input sinfo to be transform. 
msgsThe input messages to guide the transformation.
ftransleafwith signature ftransleaf(StructInfo, Array<NestedMsg<T>>)->StructInfo
Template Parameters
Tthe content type of nested msg
Nthe number of messages
FTypeThe visit function type.

◆ UpdateStructInfo()

void tvm::relax::UpdateStructInfo ( Expr  expr,
StructInfo  struct_info 
)

Update the struct info of an Expr.

Parameters
exprThe Expr whose struct info to be updated.
struct_infoThe struct_info assigned.
Note
We ensure idempotence, that is we can only update the struct_info of an Expr only if the original one is nullptr.

◆ UsedBy()

PatternSeq tvm::relax::UsedBy ( const PatternSeq lhs,
const PatternSeq rhs,
int  index = -1 
)

Create used-by relationship between lhs[-1] and rhs[0], with [*lhs, *rhs] returned.

Parameters
lhsLeft hand side of the used-by relationship.
rhsRight hand side of the used-by relationship.
indexlhs[-1] is used as the index'th argument of rhs[0].
Returns
PatternSeq The concatenated sequence of [*lhs, *rhs].

◆ WellFormed()

bool tvm::relax::WellFormed ( Variant< IRModule, Function obj,
bool  check_struct_info = true 
)

Check if the IRModule is well formed.

Parameters
objThe IRModule or relax::Function to check.
check_struct_infoA boolean flag indicating if the property "every Expr must have defined structure info" will be checked.
Returns
true if the object is well formed, false if not.
Note
By default the structure info is always checked. It is only in test cases where check_struct_info might be false, so that other well-formed requirements will be well tested and will not be blocked by not having structure info.

◆ Wildcard()

WildcardPattern tvm::relax::Wildcard ( )

Syntatic Sugar for creating a WildcardPattern.

◆ WithFields() [1/4]

Call tvm::relax::WithFields ( Call  call,
Optional< Expr opt_op = OptionalExpr >(),
Optional< Array< Expr >>  opt_args = OptionalArrayExpr >>(),
Optional< Attrs opt_attrs = OptionalAttrs >(),
Optional< Array< StructInfo >>  opt_sinfo_args = OptionalArrayStructInfo >>(),
Optional< Span opt_span = OptionalSpan >() 
)

Returns call with the given properties. A null property denotes 'no change'. Returns call if all properties are unchanged. Otherwise, returns a copy with the new fields.

◆ WithFields() [2/4]

If tvm::relax::WithFields ( If  if_expr,
Optional< Expr opt_cond = OptionalExpr >(),
Optional< Expr opt_true_branch = OptionalExpr >(),
Optional< Expr opt_false_branch = OptionalExpr >(),
Optional< Span opt_span = OptionalSpan >() 
)

Returns if_expr with the given properties. A null property denotes 'no change'. Returns if_expr if all properties are unchanged. Otherwise, returns a copy with the new fields.

◆ WithFields() [3/4]

Tuple tvm::relax::WithFields ( Tuple  tuple,
Optional< Array< Expr >>  opt_fields = OptionalArrayExpr >>(),
Optional< Span opt_span = OptionalSpan >() 
)

Returns tuple with the given properties. A null property denotes 'no change'. Returns tuple if all properties are unchanged. Otherwise, returns a copy with the new fields.

◆ WithFields() [4/4]

TupleGetItem tvm::relax::WithFields ( TupleGetItem  tuple_get_item,
Optional< Expr opt_tuple = OptionalExpr >(),
Optional< Integer opt_index = OptionalInteger >(),
Optional< Span opt_span = OptionalSpan >() 
)

Returns tuple_get_item with the given properties. A null property denotes 'no change'. Returns tuple_get_item if all properties are unchanged. Otherwise, returns a copy with the new fields.