ir.base

Concepts

Conceptually, uTensorGraph works like a container of TensorInfo and OperationInfo.

That is, as long as the TensorInfo and OperationInfo is not dangling, they always belong to some uTensorGraph which should be accessible via ugraph property of both TensorInfo and OperationInfo.

Otherwise, the graph, tensor or op is dangling.

For short, we’ll refer an instance of OperationInfo as an op or a node.

Developer Note

Keep following tips in mind if you try to directly manipulate the state of a graph, op or tensor

  • No shallow copy allowed
  • About TensorInfo:
    • name, op_name, dtype and shape are the only attributes you can manipulate directly
      • when you do, you are responsible to make sure these values are valid
    • make sure the op_name is set as the OperationInfo’s name which gererates this tensor
      • op_name is the identifier used to retrieve the op in the graph
      • incorrect op_name may make the tensor dangling
    • When you try to transfer a tensor from one graph to the other, use TensorInfo.move_into method.
    • passing a uTensorGraph as an argument to the constructor means this tensor is owned by the given graph.
  • About OperationInfo:
    • make sure the name is consistant with the op_name of tensors in output_tensors
    • Just like TensorInfo, the ownership is established by passing a uTensorGraph as an argument to its constructor
    • make sure you update n_inputs and n_outputs when you make changes to input_tensors and output_tensors
    • When you try to transfer a op from one graph to the other, use OperationInfo.move_into.
  • About uTensorGraph: - please read the note list in uTensorGraph

Module members

class utensor_cgen.ir.base.OperationInfo
Parameters:
  • name (str) – the name of the node
  • input_tensors (List[TensorInfo]) – the input tensors of the node
  • output_tensors (List[TensorInfo]) – the output tensors of the node
  • op_type (str) – the type of the node (ex: Add)
  • lib_name (str) – the name of the training library/framework, {‘tensorflow’, ‘pytorch’}
  • ugraph (uTensorGraph) – the graph which owns this op
  • op_attr (dict) – a dict containing extra information of this op
  • op_attr is dictionary with key as str and value as generic types, where generic types are types returned by ConverterFactor. all_generic_types
  • The only exception is the key which match regex pattern r'_[^_]*'. That is, any name starts with single _.
    • The values of such keys will be saved as-is without any type conversion.
add_null_input_tensor(self, idx=-1)

Insert null tensor as input tensor at given index

See TensorInfo.make_null_tensor for detail

Parameters:idx (int) – the position to be inserted
input_nodes

The ops which connected to this op by their output tensors

Return type:List[OperationInfo]
lib_name

The name of training library/framework

Return type:six.strings_type
move_into(self, ugraph)

Move semantic of the OperationInfo objects

it will transfer the ownership from current graph to the given graph

Parameters:ugraph (uTensorGraph) – the graph to transfer the ownership to
output_nodes

The ops which connected to this op by their input tensors

Return type:List[OperationInfo]
ugraph

The uTensorGraph which owns the op

Return type:uTensorGraph
class utensor_cgen.ir.base.TensorInfo
Parameters:
  • name (six.string_types) – the name of the tensor
  • op_name (six.string_types) – the name of the operator which generate this tensor
  • dtype (numpy.dtype) – the data type of the elements.
  • shape (list) – the shape of the tensor. Should be a list of integers or None.
  • ugraph (uTensorGraph) – a uTensorGraph, which this tensor belongs to. By passing an uTensorGraph object to the constructor, the tensor is *owned* by the graph
is_null_tensor

whether the tensor is a null tensor or not

Return type:bool
lib_name

the name of training library/framework the graph

Return type:six.string_types
classmethod make_null_tensor(cls, ugraph, dtype=np.dtype('float'), shape=None)

Make a null tensor

A null tensor is a tensor comes from nowhere, that is, it is not generated by any node in the graph

Parameters:
  • ugraph (uTensorGraph) – the graph where to add the null tensor
  • dtype (numpy.dtype) – the data type of the elements
  • shape (list) – the shape of the tensor
Return type:

TensorInfo
move_into(self, ugraph)

Move semantic of the TensorInfo objects

it will move the tensor to the given graph, that is, transferring ownership of the tensor from original graph to other graph

op

OperationInfo which generate this tensor

None returned for null tensor, see make_null_tensor

Return type:OperationInfo or None
ugraph

uTensorGraph which the tensor belongs to

Return type:uTensorGraph
class utensor_cgen.ir.base.uTensorGraph
Parameters:
  • output_nodes (list) – a list of names of ops which are the output nodes in the graph
  • ops_info (dict) – a dict with key as string, the op’s name, and value as an instance of OperationInfo
  • lib_name – the name of library/framework training the graph.

Can only be 'tensorflow' or 'pytorch' (future work) :type lib_name: str

NOTE:

  • topo_order is a non-init attribute which is set accordingly by the given ops_info and output_nodes. It will be a list of op names in topological sorting order

  • (IMPORTANT) How to build a uTensorGraph

    1. create a empty graph
    • give a list of names of output nodes (required)
    • (optional) give lib_name string
    • leave ops_info empty
    1. setup the ops_info
    • when you set the value of ops_info, which is an OperationInfo instance, make sure its ugraph attribute is the ugraph you just created at step 1
    1. pass the graph to utils.topologic_order_graph to setup the order of the ops
get_ops_by_type(self, given_op_type)

Return the ops of given type in the graph

Parameters:given_op_type (six.string_types) – the op_type to search with
Return type:List[OperationInfo]
graph_def

Dynamically generated tensorflow.GraphDef object

Return type:tensorflow.GraphDef
input_ops

list of input nodes

a node is considered as input node iff any one of following condition is true

  1. it takes no input tensor
  2. one of its input tensors is a null tensor
Return type:List[OperationInfo]
input_tensors

list of input tensors

a tensor is an input tensor iff its op is listed in input_ops

Return type:List[TensorInfo]
lib_name

the name of training library/framework

Return type:six.strings_type
ops

the ops of the graph in topological sorting order

Return type:List[OperationInfo]
output_ops

list of output nodes

Return type:List[OperationInfo]
output_tensors

list of output tensors

Return type:List[TensorInfo]
unsafe_merge_into(self, other_ugraph)

Merge this graph with other given graph (unsafe)

Parameters:other_ugraph (uTensorGraph) – the other graph to merge into

NOTE:(IMPORTANT)

As the name suggest, this method is not safe. Whenever you make a method call, you should consider both the graph and the other ugraph are dangling, which means following attribute may not be valid:

  • output_nodes
    • you have to manually merge the output_nodes of the two graphs
  • topo_order
  • ops_info

You should fix output_nodes first before performing any other checks and fixs.

As for topo_order and ops_info, you can make use of follwoing functions:

  1. utils.prune_graph: remove all ops that is not needed for computing output tensors of output nodes
  2. utils.topologic_order_graph: it will fix topo_order attribute of given graph in-place, given that output_nodes is valid.