mindspore.rewrite

MindSpore Rewrite package. This is an experimental python package that is subject to change or deletion.

class mindspore.rewrite.Node(node: NodeImpl)

Node is a data structure represents a source code line in network.

For the most part, Node represents an operator invoking in forward which could be an instance of Cell, an instance of Primitive or a callable method.

NodeImpl mentioned below is implementation of Node which is not an interface of Rewrite. Rewrite recommend invoking specific create method of Node to instantiate an instance of Node such as create_call_cell rather than invoking constructor of Node directly, so don’t care about what is NodeImpl and use its instance just as a handler.

Parameters

node (NodeImpl) – A handler of NodeImpl.

static create_call_cell(cell: Cell, targets: [Union[ScopedValue, str]], args: [ScopedValue] = None, kwargs: {str: ScopedValue} = None, name: str = '', is_sub_net: bool = False)

Create a node. Only support create from a Cell now.

A node is corresponding to source code like:

`targets` = self.`name`(*`args`, **`kwargs`)

Parameters

• cell (Cell) – Cell-operator of this forward-layer.

• targets (list[ScopedValue]) – Indicate output names. Used as targets of an assign statement in source code. Rewrite will check and ensure the uniqueness of each target while node being inserted.

• args (list[ScopedValue]) – Indicate input names. Used as args of a call expression of an assign statement in source code. Default is None indicate the cell has no args inputs. Rewrite will check and ensure the uniqueness of each arg while node being inserted.

• kwargs (dict) – Type of key must be str and type of value must be ScopedValue. Indicate keyword input names. Used as kwargs of a call expression of an assign statement in source code. Default is None indicate the cell has no kwargs inputs. Rewrite will check and ensure the uniqueness of each kwarg while node being inserted.

• name (str) – Indicate the name of node. Used as field name in source code. Default is None. Rewrite will generate name from targets when name is None. Rewrite will check and ensure the uniqueness of name while node being inserted.

• is_sub_net (bool) – Indicate that is cell a network. If is_sub_net is true, Rewrite will try to parse the cell to a TreeNode, else a CallCell Node. Default is a False.

Returns

An instance of Node.

Raises

• TypeError – If cell is not a Cell.

• TypeError – If targets is not list.

• TypeError – If the type of targets is not in [ScopedValue, str].

• TypeError – If arg in args is not a ScopedValue.

• TypeError – If key of kwarg is not a str or value of kwarg in kwargs is not a ScopedValue.

get_args()

Get the arguments of current node.

• When node_type of current node is CallCell, CallPrimitive or Tree, arguments are corresponding to args of ast.Call which represents arguments to invoke forward method of cell-op or primitive-op.

• When node_type of current node is Input, arguments represents default-value of argument of function.

• When node_type of current node is Output, arguments represents return values.

• When node_type of current node is Python, arguments are don’t-care.

Returns

A list of instances of ScopedValue.

get_attribute(key: str)

Get attribute of current node by key.

Parameters

key (str) – Key of attribute.

Returns

A object as attribute.

Raises

TypeError – If key is not a str.

get_attributes()

Get all attributes of current node.

Returns

A dict of str to instance of object as attributes.

get_handler()

Get handler of node implementation.

Returns

An instance of NodeImpl.

get_inputs()

Get input nodes of current node in topological order.

Returns

A list of instances of Node as input nodes.

get_instance()

Get the instance of current node.

• When node_type of current node is CallCell, instance is an instance of Cell.

• When node_type of current node is CallPrimitive, instance is an instance of primitive.

• When node_type of current node is Tree, instance is an instance of network-cell.

• When node_type of current node is Python, Input, Output or CallMethod, instance should be None.

Returns

A object represents corresponding instance of current node.

get_instance_type()

Get the instance_type of current node.

• When node_type of current node is CallCell, instance_type is type of cell-op.

• When node_type of current node is CallPrimitive, instance_type is type of primitive-op.

• When node_type of current node is Tree, instance_type is type of network-cell.

• When node_type of current node is Python, Input, Output or CallMethod, instance_type should be NoneType.

Returns

A type object represents corresponding instance type of current node.

get_kwargs()

Get the keyword arguments of current node.

• When node_type of current node is CallCell, CallPrimitive or Tree, keyword arguments are corresponding to kwargs of ast.Call which represents arguments to invoke forward method of cell-op or primitive-op.

• When node_type of current node is Python, Input or Output, keyword arguments are don’t-care.

Returns

A dict of str to instance of ScopedValue.

get_name()

