layer_function_generator.py 12.2 KB
Newer Older
1
#  Copyright (c) 2018 PaddlePaddle Authors. All Rights Reserved.
D
dzhwinter 已提交
2
#
3 4 5
# 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
D
dzhwinter 已提交
6 7 8
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
9 10 11 12 13
# 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.
14 15

from __future__ import print_function
D
dzhwinter 已提交
16 17
import re
import functools
18
import warnings
Y
yuyang18 已提交
19
import string
D
dzhwinter 已提交
20

21
from six.moves import cStringIO
22
from ..proto import framework_pb2
W
Wu Yi 已提交
23
from ..framework import OpProtoHolder, Variable, core, convert_np_dtype_to_dtype_
24
from ..layer_helper import LayerHelper
25
from ..data_feeder import check_type_and_dtype
D
dzhwinter 已提交
26

27
__all__ = [
28
    'deprecated', 'generate_layer_fn', 'generate_activation_fn', 'autodoc',
29 30
    'templatedoc'
]
D
dzhwinter 已提交
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48


def _convert_(name):
    """
    Formatting.

    Args:
       name: The name/alias

    This function takes in a name and converts it to a standard format of
    group1_group2. Where as per the regular expression, group1 can have
    alphabets and numbers and group2 has capital alphabets.

    """
    s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
    return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()


Y
yuyang18 已提交
49 50 51 52
def _type_to_str_(tp):
    return framework_pb2.AttrType.Name(tp)


53 54 55 56 57
_two_dollar_pattern_ = re.compile(r"\$\$([^\$]+)\$\$")
_single_dollar_pattern_ = re.compile(r"\$([^\$]+)\$")
_two_bang_pattern_ = re.compile(r"!!([^!]+)!!")


Y
yuyang18 已提交
58 59 60 61 62 63 64
def escape_math(text):
    return _two_bang_pattern_.sub(
        r'$$\1$$',
        _single_dollar_pattern_.sub(r':math:`\1`',
                                    _two_dollar_pattern_.sub(r"!!\1!!", text)))


65 66 67
def _generate_doc_string_(op_proto,
                          additional_args_lines=None,
                          skip_attrs_set=None):
D
dzhwinter 已提交
68 69 70 71 72 73 74 75 76 77 78 79 80
    """
    Generate docstring by OpProto

    Args:
        op_proto (framework_pb2.OpProto): a protobuf message typed OpProto

    Returns:
        str: the document string
    """

    if not isinstance(op_proto, framework_pb2.OpProto):
        raise TypeError("OpProto should be `framework_pb2.OpProto`")

81
    buf = cStringIO()
82
    buf.write(escape_math(op_proto.comment))
D
dzhwinter 已提交
83 84 85 86
    buf.write('\nArgs:\n')
    for each_input in op_proto.inputs:
        line_begin = '    {0}: '.format(_convert_(each_input.name))
        buf.write(line_begin)
87 88 89 90 91
        buf.write(escape_math(each_input.comment))
        if each_input.duplicable:
            buf.write("  Duplicatable.")
        if each_input.dispensable:
            buf.write("  Optional.")
D
dzhwinter 已提交
92 93
        buf.write('\n')

94
    skip_attrs = OpProtoHolder.generated_op_attr_names()
95 96 97
    # attr use_mkldnn and is_test also should not be visible to users.
    skip_attrs.add("use_mkldnn")
    skip_attrs.add("is_test")
98
    skip_attrs.add("use_cudnn")
99 100 101 102 103

    if skip_attrs_set:
        for t in skip_attrs_set:
            skip_attrs.add(t)

D
dzhwinter 已提交
104
    for each_attr in op_proto.attrs:
105 106
        if each_attr.name in skip_attrs:
            continue
D
dzhwinter 已提交
107 108 109 110 111
        buf.write('    ')
        buf.write(each_attr.name)
        buf.write(' (')
        buf.write(_type_to_str_(each_attr.type))
        buf.write('): ')
