Source code for nnabla.function_bases

# Copyright (c) 2017 Sony Corporation. All Rights Reserved.
# 
# 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.

#
# *WARNING*
# THIS FILE IS AUTO-GENERATED BY CODE GENERATOR.
# PLEASE DO NOT EDIT THIS FILE BY HAND!
# If you want to modify this file, edit following files.
# - python/src/nnabla/function_bases.py.tmpl
# - build-tools/code_generator/generate.py

from __future__ import absolute_import

from .context import get_current_context
from . import function as F
from .auto_forward import get_auto_forward

import inspect


# Templates for function_api source building.
FUNCTION_API_HEADER = "def {name}{signature}:"
FUNCTION_API_BODY = '''ctx = get_current_context()
return _func_(ctx, {shortsignature})'''


def function_api(func):
    """
    Decorator for making function called with current context.
    Some tricky things are done here so that signature and docstring are available.
    """
    name = func.__name__
    doc = func.__doc__
    if doc is None:
        doc = "No docstring."

    # Parsing argspecs
    spec = inspect.getargspec(func)
    defaults = spec.defaults
    if spec.defaults is None:
        defaults = None
    elif len(spec.defaults) == len(spec.args):
        defaults = defaults[1:]
    # Creating signature
    # e.g. (x, weights, biases=None, n_outputs=None)
    signature = inspect.formatargspec(
        spec.args[1:], spec.varargs, spec.keywords, defaults)
    # Creating signature without parans and defaults
    # e.g. x, weights, biases, n_outputs
    shortsignature = inspect.formatargspec(
        spec.args[1:], spec.varargs, spec.keywords, None)[1:-1]

    # Create code by string
    src = (FUNCTION_API_HEADER + '\n' + '\n'.join(map(lambda x: '    ' +
                                                      x, FUNCTION_API_BODY.splitlines()))).format(**locals())

    # Evaluate source code from string
    code = compile(src, "<{name}>".format(**locals()), 'single')
    execdict = dict(_func_=func, get_current_context=get_current_context)
    exec(code, execdict)

    # Get created function.
    newfunc = execdict[name]
    # DOC newfunc.__doc__ = FUNCTION_API_DOC.format(**locals())
    doc += '''

    Note:
        All nnabla functions in :obj:`nnabla.functions` are decorated with the :obj:`nnabla.function_bases.function_api` decorator,
        which queries the current context and passes it into the first argument of the
        original function. The original function always takes a context as the first argument.

    '''
    newfunc.__doc__ = doc
    newfunc.__source__ = src
    newfunc.__function_api_base__ = func
    newfunc.__module__ = __name__
    return newfunc





