Operator Prototype Definition APIs

Prototype

See the following example.

REG_OP(xxx)
.INPUT(x1, type)
.OPTIONAL_INPUT(x2, type)
.DYNAMIC_INPUT(x3, type)
.OUTPUT(y1, type)
.DYNAMIC_OUTPUT(y3, type)
.REQUIRED_ATTR(a, type)
.ATTR(b, type, default_value)
.GRAPH(z1)
.DYNAMIC_GRAPH(z2)
.OP_END_FACTORY_REG(xxx)

Description

Defines the inputs, outputs, attributes, and data types of an operator for prototype definition.

After an operator prototype is defined, the prototype is registered with the GE, including the inputs, outputs and attributes of the operators. In addition, an op::xxx Class is defined. You can include the prototype header file and instantiate the class to build an IR model, as shown in the following lines.

conv = op::Conv()
conv.set_input_x(feature_map_data)
conv.set_input_weight(weight_data)

For details about how to build a model, see IR Model Building Guide.

APIs

The OpReg &N() API in the class OpReg is used to call the OpReg APIs in .** mode during operator registration, for example, .INPUT(x, type) and .OUTPUT(x, type).

Returns

None

Restrictions and Limitations

• The operator type passed to the REG_OP call must be unique.
• The input name of the same operator must be unique.
• The output name of the same operator must be unique.
• The attribute name of the same operator must be unique.

Calling Examples and APIs

The following is an example of defining the operator prototype for dynamic input.

REG_OP(AddN)
.DYNAMIC_INPUT(x, TensorType::NumberType())
.OUTPUT(y, TensorType::NumberType())
.REQUIRED_ATTR(N, Int)
.OP_END_FACTORY_REG(AddN)

The following is an example of defining a multi-input operator prototype.

REG_OP(GreaterEqual)
.INPUT(x1, TensorType::RealNumberType())
.INPUT(x2, TensorType::RealNumberType())
.OUTPUT(y, TensorType({DT_BOOL}))
.OP_END_FACTORY_REG(GreaterEqual)

The following is an example of defining the operator prototype for registering a subgraph.

REG_OP(If)
    .INPUT(cond, TensorType::ALL())
    .DYNAMIC_INPUT(input, TensorType::ALL())
    .DYNAMIC_OUTPUT(output, TensorType::ALL())
    .GRAPH(then_branch)
    .GRAPH(else_branch)
    .OP_END_FACTORY_REG(If)

Description of Class TensorType

For details about the data types supported by TensorType, see the atc/include/graph/types.h file in the ATC installation path.

REG_OP

Registers an operator type. Two constructors corresponding to the operator type are automatically generated.

For example, register an operator type Conv2D by calling the REG_OP(Conv2D) API. Two Conv2D constructors are generated. The operator name needs to be specified for Conv2D(const string& name), for example, Conv2D Unique index. If the operator name is left blank, that is, Conv2D(), the default operator name is used.

class Conv2D : public Operator {
    typedef Conv2D _THIS_TYPE;
public:
    explicit Conv2D(const string& name);
    explicit Conv2D();
}

INPUT

After the operator input information is successfully registered, APIs (for obtaining the operator input name and setting the operator input description) are generated automatically.

For example, if the operator input is x and the data type supported by the operator input is TensorType{DT_FLOAT}, call the INPUT(x, TensorType{DT_FLOAT}) API. After the operator input is successfully registered, the following APIs are automatically generated:

static const string name_in_x(); // Returns the input name, that is, x.
_THIS_TYPE&set_input_x(Operator& v, const string& srcName);// Specifies the link between input x and output srcName of the operator object v. The operator object itself is returned.
_THIS_TYPE &set_input_x(Operator &v, uint32_t index); // Specifies the link between input x and output index of the operator object v. The operator object itself is returned.
_THIS_TYPE& set_input_x(Operator& v); // Specifies the link between input x and output 0 of the operator object v. The operator object is returned.
TensorDesc get_input_desc_x(); // Returns the description of input x.
graphStatus update_input_desc_x(const TensorDesc& tensorDesc);// Sets the description of input x, including Shape, DataType, and Format. graphStatus indicates the uint32_t type. If a non-zero value is returned, an error occurs.