Get the name of current node.

When node has been inserted into SymbolTree, the name of node should be unique in SymbolTree.

Returns

A string as name of node.

get_next()

Get next node of current node in source code order.

Returns

An instance of Node as next node.

get_node_type()

Get the node_type of current node.

Returns

A NodeType as node_type of node.

get_prev()

Get previous node of current node in source code order.

Returns

An instance of Node as previous node.

get_targets()

Get targets of current node.

• When node_type of current node is CallCell, CallPrimitive, CallMethod or Tree, targets are strings represents invoke result of the cell-op or primitive-op or function-call which are corresponding to targets of ast.Assign.

• When node_type of current node is Input, targets should have only one element which is a string represents parameter of function.

• When node_type of current node is Python or Output, targets are don’t-care.

Returns

A list of instances of ScopedValue as targets of node.

get_users()

Get output nodes of current node in topological order.

Returns

A list of nodes represents users.

set_arg(index: int, arg: Union[ScopedValue, str])

Set argument of current node.

Parameters

• index (int) – Indicate which input being modified.

• arg (Union[ScopedValue, str]) – New argument to been set.

Raises

• TypeError – If index is not a int number.

• TypeError – If the type of arg is not in [ScopedValue, str].

set_arg_by_node(arg_idx: int, src_node: 'Node', out_idx: Optional[int] = None)

Set argument of current node by another Node.

Parameters

• arg_idx (int) – Indicate which input being modified.

• src_node (Node) – A Node as new input. Can be a node or name of node.

• out_idx (int, optional) – Indicate which output of src_node as new input of current node. Default is None which means use first output of src_node as new input.

Raises

• RuntimeError – If src_node is not belong to current SymbolTree.

• RuntimeError – If current node and src_node is not belong to same SymbolTree.

• TypeError – If arg_idx is not a int number.

• ValueError – If arg_idx is out of range.

• TypeError – If src_node is not a Node instance.

• TypeError – If out_idx is not a int number.

• ValueError – If out_idx is out of range.

• ValueError – If src_node has multi-outputs while out_idx is None or out_idx is not offered.

set_attribute(key: str, value)

Set attribute of current node.

Parameters

• key (str) – Key of attribute.

• value (object) – Value of attribute.

Raises

TypeError – If key is not a str.

class mindspore.rewrite.NodeType

NodeType represents type of Node.

• Unknown: Not inited NodeType.

• CallCell: CallCell node represents invoking cell-op in forward method.

• CallPrimitive: CallPrimitive node represents invoking primitive-op in forward method.

• CallMethod: CallMethod node represents invoking of method in forward method which can not be mapped to cell-op or primitive-op in MindSpore.

• Python: Python node holds unsupported-ast-node or unnecessary-to-parse-ast-node.

• Input: Input node represents input of SymbolTree corresponding to arguments of forward method.

• Output: Output node represents output of SymbolTree corresponding to return statement of forward method.

• Tree: Tree node represents sub-network invoking in forward method.

class mindspore.rewrite.PatternEngine(pattern: Union[PatternNode, List], replacement: Replacement = None)

PatternEngine is defined how to transform a SymbolTree by PattenNode.

Parameters

• pattern (Union[PatternNode, List]) – An instance of PatternNode or a cell-type-list to construct PatternNode as root of a pattern.

• replacement (callable) – A callable define how to generate new_node.

apply(stree: SymbolTree)

Apply current pattern to a SymbolTree.

Note

Sub-tree node will be supported in the near feature.

Parameters

stree (SymbolTree) – A SymbolTree to be transformed.

Returns

A bool represents if stree been changed.

Raises

TypeError – If stree is not a SymbolTree instance.

pattern()

Getter of pattern.

class mindspore.rewrite.PatternNode(pattern_node_name: str, match_type: Type = Type[None], inputs: ['PatternNode'] = None)

PatternNode is defined as a node while defining pattern.

Parameters

• pattern_node_name (str) – Name of current node.

• match_type (Type) – A type represents what type would be matched of current node.

• inputs (list[PatternNode]) – Input nodes of current node.

add_input(node)

Add an input for current PatternNode.

Parameters

node (PatternNode) – Cell type as an input.

Raises

TypeError – If node is not a PatternNode instance.

static create_pattern_from_list(type_list: [])

Create a Pattern from a cell type list.

Parameters

type_list (list[type]) – Input cell type list.

Returns

A PatternNode as root of pattern created from cell type list.

Raises

TypeError – If type_list is not a list.