[docs]@function_api def affine(ctx, x, weight, bias=None, base_axis=1, n_outputs=-1, outputs=None): r""" Affine layer, also called as the fully connected layer. It calculates: .. math:: {\mathbf y} = {\mathbf A} {\mathbf x} + {\mathbf b}. where :math:`{\mathbf x}` is the input and :math:`{\mathbf y}` is the output. Args: x(~nnabla.Variable): Input N-D array with shape (:math:`M_0 \times ... \times M_{B-1} \times D_B \times ... \times D_N`). Dimensions before and after base_axis are flattened as if it is a matrix. weight(~nnabla.Variable): Weight matrix with shape (:math:`(D_B \times ... \times D_N) \times L`) [parameter] bias(~nnabla.Variable): Bias vector (:math:`L`) [optional][parameter] base_axis(int): Base axis of Affine operation. Dimensions up to base_axis is treated as sample dimension. [default=``1``] Returns: ~nnabla.Variable: :math:`(B + 1)`-D array. (:math:`M_0 \times ... \times M_{B-1} \times L`) """ inputs = [x, weight] if bias is not None: inputs += [bias] return F.Affine(ctx, base_axis)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def convolution(ctx, x, weight, bias=None, base_axis=1, pad=None, stride=None, dilation=None, group=1, n_outputs=-1, outputs=None): r""" N-D Convolution with bias. See references for dilated convolution (a.k.a. atrous convolution). References: * `Chen et al., DeepLab: Semantic Image Segmentation with Deep Convolutional Nets, Atrous Convolution, and Fully Connected CRFs. <https://arxiv.org/abs/1606.00915>`_ * `Yu et al., Multi-Scale Context Aggregation by Dilated Convolutions. <https://arxiv.org/abs/1511.07122>`_ Args: x(~nnabla.Variable): :math:`(B + 1 + N)`-D array (:math:`M_1 \times ... \times M_B \times C \times L_1 \times ... \times L_N`). weight(~nnabla.Variable): :math:`(2 + N)`-D array (:math:`C' \times C \times K_1 \times ... \times K_N`). [parameter] bias(~nnabla.Variable): Bias vector (:math:`C'`). [optional][parameter] base_axis(int): base axis :math:`B`. [default=``1``] pad(:obj:`tuple` of :obj:`int`): Padding sizes for dimensions. [default=``(0,) * (len(x.shape) - (base_axis+1))``] stride(:obj:`tuple` of :obj:`int`): Stride sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] dilation(:obj:`tuple` of :obj:`int`): Dilation sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] group(int): Number of groups of channels. This makes the connection across channels sparser, by grouping connections along the mapping direction. [default=``1``] Returns: ~nnabla.Variable: :math:`(B + 1 + N)`-D array (:math:`M_1 \times ... \times M_B \times C' \times L'_1 \times ... \times L'_N`). """ if pad is None: pad = (0,) * (len(x.shape) - (base_axis+1)) if stride is None: stride = (1,) * (len(x.shape) - (base_axis+1)) if dilation is None: dilation = (1,) * (len(x.shape) - (base_axis+1)) inputs = [x, weight] if bias is not None: inputs += [bias] return F.Convolution(ctx, base_axis, pad, stride, dilation, group)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def depthwise_convolution(ctx, x, weight, bias=None, base_axis=1, pad=None, stride=None, dilation=None, multiplier=1, n_outputs=-1, outputs=None): r""" N-D Depthwise Convolution with bias. References: * `F. Chollet: Chollet, Francois. "Xception: Deep Learning with Depthwise Separable Convolutions. <https://arxiv.org/abs/1610.02357>`_ Args: x(~nnabla.Variable): :math:`(B + 1 + N)`-D array (:math:`M_1 \times ... \times M_B \times C \times L_1 \times ... \times L_N`). weight(~nnabla.Variable): :math:`(1 + N)`-D array (:math:`C \times K_1 \times ... \times K_N`). [parameter] bias(~nnabla.Variable): Bias vector (:math:`C`). [optional][parameter] base_axis(int): base axis :math:`B`. [default=``1``] pad(:obj:`tuple` of :obj:`int`): Padding sizes for dimensions. [default=``(0,) * (len(x.shape) - (base_axis+1))``] stride(:obj:`tuple` of :obj:`int`): Stride sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] dilation(:obj:`tuple` of :obj:`int`): Dilation sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] multiplier(int): Number of output feature maps per input feature map. [default=``1``] Returns: ~nnabla.Variable: :math:`(B + 1 + N)`-D array (:math:`M_1 \times ... \times M_B \times C \times L'_1 \times ... \times L'_N`). """ if pad is None: pad = (0,) * (len(x.shape) - (base_axis+1)) if stride is None: stride = (1,) * (len(x.shape) - (base_axis+1)) if dilation is None: dilation = (1,) * (len(x.shape) - (base_axis+1)) inputs = [x, weight] if bias is not None: inputs += [bias] return F.DepthwiseConvolution(ctx, base_axis, pad, stride, dilation, multiplier)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def deconvolution(ctx, x, weight, bias=None, base_axis=1, pad=None, stride=None, dilation=None, group=1, n_outputs=-1, outputs=None): r""" N-D deconvolution, also known as transposed convolution, with bias operates backward convolution (derivative of the output w.r.t. the input) plus channel-wise learned bias. The weights are specified in the same manner as :meth:`~nnabla.functions.convolution` , as if it was an ordinary convolution function. The forward operation of :meth:`~nnabla.functions.deconvolution` will then be operationally equivalent to the backward pass of :meth:`~nnabla.functions.convolution` . Therefore, the number of input channels (can be seen as output channels of forward convolution) is specified in the first dimension, and the number of the output channels divided by the number of groups is specified in the second dimension. Args: x(~nnabla.Variable): :math:`(B + 1 + N)`-D array (:math:`M_1 \times ... \times M_B \times C \times L_1 \times ... \times L_N`). weight(~nnabla.Variable): :math:`(2 + N)`-D array (:math:`C' \times C \times K_1 \times ... \times K_N`). [parameter] bias(~nnabla.Variable): Bias vector (:math:`C'`). [optional][parameter] base_axis(int): base axis :math:`B`. [default=``1``] pad(:obj:`tuple` of :obj:`int`): Padding sizes for dimensions. [default=``(0,) * (len(x.shape) - (base_axis+1))``] stride(:obj:`tuple` of :obj:`int`): Stride sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] dilation(:obj:`tuple` of :obj:`int`): Dilation sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] group(int): Number of groups of channels. This makes the connection across channels sparser, by grouping connections along the mapping direction. [default=``1``] Returns: ~nnabla.Variable: :math:`(B + 1 + N)`-D array (:math:`M_1 \times ... \times M_B \times C' \times L'_1 \times ... \times L'_N`). """ if pad is None: pad = (0,) * (len(x.shape) - (base_axis+1)) if stride is None: stride = (1,) * (len(x.shape) - (base_axis+1)) if dilation is None: dilation = (1,) * (len(x.shape) - (base_axis+1)) inputs = [x, weight] if bias is not None: inputs += [bias] return F.Deconvolution(ctx, base_axis, pad, stride, dilation, group)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def depthwise_deconvolution(ctx, x, weight, bias=None, base_axis=1, pad=None, stride=None, dilation=None, divisor=1, n_outputs=-1, outputs=None): r""" Depthwise deconvolution computes the transposed depthwise convolution with bias for one-dimensional and two-dimensional input data. Args: x(~nnabla.Variable): :math:`(B + 1 + N)`-D array (:math:`M_1 \times ... \times M_B \times C \times L_1 \times ... \times L_N`). weight(~nnabla.Variable): :math:`(1 + N)`-D array (:math:`C \times K_1 \times ... \times K_N`). [parameter] bias(~nnabla.Variable): Bias vector (:math:`C`). [optional][parameter] base_axis(int): base axis :math:`B`. [default=``1``] pad(:obj:`tuple` of :obj:`int`): Padding sizes for dimensions. [default=``(0,) * (len(x.shape) - (base_axis+1))``] stride(:obj:`tuple` of :obj:`int`): Stride sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] dilation(:obj:`tuple` of :obj:`int`): Dilation sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] divisor(int): Number of input feature maps per output feature map. [default=``1``] Returns: ~nnabla.Variable: :math:`(B + 1 + N)`-D array (:math:`M_1 \times ... \times M_B \times C \times L'_1 \times ... \times L'_N`). """ if pad is None: pad = (0,) * (len(x.shape) - (base_axis+1)) if stride is None: stride = (1,) * (len(x.shape) - (base_axis+1)) if dilation is None: dilation = (1,) * (len(x.shape) - (base_axis+1)) inputs = [x, weight] if bias is not None: inputs += [bias] return F.DepthwiseDeconvolution(ctx, base_axis, pad, stride, dilation, divisor)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def max_pooling(ctx, x, kernel, stride=None, ignore_border=True, pad=None, n_outputs=-1, outputs=None): r""" Max pooling. It pools the maximum values inside the scanning kernel: .. math:: y_{i_1, i_2} = \max_{k_1, k_2 \in K} (x_{i_1 + k_1, i_2 + k_2}) where :math:`x_{i_1 + k_1, i_2 + k_2}` is the input and :math:`y_{i_1, i_2}` is the output. Args: x(~nnabla.Variable): Input variable. kernel(:obj:`tuple` of :obj:`int`): Kernel sizes for each spatial axis. stride(:obj:`tuple` of :obj:`int`): Subsampling factors for each spatial axis. [default=``kernel``] ignore_border(bool): If false, kernels covering borders are also considered for the output. [default=``True``] pad(:obj:`tuple` of :obj:`int`): Border padding values for each spatial axis. Padding will be added both sides of the dimension. [default=``(0,) * len(kernel)``] Returns: ~nnabla.Variable: Maximum values variable """ if stride is None: stride = kernel if pad is None: pad = (0,) * len(kernel) return F.MaxPooling(ctx, kernel, stride, ignore_border, pad)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def average_pooling(ctx, x, kernel, stride=None, ignore_border=True, pad=None, including_pad=True, n_outputs=-1, outputs=None): r""" Average pooling. It pools the averaged values inside the scanning kernel: .. math:: y_{i_1, i_2} = \frac{1}{K_1 K_2} \sum_{k1} \sum_{k2} x_{i_1 + k_1, i_2 + k_2} where :math:`x_{i_1 + k_1, i_2 + k_2}` is the input and :math:`y_{i_1, i_2}` is the output. Args: x(~nnabla.Variable): Input variable. kernel(:obj:`tuple` of :obj:`int`): Kernel sizes for each spatial axis. stride(:obj:`tuple` of :obj:`int`): Subsampling factors for each spatial axis. [default=``kernel``] ignore_border(bool): If false, kernels covering borders are also considered for the output. [default=``True``] pad(:obj:`tuple` of :obj:`int`): Border padding values for each spatial axis. Padding will be added both sides of the dimension. [default=``(0,) * len(kernel)``] including_pad(bool): If true, border padding values are considered for the output. [default=``True``] Returns: ~nnabla.Variable: Average values variable """ if stride is None: stride = kernel if pad is None: pad = (0,) * len(kernel) return F.AveragePooling(ctx, kernel, stride, ignore_border, pad, including_pad)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def global_average_pooling(ctx, x, n_outputs=-1, outputs=None): r""".. WARNING:: This function is experimental suppport, so please do not actively use it. Global average pooling. It pools an averaged value from the whole image Args: x(~nnabla.Variable): Input variable. Returns: ~nnabla.Variable: Average values variable """ return F.GlobalAveragePooling(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def sum_pooling(ctx, x, kernel, stride=None, ignore_border=True, pad=None, n_outputs=-1, outputs=None): r""" Sum pooling. It pools the summed values inside the scanning kernel: .. math:: y_{i_1, i_2} = \sum_{k1} \sum_{k2} x_{i_1 + k_1, i_2 + k_2} where :math:`x_{i_1 + k_1, i_2 + k_2}` is the input and :math:`y_{i_1, i_2}` is the output. Args: x(~nnabla.Variable): Input variable. kernel(:obj:`tuple` of :obj:`int`): Kernel sizes for each spatial axis. stride(:obj:`tuple` of :obj:`int`): Subsampling factors for each spatial axis. [default=``kernel``] ignore_border(bool): If false, kernels covering borders are also considered for the output. [default=``True``] pad(:obj:`tuple` of :obj:`int`): Border padding values for each spatial axis. Padding will be added both sides of the dimension. [default=``(0,) * len(kernel)``] Returns: ~nnabla.Variable: Summed values variable """ if stride is None: stride = kernel if pad is None: pad = (0,) * len(kernel) return F.SumPooling(ctx, kernel, stride, ignore_border, pad)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def unpooling(ctx, x, kernel, n_outputs=-1, outputs=None): r""" Inverse operation of pooling. It spreads the input values: .. math:: y_{k_1 i_1 + j_1, k_2 i_2 + j_2} = x_{i_1, i_2} where :math:`_{i_1, i_2}` is the input and :math:`y_{k_1 i_1 + j_1, k_2 i_2 + j_2}` is the output. Args: x(~nnabla.Variable): Input variable. kernel(:obj:`tuple` of :obj:`int`): Kernel sizes for each spatial axis. Returns: ~nnabla.Variable: Spread values variable """ return F.Unpooling(ctx, kernel)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def embed(ctx, x0, w, n_outputs=-1, outputs=None): r""" Embed slices of a matrix/tensor with indexing array/tensor. Args: x0(~nnabla.Variable): Indices with shape :math:`(I_0, ..., I_N)` w(~nnabla.Variable): Weights with shape :math:`(W_0, ..., W_M)` [parameter] Returns: ~nnabla.Variable: Output with shape :math:`(I_0, ..., I_N, W_1, ..., W_M)` """ return F.Embed(ctx)(x0, w, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def sigmoid(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise sigmoid function. .. math:: f(x) = \frac{1}{1 + \exp(-x)}, Args: x(~nnabla.Variable): Input Returns: ~nnabla.Variable: Output """ return F.Sigmoid(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def swish(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise swish function, by Ramachandran et al. (2017). .. math:: y_i = \frac{x_i}{1 + \exp(-x_i)}, References: * `Prajit Ramachandran, Barret Zoph, and Quoc V. Le, Swish: a Self-Gated Activation Function, arXiv:1710.05941 [cs.NE] <https://arxiv.org/abs/1710.05941>`_ Args: x(~nnabla.Variable): Input Returns: ~nnabla.Variable: Output """ return F.Swish(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def tanh(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise hyperbolic tangent (tanh) function. .. math:: y_i = \tanh (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Tanh(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def relu(ctx, x, inplace=False, n_outputs=-1, outputs=None): r""" Element-wise Rectified Linear Unit (ReLU) function. .. math:: y_i = \max (0, x_i) Args: x(~nnabla.Variable): N-D array inplace(bool): The output array is shared with the input array if True. [default=``False``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.ReLU(ctx, inplace)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def leaky_relu(ctx, x, alpha=0.1, n_outputs=-1, outputs=None): r""" Element-wise Leaky Rectified Linear Unit (ReLU) function. It is defined as: .. math:: y_i = \alpha * \min(0, x_i) + \max (0, x_i) Args: x(~nnabla.Variable): N-D array alpha(float): The slope value multiplied to negative numbers. :math:`\alpha` in the definition. [default=``0.1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.LeakyReLU(ctx, alpha)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def softmax(ctx, x, axis=None, n_outputs=-1, outputs=None): r""" Softmax normalization. Calculates .. math:: y_i = \frac{\exp(x_i)}{\sum_j \exp(x_j)} along the dimension specified by `axis`, where :math:`y_i` is the input and :math:`x_i` is the output. Args: x(~nnabla.Variable): N-D array. Typically indicates a score. axis(int): Axis normalization is taken. [default=``len(x.shape) - 1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ if axis is None: axis = len(x.shape) - 1 return F.Softmax(ctx, axis)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def elu(ctx, x, alpha=1.0, n_outputs=-1, outputs=None): r""" Element-wise Exponential Linear Unit (ELU) function. .. math:: y_i= \left\{ \begin{array}{ll} x_i & (x > 0)\\ \alpha (\exp(x_i) - 1) & (x \leq 0) \end{array} \right.. References: * `Clevart et al., Fast and Accurate Deep Network Learning by Exponential Linear Units (ELUs). <http://arxiv.org/abs/1511.07289>`_ Args: x(~nnabla.Variable): N-D array alpha(float): Coefficient for negative outputs. :math:`\alpha` in definition [default=``1.0``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.ELU(ctx, alpha)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def selu(ctx, x, scale=1.05070098735548, alpha=1.673263242354377, n_outputs=-1, outputs=None): r""" Element-wise Scaled Exponential Linear Unit (SELU) function by Klambauer et al. (2017). .. math:: y_i= \lambda \left\{ \begin{array}{ll} x_i & (x > 0)\\ \alpha (\exp(x_i) - 1) & (x \leq 0) \end{array} \right.. The coefficients :math:`\lambda` and :math:`\alpha` default to the following values :math:`\lambda_{01}` and :math:`\alpha_{01}`, respectively, provided by Klambauer et al. (2017): .. math:: \begin{array}{lll} \lambda_{01} &=& \left( 1 - \operatorname{erfc}\left( \frac{1}{\sqrt{2}} \right) \sqrt{e} \right) \sqrt{2 \pi} \\ && \left( 2 \operatorname{erfc} \left( \sqrt{2} \right) e^2 + \pi \operatorname{erfc}\left( \frac{1}{\sqrt{2}} \right)^2 e \right. \\ && \left. - 2(2 + \pi) \operatorname{erfc} \left( \frac{1}{\sqrt{2}} \right) \sqrt{e} + \pi + 2 \right)^{-1/2} \\ &\approx& 1.0507 \\ \alpha_{01} &=& - \frac {\sqrt {\frac {2}{\pi}}} {\operatorname{erfc} \left( \frac{1}{\sqrt{2}} \right) \exp \left(\frac {1} {2} \right) - 1} \\ &\approx& 1.67326 \end{array} References: * `Klambauer, G., Unterthiner, T., Mayr, A., & Hochreiter, S. (2017). Self-Normalizing Neural Networks. In Advances in Neural Information Processing Systems (NIPS). <https://arxiv.org/abs/1706.02515>`_ Args: x(~nnabla.Variable): N-D array scale(float): The coefficient :math:`\lambda` in the definition. [default=``1.05070098735548``] alpha(float): The coefficient :math:`\alpha` in the definition. [default=``1.673263242354377``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.SELU(ctx, scale, alpha)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def crelu(ctx, x, axis=1, n_outputs=-1, outputs=None): r""" Element-wise Concatenated Rectified Linear Unit (CReLU) function. This function calculates the ReLU of :math:`x` and :math:`-x` , then concatenates the results together at a specified axis, and returns the resulting array. References: * `Wenling Shang, Kihyuk Sohn, Diogo Almeida, Honglak Lee. Understanding and Improving Convolutional Neural Networks via Concatenated Rectified Linear Units. <https://arxiv.org/abs/1603.05201>`_ Args: x(~nnabla.Variable): N-D array. axis(int): The ReLU activations of positive inputs and negative inputs are concatenated at axis. [default=``1``] Returns: ~nnabla.Variable: N-D array where axis dimension is doubled by concatenating. """ return F.CReLU(ctx, axis)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def celu(ctx, x, alpha=1.0, axis=1, n_outputs=-1, outputs=None): r""" Element-wise Concatenated Exponential Linear Unit (CELU) function. Concatenates ELU outputs of positive and negative inputs together at specified axis. Args: x(~nnabla.Variable): N-D array. alpha(float): Coefficient for negative outputs. :math:`\alpha` in definition. [default=``1.0``] axis(int): The ELU activations of positive inputs and negative inputs are concatenated at axis. [default=``1``] Returns: ~nnabla.Variable: N-D array where axis dimension is doubled by concatenating. """ return F.CELU(ctx, alpha, axis)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def prelu(ctx, x0, x1, base_axis=1, n_outputs=-1, outputs=None): r""" Element-wise Parametrized Rectified Linear Unit function. Calculates: .. math:: y_i = \max(0, x_i) + w_i \min(0, -x_i) where negative slope :math:`w` is learned and can vary across channels (an axis specified with `base_axis`). Args: x0(~nnabla.Variable): (N-D array) Input x1(~nnabla.Variable): (N-D array) Weights base_axis(int): Dimensions up to base_axis is treated as sample dimension. [default=``1``] Returns: ~nnabla.Variable: N-D array. """ return F.PReLU(ctx, base_axis)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
@function_api def batch_normalization(ctx, x, beta, gamma, mean, variance, axes=(1,), decay_rate=0.9, eps=1e-05, batch_stat=True, n_outputs=-1, outputs=None): r""" Batch normalization. .. math:: \begin{eqnarray} \mu &=& \frac{1}{M} \sum x_i \\ \sigma^2 &=& \frac{1}{M} \left(\sum x_i - \mu\right)^2 \\ \hat{x}_i &=& \frac{x_i - \mu}{\sqrt{\sigma^2 + \epsilon}} \\ y_i &=& \hat{x}_i \gamma + \beta. \end{eqnarray} At testing time, the mean and variance values used are those that were computed during training by moving average. References: * `Ioffe and Szegedy, Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift. <https://arxiv.org/abs/1502.03167>`_ Args: x(~nnabla.Variable): N-D array of input. beta(~nnabla.Variable): N-D array of beta which is learned. gamma(~nnabla.Variable): N-D array of gamma which is learned. mean(~nnabla.Variable): N-D array of running mean (modified during forward execution). variance(~nnabla.Variable): N-D array of running variance (modified during forward execution). axes(repeated int64): Axes mean and variance are taken. [default=``(1,)``] decay_rate(float): Decay rate of running mean and variance. [default=``0.9``] eps(float): Tiny value to avoid zero division by std. [default=``1e-05``] batch_stat(bool): Use mini-batch statistics rather than running ones. [default=``True``] Returns: ~nnabla.Variable: N-D array """ return F.BatchNormalization(ctx, axes, decay_rate, eps, batch_stat)(x, beta, gamma, mean, variance, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs) @function_api def mean_subtraction(ctx, x, rmean, t, base_axis=1, update_running_mean=True, n_outputs=-1, outputs=None): r""" It subtracts the mean of the elements of the input array, and normalizes it to :math:`0`. Preprocessing arrays with this function has the effect of improving accuracy in various tasks such as image classification. At training time, this function is defined as .. math:: \begin{eqnarray} \mu &=& \frac{1}{M} \sum x_i \\ y_i &=& x_i - \mu \end{eqnarray} At testing time, the mean values used are those that were computed during training by moving average. Note: The backward performs an approximated differentiation that takes into account only the latest mini-batch. Args: x(~nnabla.Variable): N-D array of input. rmean(~nnabla.Variable): N-D array of running mean (modified during forward execution). t(~nnabla.Variable): Scalar of num of iteration of running mean (modified during forward execution). base_axis(int): Base axis of Mean Subtraction operation. Dimensions up to base_axis is treated as sample dimension. [default=``1``] update_running_mean(bool): Update running mean during forward execution. [default=``True``] Returns: ~nnabla.Variable: N-D array. """ return F.MeanSubtraction(ctx, base_axis, update_running_mean)(x, rmean, t, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def clip_grad_by_value(ctx, x, min, max, n_outputs=-1, outputs=None): r"""In forward pass, the function behaves as the identity. In backward pass, .. math:: g_x = \begin{cases} max & (g_y > max) \\ g_y & (otherwise) \\ min & (g_y < min) \end{cases}. A typical case for use is to prevent the gradient explosion through a whole computational graph. For example, if you want to clip gradient values for each feature map, .. code-block:: python x = nn.Variable([16, 3, 32, 32]) min = F.broadcast(nn.Variable.from_numpy_array(np.asarray([-1.0]).reshape((1, 1, 1, 1))), (16, 3, 32, 32)) max = F.broadcast(nn.Variable.from_numpy_array(np.asarray([1.0]).reshape((1, 1, 1, 1))), (16, 3, 32, 32)) c = F.clip_grad_by_value(x, min=min, max=max) h = PF.convolution(c, 64, (3, 3), pad=(1, 1)) Args: x(~nnabla.Variable): N-D array of input. min(~nnabla.Variable): N-D array of minimum input value by which the gradients of the `y` are clipped. Note that the shape of `min` must be the same as `x`'s and the backward to `min` is not performed. max(~nnabla.Variable): N-D array of maximum input value by which the gradients of the `y` are clipped. Note that the shape of `max` must be the same as `x`'s and the backward to `max` is not performed. Returns: ~nnabla.Variable: N-D array. """ return F.ClipGradByValue(ctx)(x, min, max, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def clip_grad_by_norm(ctx, x, clip_norm=None, axes=None, n_outputs=-1, outputs=None): r""" In the forward pass, the function behaves like the identity. In the backward pass, .. math:: g_x = N \times \frac{g_y}{\|g_y\|_2}. where :math:`g_x` is the gradient w.r.t the input, :math:`g_y` is the gradient w.r.t. the output, and :math:`N` is `clip_norm` where the norm of :math:`g_y` becomes. this is the case that `axes` is not set. When `axes` is set, the norm is computed over `axes`. A typical case for use is to prevent the gradient explosion through a whole computational graph. For example, if you want to normalize gradient values over feature axis, .. code-block:: python x = nn.Variable([16, 3, 32, 32]) c = F.clip_grad_by_norm(x, axes=(1, )) h = PF.convolution(c, 64, (3, 3), pad=(1, 1)) Args: x(~nnabla.Variable): N-D array of input. clip_norm(float): Clip to the norm of input to `clip_norm` in the backward pass. [default=``1.0``] axes(repeated int64): Axes to be reduced. If empty list is given, all dimensions are reduced to scalar. This is used in the forward pass. [default=``range(x.ndim)``] Returns: ~nnabla.Variable: N-D array. """ if clip_norm is None: clip_norm = 1.0 if axes is None: axes = range(x.ndim) return F.ClipGradByNorm(ctx, clip_norm, axes)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
@function_api def sum(ctx, x, axes=None, keep_dims=False, n_outputs=-1, outputs=None): r""" Reduces a matrix along a specified axis with the sum function. Args: x(~nnabla.Variable): N-D array. axes(repeated int64): Axes to be reduced. If empty list is given, all dimensions are reduced to scalar. [default=``range(x.ndim)``] keep_dims(bool): Flag whether the reduced axis is kept. [default=``False``] Returns: ~nnabla.Variable: N-D array """ if axes is None: axes = range(x.ndim) return F.Sum(ctx, axes, keep_dims)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs) @function_api def mean(ctx, x, axes=None, keep_dims=False, n_outputs=-1, outputs=None): r""" Reduces a matrix along a specified axis with the mean function. Args: x(~nnabla.Variable): N-D array. axes(repeated int64): Axes to be reduced. [default=``range(x.ndim)``] keep_dims(bool): Flag whether the reduced axis is kept. [default=``False``] Returns: ~nnabla.Variable: N-D array """ if axes is None: axes = range(x.ndim) return F.Mean(ctx, axes, keep_dims)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs) @function_api def max(ctx, x, axes=None, keep_dims=False, n_outputs=-1, outputs=None): r""" Reduction along axis or axes with max operation. Args: x(~nnabla.Variable): N-D array. axes(repeated int64): Axes to be reduced. [default=``range(x.ndim)``] keep_dims(bool): Flag whether the reduced axis is kept. [default=``False``] Returns: ~nnabla.Variable: N-D array """ if axes is None: axes = range(x.ndim) return F.Max(ctx, axes, keep_dims)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs) @function_api def min(ctx, x, axes=None, keep_dims=False, n_outputs=-1, outputs=None): r""" Reduction along axis or axes with min operation. Args: x(~nnabla.Variable): N-D array. axes(repeated int64): Axes to be reduced. [default=``range(x.ndim)``] keep_dims(bool): Flag whether the reduced axis is kept. [default=``False``] Returns: ~nnabla.Variable: N-D array """ if axes is None: axes = range(x.ndim) return F.Min(ctx, axes, keep_dims)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs) @function_api def prod(ctx, x, axes=None, keep_dims=False, n_outputs=-1, outputs=None): r""" Reduction along axis or axes with product operation. Note: Backward computation is not accurate in a zero value input. Args: x(~nnabla.Variable): N-D array. axes(repeated int64): Axes to be reduced. [default=``range(x.ndim)``] keep_dims(bool): Flag whether the reduced axis is kept. [default=``False``] Returns: ~nnabla.Variable: N-D array """ if axes is None: axes = range(x.ndim) return F.Prod(ctx, axes, keep_dims)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def reduce_sum(ctx, x, n_outputs=-1, outputs=None): r""" Reduction along an axis with sum operation. Note: This is deprecated. Use ``sum`` instead. Args: x(~nnabla.Variable): N-D array. Returns: ~nnabla.Variable: N-D array """ return F.ReduceSum(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def reduce_mean(ctx, x, n_outputs=-1, outputs=None): r""" Reduction by mean along an axis. Note: This is deprecated. Use ``mean`` instead. Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array """ return F.ReduceMean(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def add2(ctx, x0, x1, inplace=False, n_outputs=-1, outputs=None): r""" Element-wise addition. .. math:: y_i = x^{(0)}_i + x^{(1)}_i Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array inplace(bool): The output array is shared with the 1st input array if True. [default=``False``] Returns: ~nnabla.Variable: N-D array """ return F.Add2(ctx, inplace)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
@function_api def bc_add2(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Note: This shouldn't be called by users. Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array """ return F.BcAdd2(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def sub2(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element-wise subtraction. .. math:: y_i = x^{(0)}_i - x^{(1)}_i Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array """ return F.Sub2(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def mul2(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element-wise multiplication. .. math:: y_i = x^{(0)}_i x^{(1)}_i Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array """ return F.Mul2(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def div2(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element-wise division. .. math:: y_i = \frac{x^{(0)}_i} {x^{(1)}_i} Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array """ return F.Div2(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def pow2(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element-wise power function. .. math:: y_i = {(x^{(0)}_i)} ^ {x^{(1)}_i} Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array """ return F.Pow2(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def add_scalar(ctx, x, val=1, n_outputs=-1, outputs=None): r""" Element-wise scalar addition. .. math:: y_i = x_i + v Args: x(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.AddScalar(ctx, val)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def mul_scalar(ctx, x, val=1, n_outputs=-1, outputs=None): r""" Element-wise scalar multiplication. .. math:: y_i = v x_i Args: x(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.MulScalar(ctx, val)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def pow_scalar(ctx, x, val=1, n_outputs=-1, outputs=None): r""" Element-wise scalar power function. .. math:: y_i = (x_i) ^ v Args: x(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.PowScalar(ctx, val)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def r_sub_scalar(ctx, x, val=1, n_outputs=-1, outputs=None): r""" Element-wise scalar subtraction. .. math:: y_i = v - x_i Args: x(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.RSubScalar(ctx, val)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def r_div_scalar(ctx, x, val=1, n_outputs=-1, outputs=None): r""" Element-wise scalar division. .. math:: y_i = \frac{v}{x_i} Args: x(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.RDivScalar(ctx, val)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def r_pow_scalar(ctx, x, val=1, n_outputs=-1, outputs=None): r""" Element-wise scalar power function. .. math:: y_i = v ^ {x_i} Args: x(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.RPowScalar(ctx, val)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def sign(ctx, x, alpha=0.0, n_outputs=-1, outputs=None): r""" Element-wise sign function. In the forward pass, it is defined as .. math:: f(x) = \begin{cases} 1 & (x > 0) \\ -1 & (x < 0) \\ \alpha & (x = 0) \end{cases}. In the backward pass, it is defined as .. math:: \frac{\partial f(x)}{\partial x} = 1, or in other words, it behaves as the identity function for the gradient in the backward pass. Args: x(~nnabla.Variable): Input alpha(float): Value in case of :math:`x = 0`. [default=``0.0``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Sign(ctx, alpha)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def minimum2(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element-wise minimum. .. math:: y_i = \min(x^{(0)}_i, x^{(1)}_i) Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array of min value """ return F.Minimum2(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def maximum2(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element-wise maximum. .. math:: y_i = \max(x^{(0)}_i, x^{(1)}_i) Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array of max value """ return F.Maximum2(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def minimum_scalar(ctx, x, val=1.0, n_outputs=-1, outputs=None): r""" Element-wise scalar minimum. .. math:: y_i = \min(x_i, v) Args: x(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1.0``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.MinimumScalar(ctx, val)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def maximum_scalar(ctx, x, val=1.0, n_outputs=-1, outputs=None): r""" Element-wise scalar maximum. .. math:: y_i = \max (x_i, v) Args: x(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1.0``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.MaximumScalar(ctx, val)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def logical_and(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Elementwise logical AND. .. math:: f(x^{(0)}_i,x^{(1)}_i) = \begin{cases} 1 & (x^{(0)}_i \neq 0 \;\&\; x^{(1)}_i \neq 0) \\ 0 & otherwise \end{cases}. Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: No Description """ return F.LogicalAnd(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def logical_or(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Elementwise logical OR. .. math:: f(x^{(0)}_i,x^{(1)}_i) = \begin{cases} 0 & (x^{(0)}_i = 0 \;\&\; x^{(1)}_i = 0) \\ 1 & otherwise \end{cases}. Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: No Description """ return F.LogicalOr(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def logical_xor(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Elementwise logical XOR. .. math:: f(x^{(0)}_i,x^{(1)}_i) = \begin{cases} 1 & (x^{(0)}_i = 0 \;\&\; x^{(1)}_i = 0) \\ 1 & (x^{(0)}_i \neq 0 \;\&\; x^{(1)}_i \neq 0) \\ 0 & otherwise \end{cases}. Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: No Description """ return F.LogicalXor(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def equal(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element wise 'equal' .. math:: f(x^{(0)}_i,x^{(1)}_i) = \begin{cases} 1 & (x^{(0)}_i = x^{(1)}_i) \\ 0 & otherwise \end{cases}. Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: No Description """ return F.Equal(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def not_equal(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element wise 'not equal' .. math:: f(x^{(0)}_i,x^{(1)}_i) = \begin{cases} 0 & (x^{(0)}_i = x^{(1)}_i) \\ 1 & otherwise \end{cases}. Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: No Description """ return F.NotEqual(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def greater_equal(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element wise comparison. The :math:`i^{th}` element of the output is: .. math:: f(x^{(0)}_i,x^{(1)}_i) = \begin{cases} 1 & (x^{(0)}_i \geq x^{(1)}_i) \\ 0 & (x^{(0)}_i < x^{(1)}_i) \end{cases}. Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: No Description """ return F.GreaterEqual(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def greater(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element wise comparison. The :math:`i^{th}` element of the output is: .. math:: f(x^{(0)}_i,x^{(1)}_i) = \begin{cases} 1 & (x^{(0)}_i > x^{(1)}_i) \\ 0 & (x^{(0)}_i \leq x^{(1)}_i) \end{cases}. Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: No Description """ return F.Greater(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def less_equal(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element wise comparison. The :math:`i^{th}` element of the output is: .. math:: f(x^{(0)}_i,x^{(1)}_i) = \begin{cases} 1 & (x^{(0)}_i \leq x^{(1)}_i) \\ 0 & (x^{(0)}_i > x^{(1)}_i) \end{cases}. Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: No Description """ return F.LessEqual(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def less(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element wise comparison. The :math:`i^{th}` element of the output is: .. math:: f(x^{(0)}_i,x^{(1)}_i) = \begin{cases} 1 & (x^{(0)}_i < x^{(1)}_i) \\ 0 & (x^{(0)}_i \geq x^{(1)}_i) \end{cases}. Args: x0(~nnabla.Variable): N-D array x1(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: No Description """ return F.Less(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def logical_and_scalar(ctx, x0, val, n_outputs=-1, outputs=None): r""" Elementwise logical AND with scalar. .. math:: f(x_i,v) = \begin{cases} 1 & (x_i \neq 0 \;\&\; v \neq 0) \\ 0 & otherwise \end{cases}. Args: x0(~nnabla.Variable): Input variable val(bool): No Description Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.LogicalAndScalar(ctx, val)(x0, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def logical_or_scalar(ctx, x0, val, n_outputs=-1, outputs=None): r""" Elementwise logical OR with scalar. .. math:: f(x_i,v) = \begin{cases} 0 & (x_i = 0 \;\&\; v = 0) \\ 1 & otherwise \end{cases}. Args: x0(~nnabla.Variable): Input variable val(bool): No Description Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.LogicalOrScalar(ctx, val)(x0, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def logical_xor_scalar(ctx, x0, val, n_outputs=-1, outputs=None): r""" Elementwise logical XOR with scalar. .. math:: f(x_i,v) = \begin{cases} 1 & (x_i = 0 \;\&\; v = 0) \\ 1 & (x_i \neq 0 \;\&\; v \neq 0) \\ 0 & otherwise \end{cases}. Args: x0(~nnabla.Variable): Input variable val(bool): No Description Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.LogicalXorScalar(ctx, val)(x0, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def equal_scalar(ctx, x0, val=1, n_outputs=-1, outputs=None): r""" Element wise 'equal' with a scalar .. math:: f(x_i,v) = \begin{cases} 1 & (x_i = v) \\ 0 & otherwise \end{cases}. Args: x0(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.EqualScalar(ctx, val)(x0, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def not_equal_scalar(ctx, x0, val=1, n_outputs=-1, outputs=None): r""" Element wise 'not equal' with a scalar .. math:: f(x_i,v) = \begin{cases} 0 & (x_i = v) \\ 1 & otherwise \end{cases}. Args: x0(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.NotEqualScalar(ctx, val)(x0, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def greater_equal_scalar(ctx, x0, val=1, n_outputs=-1, outputs=None): r""" Element wise comparison with a scalar. The :math:`i^{th}` element of the output is: .. math:: f(x^{(0)}_i,v) = \begin{cases} 1 & (x^{(0)}_i \geq v \\ 0 & (x^{(0)}_i < v \end{cases}. Args: x0(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.GreaterEqualScalar(ctx, val)(x0, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def greater_scalar(ctx, x0, val=1, n_outputs=-1, outputs=None): r""" Element wise comparison with a scalar. The :math:`i^{th}` element of the output is: .. math:: f(x^{(0)}_i,v) = \begin{cases} 1 & (x^{(0)}_i > v \\ 0 & (x^{(0)}_i \leq v \end{cases}. Args: x0(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.GreaterScalar(ctx, val)(x0, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def less_equal_scalar(ctx, x0, val=1, n_outputs=-1, outputs=None): r""" Element wise comparison with a scalar. The :math:`i^{th}` element of the output is: .. math:: f(x^{(0)}_i,v) = \begin{cases} 1 & (x^{(0)}_i \leq v) \\ 0 & (x^{(0)}_i > v) \end{cases}. Args: x0(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.LessEqualScalar(ctx, val)(x0, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def less_scalar(ctx, x0, val=1, n_outputs=-1, outputs=None): r""" Element wise comparison with a scalar. The :math:`i^{th}` element of the output is: .. math:: f(x^{(0)}_i,v) = \begin{cases} 1 & (x^{(0)}_i < v) \\ 0 & (x^{(0)}_i \geq v) \end{cases}. Args: x0(~nnabla.Variable): Input variable val(float): Value of the scalar [default=``1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.LessScalar(ctx, val)(x0, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def logical_not(ctx, x0, n_outputs=-1, outputs=None): r""" Element-wise logical NOT operation .. math:: f(x_i) = \begin{cases} 1 & (x_i = 0) \\ 0 & otherwise \end{cases}. Args: x0(~nnabla.Variable): Input variable Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.LogicalNot(ctx)(x0, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def constant(ctx, val=0, shape=[], n_outputs=-1, outputs=None): r""" Generate a constant-valued array. Args: val(float): Constant value. [default=``0``] shape(:obj:`tuple` of :obj:`int`): Shape of the output array. [default=``[]``] Returns: ~nnabla.Variable: N-D array where all values are the specified constant. """ return F.Constant(ctx, val, shape)(n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def abs(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise absolute value function. .. math:: y_i = |x_i| Args: x(~nnabla.Variable): Input variable Returns: ~nnabla.Variable: Element-wise absolute variable """ return F.Abs(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def exp(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise natural exponential function. .. math:: y_i = \exp(x_i). Args: x(~nnabla.Variable): Input variable Returns: ~nnabla.Variable: Element-wise exp variable """ return F.Exp(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def log(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise natural logarithm function. .. math:: y_i = \ln(x_i). Args: x(~nnabla.Variable): Input variable Returns: ~nnabla.Variable: Element-wise log variable """ return F.Log(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def identity(ctx, x, n_outputs=-1, outputs=None): r""" Identity function. .. math:: y = x Args: x(~nnabla.Variable): N-D array. Returns: ~nnabla.Variable: N-D array """ return F.Identity(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def batch_matmul(ctx, a, b, transpose_a=False, transpose_b=False, n_outputs=-1, outputs=None): r""" Batch matrix multiplication. Two of batchs of matrices are multiplied for each sample in a batch. A batch of matrices is composed as [..., P, Q] where the last two dimensions compose matrix dimensions, and the first dimensions up to the third last dimension are considered as batch samples. Args: a(~nnabla.Variable): N-D array with >= 2-dim. The last two dimensions will be treated as a matrix. b(~nnabla.Variable): N-D array with >= 2-dim. The last two dimensions will be treated as a matrix. The product of the size of 0-th dimension through the size of the third last dimension must be same as that of the input ``a``. transpose_a(bool): Transpose the last two axes of ``a`` in matrix multiplication. [default=``False``] transpose_b(bool): Transpose the last two axes of ``b`` in matrix multiplication. [default=``False``] Returns: ~nnabla.Variable: Output of sample-wise matrix multiplication in a batch. When ``a`` is of a shape of [N, P, Q], ``b`` is of a shape of [N, Q, R], and transpose options are all False, the output will be a shape of [N, P, R]. """ return F.BatchMatmul(ctx, transpose_a, transpose_b)(a, b, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def round(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise round function. In the forward pass, this function simply computes `round` to the nearest integer value. .. math:: y_i = round(x_i). In the backward pass, the simple Straight-Through Estimator (STE) is applied, .. math:: \frac{\partial y_i}{\partial x_i} = 1. Args: x(~nnabla.Variable): Input variable Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Round(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def ceil(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise ceil function. In the forward pass, this function simply returns the smallest integer which is not less than the input. .. math:: y_i = ceil(x_i). In the backward pass, the simple Straight-Through Estimator (STE) is applied, .. math:: \frac{\partial y_i}{\partial x_i} = 1. Args: x(~nnabla.Variable): Input variable Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Ceil(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def floor(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise floor function. In the forward pass, this function simply returns the largest integer which is not greater than the input. .. math:: y_i = floor(x_i). In the backward pass, the simple Straight-Through Estimator (STE) is applied, .. math:: \frac{\partial y_i}{\partial x_i} = 1. Args: x(~nnabla.Variable): Input variable Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Floor(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def sin(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise sine (sin) function. .. math:: y_i = \sin (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Sin(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def cos(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise cosine (cos) function. .. math:: y_i = \cos (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Cos(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def tan(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise tangent (tan) function. .. math:: y_i = \tan (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Tan(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def sinh(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise hyperbolic sine (sinh) function. .. math:: y_i = \sinh (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Sinh(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def cosh(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise hyperbolic cosine (cosh) function. .. math:: y_i = \cosh (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Cosh(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def asin(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise arcsine (asin) function. .. math:: y_i = \arcsin (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.ASin(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def acos(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise arccosine (acos) function. .. math:: y_i = \arccos (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.ACos(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def atan(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise arctangent (atan) function. .. math:: y_i = \arctan (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.ATan(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def asinh(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise hyperbolic arcsine (asinh) function. .. math:: y_i = \text{arcsinh} (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.ASinh(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def acosh(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise hyperbolic arccosine (acosh) function. .. math:: y_i = \text{arccosh} (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.ACosh(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def atanh(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise hyperbolic arctangent (atanh) function. .. math:: y_i = \text{arctanh} (x_i) Args: x(~nnabla.Variable): N-D array Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.ATanh(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def concatenate(ctx, *x, **kw): r""" Concatenate a variable number of input arrays along the specified axis. Args: *x(~nnabla.Variable): N-D arrays. [variadic][parameter] axis(int): Axis [default=``len(x[0].shape) - 1``] Returns: ~nnabla.Variable: Concatenate variable """ assert len(x) >= 1, "concatenate must take more than 1 inputs" n_outputs = kw.pop('n_outputs', -1) outputs = kw.pop('outputs', None) axis = kw.pop('axis', len(x[0].shape) - 1) return F.Concatenate(ctx, axis)(*x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
@function_api def split(ctx, x, axis=0, n_outputs=-1, outputs=None): r""" Split arrays at the specified axis. note: This function should not be called directly when constructing models. Instead, use :meth:`nnabla.functions.split` which automatically sets `n_output` from the input's shape and axis. Args: x(~nnabla.Variable): N-D array axis(int): Axis [default=``0``] Returns: ~nnabla.Variable: list of N-D arrays [variadic][parameter] """ return F.Split(ctx, axis)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def stack(ctx, *x, **kw): r""" Joins two or more arrays on a new axis. Note: Unlike :meth:`nnabla.functions.concatenate` , which joins arrays on an existing axis, Stack joins arrays on a new axis. Args: *x(~nnabla.Variable): N-D arrays. The sizes of all the arrays to be stacked must be the same. [variadic][parameter] axis(int): The axis on which to concatenate arrays. Axis indices take on values 0, 1, 2, and so on from the left. For example, to stack four (3,28,28) inputs on the second axis, specify 1. In this case, the output size will be (3,4,28,28). [default=``0``] Returns: ~nnabla.Variable: Output """ assert len(x) >= 1, "stack must take more than 1 inputs" n_outputs = kw.pop('n_outputs', -1) outputs = kw.pop('outputs', None) axis = kw.pop('axis', 0) return F.Stack(ctx, axis)(*x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def slice(ctx, x, start=None, stop=None, step=None, n_outputs=-1, outputs=None): r""" Slice arrays along specified axis. Args: x(~nnabla.Variable): N-D array start(repeated int64): Start indices for each axis [default=``(0,) * len(x.shape)``] stop(repeated int64): Stop indices for each axis [default=``tuple(x.shape)``] step(repeated int64): Step indices for each axis [default=``(1,) * len(x.shape)``] Returns: ~nnabla.Variable: Sliced N-D array """ if start is None: start = (0,) * len(x.shape) if stop is None: stop = tuple(x.shape) if step is None: step = (1,) * len(x.shape) return F.Slice(ctx, start, stop, step)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def pad(ctx, x, pad_width=None, mode='constant', constant_value=None, n_outputs=-1, outputs=None): r""" Pads given N-D array with specified sizes of dimensions. Padding begins at the last dimension of input x and continues for the specified padding dimension. Args: x(~nnabla.Variable): N-D array pad_width(repeated int64): n-elem tuple, where n/2 <= input dimensions and n is even. len(pad_width)/2 represents the padding dimension(e.g. 1D, 2D, 3D etc.). (Currently padding upto 3D is supported) [default=``(0,) * len(x.shape)``] mode(string): Padding mode is one of the following. 1) constant : Elements in pad region are filled with constant_value. 2) replicate : Padded elements are filled with the values in nearest edges. 3) reflect : Padded with the reflection of the vector mirrored on the first and last values of the vector along each axis. (Currently only `constant` mode is supported) [default=``'constant'``] constant_value(float): Constant values filled in padded regions if mode is `constant`. [default=``0``] Returns: ~nnabla.Variable: Padded N-D array (e.g. (B, C, H, W) shape) where dimension depends on pad_width. ndim() of output N-D array will be same as ndim() of input N-D array. -for 1D padding : N-D input array with padding of the form (padLeft, padRight). The output N-D array dimension (B, C, H, padLeft + W + padRight). -for 2D padding : N-D input array with padding of the form (padTop, padBottom, padLeft, padRight). The output N-D array dimension (B, C, padTop + H + padBottom, padLeft + W + padRight). -for 3D padding : N-D input array with padding of the form (pasFront, padBack, padTop, padBottom, padLeft, padRight). The output N-D array dimension (B, padFront + C + padBack, padTop + H + padBottom, padLeft + W + padRight). """ if pad_width is None: pad_width = (0,) * len(x.shape) if constant_value is None: constant_value = 0 return F.Pad(ctx, pad_width, mode, constant_value)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def transpose(ctx, x, axes, n_outputs=-1, outputs=None): r""" Transposes tensor dimensions. Args: x(~nnabla.Variable): N-D array axes(repeated int64): Source axis indices for each axis. Returns: ~nnabla.Variable: Transposed N-D array. """ return F.Transpose(ctx, axes)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def broadcast(ctx, x, shape, n_outputs=-1, outputs=None): r""" Broadcasting ND-array to the specified shape. Args: x(~nnabla.Variable): N-D array shape(:obj:`tuple` of :obj:`int`): Shape broadcasted to. The size must be the same in axis where ``x``'s shape is not 1. Returns: ~nnabla.Variable: Broadcasted N-D array """ return F.Broadcast(ctx, shape)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def broadcast_to(ctx, x, y, axis=None, n_outputs=-1, outputs=None): r""".. WARNING:: This function is experimental suppport, so please do not actively use it. Broadcasting ND-array to the specified buffer. Args: x(~nnabla.Variable): N-D array y(~nnabla.Variable): N-D array axis(int): Target axis to start broadcasting. If this is not set, broadcast will try to fit y to x starting from the last dimension [default=``-1``] Returns: ~nnabla.Variable: Broadcasted N-D array """ if axis is None: axis = -1 return F.BroadcastTo(ctx, axis)(x, y, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def one_hot(ctx, x, shape, n_outputs=-1, outputs=None): r""" OneHot creates one-hot vector based on input indices. Args: x(~nnabla.Variable): N-D array shape(:obj:`tuple` of :obj:`int`): No Description Returns: ~nnabla.Variable: N-D array """ return F.OneHot(ctx, shape)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def flip(ctx, x, axes=None, n_outputs=-1, outputs=None): r""" Reverses the order of elements of the specified dimension of an array. Args: x(~nnabla.Variable): N-D array axes(repeated int64): The index of the dimension to reverse the order of the elements. Axis indices take on values 0, 1, 2, and so on from the left. For example, to flip a 32 (W) by 24 (H) 100 RGB image (100,3,24,32) vertically and horizontally, specify (2,3). [default=``[len(x.shape) - 1]``] Returns: ~nnabla.Variable: N-D array """ if axes is None: axes = [len(x.shape) - 1] return F.Flip(ctx, axes)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def shift(ctx, x, shifts=None, border_mode='nearest', n_outputs=-1, outputs=None): r""" Shifts the array elements by the specified amount. Args: x(~nnabla.Variable): N-D array. shifts(repeated int64): The amount to shift elements. For example, to shift image data to the right by 2 pixels and up 3 pixels, specify (-3,2). [default=``(0,) * len(x.shape)``] border_mode(string): Specify how to process the ends of arrays whose values will be undetermined as a result of shifting. nearest: The data at the ends of the original array is copied and used. reflect: Original data reflected at the ends of the original array is used. [default=``'nearest'``] Returns: ~nnabla.Variable: N-D array. """ if shifts is None: shifts = (0,) * len(x.shape) return F.Shift(ctx, shifts, border_mode)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def reshape(ctx, x, shape, inplace=True, n_outputs=-1, outputs=None): r""" Reshapes the input variable in-place. It does not create a copy of the variable. The output variable (y) has a new shape but points to the same data as the input variable (x). This means that if the data in the output variable (y) is modified, the data in the input variable (x) also gets modified since the reshape was done in-place. Note: This function has the same behavior as the :meth:`nnabla.Variable.reshape` method. Args: x(~nnabla.Variable): N-D array. shape(:obj:`tuple` of :obj:`int`): Dimensions for each axis. ``-1`` can be specified only in one shape dimension. The value is calculated from the size of the array and remaining dimensions. inplace(bool): The output array is shared with the input array if True. [default=``True``] Returns: ~nnabla.Variable: Reshaped N-D array """ return F.Reshape(ctx, shape, inplace)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def matrix_diag(ctx, x, n_outputs=-1, outputs=None): r""" Returns an array where the last two dimensions consist of the diagonal matrix. Args: x(~nnabla.Variable): N-D array with shape (:math:`M_0 \times \ldots \times M_N`). Returns: ~nnabla.Variable: N-D array with shape (:math:`M_0 \times \ldots \times M_N \times M_N`). """ return F.MatrixDiag(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def matrix_diag_part(ctx, x, n_outputs=-1, outputs=None): r""" Returns an array in which the values of the last dimension consist of the diagonal elements of the last two dimensions of an input array. Args: x(~nnabla.Variable): N-D array with shape (:math:`M_0 \times \ldots \times M_N \times M_N`). Returns: ~nnabla.Variable: N-D array with shape (:math:`M_0 \times \ldots \times M_N`). """ return F.MatrixDiagPart(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def dropout(ctx, x, p=0.5, seed=-1, n_outputs=-1, outputs=None): r""" Dropout. Samples a number :math:`u` from a uniform distribution in :math:`[0, 1]` , and ignores the input if :math:`u \leq p`. .. math:: y = \left\{ \begin{array}{ll} \frac{x}{1 - p} & (u > p) \\ 0 & ({\rm otherwise}) \end{array} \right. Note: Usually dropout only applied during training as below (except `Bayesian dropout`_). .. code-block:: python h = PF.affine(x, num_hidden) if train: h = F.dropout(h, 0.5) .. _Bayesian dropout: https://arxiv.org/abs/1506.02142 Args: x(~nnabla.Variable): N-D array p(float): :math:`p` in definition. [default=``0.5``] seed(int): Random seed. When -1, seed is sampled from global random number generator. [default=``-1``] Returns: ~nnabla.Variable: N-D array with the same shape as x """ return F.Dropout(ctx, p, seed)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def top_k_data(ctx, x, k, abs=False, reduce=True, base_axis=1, n_outputs=-1, outputs=None): r""" Select the `k` largest values from each sample in `x` to propagate unmodified and set all other values to 0. If `abs` is True, the `k` largest values are selected by magnitude. If `reduce` is True (the default), all feature dimensions are reduced to a single dimension of size `k` that propagates only the `k` largest values. Otherwise, if `reduce` is False, input and output dimensions are identical. Dimensions before `base_axis` are treated as number of sample dimensions and `k` values get selected from all elements of a sample (dimensions from `base_axis`) regardless of shape. >>> import nnabla as nn, nnabla.functions as F >>> x = nn.Variable((4, 5, 6)) >>> F.top_k_data(x, 3, reduce=False).shape (4, 5, 6) >>> F.top_k_data(x, 3, reduce=True).shape (4, 3) >>> F.top_k_data(x, 3, reduce=True, base_axis=2).shape (4, 5, 3) Args: x(~nnabla.Variable): N-D array k(int): Number of largest data values to propagate. abs(bool): Determine largest data values by magnitude. [default=``False``] reduce(bool): Reduce feature size to one dimension of size `k`. [default=``True``] base_axis(int): First dimension of the sample shape. [default=``1``] Returns: ~nnabla.Variable: N-D array. """ return F.TopKData(ctx, k, abs, reduce, base_axis)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def top_k_grad(ctx, x, k, abs=False, base_axis=1, n_outputs=-1, outputs=None): r""" Select the `k` largest gradients for each sample in `x` to back-propagate unmodified and set all other gradients to 0. If `abs` is True, the `k` largest gradients are selected by magnitude. Dimensions before `base_axis` are treated as number of sample dimensions and `k` gradients get selected from all gradients of a sample (dimensions from `base_axis`) regardless of shape. Args: x(~nnabla.Variable): N-D array k(int): Number of largest gradients to propagate. abs(bool): Determine largest gradients by magnitude. [default=``False``] base_axis(int): First dimension of the sample shape. [default=``1``] Returns: ~nnabla.Variable: N-D array with same shape and data as `x`. """ return F.TopKGrad(ctx, k, abs, base_axis)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def rand(ctx, low=0, high=1, shape=[], seed=-1, n_outputs=-1, outputs=None): r""" Samples numbers from a uniform distribution :math:`x \sim U(low, high)` given lowest value :math:`low`, upper bound :math:`high`, and shape of the returned Variable. Args: low(float): :math:`low` in definition. [default=``0``] high(float): :math:`high` in definition. [default=``1``] shape(:obj:`tuple` of :obj:`int`): Shape of returned variable. [default=``[]``] seed(int): Random seed. When -1, seed is sampled from global random number generator. [default=``-1``] Returns: ~nnabla.Variable: Variable with the shape specified in the argument. """ return F.Rand(ctx, low, high, shape, seed)(n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def randint(ctx, low=0, high=1, shape=[], seed=-1, n_outputs=-1, outputs=None): r""" Samples integer numbers from a uniform distribution :math:`x \sim U(low, high)` given lowest value :math:`low`, upper bound :math:`high`, and shape of the returned Variable. Args: low(int): :math:`low` in definition. [default=``0``] high(int): :math:`high` in definition. [default=``1``] shape(:obj:`tuple` of :obj:`int`): Shape of returned variable. [default=``[]``] seed(int): Random seed. When -1, seed is sampled from global random number generator. [default=``-1``] Returns: ~nnabla.Variable: Variable with the shape specified in the argument. The dtype is int32. """ return F.Randint(ctx, low, high, shape, seed)(n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def randn(ctx, mu=0, sigma=1, shape=[], seed=-1, n_outputs=-1, outputs=None): r""" Samples numbers from a normal distribution :math:`x \sim N(\mu, \sigma)` given mean :math:`\mu`, standard deviation :math:`\sigma`, and shape of the returned Variable. Args: mu(float): :math:`\mu` in definition. [default=``0``] sigma(float): :math:`\sigma` in definition. [default=``1``] shape(:obj:`tuple` of :obj:`int`): Shape of returned variable. [default=``[]``] seed(int): Random seed. When -1, seed is sampled from global random number generator. [default=``-1``] Returns: ~nnabla.Variable: Variable with the shape specified in the argument. """ return F.Randn(ctx, mu, sigma, shape, seed)(n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def random_crop(ctx, x, shape=None, base_axis=1, seed=-1, n_outputs=-1, outputs=None): r""" RandomCrop randomly extracts a portion of an array. Args: x(~nnabla.Variable): N-D array shape(:obj:`tuple` of :obj:`int`): The data size to extract. For example, to randomly extract a portion of the image (3,48,48) from a 3,64,64 image, specify (3,48,48). [default=``x.shape``] base_axis(int): No Description [default=``1``] seed(int): Random seed. When -1, seed is sampled from global random number generator. [default=``-1``] Returns: ~nnabla.Variable: N-D array """ if shape is None: shape = x.shape return F.RandomCrop(ctx, shape, base_axis, seed)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def random_flip(ctx, x, axes=None, base_axis=1, seed=-1, n_outputs=-1, outputs=None): r""" Reverses the order of elements of the specified dimension of an array at 50% probability. Args: x(~nnabla.Variable): N-D array axes(repeated int64): The index of the axis to reverse the order of the elements. Axis indices take on values 0, 1, 2, and so on from the left. For example, to flip a 32 (W) by 24 (H) 100 RGB images (100, 3,24,32) vertically and horizontally at random, specify (2,3). [default=``[len(x.shape) - 1]``] base_axis(int): No Description [default=``1``] seed(int): Random seed. When -1, seed is sampled from global random number generator. [default=``-1``] Returns: ~nnabla.Variable: N-D array """ if axes is None: axes = [len(x.shape) - 1] return F.RandomFlip(ctx, axes, base_axis, seed)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def random_shift(ctx, x, shifts=None, border_mode='nearest', base_axis=1, seed=-1, n_outputs=-1, outputs=None): r""" Randomly shifts the array elements within the specified range. Args: x(~nnabla.Variable): N-D array. shifts(repeated int64): Max absolute amount to shift elements. For example, to shift image data horizontally by :math:`\pm 2` pixels and vertically by :math:`\pm 3` pixels, specify (3,2). [default=``(0,) * len(x.shape)``] border_mode(string): Specify how to process the ends of arrays whose values will be undetermined as a result of shifting. nearest: The data at the ends of the original array is copied and used. reflect: Original data reflected at the ends of the original array is used. [default=``'nearest'``] base_axis(int): No Description [default=``1``] seed(int): Random seed. When -1, seed is sampled from global random number generator. [default=``-1``] Returns: ~nnabla.Variable: N-D array. """ if shifts is None: shifts = (0,) * len(x.shape) return F.RandomShift(ctx, shifts, border_mode, base_axis, seed)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def image_augmentation(ctx, x, shape=None, pad=(0, 0), min_scale=1.0, max_scale=1.0, angle=0.0, aspect_ratio=1.0, distortion=0.0, flip_lr=False, flip_ud=False, brightness=0.0, brightness_each=False, contrast=1.0, contrast_center=0.0, contrast_each=False, noise=0.0, seed=-1, n_outputs=-1, outputs=None): r""" ImageAugmentation randomly alters the input image. Args: x(~nnabla.Variable): N-D array. shape(:obj:`tuple` of :obj:`int`): The output image data size. [default=``x.shape``] pad(:obj:`tuple` of :obj:`int`): Border padding values for each spatial axis. Padding will be added both sides of the dimension. [default=``(0, 0)``] min_scale(float): The minimum scale ratio when randomly scaling the image. For example, to scale down to 0.8 times the size of the original image, specify "0.8". To not apply random scaling, set both min_scale and max_scale to "1.0". [default=``1.0``] max_scale(float): The maximum scale ratio when randomly scaling the image. For example, to scale down to 2 times the size of the original image, specify "2.0". [default=``1.0``] angle(float): The rotation angle range in radians when randomly rotating the image. The image is randomly rotated in the -Angle to +Angle range. For example, to rotate in a +-15 degree range, specify "0.26" (15 degrees/360 degrees * 2PI). To not apply random rotation, specify "0.0". [default=``0.0``] aspect_ratio(float): The aspect ratio range when randomly deforming the image. For example, to deform aspect ratio of image from 1:1.3 to 1.3:1, specify "1.3". To not apply random deforming, specify "1.0". [default=``1.0``] distortion(float): The distortion range when randomly distorting the image. To not apply distortion, specify "0.0". [default=``0.0``] flip_lr(bool): Whether to randomly flip the image horizontally at 50% probability. [default=``False``] flip_ud(bool): Whether to randomly flip the image vertically at 50% probability. [default=``False``] brightness(float): The absolute range of values to randomly add to the brightness. A random value in the -Brightness to +Brightness range is added to the brightness. For example, to vary the brightness in the -0.05 to +0.05 range, specify "0.05". To not apply random addition to brightness, specify "0.0". [default=``0.0``] brightness_each(bool): Whether to apply the random addition to brightness (as specified by brightness) to each color channel. True: brightness is added based on a different random number for each channel. False: brightness is added based on a random number common to all channels. [default=``False``] contrast(float): The range in which to randomly vary the image contrast. The contrast is varied in the 1/Contrast times to Contrast times range. The output brightness is equal to (input - contrast_center) * contrast + contrast_center. For example, to vary the contrast in the 0.91 times to 1.1 times range, specify "1.1". To not apply random contrast variation, specify "1.0". [default=``1.0``] contrast_center(float): Intensity center used for applying contrast. [default=``0.0``] contrast_each(bool): Whether to apply the random contrast variation (as specified by contrast) to each color channel. True: contrast is varied based on a different random number for each channel. False: contrast is varied based on a random number common to all channels. [default=``False``] noise(float): Sigma of normal random number to be added. [default=``0.0``] seed(int): Random seed. When -1, seed is sampled from global random number generator. [default=``-1``] Returns: ~nnabla.Variable: N-D array. """ if shape is None: shape = x.shape return F.ImageAugmentation(ctx, shape, pad, min_scale, max_scale, angle, aspect_ratio, distortion, flip_lr, flip_ud, brightness, brightness_each, contrast, contrast_center, contrast_each, noise, seed)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def sigmoid_cross_entropy(ctx, x, target, n_outputs=-1, outputs=None): r""" Element-wise cross entropy between `x` and the target variables, passed to a sigmoid function. .. math:: y_i = - \left(x^{(1)}_i \ln \left(\sigma \left(x^{(0)}_i \right)\right) + \ \left(1 - x^{(1)}_i\right) \ln \left(1 - \sigma \left(x^{(0)}_i \ \right)\right)\right) where :math:`\sigma(s)=\frac{1}{1+\exp(-s)}`. Note: SigmoidCrossEntropy is equivalent to Sigmoid+BinaryCrossEntropy, but computing them at once has the effect of reducing computational error. Args: x(~nnabla.Variable): N-D array. Typically indicates a score. The value lies in :math:`[-\infty, \infty]` [parameter] target(~nnabla.Variable): N-D array of labels. Only 0 or 1 value is allowed. [parameter] Returns: ~nnabla.Variable: N-D array of element-wise losses. """ return F.SigmoidCrossEntropy(ctx)(x, target, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def binary_cross_entropy(ctx, x, target, n_outputs=-1, outputs=None): r""" Element-wise cross entropy between `x` and the target variables. .. math:: y_i = - \left(x^{(1)}_i * \ln \left(x^{(0)}_i\right) + \left(1 - \ x^{(1)}_i\right) * \ln \left(1 - x^{(0)}_i\right)\right). Args: x(~nnabla.Variable): Probabilities N-D array. :math:`-\infty` to :math:`\infty`. target(~nnabla.Variable): N-D array of labels. Usually set as 0 or 1, but, unlike SigmoidCrossEntropy, it allows probability (0 to 1) as inputs and backpropagation can be done. Returns: ~nnabla.Variable: N-D array of element-wise losses. """ return F.BinaryCrossEntropy(ctx)(x, target, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def softmax_cross_entropy(ctx, x, target, axis=None, n_outputs=-1, outputs=None): r""" Element-wise cross entropy between the variables and the variables of a label given by a category index with Softmax normalization. .. math:: y_{j} = -\ln \left(\frac{\exp(x_{j,t_j})}{\sum_{i'} \exp(x_{j,i'})}\right) along dimension specified by axis (:math:`i` is the axis where normalization is performed on). Note: SoftmaxCrossEntropy is equivalent to Softmax+CategoricalCrossEntropy, but computing them at once has the effect of reducing computational error. Args: x(~nnabla.Variable): N-D array. Typically indicates a score. :math:`(D_1 \times ... \times D_i \times ... \times D_N)` [parameter] target(~nnabla.Variable): N-D array of labels. :math:`(D_1 \times ... \times 1 \times ... \times D_N)` [parameter] axis(int): Axis normalization is taken. [default=``len(x.shape) - 1``] Returns: ~nnabla.Variable: N-D array of element-wise losses. :math:`(D_1 \times ... \times 1 \times ... \times D_N)` """ if axis is None: axis = len(x.shape) - 1 return F.SoftmaxCrossEntropy(ctx, axis)(x, target, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def categorical_cross_entropy(ctx, x, target, axis=None, n_outputs=-1, outputs=None): r""" Element-wise cross entropy between `x` and the target `t` where targets are given by a category index. .. math:: y_{j} = -\ln \left( x_{j, t_j} \right) along dimension specified by axis (:math:`i` is the axis where normalization is performed on). Args: x(~nnabla.Variable): N-D array. Typically indicates a score. :math:`(D_1 \times ... \times D_i \times ... \times D_N)` [parameter] target(~nnabla.Variable): N-D array of labels. :math:`(D_1 \times ... \times 1 \times ... \times D_N)` [parameter] axis(int): Axis normalization is taken. [default=``len(x.shape) - 1``] Returns: ~nnabla.Variable: N-D array of element-wise losses. :math:`(D_1 \times ... \times 1 \times ... \times D_N)` """ if axis is None: axis = len(x.shape) - 1 return F.CategoricalCrossEntropy(ctx, axis)(x, target, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def squared_error(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element-wise squared error .. math:: y_i = \left(x^{(0)}_i - x^{(1)}_i\right)^2. Args: x0(~nnabla.Variable): N-D array. x1(~nnabla.Variable): N-D array. Returns: ~nnabla.Variable: N-D array. """ return F.SquaredError(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def absolute_error(ctx, x0, x1, n_outputs=-1, outputs=None): r""" Element-wise absolute error .. math:: y_i = | x^{(0)}_i - x^{(1)}_i |. Args: x0(~nnabla.Variable): N-D array. x1(~nnabla.Variable): N-D array. Returns: ~nnabla.Variable: N-D array. """ return F.AbsoluteError(ctx)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def huber_loss(ctx, x0, x1, delta=1.0, n_outputs=-1, outputs=None): r""" Element-wise Huber loss .. math:: y_i= \left\{ \begin{array}{ll} d^2 & (|d| < \delta)\\ \delta (2 |d| - \delta) & ({\rm otherwise}) \end{array} \right. where :math:`d = x^{(0)}_i - x^{(1)}_i` Args: x0(~nnabla.Variable): N-D array. x1(~nnabla.Variable): N-D array. delta(float): Delta [default=``1.0``] Returns: ~nnabla.Variable: N-D array of element-wise losses. """ return F.HuberLoss(ctx, delta)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def epsilon_insensitive_loss(ctx, x0, x1, epsilon, n_outputs=-1, outputs=None): r""" Element-wise Epsilon Insensitive Loss .. math:: y_i= \left\{ \begin{array}{ll} | x^{(0)}_i - x^{(1)}_i | - \epsilon & if \ \ | x^{(0)}_i - x^{(1)}_i | > \epsilon \\ 0 & otherwise \end{array} \right. Args: x0(~nnabla.Variable): N-D array. x1(~nnabla.Variable): N-D array. epsilon(float): Insensitive parameter. Returns: ~nnabla.Variable: N-D array of element-wise losses. """ return F.EpsilonInsensitiveLoss(ctx, epsilon)(x0, x1, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def kl_multinomial(ctx, p, q, base_axis=1, n_outputs=-1, outputs=None): r""" The Kullback Leibler Divergence for multinomial distributions. .. math:: D = \sum_i p_i \log \left( \frac{p_i}{q_i} \right) Args: p(~nnabla.Variable): N-D array of the source categorical probabilities q(~nnabla.Variable): N-D array of the target categorical probabilities base_axis(int): Dimensions up to base_axis is treated as sample dimension. [default=``1``] Returns: ~nnabla.Variable: Kullback Leibler divergence :math:`KL(p \parallel q)`. """ return F.KLMultinomial(ctx, base_axis)(p, q, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def binary_sigmoid(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise binary sigmoid function. In the forward pass, it computes .. math:: f(x) = \begin{cases} 1 & (x > 0) \\ 0 & ({\rm otherwise})\end{cases}, but in the backward pass, a straight-through approximation of the gradient is used, i.e., .. math:: \frac{\partial f(x)}{\partial x} = \begin{cases} 0 & (|x| \geq 1) \\ \frac{1}{2} & ({\rm otherwise}) \end{cases}. References: * `Courbariaux, Matthieu, and Yoshua Bengio. Binarynet: Training deep neural networks with weights and activations constrained to+ 1 or-1. <https://arxiv.org/abs/1602.02830>`_ Args: x(~nnabla.Variable): Input . Returns: ~nnabla.Variable: Output. """ return F.BinarySigmoid(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def binary_tanh(ctx, x, n_outputs=-1, outputs=None): r""" Element-wise binary tanh function. In the forward pass, it computes .. math:: f(x) = \begin{cases} 1 & (x > 0) \\ -1 & ({\rm otherwise}) \end{cases}, but in the backward pass, a straight-through approximation of the gradient is used, i.e., .. math:: \frac{\partial f(x)}{\partial x} = \begin{cases} 0 & (|x| \geq 1) \\ 1 & ({\rm otherwise}) \end{cases}. References: * `Courbariaux, Matthieu, and Yoshua Bengio. Binarynet: Training deep neural networks with weights and activations constrained to+ 1 or-1. <https://arxiv.org/abs/1602.02830>`_ Args: x(~nnabla.Variable): Input . Returns: ~nnabla.Variable: Output. """ return F.BinaryTanh(ctx)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def binary_connect_affine(ctx, x, weight, binary_weight, bias=None, base_axis=1, n_outputs=-1, outputs=None): r""" This function provides a BinaryConnect affine layer. It computes in the forward pass .. math:: y_j = \sum_{i} sign(w_{j,i}) x_i, i.e., the weights :math:`w_{j,i}` are binarized to :math:`sign(w_{j,i})` and, hence, each weight is in :math:`\{-1,\,1\}`. By this weight binarization, the inner product computations do not require any multiplications anymore as they turn into additions/subtractions. This function should be used together with :meth:`~nnabla.functions.batch_normalization`. .. note:: 1) If you would like to share the binary weights between other layers, please use the standard, floating value weights (`weight`) and not the binary weights (`binary_weight`). 2) The weights and the binary weights become in sync only after a call to :meth:`~nnabla.Variable.forward`, and not after a call to :meth:`~nnabla.Variable.backward`. If you wish to store the parameters of the network, remember to call :meth:`~nnabla.Variable.forward`, once before doing so, otherwise the weights and the binary weights will not be in sync. 3) CPU and GPU implementations now use floating values for `binary_weight`, since this function is for simulation purposes. References: * `M. Courbariaux, Y. Bengio, and J.-P. David. BinaryConnect: Training Deep Neural Networks with binary weights during propagations. <https://arxiv.org/abs/1511.00363>`_ Args: x(~nnabla.Variable): Input . weight(~nnabla.Variable): Weight . [parameter] binary_weight(~nnabla.Variable): Binarized weight . [parameter] bias(~nnabla.Variable): Bias. [optional][parameter] base_axis(int): Dimensions up to base_axis is treated as sample dimension. [default=``1``] Returns: ~nnabla.Variable: Output. """ inputs = [x, weight, binary_weight] if bias is not None: inputs += [bias] return F.BinaryConnectAffine(ctx, base_axis)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def binary_connect_convolution(ctx, x, weight, binary_weight, bias=None, base_axis=1, pad=None, stride=None, dilation=None, group=1, n_outputs=-1, outputs=None): r""" This function provides a BinaryConnect convolution layer. It computes in the forward pass .. math:: y_{n, a, b} = \sum_{m} \sum_{i} \sum_{j} sign(w_{n, m, i, j}) x_{m, a + i, b + j}, i.e., the weights :math:`w_{n, m, i, j}` are binarized to :math:`sign(w_{n, m, i, j})` and, hence, each weight is in :math:`\{-1,\,1\}`. By this weight binarization, the inner product computations do not require any multiplications anymore as they turn into additions/subtractions. This function should be used together with :meth:`~nnabla.functions.batch_normalization`. Reference * `M. Courbariaux, Y. Bengio, and J.-P. David. BinaryConnect: Training Deep Neural Networks with binary weights during propagations. <https://arxiv.org/abs/1511.00363>`_ .. note:: 1) If you would like to share the binary weights between other layers, please use the standard, floating value weights (`weight`) and not the binary weights (`binary_weight`). 2) The weights and the binary weights become in sync only after a call to :meth:`~nnabla.Variable.forward`, and not after a call to :meth:`~nnabla.Variable.backward`. If you wish to store the parameters of the network, remember to call :meth:`~nnabla.Variable.forward`, once before doing so, otherwise the weights and the binary weights will not be in sync. 3) CPU and GPU implementations now use floating values for `binary_weight`, since this function is for simulation purposes. Args: x(~nnabla.Variable): Input. weight(~nnabla.Variable): Weight. [parameter] binary_weight(~nnabla.Variable): Binarized weight. [parameter] bias(~nnabla.Variable): Bias. [optional][parameter] base_axis(int): Dimensions up to base_axis is treated as sample dimension. [default=``1``] pad(:obj:`tuple` of :obj:`int`): Padding sizes for dimensions. [default=``(0,) * (len(x.shape) - (base_axis+1))``] stride(:obj:`tuple` of :obj:`int`): Stride sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] dilation(:obj:`tuple` of :obj:`int`): Dilation sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] group(int): Number of groups of channels. This makes the connection across channels sparser, by grouping connections along the mapping direction. [default=``1``] Returns: ~nnabla.Variable: Output """ if pad is None: pad = (0,) * (len(x.shape) - (base_axis+1)) if stride is None: stride = (1,) * (len(x.shape) - (base_axis+1)) if dilation is None: dilation = (1,) * (len(x.shape) - (base_axis+1)) inputs = [x, weight, binary_weight] if bias is not None: inputs += [bias] return F.BinaryConnectConvolution(ctx, base_axis, pad, stride, dilation, group)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def binary_weight_affine(ctx, x, weight, binary_weight, alpha, bias=None, base_axis=1, n_outputs=-1, outputs=None): r""" This function provides a Binary Weight Network affine layer. It computes in the forward pass .. math:: y_j = \frac{1}{\|\mathbf{w}_j\|_{\ell_1}} \sum_{i} sign(w_{j,i}) x_i i.e., the weights :math:`w_{j,i}` are binarized to :math:`sign(w_{j,i})` and, hence, each weight is in :math:`\{-1,\,1\}`. By this weight binarization, the inner product computations turn into additions/subtractions which are followed by multiplication with the scaling factor :math:`\alpha_j = \frac{1}{\|\mathbf{w}_j\|_{\ell_1}}`. Reference * `Rastegari, Mohammad, et al. XNOR-Net: ImageNet Classification Using Binary Convolutional Neural Networks. <https://arxiv.org/abs/1603.05279>`_ .. note:: 1) If you would like to share the binary weights with other layers, please use the standard, floating value weights (`weight`) and not the binary weights (`binary_weight`). 2) The weights and the binary weights become in sync only after a call to :meth:`~nnabla.Variable.forward`, and not after a call to :meth:`~nnabla.Variable.backward`. If you wish to store the parameters of the network, remember to call :meth:`~nnabla.Variable.forward`, once before doing so, otherwise the weights and the binary weights will not be in sync. 3) CPU and GPU implementations now use floating values for `binary_weight`, since this function is for simulation purposes. Args: x(~nnabla.Variable): Input . weight(~nnabla.Variable): Weight. [parameter] binary_weight(~nnabla.Variable): Binarized weight. [parameter] alpha(~nnabla.Variable): Alpha. [parameter] bias(~nnabla.Variable): Bias. [optional][parameter] base_axis(int): Dimensions up to base_axis is treated as sample dimension. [default=``1``] Returns: ~nnabla.Variable: Output. """ inputs = [x, weight, binary_weight, alpha] if bias is not None: inputs += [bias] return F.BinaryWeightAffine(ctx, base_axis)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def binary_weight_convolution(ctx, x, weight, binary_weight, alpha, bias=None, base_axis=1, pad=None, stride=None, dilation=None, group=1, n_outputs=-1, outputs=None): r""" This function provides a Binary Weight Network convolution layer. It computes in the forward pass .. math:: y_{n, a, b} = \frac{1}{\|\mathbf{w}_n\|_{\ell_1}} \sum_{m} \sum_{i} \sum_{j} sign(w_{n, m, i, j}) x_{m, a + i, b + j}. i.e., the weights :math:`w_{n, m, i, j}` are binarized to :math:`sign(w_{n, m, i, j})` and, hence, each weight is in :math:`\{-1,\,1\}`. By this weight binarization, the inner product computations turn into additions/subtractions which are followed by multiplication with the scaling factor :math:`\alpha_n = \frac{1}{\|\mathbf{w}_n\|_{\ell_1}}`. Reference * `Rastegari, Mohammad, et al. XNOR-Net: ImageNet Classification Using Binary Convolutional Neural Networks. <https://arxiv.org/abs/1603.05279>`_ .. note:: 1) If you would like to share the binary weights between other standard layers, please use the standard, floating value weights (`weight`) and not the binary weights (`binary_weight`). 2) The weights and the binary weights become in sync only after a call to :meth:`~nnabla.Variable.forward`, and not after a call to :meth:`~nnabla.Variable.backward`. If you wish to store the parameters of the network, remember to call :meth:`~nnabla.Variable.forward`, once before doing so, otherwise the weights and the binary weights will not be in sync. 3) CPU and GPU implementations now use floating values for `binary_weight`, since this function is for simulation purposes. Args: x(~nnabla.Variable): Input. weight(~nnabla.Variable): Weight. [parameter] binary_weight(~nnabla.Variable): Binarized weight. [parameter] alpha(~nnabla.Variable): Alpha. [parameter] bias(~nnabla.Variable): Bias. [optional][parameter] base_axis(int): Dimensions up to base_axis is treated as sample dimension. [default=``1``] pad(:obj:`tuple` of :obj:`int`): Padding sizes for dimensions. [default=``(0,) * (len(x.shape) - (base_axis+1))``] stride(:obj:`tuple` of :obj:`int`): Stride sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] dilation(:obj:`tuple` of :obj:`int`): Dilation sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] group(int): Number of groups of channels. This makes the connection across channels sparser, by grouping connections along the mapping direction. [default=``1``] Returns: ~nnabla.Variable: Output """ if pad is None: pad = (0,) * (len(x.shape) - (base_axis+1)) if stride is None: stride = (1,) * (len(x.shape) - (base_axis+1)) if dilation is None: dilation = (1,) * (len(x.shape) - (base_axis+1)) inputs = [x, weight, binary_weight, alpha] if bias is not None: inputs += [bias] return F.BinaryWeightConvolution(ctx, base_axis, pad, stride, dilation, group)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
@function_api def inq_affine(ctx, x, weight, indicator_fixedweights, bias=None, base_axis=1, num_bits=4, inq_iterations=(), selection_algorithm='largest_abs', seed=-1, n_outputs=-1, outputs=None): r""" This function provides a INQ affine layer. It computes in the forward pass .. math:: y_j = \sum_{i} w_{j,i} x_i, where the weights :math:`w_{j,i}` are quantized sequentially during training to power-of-two numbers. In the backward pass, only the non-fixed (i.e., learnable) weights are updated. References: * `Zhou A, Yao A, Guo Y, Xu L, Chen Y. Incremental network quantization: Towards lossless CNNs with low-precision weights. <https://arxiv.org/abs/1702.03044>`_ Args: x(~nnabla.Variable): Input . weight(~nnabla.Variable): Weight . [parameter] indicator_fixedweights(~nnabla.Variable): Indicates which weights are already fixed (0 = not fixed, 1 = fixed) . [parameter] bias(~nnabla.Variable): Bias. [optional][parameter] base_axis(int): Dimensions up to base_axis is treated as sample dimension. [default=``1``] num_bits(int): Number of bits per weight. Needs to be >= 2 as two bits are used to code `zero` and sign of weight. [default=``4``] inq_iterations(repeated int64): List which specifies after how many forward passes we fix 50% of the learnable weights. If we have done as many iterations as specified in the last element of `inq_iterations`, then all weights are fixed. [default=``()``] selection_algorithm(string): Chooses algorithm that we use for selecting the weights to fix ("largest_abs" ... fix weights with largest absolute value, "random" ... fix weights randomly) [default=``'largest_abs'``] seed(int): Random seed. When -1, seed is sampled from global random number generator. [default=``-1``] Returns: ~nnabla.Variable: Output. """ inputs = [x, weight, indicator_fixedweights] if bias is not None: inputs += [bias] return F.INQAffine(ctx, base_axis, num_bits, inq_iterations, selection_algorithm, seed)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs) @function_api def inq_convolution(ctx, x, weight, indicator_fixedweights, bias=None, base_axis=1, pad=None, stride=None, dilation=None, group=1, num_bits=4, inq_iterations=(), selection_algorithm='largest_abs', seed=-1, n_outputs=-1, outputs=None): r""" This function provides a INQ convolution layer. It computes in the forward pass .. math:: y_{n, a, b} = \sum_{m} \sum_{i} \sum_{j} w_{n, m, i, j} x_{m, a + i, b + j}, where the weights :math:`w_{j,i}` are quantized sequentially during training to power-of-two numbers. In the backward pass, only the non-fixed (i.e., learnable) weights are updated. Reference * `Zhou A, Yao A, Guo Y, Xu L, Chen Y. Incremental network quantization: Towards lossless CNNs with low-precision weights. <https://arxiv.org/abs/1702.03044>`_ Args: x(~nnabla.Variable): Input. weight(~nnabla.Variable): Weight. [parameter] indicator_fixedweights(~nnabla.Variable): Indicates which weights are already fixed (0 = not fixed, 1 = fixed) . [parameter] bias(~nnabla.Variable): Bias. [optional][parameter] base_axis(int): Dimensions up to base_axis is treated as sample dimension. [default=``1``] pad(:obj:`tuple` of :obj:`int`): Padding sizes for dimensions. [default=``(0,) * (len(x.shape) - (base_axis+1))``] stride(:obj:`tuple` of :obj:`int`): Stride sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] dilation(:obj:`tuple` of :obj:`int`): Dilation sizes for dimensions. [default=``(1,) * (len(x.shape) - (base_axis+1))``] group(int): Number of groups of channels. This makes the connection across channels sparser, by grouping connections along the mapping direction. [default=``1``] num_bits(int): Number of bits per weight. Needs to be >= 2 as two bits are used to code `zero` and sign of weight. [default=``4``] inq_iterations(repeated int64): List which specifies after how many forward passes we fix 50% of the learnable weights. If we have done as many iterations as specified in the last element of `inq_iterations`, then all weights are fixed. [default=``()``] selection_algorithm(string): Chooses algorithm that we use for selecting the weights to fix ("largest_abs" ... fix weights with largest absolute value, "random" ... fix weights randomly) [default=``'largest_abs'``] seed(int): Random seed. When -1, seed is sampled from global random number generator. [default=``-1``] Returns: ~nnabla.Variable: Output """ if pad is None: pad = (0,) * (len(x.shape) - (base_axis+1)) if stride is None: stride = (1,) * (len(x.shape) - (base_axis+1)) if dilation is None: dilation = (1,) * (len(x.shape) - (base_axis+1)) inputs = [x, weight, indicator_fixedweights] if bias is not None: inputs += [bias] return F.INQConvolution(ctx, base_axis, pad, stride, dilation, group, num_bits, inq_iterations, selection_algorithm, seed)(*inputs, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs) @function_api def fixed_point_quantize(ctx, x, sign=True, n=8, delta=0.0625, ste_fine_grained=True, n_outputs=-1, outputs=None): r"""This function uniformly quantizes values in fixed-point number representation. In the forward pass, .. math:: q_i= \left\{ \begin{array}{ll} max & if \ \ \ x_i > max \\ sign(x_i) \times floor(|x_i| \delta^{-1} + 2^{-1}) \times \delta & if \ \ min \le x_i \le max \\ min & if \ \ x_i < min \\ \end{array} \right., where :math:`\delta` is the step size, :math:`(min, max) :=(- (2^{n-1} - 1)\delta, (2^{n-1} - 1)\delta)` if :math:`sign` is true, :math:`(min, max) := (0, (2^n - 1) \delta)` otherwise, and :math:`n` is the total bit-width used. In the backward pass when using `ste_fine_grained` as false, .. math:: \frac{\partial q_i}{\partial x_i} = 1. In the backward pass when using `ste_fine_grained` as true, .. math:: \frac{\partial q_i}{\partial x_i}= \left\{ \begin{array}{ll} 0 & if \ \ \ x_i > max \\ 1 & if \ \ min \le x_i \le max \\ 0 & if \ \ x_i < min \\ \end{array} \right.. .. note:: Quantized values are stored as floating point number, since this function is for simulation purposes. Args: x(~nnabla.Variable): N-D array sign(bool): Indicate the signed number or the unsigned number. Default is true. [default=``True``] n(int): Bit width used. Note that `sign` consumes one bit. :math:`n-1` is used for number representation in `signed` case. [default=``8``] delta(float): Step size. [default=``0.0625``] ste_fine_grained(bool): Straight Through Estimator is fine-grained or not. [default=``True``] Returns: ~nnabla.Variable: N-D array. """ return F.FixedPointQuantize(ctx, sign, n, delta, ste_fine_grained)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs) @function_api def pow2_quantize(ctx, x, sign=True, with_zero=True, n=8, m=1, ste_fine_grained=True, n_outputs=-1, outputs=None): r""" This function quantizes values in the power of 2 number representation, in other words, it is linear (uniform) quantization in :math:`log_2` domain. In the forward pass of `signed` case, .. math:: q_i= \left\{ \begin{array}{ll} max_{+} & if \ \ \overline{q_i} > max_{+} \\ \overline{q_i} & if \ \ min_{+} \le \overline{q_i} \le max_{+} \\ min_{+} & if \ \ 0 \le \overline{q_i} < min_{+} \\ min_{-} & if \ \ min_{-} < \overline{q_i} < 0 \\ \overline{q_i} & if \ \ max_{-} \le \overline{q_i} \le min_{-}\\ max_{-} & if \ \ \overline{q_i} < max_{-} \\ \end{array} \right., where .. math:: && max_{+} = 2^{m}, min_{+} = 2^{m - (2^{n-1} - 1)},\\ && max_{-} = -2^{m}, min_{-} = -2^{m - (2^{n-1} - 1)},\\ && \overline{q_i} = sign(x_i) \times 2^{round(\log_2 |x_i|)}. This quantization uses the geometric mean between two power-of-two numbers as quantization threshold. In the forward pass of `unsigned` case, .. math:: q_i= \left\{ \begin{array}{ll} max & if \ \ \overline{q_i} > max \\ \overline{q_i} & if \ \ min \le \overline{q_i} \le max \\ min & if \ \ 0 < \overline{q_i} < min \\ \end{array} \right., where .. math:: && max = 2^{m}, min = 2^{m - (2^{n} - 1)},\\ && \overline{q_i} = 2^{int(\log_2 |x_i|)}. When using `with_zero` as true, a pruning threshold is used to round an input to 0 or :math:`min`. The pruning threshold is defined in this function as the following, .. math:: pruning\ threshold = min \times 2^{-\frac{1}{2}}. If an absolute value of the input is lesser than this value, the input is rounded to 0, otherwise :math:`min`. In the backward pass when using ste_fine_grained as false, .. math:: \frac{\partial q_i}{\partial x_i} = 1. In the backward pass when using ste_fine_grained as true, .. math:: \frac{\partial q_i}{\partial x_i}= \left\{ \begin{array}{ll} 0 & if \ \ \overline{q_i} > max_{+} \\ 1 & if \ \ otherwise \\ 0 & if \ \ \overline{q_i} < max_{-} \\ \end{array} \right.. There are some literatures using pow2 quantization in their proposed methods. References: * `Miyashita Daisuke, Lee H. Edward, Murmann Boris. Convolutional Neural Networks using Logarithmic Data Representation. <https://arxiv.org/abs/1603.01025>`_ * `Aojun Zhou, Anbang Yao, Yiwen Guo, Lin Xu, Yurong Chen. Incremental Network Quantization: Towards Lossless CNNs with Low-precision Weights. <https://arxiv.org/abs/1702.03044>`_ .. note:: Quantized values are stored as floating point number, since this function is for simulation purposes. Args: x(~nnabla.Variable): N-D array sign(bool): Indicate the signed number or the unsigned number. Default is true. [default=``True``] with_zero(bool): Indicate using zero as a quantized value. Default is true. Note that `zero` consumes one bit. [default=``True``] n(int): Bit width used, Note that `sign` consumes one bit. :math:`n-1` is used for number representation in `signed` case. Default is 8. [default=``8``] m(int): :math:`2^m` is the upper bound of the dynamic range and :math:`-2^m` is the lower bound, :math:`m \in \mathcal{Z}`. Default is 1. [default=``1``] ste_fine_grained(bool): Straight Through Estimator is fine-grained or not. [default=``True``] Returns: ~nnabla.Variable: N-D array. """ return F.Pow2Quantize(ctx, sign, with_zero, n, m, ste_fine_grained)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def fft(ctx, x, signal_ndim, normalized=False, n_outputs=-1, outputs=None): r""" Complex-to-complex Descrete Fourier Transform, .. math:: X_{k_1, \ldots, k_d} = \sum_{n_1=0}^{N_1-1} \dots \sum_{n_d=0}^{N_d-1} x_{n_1, \ldots, n_d} \exp\left(-2 \pi j \left( \sum_{i=0}^{d} \frac{k_i n_i}{N_i} \right) \right), where .. math:: k_i = 0, \ldots, N_i - 1. This function now supports 1-D, 2-D, and 3-D DFT with or without the leading batch dimentsion(s). The input is expected to be complex-valued with at least signal_ndim + 1 dimensions. The last dimension has a shape of two where x[..., 0] is the real part and x[..., 1] the imaginary part. Example: .. code-block:: python import numpy as np import nnabla as nn import nnabla.functions as F from nnabla.ext_utils import get_extension_context ctx = get_extension_context("cudnn") nn.set_default_context(ctx) # Example for a batched 2D-FFT and 2D-IFFT (batch-size: 2, data-size: 4x3) x_data = np.random.rand(2, 4, 3) + 1j * np.random.rand(2, 4, 3) x = nn.Variable.from_numpy_array(np.stack([np.real(x_data), np.imag(x_data)], axis=3)) y = F.fft(x, signal_ndim=2, normalized=True) z = F.ifft(y, signal_ndim=2, normalized=True) z.forward() np.allclose(z.d[..., 0] + 1j*z.d[...,1], x_data) Args: x(~nnabla.Variable): Input. signal_ndim(int): The number of dimentsions for each signal. It must be 1, 2, or 3. normalized(bool): Use unitary normalization. If `True`, the normalization constant :math:`\sqrt{\frac{1}{\prod_{i=1}^{d} N_i}}` is multiplied. [default=``False``] Returns: ~nnabla.Variable: FFT transformed signal. """ return F.FFT(ctx, signal_ndim, normalized)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def ifft(ctx, x, signal_ndim, normalized=False, n_outputs=-1, outputs=None): r""" Complex-to-complex inverse Descrete Fourier Transform, .. math:: X_{k_1, \ldots, k_d} = \frac{1}{\prod_{i=1}^{d} N_i} \sum_{n_1=0}^{N_1-1} \dots \sum_{n_d=0}^{N_d-1} x_{n_1, \ldots, n_d} \exp\left(2 \pi j \left( \sum_{i=0}^{d} \frac{k_i n_i}{N_i} \right) \right), where .. math:: k_i = 0, \ldots, N_i - 1. This function now supports 1-D, 2-D, and 3-D DFT with or without the leading batch dimentsion(s). The input is expected to be complex-valued with at least signal_ndim + 1 dimensions. The last dimension has a shape of two where x[..., 0] is the real part and x[..., 1] the imaginary part. Args: x(~nnabla.Variable): Input. signal_ndim(int): The number of dimentsions for each signal. It must be 1, 2, or 3. normalized(bool): Use unitary normalization. If `True`, the normalization constant :math:`\frac{1}{\prod_{i=1}^{d} N_i}` becomes :math:`\sqrt{\frac{1}{\prod_{i=1}^{d} N_i}}`. [default=``False``] Returns: ~nnabla.Variable: IFFT transformed signal. """ return F.IFFT(ctx, signal_ndim, normalized)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def top_n_error(ctx, x, target, axis=None, n=1, n_outputs=-1, outputs=None): r""" Top N error along the dimension specified by the axis, the element of outputs is .. math:: y_i = \left \{ \begin{array}{l} 1 \ (x_i \ is \ not \ within \ N-th \ place) \\ 0 \ (x_i \ is \ within \ N-th \ place) \end{array} \right. Args: x(~nnabla.Variable): Probabilities N-D array. :math:`D_1 \times ... \times D_i \times ... \times D_N` target(~nnabla.Variable): N-D array of labels. :math:`D_1 \times ... \times 1 \times ... \times D_N` axis(int): Axis on which the top N error is calculated. [default=``len(x.shape) - 1``] n(int): top N [default=``1``] Returns: ~nnabla.Variable: Element-wise error N-D array. (:math:`D_1 \times ... \times 1 \times ... \times D_N`) """ if axis is None: axis = len(x.shape) - 1 return F.TopNError(ctx, axis, n)(x, target, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
@function_api def binary_error(ctx, x, target, n_outputs=-1, outputs=None): r""" Elementwise binary error. .. math:: y_i = \left \{ \begin{array}{l} 0 ((x^{(0)} \geq 0.5) = (x^{(1)} \geq 0.5)) \\ 1 ((x^{(0)} \geq 0.5) \neq (x^{(1)} \geq 0.5)) \end{array} \right. Args: x(~nnabla.Variable): Probabilities N-D array. \f$-\infty\f$ to \f$\infty\f$. target(~nnabla.Variable): Labels N-D array. Usually set as 0 or 1, but, it allows probability (0 to 1) as inputs. Returns: ~nnabla.Variable: Element-wise errors N-D array. """ return F.BinaryError(ctx)(x, target, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs) @function_api def confusion_matrix(ctx, x, target, axis=None, n_outputs=-1, outputs=None): r""" Confusion matrix. The return value is already summed over samples. Args: x(~nnabla.Variable): Probabilities N-D array. (\f$D_1 \times ... \times D_i \times ... \times D_N\f$) target(~nnabla.Variable): Labels N-D array. (\f$D_1 \times ... \times 1 \times ... \times D_N\f$) axis(int): Axis on which the confusion matrix is calculated. [default=``len(x.shape) - 1``] Returns: ~nnabla.Variable: Confusion matrix 2-D array. Col index is estimated class. Row index is label class. """ if axis is None: axis = len(x.shape) - 1 return F.ConfusionMatrix(ctx, axis)(x, target, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def vat_noise(ctx, x, w, base_axis=1, eps=1.0, n_outputs=-1, outputs=None): r""" Noise for virtual adversarial training. This layer is a special layer for GUI network designing, specialized for getting the noise of virtual adversarial training. In the backward process, the weight parameter will be replaced with the gradient. Forward .. math:: y_i = \frac{\epsilon x_i}{\sqrt{\sum_k x_k^2 + c}} Backward .. math:: \delta x_i = 0 .. math:: w_i = \epsilon \delta y_i Note: This layer is a special layer for GUI network designing. References: * `Miyato et.al, Distributional Smoothing with Virtual Adversarial Training. <https://arxiv.org/abs/1507.00677>`_ Args: x(~nnabla.Variable): N-D array of noise input. Noise is standard Gaussian noise initially, but the next step, fed back gradient variable. w(~nnabla.Variable): N-D array for keep gradient values. base_axis(int): Dimensions up to base_axis is treated as sample dimension. [default=``1``] eps(float): Noise norm (l2) factor. [default=``1.0``] Returns: ~nnabla.Variable: N-D array """ return F.VATNoise(ctx, base_axis, eps)(x, w, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def sink(ctx, *x, **kw): r""" Creates a dummy variable used to call forward or backward function of multiple variables at one place. This takes any numbers of input variables with any shape, and creates a single 0-shape outputs. The forward pass does nothing. The backward pass set ones to the input grads if one_input_grad is set as true. Note: ``sink`` can only be called at the very end of the graph, and ``grad`` of input variables are cleared when ``y.backward(clear_buffer=True)`` is called. Args: *x(~nnabla.Variable): Any number of inputs with any shape. [variadic] one_input_grad(bool): Set grads of inputs as one during backward. It is useful to set false if you want to set external gradients to the input variables. [default=``True``] Returns: ~nnabla.Variable: Dummy variable. """ assert len(x) >= 1, "sink must take more than 1 inputs" n_outputs = kw.pop('n_outputs', -1) outputs = kw.pop('outputs', None) one_input_grad = kw.pop('one_input_grad', True) return F.Sink(ctx, one_input_grad)(*x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)
[docs]@function_api def nms_detection2d(ctx, x, thresh=None, nms=None, nms_per_class=None, n_outputs=-1, outputs=None): r""" Non-Maximum Suppression (NMS) to 2D Object detector output. The input is a 3-dimensional tensor with shape of ``(B, N, 5 + C)`` where ``B`` denotes batch size, ``N`` denotes the number of detection box candidates, and ``C`` denotes the number of classes of object detection. ``5 + C`` consists of the box coordinates ``x, y, w, h`` in normalized coordinates (size of each x and y are 1.0), objectness (learned to predict IoU value to ground truth box), and the class probabilities of ``C`` classes. It outputs a tensor with the same dimensions as the input, where all values are copied from the input to the output, except the class probabilities are multiplied by objectness, and possibly suppressed to 0 by NMS. During NMS, all of combination of pairs of bounding boxes is compared. For each pair, the bounding box with a lower detection score (described below) is suppressed if the overlap ratio (the IoU) is greater than the value of ``nms``. There are two suppression modes for NMS. 1. Suppress by class probability (``nms_per_class`` is ``True``): For each bounding box, the detection score is calculated by ``objectness * probability[class_id]`` for each class. The suppression is done for each class independently. 2. Suppress by objectness (``nms_per_class`` is ``False``): The suppression is done for each bounding box using ``objectness`` as a detection score. All class probabilities becomes 0 for every suppressed boxes. References: * `Joseph Redmon, Ali Farhadi, YOLO9000: Better, Faster, Stronger. <https://arxiv.org/abs/1612.08242>`_ Args: x(~nnabla.Variable): A 3-dimensional array. thresh(float): Detection score threshold. [default=``0.5``] nms(float): IoU threshold for Non-maximum suppression (NMS). [default=``0.45``] nms_per_class(bool): If true, NMS is applied for each class. [default=``True``] Returns: ~nnabla.Variable: A 3-dim array with the same dimensions with the input. """ if thresh is None: thresh = 0.5 if nms is None: nms = 0.45 if nms_per_class is None: nms_per_class = True return F.NmsDetection2d(ctx, thresh, nms, nms_per_class)(x, n_outputs=n_outputs, auto_forward=get_auto_forward(), outputs=outputs)