/* Copyright (c) 2016 PaddlePaddle Authors. All Rights Reserve.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. */

// Protocol Message for 3rd-party language binding.
//
// Paddle Python package will use `OpProto` to generate op creation methods.
// The op creation methods take user's input and generate `OpDesc` proto message,
// then pass `OpDesc` to C++ side and create Op pointer.
//
syntax="proto2";
package paddle.framework;

import "attr_type.proto";

// Attribute protocol message for 3rd-party language binding.
// It will store the Op support what attribute and what type.
message AttrProto {
    // Supported attribute name. e.g. `scale` for cosine op.
    required string name = 1;

    // Supported attribute type.
    required AttrType type = 2;

    // Supported attribute comments. It helps 3rd-party language generate doc-string.
    required string comment = 3;

    // If that attribute is generated, it means the Paddle third language
    // binding has responsibility to fill that attribute. End-User should
    // not set that attribute.
    optional bool generated = 4 [default=false];
}

// Input or output message for 3rd-party language binding.
// It contains parameter name and its comments.
message VarProto {
    // Input or output name in that op creation function.
    // e.g. `cos(a, b, output, ...)`, "a", "b", "output" are names.
    required string name = 1;

    // The comment for that input. It helps 3rd-party language generate doc-string.
    required string comment = 2;

    // Is that input/output could be a list or not.
    // If so, that Op should write a attributed named `input_format` or
    // `output_format`.
    //
    // e.g.
    //   If the op is a fc op, the inputs are `X`, `W`, `b`. The `X` and `W`
    //   could be multiple, so the multiple of `X` and `W` is True, and OpDesc
    //   will hold a attribute of them.
    //
    //   The Op desc of same fc could be
    //   {
    //      "type": "fc",
    //      "input": ["X1", "X2", "W1", "W2", "b"],
    //      "output": "fc.out",
    //      "attrs" : {
    //        "input_format": [0, 2, 4, 5]
    //      }
    //   }
    //
    optional bool multiple = 3 [default=false];

    // It marks that output is a temporary output. That output is not used by
    // user, but used by other op internally as input. If other op is not use
    // that output, it could be optimized early.
    //
    // Attribute temporary_index will be set in OpDesc if there is some
    // outputs are temporary.
    //
    // output = [ "xxx.out1", "xxx.tmp", "xxx.out2"],
    // attrs = {
    //   "temporary_index": [1]
    // }
    optional bool temporary = 4 [default=false];

    // The gradient of operator can be ignored immediately
    // e.g. operator AddOp, y = x1 + x2, the gradient of dy/dx1, dy/dx2
    // can be ignored for the future optimized on graph.
    optional bool ignore_gradient = 6;
}

// Op protocol message for 3rd-party language binding.
// It contains all information for generating op creation method.
message OpProto {
    // The input information to generate op creation method.
    repeated VarProto inputs = 1;

    // The output information to generate op creation method.
    repeated VarProto outputs = 2;

    // The attribute information to generate op creation method.
    repeated AttrProto attrs = 3;

    // The comments for that Op. It helps 3rd-party language generate
    // doc-string. The whole documentation of that Op is generated by comment,
    // inputs, outputs, attrs together.
    required string comment = 4;

    // The type of that Op.
    required string type = 5;

}