112
        buf.write(escape_math(each_attr.comment))
D
dzhwinter 已提交
113 114
        buf.write('\n')

S
sneaxiy 已提交
115 116 117 118 119 120 121
    if additional_args_lines is not None:
        for line in additional_args_lines:
            line = line.strip()
            buf.write('    ')
            buf.write(line)
            buf.write('\n')

D
dzhwinter 已提交
122 123 124 125 126 127
    if len(op_proto.outputs) != 0:
        buf.write('\nReturns:\n')
        buf.write('    ')
        for each_opt in op_proto.outputs:
            if not each_opt.intermediate:
                break
128
        buf.write(escape_math(each_opt.comment))
D
dzhwinter 已提交
129 130 131 132

    return buf.getvalue()


133
def generate_layer_fn(op_type):
134
    """Register the Python layer for an Operator.
D
dzhwinter 已提交
135 136

    Args:
137
       op_type: The name of the operator to be created.
D
dzhwinter 已提交
138 139 140 141 142 143 144

    This function takes in the operator type (sigmoid, mean , average etc) and
    creates the operator functionality.

    """
    op_proto = OpProtoHolder.instance().get_op_proto(op_type)
    not_intermediate_outputs = \
145
        [output for output in op_proto.outputs if not output.intermediate]
D
dzhwinter 已提交
146
    intermediate_outputs = \
147
        [output for output in op_proto.outputs if output.intermediate]
D
dzhwinter 已提交
148 149 150

    if len(not_intermediate_outputs) != 1:
        raise ValueError("Only one non intermediate output operator can be",
Y
yuyang18 已提交
151
                         "automatically generated. {0}".format(op_type))
D
dzhwinter 已提交
152 153 154

    if not_intermediate_outputs[0].duplicable:
        raise ValueError(
155
            "Only non duplicable op can be automatically generated.")
D
dzhwinter 已提交
156 157 158 159

    for output in intermediate_outputs:
        if output.duplicable:
            raise ValueError("The op can be automatically generated only when ",
160
                             "all intermediate ops are not duplicable.")
D
dzhwinter 已提交
161 162 163 164

    o_name = not_intermediate_outputs[0].name
    intermediate_output_names = [output.name for output in intermediate_outputs]

Y
Yu Yang 已提交
165
    def infer_and_check_dtype(op_proto, *args, **kwargs):
D
dzhwinter 已提交
166 167 168 169 170 171 172 173 174 175
        """
        This function performs the sanity check for dtype and
        instance type.
        """
        dtype = None
        for ipt in op_proto.inputs:
            name = _convert_(ipt.name)
            val = kwargs.pop(name, [])
            if not isinstance(val, list) and not isinstance(val, tuple):
                val = [val]
Y
Yu Yang 已提交
176 177 178 179
            if len(val) == 0:
                val = [args[0]]
                args = args[1:]

D
dzhwinter 已提交
180 181 182 183 184 185 186 187 188 189 190 191
            for each in val:
                if not isinstance(each, Variable):
                    raise ValueError("input of {0} must be variable".format(
                        op_type))

                if dtype is None:
                    dtype = each.dtype
                elif dtype != each.dtype:
                    raise ValueError(
                        "operator {0} must input same dtype. {1} vs {2}".format(
                            op_type, dtype, each.dtype))

W
Wu Yi 已提交
192 193 194 195 196 197 198 199 200
        if dtype is None:
            arg_dtype = kwargs.get("dtype")
            if arg_dtype:
                if not isinstance(arg_dtype, core.VarDesc.VarType):
                    dtype = convert_np_dtype_to_dtype_(arg_dtype)
                else:
                    dtype = arg_dtype
            else:
                dtype = core.VarDesc.VarType.FP32
D
dzhwinter 已提交
201 202
        return dtype

Y
Yu Yang 已提交
203
    def func(*args, **kwargs):