static create_pattern_from_node(node: Node)

Create a Pattern from node with its inputs.

Parameters

node (Node) – Input rewrite node.

Returns

A PatternNode as root of pattern created from rewrite node.

Raises

TypeError – If node is not a Node instance.

static from_node(node: Node)

Create a PatternNode from node.

Parameters

node (Node) – Input rewrite node.

Returns

A PatternNode created from node.

Raises

TypeError – If node is not a Node instance.

get_inputs()

Getter of inputs.

match(node: Node)

Check if current PatternNode can match with node.

Parameters

node (Node) – A rewrite node to be match.

Raises

TypeError – If node is not a Node instance.

name()

Getter of name.

set_inputs(inputs)

Set inputs for current PatternNode.

Parameters

inputs (list[PatternNode]) – Inputs to be set as inputs of current PatternNode.

Raises

TypeError – If inputs is not a list or input in inputs is not PatternNode instance.

type()

Getter of type.

class mindspore.rewrite.Replacement

Interface of replacement function.

abstract build(pattern: PatternNode, is_chain_pattern: bool, matched: OrderedDict)

Interface define for creating replacement nodes from matched result.

Note

Return value will be delivered into replace api of SymbolTree as argument, return value should follow restraint of parameter new_nodes of replace api if SymbolTree. See detail in docstring of replace api of SymbolTree.

Parameters

• pattern (PatternNode) – A PatternNode represents root node of current pattern.

• is_chain_pattern (bool) – A bool indicated if pattern is a chain pattern or a tree pattern.

• matched (OrderedDict) – An OrderedDict map from pattern_node name to node represents matched result.

Returns

A list of instance of Node as replacement nodes.

class mindspore.rewrite.ScopedValue(arg_type: ValueType, scope: str = '', value=None)

ScopedValue represents a value with its full-scope.

ScopedValue is used to express: a left-value such as target of an assign statement, or a callable object such as func of a call statement, or a right-value such as args and kwargs of an assign statement.

Parameters

• arg_type (ValueType) – A ValueType represents type of current value.

• scope (str) – A string represents scope of current value. Take “self.var1” as an example, scope of this var1 is “self”.

• value – A handler represents value of current value. The type of value is corresponding to arg_type.

static create_name_values(names: Union[list, tuple], scopes: Union[list, tuple] = None)

Create a list of naming ScopedValue.

Parameters

• names – (list[str] or tuple[str]): List or tuple of str represents names of referenced variables.

• scopes – (list[str] or tuple[str]): List or tuple of str represents scopes of referenced variables.

Returns

An list of instance of ScopedValue.

Raises

• RuntimeError – If the length of names is not equal to the length of scopes when scopes are not None.

• TypeError – If names is not list or tuple and name in names is not str.

• TypeError – If scopes is not list or tuple and scope in scopes is not str.

classmethod create_naming_value(name: str, scope: str = '')

Create a naming ScopedValue. A NamingValue represents a reference to another variable.

Parameters

• name – (str): A string represents the identifier of another variable.

• scope – (str): A string represents the scope of another variable.

Returns

An instance of ScopedValue.

Raises

• TypeError – If name is not str.

• TypeError – If scope is not str.

classmethod create_variable_value(value)

Create ScopedValue from a variable.

ScopedValue’s type is determined by type of value. ScopedValue’s scope is empty.

Parameters

value – The value to be converted to ScopedValue.

Returns

An instance of ScopedValue.

class mindspore.rewrite.SymbolTree(handler: SymbolTreeImpl)

A SymbolTree usually corresponding to forward method of a network.

Parameters

network (Cell) – Network to be rewritten. Only support Cell-type-network now.

Raises

• RuntimeError – If network is not a Cell.

• RuntimeError – If there is any unsupported ast node type while parsing or optimizing.

after(node: Node)

Get insert position after input node.

Position is used to indicate where to insert node, it indicates position in source code rather than position in topological order. We don’t need to care about what Position is, just treat it as a handler and use it as an arguments of insert api of SymbolTree.

Parameters

node (Node) – Indicate the position after which node. Can be a node or name of node.

Returns

A Position to indicate where to insert node.

Raises

TypeError – If node is not a Node.

before(node: Node)

Get insert position before input node.

Position is used to indicate where to insert node, it indicates position in source code rather than position in topological order. We don’t need to care about what Position is, just treat it as a handler and use it as an arguments of insert api of SymbolTree.

Parameters

node (Node) – Indicate the position before which node. Can be a node or name of node.

Returns

A Position to indicate where to insert node.