OPTIONAL_INPUT

After the optional input information is successfully registered, APIs (for obtaining the operator input name and setting the operator input description) are generated automatically.

For example, if the operator input is b and the data type supported by the operator input is TensorType{DT_FLOAT}, call the OPTIONAL_INPUT(b, TensorType{DT_FLOAT}) API. After the operator input is successfully registered, the following APIs are automatically generated:

static const string name_in_b(); // Returns the input name, that is, b.
_THIS_TYPE& set_input_b(Operator& v, const string& srcName);// Specifies the link between input b and output srcName of the operator object v. The operator object itself is returned.
_THIS_TYPE& set_input_b(Operator& v); // Specifies the link between input x and output 0 of the operator object v. The operator object is returned.
TensorDesc get_input_desc_b(); // Returns the description of input b.
graphStatus update_input_desc_b(const TensorDesc& tensorDesc);// Sets the description of input b, including Shape, DataType, and Format.

DYNAMIC_INPUT

After the dynamic input information is successfully registered, APIs (for creating dynamic input and setting the input description) are generated automatically.

For example, if the dynamic input is d and the data type supported by the operator input is TensorType{DT_FLOAT}, call the DYNAMIC_INPUT(d, TensorType{DT_FLOAT}) API. After the dynamic input is successfully registered, the following APIs are automatically generated:

_THIS_TYPE& create_dynamic_input_d(unsigned int num); //: Creates dynamic input d, including num inputs. The two inputs are the last input of the operator.
_THIS_TYPE &create_dynamic_input_byindex_d(unsigned int num, size_t index) // Creates dynamic inputs d, including num inputs, and inserts y behind the position indexed index. This API is mutually exclusive with create_dynamic_input_d.
TensorDesc get_dynamic_input_desc_d(unsigned int index);// Returns description indexth of dynamic input d, including Shape, DataType, and Format.
graphStatus update_dynamic_input_desc_d(unsigned int index, const TensorDesc& tensorDesc);// Updates description indexth of dynamic input d.
_THIS_TYPE& set_dynamic_input_d(unsigned int dstIndex, Operator &v); // Specifies that the dynamic input indexed dstIndex has a connection with index 0 of the operator object v, and returns the operator object itself.
_THIS_TYPE& set_dynamic_input_d(unsigned int dstIndex, Operator &v, const string &srcName); // Specifies the link between input dstIndex of d and output srcName of the operator object v. The operator object itself is returned.

OUTPUT

After the operator output information is successfully registered, APIs (for obtaining the operator output name and setting the operator output description) are generated automatically.

For example, if the operator output is y and the data type supported by the operator input is TensorType{DT_FLOAT}, call the OUTPUT(y, TensorType{DT_FLOAT}) API. After the operator output is successfully registered, the following APIs are automatically generated:

static const string name_out_y();// Returns the output name, that is, y.
TensorDesc get_output_desc_y();// Returns the description of output y.
graphStatus update_output_desc_y(const TensorDesc& tensorDesc););// Sets the description of output y, including Shape, DataType, and Format.

DYNAMIC_OUTPUT

After the dynamic output information is successfully registered, APIs (for creating dynamic output and setting the output description) are generated automatically.

For example, if the dynamic output is d and the data type supported by the operator output is TensorType{DT_FLOAT}, call the DYNAMIC_OUTPUT (d, TensorType{DT_FLOAT}) API. After the dynamic output is successfully registered, the following APIs are automatically generated:

_THIS_TYPE& create_dynamic_output_d(unsigned int num); // Creates dynamic output d, including a number of num inputs.
TensorDesc get_dynamic_output_desc_d(unsigned int index);// Returns description indexth of dynamic output d, including Shape, DataType, and Format.
graphStatus update_dynamic_output_desc_d(unsigned int index, const TensorDesc& tensorDesc);// Updates description indexth of dynamic output d.

REQUIRED_ATTR

After the operator attributes are successfully registered, three external APIs (for obtaining the attribute name, obtaining the attribute value, and setting the attribute value, respectively) are automatically generated.

For example, register the attribute mode of the int64_t type by calling the REQUIRED_ATTR (mode, Int) API. After the operator attribute is successfully registered, the following APIs are automatically generated:

static const string name_attr_mode(); // Returns the attribute name, that is, mode.
OpInt get_attr_mode() const; // Returns the value of the mode attribute. OpInt indicates int64_t.
_THIS_TYPE& set_attr_mode(const OpInt& v); // Sets the value of the mode attribute. A this object is returned.

ATTR

After the operator attributes are successfully registered, three external APIs (for obtaining the attribute name, obtaining the attribute value, and setting the attribute value, respectively) are automatically generated.

The following describes the operator attribute APIs generated in int64_t and int64_t list scenarios:

• Call ATTR(mode, Int, 1) to register the attribute mode. The attribute is of type int64_t and the default value is 1.

  After the attribute is successfully registered, the following APIs are automatically generated:

  static const string name_attr_mode(); // Returns the attribute name, that is, mode.
  OpInt get_attr_mode() const; // Returns the value of the mode attribute. OpInt indicates int64_t.
  _THIS_TYPE& set_attr_mode(const OpInt& v); // Sets the value of the mode attribute. The operator object is returned.

• Call ATTR(pad, ListInt, {0, 0, 0, 0}) to register the attribute pad. The attribute is a list of int64_t integers, and the default value is {0,0,0,0}.

  After the attribute is successfully registered, the following APIs are automatically generated:

  static const string name_attr_pad(); // Returns the attribute name, that is, pad.
  OpListInt get_attr_pad() const;; // Return the value of the attribute pad, that is, OpListInt, indicating vector<int64_t>.
  _THIS_TYPE& set_attr_pad(const OpListInt& v); // Set the value of the attribute pad and return the operator object itself.

GRAPH

After successfully registered, the following APIs are automatically generated for obtaining the name and description of the subgraph, and setting the description of the subgraph.

For example, to register operator subgraph y, call GRAPH(y). After the subgraph is successfully registered, the following APIs are automatically generated:

static const string name_graph_y(); // Returns the subgraph name, that is, y.
SubgraphBuilder get_subgraph_builder_y() const;// Returns the SubgraphBuilder object of subgraph y.
_THIS_TYPE &set_subgraph_builder_y(const SubgraphBuilder &v);// Sets the SubgraphBuilder object of subgraph y.
Graph get_subgraph_y() const; // Sets the Graph object of subgraph y.

DYNAMIC_GRAPH

After successfully registered, APIs (for creating a subgraph, and setting the description of the subgraph) are automatically generated.

For example, to register dynamic operator subgraphs branches, call DYNAMIC_GRAPH (branches). After the subgraph is successfully registered, the following APIs are automatically generated:

_THIS_TYPE& create_dynamic_subgraph_branches(unsigned int num); // Creates dynamic subgraphs branches, including num subgraphs.
SubgraphBuilder get_dynamic_subgraph_builder_branches(unsigned int index) ;// Returns the SubgraphBuilder object of the dynamic subgraph indexed index.
Graph get_dynamic_subgraph_branches(unsigned int index) ;// Returns the Graph object of the dynamic subgraph indexed index.
_THIS_TYPE &set_dynamic_subgraph_builder_branches(unsigned int index,const SubgraphBuilder &v);// Sets the SubgraphBuilder object of the dynamic subgraph indexed index.