D
dzhwinter 已提交
204 205
        helper = LayerHelper(op_type, **kwargs)

Y
Yu Yang 已提交
206
        dtype = infer_and_check_dtype(op_proto, *args, **kwargs)
D
dzhwinter 已提交
207 208 209 210 211 212 213

        inputs = dict()
        for ipt in op_proto.inputs:
            name = _convert_(ipt.name)
            val = kwargs.pop(name, [])
            if not isinstance(val, list) and not isinstance(val, tuple):
                val = [val]
Y
Yu Yang 已提交
214 215 216
            if len(val) == 0 and len(args) != 0:
                val = args[0]
                args = args[1:]
D
dzhwinter 已提交
217 218 219
            inputs[ipt.name] = val

        outputs = dict()
220 221 222 223 224
        out = kwargs.pop(_convert_(o_name), [])
        if out:
            out_var = out[0] if (isinstance(out, list) or
                                 isinstance(out, tuple)) else out
        else:
X
Xin Pan 已提交
225
            out_var = helper.create_variable_for_type_inference(dtype=dtype)
226
        outputs[o_name] = [out_var]
D
dzhwinter 已提交
227
        for name in intermediate_output_names:
X
Xin Pan 已提交
228 229 230
            outputs[name] = [
                helper.create_variable_for_type_inference(dtype=dtype)
            ]
D
dzhwinter 已提交
231 232
        helper.append_op(
            type=op_type, inputs=inputs, outputs=outputs, attrs=kwargs)
233
        return helper.append_activation(out_var)
D
dzhwinter 已提交
234 235 236 237 238 239

    func.__name__ = op_type
    func.__doc__ = _generate_doc_string_(op_proto)
    return func


240
def generate_activation_fn(op_type):
241 242 243 244 245 246 247 248 249 250 251
    """Register the Python layer for an Operator without Attribute.

    Args:
       op_type: The name of the operator to be created.

    This function takes in the operator type (sigmoid, exp , tanh etc) and
    creates the operator functionality.

    """
    op_proto = OpProtoHolder.instance().get_op_proto(op_type)

T
tensor-tang 已提交
252
    def func(x, name=None):
253
        helper = LayerHelper(op_type, **locals())
254 255
        check_type_and_dtype(x, 'x', Variable,
                             ['float16', 'float32', 'float64'], op_type)
X
Xin Pan 已提交
256
        output = helper.create_variable_for_type_inference(dtype=x.dtype)
T
tensor-tang 已提交
257
        helper.append_op(type=op_type, inputs={"X": x}, outputs={"Out": output})
258 259 260
        return output

    func.__name__ = op_type
261 262 263 264 265
    func.__doc__ = _generate_doc_string_(
        op_proto,
        additional_args_lines=[
            "name(str, optional): The default value is None.  Normally there is no need for user to set this property.  For more information, please refer to :ref:`api_guide_Name` ."
        ])
266
    func.__doc__ = func.__doc__ + """
267 268 269

Return type
  Variable
270 271
Examples:
    .. code-block:: python
272

273
        import paddle.fluid as fluid
274 275
        import numpy as np

276
        inputs = fluid.data(name="x", shape = [None, 4], dtype='float32')
277 278 279 280 281
        output = fluid.layers.%s(inputs)

        exe = fluid.Executor(fluid.CPUPlace())
        exe.run(fluid.default_startup_program())

282 283
        #input.shape=1X4, batch_size=1
        img = np.array([[1.0, 2.0, 3.0, 4.0]]).astype(np.float32)
284 285
        res = exe.run(fluid.default_main_program(), feed={'x':img}, fetch_list=[output])
        print(res)
286
""" % op_type
287 288 289
    return func


D
dzhwinter 已提交
290 291 292 293 294 295 296 297 298 299 300
def deprecated(func_or_class):
    """
    Deprecated warning decorator. It will result a warning message.
    Should be used before class or function, member function
    """

    @functools.wraps(func)
    def func_wrapper(*args, **kwargs):
        """
        Wrap func with deprecated warning
        """