Raises

TypeError – if node is not a Node.

classmethod create(network)

Create a new SymbolTree of the input network.

Parameters

network (Cell) – network used to create SymbolTree.

Returns

Symboltree, a Symboltree created based on network.

Raises

TypeError – If network is not a Cell instance.

dump()

Dump graph to console.

erase_node(node: Node)

Erase a node from rewrite. Can only erase a node not being depended on.

Parameters

node (Node) – A Node to be erased. Can be a node or name of node.

Returns

An instance of Node being erased if node is in SymbolTree else None.

Raises

TypeError – If node is not a Node.

get_code()

Get source code of modified network.

Returns

A str represents source code of modified network.

get_handler()

Get handler of SymbolTree implementation.

Returns

An instance of SymbolTree.

get_inputs()

Get input nodes of current SymbolTree.

Returns

[Node], the node list of the current Symboltree.

get_network()

Get modified network. The source code of network is saved to a file, the default file name is network_define.py.

Returns

A network object.

get_node(node_name: str)

Get node by node_name.

Parameters

node_name (str) – A string represents name of node.

Returns

An instance of node if find else None.

Raises

TypeError – If node_name is not str.

get_saved_file_name()

Gets the filename used to save the network.

insert(position, node: Node)

Insert a node into SymbolTree at position.

position is obtained from before api or after api of SymbolTree.

Parameters

• position (Position) – Indicate where to insert node.

• node (Node) – An instance of Node to be inserted.

Returns

An instance of Node being inserted. node could be changed while calling this method for uniqueness and custom-object in args or kwargs.

Raises

• RuntimeError – If position is not belong to current SymbolTree.

• TypeError – If position is not a Position.

• TypeError – If node is not a Node.

nodes()

Get a generator for node of corresponding network.

Returns

A generator for node of current SymbolTree.

print_node_tabulate()

Print node information of graph.

replace(old_node: Node, new_nodes: [Node])

Replace old_node with a node_tree.

Note

1. Replace support one-to-one replacement or one-to-multi replacement. If you need multi-to-multi replacement, please refer to PatternEngine.

2. When applying one-to-multi replacement, Rewrite will insert all new_nodes into symbol_tree.

3. Caller should maintain arguments and targets of nodes intra sub-tree for specifying topological relation intra sub-tree.

4. Caller should maintain arguments of input nodes of sub-tree and for specifying topological relation of inputs of sub-tree.

5. Rewrite will maintain arguments of prepend node of sub-tree for specifying topological relation of outputs of sub-tree.

6. Rewrite will maintain all inputs of nodes after replace new_nodes into SymbolTree.

Parameters

• old_node (Node) – Node to be replaced.

• new_nodes (list[Node]) – Nodes of the node_tree to replace in.

Returns

An instance of Node represents root of node_tree been replaced in.

Raises

• RuntimeError – Old node is isolated.

• TypeError – If old_node is not a Node.

• TypeError – If new_nodes is not a list or node in new_nodes is not a Node.

save_network_to_file()

Save the modified network to a file. Default file name is network_define.py.

set_output(index: int, return_value: str)

Set return value of network.

Parameters

• index (int) – Indicate which output being modified.

• return_value (str) – New return value to been set.

Returns

Return node of current rewrite.

Raises

• RuntimeError – If index is out of range.

• TypeError – If index is not a int number.

• TypeError – If return_value is not a str.

set_saved_file_name(file_name: str)

Set the name of the file used to save the network.

Parameters

file_name (str) – filename to be set.

class mindspore.rewrite.TreeNodeHelper

TreeNodeHelper is used to break circle reference while getting symbol_tree from a Tree type Node.

TreeNodeHelper provides a staticmethod get_sub_tree for getting symbol_tree from a Tree type Node.

static get_sub_tree(node: Node)

Getting symbol_tree from a Tree type Node.

Parameters

node (Node) – A Node who may hold a sub-symbol_tree.

Returns

An instance of SymbolTree represents sub-symbol_tree. Note that node’s symbol_tree maybe None, in this case, method will return None.

Raises

• RuntimeError – If node’s type is not NodeType.Tree.

• TypeError – If node is not a Node instance.

class mindspore.rewrite.ValueType

ValueType represents type of ScopedValue.

• A NamingValue represents a reference to another variable.

• A CustomObjValue represents an instance of custom class or an object whose type is out of range of base-type and container-type of ValueType.

class mindspore.rewrite.VarNode

VarNode is a subclass of PatternNode whose match method is always return True.