Y
Yang Yu 已提交
301
        warnings.simplefilter('always', DeprecationWarning)  # turn off filter
D
dzhwinter 已提交
302 303 304 305
        warnings.warn(
            "Call to deprecated function {}.".format(func.__name__),
            category=DeprecationWarning,
            stacklevel=2)
Y
Yang Yu 已提交
306
        warnings.simplefilter('default', DeprecationWarning)  # reset filter
D
dzhwinter 已提交
307 308 309
        return func(*args, **kwargs)

    return func_wrapper
Y
Yang Yu 已提交
310 311


312 313 314 315 316 317 318
def autodoc(comment=""):
    def __impl__(func):
        func.__doc__ = _generate_doc_string_(OpProtoHolder.instance(
        ).get_op_proto(func.__name__)) + comment
        return func

    return __impl__
Y
yuyang18 已提交
319 320


Y
yuyang18 已提交
321
def templatedoc(op_type=None):
Y
yuyang18 已提交
322 323 324 325 326 327 328 329 330 331
    """
    Decorator of layer function. It will use the docstring from the layer
    function as the template. The template arguments are:

    * ${comment}: The operator comment written in CPP.
    * ${{name}_comment}: The comment of ${name} written with AddAttr, AddOutput,
        and AddInput. The ${name} is Python snake style. i.e., xxx_xxx.
    * ${{name}_type}: The type of ${name}.

    Returns:
Y
yuyang18 已提交
332
        Decorated function.
Y
yuyang18 已提交
333 334
    """

Y
yuyang18 已提交
335 336 337
    def trim_ending_dot(msg):
        return msg.rstrip('.')

Y
yuyang18 已提交
338
    def __impl__(func):
Y
yuyang18 已提交
339 340 341 342 343
        if op_type is None:
            op_type_name = func.__name__
        else:
            op_type_name = op_type
        op_proto = OpProtoHolder.instance().get_op_proto(op_type_name)
Y
yuyang18 已提交
344
        tmpl = string.Template(func.__doc__)
Y
yuyang18 已提交
345 346 347 348

        comment_lines = op_proto.comment.split("\n")
        comment = ""
        for line in comment_lines:
Y
yuyang18 已提交
349 350
            line = line.strip()
            if len(line) != 0:
Y
yuyang18 已提交
351
                comment += escape_math(line)
Y
yuyang18 已提交
352
                comment += " "
Y
yuyang18 已提交
353 354
            elif len(comment) != 0:
                comment += "\n    \n    "
Y
yuyang18 已提交
355

Y
yuyang18 已提交
356
        args = {"comment": trim_ending_dot(comment)}
Y
yuyang18 已提交
357 358
        for each_input in op_proto.inputs:
            input_name = _convert_(each_input.name)
Y
yuyang18 已提交
359 360
            args["{0}_comment".format(input_name)] = trim_ending_dot(
                each_input.comment)
Y
yuyang18 已提交
361 362 363
            args["{0}_type".format(input_name)] = "Variable"
        for each_attr in op_proto.attrs:
            input_name = _convert_(each_attr.name)
Y
yuyang18 已提交
364 365
            args["{0}_comment".format(input_name)] = trim_ending_dot(
                each_attr.comment)
Y
yuyang18 已提交
366 367 368 369
            args["{0}_type".format(input_name)] = _type_to_str_(each_attr.type)

        for each_opt in op_proto.outputs:
            output_name = _convert_(each_opt.name)
Y
yuyang18 已提交
370 371
            args["{0}_comment".format(output_name)] = trim_ending_dot(
                each_opt.comment)
Y
yuyang18 已提交
372 373 374 375 376
            args["{0}_type".format(output_name)] = "Variable"
        func.__doc__ = tmpl.substitute(args)
        return func

    return __impl__