NeuralNetwork.proto

// Copyright (c) 2017, Apple Inc. All rights reserved.
//
// Use of this source code is governed by a BSD-3-clause license that can be
// found in LICENSE.txt or at https://opensource.org/licenses/BSD-3-Clause

/**
 * A neural network is defined through a collection of layers
 * and represents a directed acyclic graph (DAG).
 * Each layer has a name, a layer type,
 * a list of input names, a list of output names,
 * and a collection of parameters specific to the layer type.
 *
 * The graph structure and connectivity of the neural network
 * is inferred from the input and output names.
 * A neural network starts with the layer
 * whose input name is equal to the value specified in
 * ``Model.description.input.name``,
 * and ends with the layer
 * whose output name is equal to the value specified in
 * ``Model.description.output.name``.
 * Layers must have unique input and output names,
 * and a layer may not have input or output names that
 * refer to layers that are not yet defined.
 *
 * CoreML supports sequential data that can be 1- or 3-dimensional.
 * 3-dimensional data typically represents an image feature map,
 * whose shape is denoted by ``[C, H, W]``,
 * which corresponds to the channel, height, and width, respectively.
 * 1-dimensional data is a set of features
 * whose shape is denoted by ``[C]``,
 * and is equivalent to 3-dimensional data
 * with the shape ``[C, 1, 1]``.
 *
 * For the purposes of this specification,
 * batch dimension is ignored.
 * Thus, a sequence of 3-dimensional data
 * is to be understood as a 4-dimensional array,
 * whose shape is denoted by ``[Seq_length, C, H, W]``,
 * and a sequence of 1-dimensional data
 * is to be understood as a 2-dimensional array,
 * whose shape is denoted by ``[Seq_length, C]``,
 * which is equivalent to a 4-dimensional array
 * with the shape ``[Seq_length, C, 1, 1]``. This axes order is important to
 * remember while setting parameters for layers such as "reshape" and "permute".
 *
 *
 * At runtime, all data blobs are internally represented
 * as 5-dimensional blobs
 * with the shape ``[Seq_length, Batch, C, H, W]``.
 *
 * A layer may process input data differently if operating over a sequence;
 * details of this behavior is documented in the layer's message.
 * Otherwise, sequential data is processed like a batch ---
 * that is, the sequence of inputs are processed independently and in parallel.
 *
 * The network input shape specified by ``Model.description.input.type``
 * must be compatible with the expected input shape
 * of the network input layer, i.e. the last dimension is the fastest moving one.
 *
 * All data blobs, as well as weight parameters,
 * are stored using row-major ordering, i.e. the last dimension is the fastest moving one.
 */

syntax = "proto3";
option optimize_for = LITE_RUNTIME;

import public "DataStructures.proto";

package CoreML.Specification;

/**
 A neural network.
 */
message NeuralNetwork {
    repeated NeuralNetworkLayer layers = 1;
    repeated NeuralNetworkPreprocessing preprocessing = 2;
}

/// Preprocessing
/// -------------

/**
 * A neural network preprocessor that
 * performs a scalar multiplication of an image
 * followed by addition of scalar biases to the channels.
 *
 * Input: X
 *    An image in BGR or RGB format with shape ``[3, H, W]``
 *    or in grayscale format with shape ``[1, H, W]``.
 * Output: Y
 *    An image with format and shape corresponding to the input.
 *
 * If the input image is in BGR format:
 *
 * .. code::
 *
 *     Y[0, :, :] = channelScale * X[0, :, :] + blueBias
 *     Y[1, :, :] = channelScale * X[1, :, :] + greenBias
 *     Y[2, :, :] = channelScale * X[2, :, :] + redBias
 *
 * If the input image is in RGB format:
 *
 * .. code::
 *
 *     Y[0, :, :] = channelScale * X[0, :, :] + redBias
 *     Y[1, :, :] = channelScale * X[1, :, :] + greenBias
 *     Y[2, :, :] = channelScale * X[2, :, :] + blueBias
 *
 * If the input image is in grayscale format:
 *
 * .. code::
 *
 *     Y[0, :, :] = channelScale * X[0, :, :] + grayBias
 */
message NeuralNetworkImageScaler {
    float channelScale = 10; ///Scalar to be multiplied.
    float blueBias = 20; ///Scalar blue bias to be added.
    float greenBias = 21; ///Scalar green bias to be added.
    float redBias = 22; ///Scalar red bias to be added.
    float grayBias = 30; ///Scalar bias to be added for grayscale images.
}

/**
 * A neural network preprocessor that
 * subtracts the provided mean image from the input image.
 * The mean image is subtracted from the input named
 * ``NeuralNetworkPreprocessing.featureName``.
 */
message NeuralNetworkMeanImage {
    /**
     * Mean image stored as a flattened array of floats,
     * representing shape [Channel,Height,Width].
     */
    repeated float meanImage = 1;
}

/// Preprocessing parameters for image inputs.
message NeuralNetworkPreprocessing {
    string featureName = 1; /// must be equal to the input name to which the preprocessing is applied
    oneof preprocessor {
      NeuralNetworkImageScaler scaler = 10;
      NeuralNetworkMeanImage meanImage = 11;
    }
}

/// Activation Functions
/// --------------------

/**
 * A rectified linear unit (ReLU) activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \text{max}(0, x)
 */
message ActivationReLU {
}

/**
 * A leaky rectified linear unit (ReLU) activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \begin{cases}
 *             x      & \text{if } x \geq 0 \\
 *             \alpha x & \text{if } x < 0
 *            \end{cases}
 */
message ActivationLeakyReLU {
    float alpha = 1; //negative slope value for leakyReLU
}

/**
 * A hyperbolic tangent activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \dfrac{1 - e^{-2x}}{1 + e^{-2x}}
 */
message ActivationTanh {
}

/**
 * A scaled hyperbolic tangent activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \alpha \tanh(\beta x)
 */
message ActivationScaledTanh {
    float alpha = 1;
    float beta = 2;
}

/**
 * A sigmoid activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \dfrac{1}{1 + e^{-x}}
 */
message ActivationSigmoid {
}

/**
 * A linear activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \alpha x + \beta
 */
message ActivationLinear {
    float alpha = 1;
    float beta = 2;
}

/**
 * A hard sigmoid activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \text{min}(\text{max}(\alpha x + \beta, 0), 1)
 */
message ActivationSigmoidHard {
    float alpha = 1;
    float beta = 2;
}

/**
 * A parameterized rectified linear unit (PReLU) activation function,
 * which takes ``[C]`` or ``[C,H,W]`` as an input and
 * applies different parameters in each channel dimension
 * (shared across the ``H`` and ``W`` components).
 *
 * This function has the following formula:
 *
 * .. math::
 *    f(x_i) = \begin{cases}
 *                 x_i          & \text{if } x_i \geq 0 \\
 *                 \alpha_i x_i & \text{if } x_i < 0
 *             \end{cases} \;,\;i=1,...,C
 */
message ActivationPReLU {
    // parameter of length C or 1.
    // If length is 1, same value is used for all channels
    WeightParams alpha = 1;
}

/**
 * An exponential linear unit (ELU) activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \begin{cases}
 *             x              & \text{if } x \geq 0 \\
 *             \alpha (e^x - 1) & \text{if } x < 0
 *            \end{cases}
 */
message ActivationELU {
    float alpha = 1;
}

/**
 * A thresholded rectified linear unit (ReLU) activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \begin{cases}
 *             x & \text{if } x \geq \alpha \\
 *             0 & \text{if } x < \alpha
 *            \end{cases}
 */
message ActivationThresholdedReLU {
    float alpha = 1;
}

/**
 * A softsign activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \dfrac{x}{1 + |x|}
 */
message ActivationSoftsign {
}

/**
 * A softplus activation function.
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x) = \text{log}(1 + e^x)
 */
message ActivationSoftplus {
}

/**
 * A parametric softplus activation function,
 * which takes ``[C]`` or ``[C,H,W]`` as an input and
 * applies different parameters in each channel dimension
 * (shared across the ``H`` and ``W`` components).
 *
 * This function has the following formula:
 *
 * .. math::
 *     f(x_i) = \alpha_i \text{log}(1 + e^{\beta_i x_i}) \;,\;i=1,...,C
 */
message ActivationParametricSoftplus {
    // If length is 1, same value is used for all channels
    WeightParams alpha = 1; //parameter of length C or 1
    WeightParams beta = 2;  //parameter of length C or 1
}

message ActivationParams {
    oneof NonlinearityType {
        ActivationLinear linear = 5;

        ActivationReLU ReLU = 10;
        ActivationLeakyReLU leakyReLU = 15;
        ActivationThresholdedReLU thresholdedReLU = 20;
        ActivationPReLU PReLU = 25;

        ActivationTanh tanh = 30;
        ActivationScaledTanh scaledTanh = 31;

        ActivationSigmoid sigmoid = 40;
        ActivationSigmoidHard sigmoidHard = 41;

        ActivationELU ELU = 50;

        ActivationSoftsign softsign = 60;
        ActivationSoftplus softplus = 70;
        ActivationParametricSoftplus parametricSoftplus = 71;
    }
}

/**
 * A single neural network layer.
 */
message NeuralNetworkLayer {
    string name = 1;  //descriptive name of the layer
    repeated string input = 2;
    repeated string output = 3;

    oneof layer {
        // start at 100 here
        ConvolutionLayerParams convolution = 100;

        PoolingLayerParams pooling = 120;

        ActivationParams activation = 130;

        InnerProductLayerParams innerProduct = 140;
        EmbeddingLayerParams embedding = 150;

        //normalization related layers
        BatchnormLayerParams batchnorm = 160;
        MeanVarianceNormalizeLayerParams mvn = 165;
        L2NormalizeLayerParams l2normalize = 170;
        SoftmaxLayerParams softmax = 175;
        LRNLayerParams lrn = 180;

        CropLayerParams crop = 190;
        PaddingLayerParams padding = 200;
        UpsampleLayerParams upsample = 210;

        UnaryFunctionLayerParams unary = 220;

        //elementwise operations
        AddLayerParams add = 230;
        MultiplyLayerParams multiply = 231;

        AverageLayerParams average = 240;
        ScaleLayerParams scale = 245;

        BiasLayerParams bias = 250;
        MaxLayerParams max = 260;
        MinLayerParams min = 261;

        DotProductLayerParams dot = 270;
        ReduceLayerParams reduce = 280;
        LoadConstantLayerParams loadConstant = 290;

        //data reorganization
        ReshapeLayerParams reshape = 300;
        FlattenLayerParams flatten = 301;
        PermuteLayerParams permute = 310;
        ConcatLayerParams concat = 320;
        SplitLayerParams split = 330;
        SequenceRepeatLayerParams sequenceRepeat = 340;

        ReorganizeDataLayerParams reorganizeData = 345;
        SliceLayerParams slice = 350;

        //Recurrent Layers
        SimpleRecurrentLayerParams simpleRecurrent = 400;
        GRULayerParams gru = 410;
        UniDirectionalLSTMLayerParams uniDirectionalLSTM = 420;
        BiDirectionalLSTMLayerParams biDirectionalLSTM = 430;

        // Custom (user-implemented) Layer
        CustomLayerParams custom = 500;
    }
}

/// Border Amounts
/// --------------

/**
 * Specifies the amount of spatial border to be either padded or cropped.
 *
 * For padding:
 *
 * .. code::
 *
 *     H_out = borderAmounts[0].startEdgeSize + H_in + borderAmounts[0].endEdgeSize
 *     W_out = borderAmounts[1].startEdgeSize + W_in + borderAmounts[1].endEdgeSize
 *
 *     topPaddingAmount == Height startEdgeSize
 *     bottomPaddingAmount == Height endEdgeSize
 *     leftPaddingAmount == Width startEdgeSize
 *     rightPaddingAmount == Width endEdgeSize
 *
 * For cropping:
 *
 * .. code::
 *
 *     H_out = (-borderAmounts[0].startEdgeSize) + H_in + (-borderAmounts[0].endEdgeSize)
 *     W_out = (-borderAmounts[1].startEdgeSize) + W_in + (-borderAmounts[1].endEdgeSize)
 *
 *     topCropAmount == Height startEdgeSize
 *     bottomCropAmount == Height endEdgeSize
 *     leftCropAmount == Width startEdgeSize
 *     rightCropAmount == Width endEdgeSize
 */
message BorderAmounts {
    message EdgeSizes {
        /**
         * The amount to be padded or cropped from the beginning.
         */
        uint64 startEdgeSize = 1;

        /**
         * The amount to be padded or cropped from the end.
         */
        uint64 endEdgeSize = 2;
    }

    /**
     * The border amounts.
     * This must be length 2 in the order ``[H, W]``.
     */
    repeated EdgeSizes borderAmounts = 10;
}

/**
 * Specifies the type of padding to be used with Convolution/Deconvolution and Pooling layers.
 * After padding, input spatial shape: ``[H_in, W_in]``, gets modified to the
 * output spatial shape ``[H_out, W_out]``.
 *
 * .. code::
 *
 *      topPaddingAmount == Height startEdgeSize == borderAmounts[0].startEdgeSize
 *      bottomPaddingAmount == Height endEdgeSize == borderAmounts[0].endEdgeSize
 *      leftPaddingAmount == Width startEdgeSize == borderAmounts[1].startEdgeSize
 *      rightPaddingAmount == Width endEdgeSize == borderAmounts[1].endEdgeSize
 *
 * With Convolution or Pooling:
 *
 * .. code::
 *
 *    H_out = int_division_round_down((H_in + topPaddingAmount + bottomPaddingAmount - KernelSize[0]),stride[0]) + 1
 *
 * which is same as:
 *
 * .. code::
 *
 *    H_out = int_division_round_up((H_in + topPaddingAmount + bottomPaddingAmount - KernelSize[0] + 1),stride[0])
 *
 * With Deconvolution:
 *
 * .. code::
 *
 *    H_out = (H_in-1) * stride[0] + kernelSize[0] - (topPaddingAmount + bottomPaddingAmount)
 *
 *
 * The equivalent expressions hold true for ``W_out`` as well.
 *
 *
 * By default, the values of ``paddingAmounts`` are set to ``0``,
 * which results in a "true" valid padding.
 * If non-zero values are provided for ``paddingAmounts``,
 * "valid" convolution/pooling is performed within the spatially expanded input.
 *
 */
message ValidPadding {
    BorderAmounts paddingAmounts = 1;
}

/**
 * Specifies the type of padding to be used with Convolution/Deconvolution and pooling layers.
 * After padding, input spatial shape: ``[H_in, W_in]``, gets modified to the
 * output spatial shape ``[H_out, W_out]``.
 * With Convolution or pooling:
 *
 * .. code::
 *
 *      H_out = int_division_round_up(H_in,stride[0])
 *      W_out = int_division_round_up(W_in,stride[1])
 *
 * This is achieved by using the following padding amounts:
 *
 * .. code::
 *
 *     totalPaddingHeight = max(0,(H_out-1) * stride[0] + KernelSize[0] - Hin)
 *     totalPaddingWidth = max(0,(W_out-1) * stride[1] + KernelSize[1] - Win)
 *
 * There are two modes of asymmetry:
 * ``BOTTOM_RIGHT_HEAVY``, and ``TOP_LEFT_HEAVY``.
 *
 * If the mode is ``BOTTOM_RIGHT_HEAVY``:
 *
 * .. code::
 *
 *     topPaddingAmount = floor(totalPaddingHeight / 2)
 *     bottomPaddingAmount = totalPaddingHeight - topPaddingAmount
 *     leftPaddingAmount = floor(totalPaddingWidth / 2)
 *     rightPaddingAmount = totalPaddingWidth - leftPaddingAmount
 *
 * If the mode is ``TOP_LEFT_HEAVY``:
 *
 * .. code::
 *
 *     bottomPaddingAmount = floor(totalPaddingHeight / 2)
 *     topPaddingAmount = totalPaddingHeight - bottomPaddingAmount
 *     rightPaddingAmount = floor(totalPaddingWidth / 2)
 *     leftPaddingAmount = totalPaddingWidth - rightPaddingAmount
 *
 *
 * With Deconvolution:
 *
 * .. code::
 *
 *    H_out = H_in * stride[0]
 *    W_out = W_in * stride[1]
 */
message SamePadding {
    enum SamePaddingMode {
        BOTTOM_RIGHT_HEAVY = 0;
        TOP_LEFT_HEAVY = 1;
    }
    SamePaddingMode asymmetryMode = 1;
}

/**
 * Weights for layer parameters.
 * Weights are stored as repeated floating point numbers
 * using row-major ordering
 * and can represent 1-, 2-, 3-, or 4-dimensional data.
 */
message WeightParams {
    /**
     * Values specified in single / float / FP32 precision.
     */
    repeated float floatValue = 1;

    /**
     * Values in 16-bit half precision floating point.
     */
    bytes float16Value = 2;

    /**
     * Raw value specification for smaller types. Currently only supported by custom layer implementations.
     */
    bytes rawValue  = 30;

}

/// Layers
/// ------

/**
 * A layer that performs spatial convolution or deconvolution.
 *
 * .. code::
 *
 *      y = ConvolutionLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *  A blob with shape ``[inputChannels,inputHeight,inputWidth]`` or ``[C_in, H_in, W_in]``.
 *
 * Output
 *  A blob with shape ``[outputChannels,outputHeight,outputWidth]`` or  ``[C_out, H_out, W_out]``.
 *
 *
 * If ``dilationFactor`` is not 1, effective kernel size is
 * modified as follows:
 *
 * .. code::
 *
 *      KernelSize[0] <-- (kernelSize[0]-1) * dilationFactor[0] + 1
 *      KernelSize[1] <-- (kernelSize[1]-1) * dilationFactor[1] + 1
 *
 * Type of padding can be ``valid`` or ``same``. Output spatial dimensions depend on the
 * the type of padding. For details, refer to the descriptions of the messages "ValidPadding"
 * and "SamePadding". Padded values are all zeros.
 *
 * For Deconvolution, ``ConvolutionPaddingType`` (``valid`` or ``same``) is ignored when ``outputShape`` is set.
 *
 *
 */
message ConvolutionLayerParams {
    /**
     * The number of kernels.
     * Same as ``C_out`` used in the layer description.
     */
    uint64 outputChannels = 1;

    /**
     * Channel dimension of the kernels.
     * Must be equal to ``inputChannels / nGroups``, if isDeconvolution == False
     * Must be equal to ``inputChannels``, if isDeconvolution == True
     */
    uint64 kernelChannels = 2;

    /**
     * Group convolution, i.e. weight reuse along channel axis.
     * Input and kernels are divided into g groups
     * and convolution / deconvoltuion is applied within the groups independently.
     * If not set or 0, it is set to the default value 1.
     */
    uint64 nGroups = 10;

    /**
     * Must be length 2 in the order ``[H, W]``.
     * If not set, default value ``[3, 3]`` is used.
     */
    repeated uint64 kernelSize = 20;

    /**
     * Must be length 2 in the order ``[H, W]``.
     * If not set, default value ``[1, 1]`` is used.
     */
    repeated uint64 stride = 30;

    /**
     * Must be length 2 in order ``[H, W]``.
     * If not set, default value ``[1, 1]`` is used.
     * It is ignored if ``isDeconvolution == true``.
     */
    repeated uint64 dilationFactor = 40;

    /**
     * The type of padding.
     */
    oneof ConvolutionPaddingType {
        ValidPadding valid = 50;
        SamePadding same = 51;
    }

    /**
     * Flag to specify whether it is a deconvolution layer.
     */
    bool isDeconvolution = 60;

    /**
     * Flag to specify whether a bias is to be added or not.
     */
    bool hasBias = 70;

    /**
     * Weights associated with this layer.
     * If convolution (``isDeconvolution == false``), weights have the shape
     * ``[outputChannels, kernelChannels, kernelHeight, kernelWidth]``, where kernelChannels == inputChannels / nGroups
     * If deconvolution (``isDeconvolution == true``) weights have the shape
     * ``[kernelChannels, outputChannels / nGroups, kernelHeight, kernelWidth]``, where kernelChannels == inputChannels
     */
    WeightParams weights = 90;
    WeightParams bias = 91; /// Must be of size [outputChannels].

    /**
     * The output shape, which has length 2 ``[H_out, W_out]``.
     * This is used only for deconvolution (``isDeconvolution == true``).
     * If not set, the deconvolution output shape is calculated
     * based on ``ConvolutionPaddingType``.
     */
    repeated uint64 outputShape = 100;
}

/**
 * A layer that performs a matrix vector product.
 * This is equivalent to a fully-connected, or dense layer.
 *
 * .. code::
 *
 *      y = InnerProductLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *  A blob with shape ``[C_in]`` or ``[C_in, 1, 1]``, where ``C_in`` is equal to ``inputChannels``.
 *
 * Output
 *  A blob with shape ``[C_out]``, where ``C_out`` is equal to ``outputChannels``.
 */
message InnerProductLayerParams {
    uint64 inputChannels = 1; /// Input size: C_in.
    uint64 outputChannels = 2; /// Output size: C_out.

    bool hasBias = 10; /// Whether a bias is added or not.

    WeightParams weights = 20; /// Weight matrix [C_out, C_in].
    WeightParams bias = 21; /// Bias vector [C_out].
}

/**
 * A layer that performs a matrix lookup and optionally adds a bias.
 *
 * .. code::
 *
 *      y = EmbeddingLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A sequence of integers with shape ``[1]`` or ``[1, 1, 1]``, (equivalent to ``[Seq_length, 1, 1, 1]``).
 *     Input values must be in the range ``[0, inputDim - 1]``.
 *
 * Output
 *     A sequence of 1-dimensional features of size ``outputChannels``
 *     (equivalent to ``[Seq_length, outputChannels, 1, 1]``).
 */
message EmbeddingLayerParams {
    uint64 inputDim = 1; /// Size of the input dictionary.
    uint64 outputChannels = 2; /// Size of the output vectors.

    bool hasBias = 10; /// Whether a bias is added or not.

    WeightParams weights = 20; /// 2-D weights of dimensions [outputChannels, inputDim].
    WeightParams bias = 21; /// Bias of size [outputChannels].
}

/**
 * A layer that performs batch normalization,
 * which is performed along the channel axis,
 * and repeated along the other axes, if present.
 *
 * .. code::
 *
 *      y = BatchnormLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * This operation is described by the following formula:
 *
 * .. math::
 *     y_i = \gamma_i \dfrac{ (x_i - \mu_i)}{\sqrt{\sigma_i^2 + \epsilon}} + \beta_i \;,\;i=1,....,C
 *
 * Input
 *     A blob with shape ``[C]`` or ``[C, H, W]``.
 *
 * Output
 *     A blob with the same shape as the input.
 */
message BatchnormLayerParams {
    uint64 channels = 1; /// Size of the channel dimension in the input.

    /**
     * If ``computeMeanVar == true``,
     * the mean and variance are calculated from either
     * the single input instance, if ``instanceNormalization == true``,
     * or the whole batch, if ``instanceNormalization = false``.
     * and the values provided in parameters "mean" and "variance" are ignored.
     */
    bool computeMeanVar = 5;
    bool instanceNormalization = 6;

    /**
     * A small constant to avoid division by 0 while normalizing by variance.
     * Defaults to ``1e-5`` if not set or set to ``0``.
     */
    float epsilon = 10;

    WeightParams gamma=15; /// Parameter of length [channels]
    WeightParams beta=16; /// Parameter of length [channels]
    WeightParams mean=17; /// Parameter of length [channels]
    WeightParams variance=18; /// Parameter of length [channels]
}

/**
 * A spatial pooling layer.
 *
 * .. code::
 *
 *      y = PoolingLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C, H_in, W_in]``.
 * Output
 *     A blob with shape ``[C, H_out, W_out]``.
 *
 * Padding options are similar to ``ConvolutionLayerParams``
 * with the additional option of ``ValidCompletePadding`` (``includeLastPixel``),
 * which ensures that the last application of the kernel
 * always includes the last pixel of the input image, if there is padding.
 *
 * .. code::
 *
 *     H_out = int_division_round_up((H_in + 2 * paddingAmounts[0] - kernelSize[0]),Stride[0]) + 1)
 *     if (paddingAmounts[0] > 0 or paddingAmounts[1] > 0)
 *          if ((H_out - 1) * Stride >= H_in + paddingAmounts[0]) {
 *              H_out = H_out - 1
 *          }
 *     }
 *
 * The equivalent expressions hold true for ``W_out`` as well.
 * Only symmetric padding is supported with this option.
 */
message PoolingLayerParams {
    enum PoolingType{
        MAX = 0;
        AVERAGE = 1;
        L2 = 2;
    }
    PoolingType type = 1; /// Type of pooling operation.

    /**
     * Must be length 2 in the order ``[H, W]``.
     * If not set, default value ``[3, 3]`` is used.
     */
    repeated uint64 kernelSize = 10;

    /**
     * Must be length 2 in the order ``[H, W]``.
     * If not set, default value ``[1, 1]`` is used.
     */
    repeated uint64 stride = 20;

    message ValidCompletePadding {
        /**
         * Must be length 2 in order ``[H, W]``.
         * If not set, value ``[0, 0]`` is used.
         */
        repeated uint64 paddingAmounts = 10;
    }

    oneof PoolingPaddingType {
        ValidPadding valid = 30;
        SamePadding same = 31;
        ValidCompletePadding includeLastPixel = 32;
    }

    /**
     * If true, padded values are excluded from the count (denominator)
     * when computing average pooling.
     */
    bool avgPoolExcludePadding = 50;

    /**
     * If true, global pooling is performed.
     * Kernel size is inferred from the input data spatial dimensions.
     */
    bool globalPooling = 60;
}

/**
 * A layer that performs padding along spatial dimensions.
 *
 * .. code::
 *
 *      y = PaddingLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C, H_in, W_in]``.
 *
 * Output
 *     A blob with shape ``[C, H_out, W_out]``.
 *
 * Output dimensions are calculated as follows:
 *
 * .. code::
 *
 *     H_out = H_in + topPaddingAmount + bottomPaddingAmount
 *     W_out = W_in + leftPaddingAmount + rightPaddingAmount
 *
 *     topPaddingAmount == Height startEdgeSize == borderAmounts[0].startEdgeSize
 *     bottomPaddingAmount == Height endEdgeSize == borderAmounts[0].endEdgeSize
 *     leftPaddingAmount == Width startEdgeSize == borderAmounts[1].startEdgeSize
 *     rightPaddingAmount == Width endEdgeSize == borderAmounts[1].endEdgeSize
 *
 * There are three types of padding:
 *
 * - ``PaddingConstant``, which fills a constant value at the border.
 * - ``PaddingReflection``, which reflects the values at the border.
 * - ``PaddingReplication``, which replicates the values at the border.
 *
 * Given the following input:
 *
 * .. code::
 *
 *     [1, 3, 4]  :  1   2   3   4
 *                   5   6   7   8
 *                   9   10  11  12
 *
 * Here is the output of applying the padding
 * ``(top=2, left=2, bottom=0, right=0)``
 * with each of the supported types:
 *
 * - ``PaddingConstant`` (``value = 0``):
 *   .. code::
 *
 *       [1, 5, 6]  :  0   0   0  0   0   0
 *                     0   0   0  0   0   0
 *                     0   0   1  2   3   4
 *                     0   0   5  6   7   8
 *                     0   0   9  10  11  12
 *
 * - ``PaddingReflection``:
 *   .. code::
 *
 *       [1, 5, 6]  :  11  10  9  10  11  12
 *                     7   6   5  6   7   8
 *                     3   2   1  2   3   4
 *                     7   6   5  6   7   8
 *                     11  10  9  10  11  12
 *
 * - ``PaddingReplication``:
 *   .. code::
 *
 *       [1, 5, 6]  :  1   1   1  2   3   4
 *                     1   1   1  2   3   4
 *                     1   1   1  2   3   4
 *                     5   5   5  6   7   8
 *                     9   9   9  10  11  12
 */
message PaddingLayerParams {
    /**
     * Fill a constant value in the padded region.
     */
    message PaddingConstant {
        float value = 1;
    }

    /**
     * Reflect the values at the border for padding.
     */
    message PaddingReflection {
    }

    /**
     * Replicate the values at the border for padding.
     */
    message PaddingReplication {
    }

    oneof PaddingType {
        PaddingConstant constant = 1;
        PaddingReflection reflection = 2;
        PaddingReplication replication = 3;
    }

    BorderAmounts paddingAmounts = 10; /// Amounts to be padded to the input.
}

/**
 * A layer that concatenates along the channel axis (default) or sequence axis.
 *
 * .. code::
 *
 *      y = ConcatLayer(x1,x2,....)
 *
 * Requires more than 1 input and produces 1 output.
 *
 * The input and output formats are dependent on ``sequenceConcat``.
 *
 * If ``sequenceConcat == true``:
 *
 * Input
 *     Sequences of length ``Seq_i`` of blobs with shape ``[C, H, W]``.
 * Output
 *     A Sequence of length ``summation(Seq_i)`` of blobs with shape ``[C, H, W]``.
 *
 * If ``sequenceConcat == false``:
 *
 * Input
 *     A blob with shape ``[C_i, H, W]``, where ``i = 1, 2, ...``.
 * Output
 *     A blob with shape ``[summation(C_i), H, W]``.
 */
message ConcatLayerParams {
    /**
     * If true, concatenate along the sequence axis instead of the channel axis.
     */
    bool sequenceConcat = 100;
}

/**
 * A layer that performs local response normalization (LRN).
 *
 * .. code::
 *
 *      y = LRNLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C, H, W]``
 * Output
 *     A blob with the same shape as the input.
 *
 * This layer is described by the following formula:
 *
 * .. math::
 *     x_i \leftarrow  \dfrac{x_i}{\left ( k + \dfrac{\alpha}{C} \sum_j x_j^2 \right )^\beta}
 *
 * where the summation is done over a ``(localSize, 1, 1)`` neighborhood ---
 * that is, over a window "across" channels in 1x1 spatial neighborhoods.
 */
message LRNLayerParams {
    float alpha = 1;
    float beta = 2;
    uint64 localSize = 3; /// Number of channels in the normalization window.
    float k = 4; /// Defaults to 1 if not set or 0. Must be strictly positive.
}

/**
 * Softmax Normalization Layer
 *
 * A layer that performs softmax normalization.
 * Normalization is done along the channel axis.
 *
 * .. code::
 *
 *      y = SoftmaxLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C]`` or ``[C, H, W]``.
 * Output
 *     A blob with the same shape as the input.
 *
 * This layer is described by the following formula:
 *
 * .. math::
 *     x_i \leftarrow \dfrac{e^{x_i}}{\sum_i{e^{x_i}}}
 */
message SoftmaxLayerParams {
}

/**
 * A layer that uniformly splits across the channel dimension
 * to produce a specified number of outputs.
 *
 * .. code::
 *
 *      (y1,y2,...yN) = SplitLayer(x), where N = nOutputs
 *
 * Requires 1 input and produces multiple outputs.
 *
 * Input
 *     A blob with shape ``[C]`` or ``[C, H, W]``
 * Output
 *     ``nOutputs`` blobs with shapes
 *     ``[C/nOutputs]`` or ``[C/nOutputs, H, W]``
 */
message SplitLayerParams {
    uint64 nOutputs=1; /// The number of outputs.
}

/**
 * A layer that performs elementwise addition.
 *
 * .. code::
 *
 *      y = AddLayer(x1,x2,...)
 *
 * Requires 1 or more than 1 input and produces 1 output.
 *
 * Input
 *     One or more blobs with broadcastable shapes ``[1]``, ``[C]``, ``[1, H, W]``, or ``[C, H, W]``.
 * Output
 *     A blob with shape equal to the input blob.
 *
 * If only one input is provided, scalar addition is performed:
 *
 * .. math::
 *     y = x + \alpha
 *
 */
message AddLayerParams {
    /**
     * Scalar to be added to the input.
     * Only used if there is a single input.
     */
    float alpha = 1;
}

/**
 * A layer that performs elementwise multiplication.
 *
 * .. code::
 *
 *      y = MultiplyLayer(x1,x2,...)
 *
 * Requires 1 or more than 1 input and produces 1 output.
 *
 * Input
 *     One or more blobs with broadcastable shapes ``[1]``, ``[C]``, ``[1, H, W]``, or ``[C, H, W]``.
 * Output
 *     A blob with shape equal to the first input blob.
 *
 * If only one input is provided, scalar multiplication is performed:
 *
 * .. math::
 *     y = \alpha x
 *
 */
message MultiplyLayerParams {
    /**
     * Scalar to be multiplied with the input.
     * Only used if there is a single input.
     */
    float alpha = 1;
}

/**
 * A layer that applies a unary function.
 *
 * .. code::
 *
 *      y = UnaryFunctionLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C]`` or ``[C, H, W]``.
 * Output
 *     A blob with the same shape as the input.
 *
 * The input is first modified by shifting and scaling:
 *
 * .. math::
 *     x \leftarrow \text{scale} \cdot x + \text{shift}
 */
message UnaryFunctionLayerParams {
    /**
     * A unary operator.
     *
     * The following functions are supported:
     *
     * ``SQRT``
     *     .. math:: f(x) = \sqrt{x}
     *
     * ``RSQRT``
     *     .. math:: f(x) = \dfrac{1}{\sqrt{x + \epsilon}}
     *
     * ``INVERSE``
     *     .. math:: f(x) = \dfrac{1}{x + \epsilon}
     *
     * ``POWER``
     *     .. math:: f(x) = x^\alpha
     *
     * ``EXP``
     *     .. math:: f(x) = e^x
     *
     * ``LOG``
     *     .. math:: f(x) = \log x
     *
     * ``ABS``
     *     .. math:: f(x) = |x|
     *
     * ``THRESHOLD``
     *     .. math:: f(x) = \text{max}(\alpha, x)
     */
    enum Operation{
        SQRT = 0;
        RSQRT = 1;
        INVERSE = 2;
        POWER = 3;
        EXP = 4;
        LOG = 5;
        ABS = 6;
        THRESHOLD = 7;
    }
    Operation type = 1; /// The type of unary function.

    /**
     * A constant used in ``POWER`` and ``THRESHOLD`` functions.
     */
    float alpha = 2;

    /**
     * A small constant to avoid division by 0 while normalizing variance.
     * Defaults to ``1e-6`` if not set or set to ``0``.
     */
    float epsilon = 3;

    /**
     * Input is shifted by this amount
     * before the unary function is applied.
     * Defaults to ``0.0`` if not set.
     */
    float shift = 4;

    /**
     * Input is scaled by this amount
     * before the unary function is applied.
     * Defaults to ``1.0`` if not set or set to ``0``.
     */
    float scale = 5;
}

/**
 * A layer that scales up spatial dimensions.
 * It supports two modes: nearest neighbour (default) and bilinear.
 *
 * .. code::
 *
 *      y = UpsampleLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C, H, W]``.
 * Output
 *     A blob with shape ``[C, scalingFactor[0] * H, scalingFactor[1] * W]``
 */
message UpsampleLayerParams {
    /**
     * Scaling Factor.
     * Must be length 2 in order ``[H, W]``.
     * If not set, default value ``[1, 1]`` is used.
     */
    repeated uint64 scalingFactor = 1;

    enum InterpolationMode {
        NN = 0; /// Nearest Neighbour
        BILINEAR = 1; /// Bilinear
    }

    InterpolationMode mode = 5;

}

/**
 * A layer that performs elementwise addition of a bias,
 * which is broadcasted to match the input shape.
 *
 * .. code::
 *
 *      y = BiasLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C, H, W]``.
 * Output
 *     A blob with the same shape as the input.
 */
message BiasLayerParams {
    /**
     * The shape of the bias.
     * Must be one of the following:
     * ``[1]``, ``[C]``, ``[1, H, W]`` or ``[C, H, W]``.
     */
    repeated uint64 shape = 1;

    /**
     * The bias values.
     * The size must be equal to the product of the ``shape`` dimensions.
     */
    WeightParams bias = 2;
}

/**
 * A layer that performs elmentwise multiplication by a scale factor
 * and optionally adds a bias;
 * both the scale and bias are broadcasted to match the input shape.
 *
 * .. code::
 *
 *      y = ScaleLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C, H, W]``.
 * Output
 *     A blob with the same shape as the input.
 */
message ScaleLayerParams {
    /**
     * The shape of the scale.
     * Must be one of the following:
     * ``[1]``, ``[C]``, ``[1, H, W]`` or ``[C, H, W]``.
     */
    repeated uint64 shapeScale = 1;

    /**
     * The scale values.
     * The size must be equal to the product of the ``shape`` dimensions.
     */
    WeightParams scale = 2; /// Scale values. Size must be equal to the product of dimensions specified in shapeScale.

    bool hasBias = 3; /// If true, a bias is added after scaling.

    /**
     * The shape of the bias.
     * Must be one of the following:
     * ``[1]``, ``[C]``, ``[1, H, W]`` or ``[C, H, W]``.
     */
    repeated uint64 shapeBias = 4;

    /**
     * The bias values.
     * The size must be equal to the product of the ``shape`` dimensions.
     */
    WeightParams bias = 5;
}

/**
 * A layer that loads data as a parameter and provides it as an output.
 *
 * .. code::
 *
 *      y = LoadConstantLayer()
 *
 * Takes no input. Produces 1 output.
 *
 * Input
 *     None
 * Output:
 *     A blob with shape ``[C, H, W]``
 */
message LoadConstantLayerParams {
    /**
     * The shape of the constant to be loaded,
     * which must be``[C, H, W]``.
     */
    repeated uint64 shape = 1;

    /**
     * The data values,
     * of size ``C * H * W``.
     */
    WeightParams data = 2;
}

/**
 * A layer that performs L2 normalization, i.e. divides by the
 * the square root of the sum of squares of all elements of input.
 *
 * .. code::
 *
 *      y = L2NormalizeLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C]`` or ``[C, H, W]``.
 * Output
 *     A blob with the same shape as the input.
 *
 * This layer is described by the following formula:
 *
 * .. math::
 *     x_i \leftarrow \dfrac{x_i}{\sqrt{\sum{x_i^2} + \epsilon}}
 */
message L2NormalizeLayerParams {
    /**
     * A small constant to avoid division by 0 while normalizing variance.
     * Defaults to ``1e-6`` if not set or set to ``0``.
     */
    float epsilon = 1;
}

/// Data Reorganization Layers
/// --------------------------

/**
 * A layer that flattens the input.
 *
 * .. code::
 *
 *      y = FlattenLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C, H, W]``.
 * Output
 *     A blob with shape ``[C * H * W, 1, 1]``
 *
 * There are two flatten orders: ``CHANNEL_FIRST`` and ``CHANNEL_LAST``.
 * ``CHANNEL_FIRST`` does not require data to be rearranged,
 * because row major ordering is used by internal storage.
 * ``CHANNEL_LAST`` requires data to be rearranged.
 */
message FlattenLayerParams {
    enum FlattenOrder {
        CHANNEL_FIRST = 0;
        CHANNEL_LAST = 1;
    }
    FlattenOrder mode = 1;
}

/**
 * A layer that recasts the input into a new shape.
 *
 * .. code::
 *
 *      y = ReshapeLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C, H, W]`` or ``[Seq, C, H, W]``.
 * Output
 *     A blob with shape ``[C_out, H_out, W_out]``
 *     or ``[Seq_out, C_out, H_out, W_out]``.
 *
 * There are two reshape orders: ``CHANNEL_FIRST`` and ``CHANNEL_LAST``.
 * ``CHANNEL_FIRST`` is equivalent to
 * flattening the input to ``[C * H * W, 1, 1]`` in channel first order
 * and then reshaping it to the target shape;
 * no data rearrangement is required.
 * ``CHANNEL_LAST`` is equivalent to
 * flattening the input to ``[H * W * C, 1, 1]`` in channel last order,
 * reshaping it to ``[H_out, W_out, C_out]`` (it is now in "H_out-major"" order),
 * and then permuting it to ``[C_out, H_out, W_out]``;
 * both the flattening and permuting requires the data to be rearranged.
 */
message ReshapeLayerParams {
    /**
     * The shape of the output.
     * Must be of length 3 or 4.
     * If set to 3, ``targetShape`` is interpreted as
     * ``[C_out, H_out, W_out]``, and sequence length of the input is preserved.
     * If set to 4, ``targetShape`` is interpreted as
     * ``[Seq_out, C_out, H_out, W_out]``,
     * where ``Seq_out`` is the new sequence length.
     */
    repeated int64 targetShape = 1;

    enum ReshapeOrder {
        CHANNEL_FIRST = 0;
        CHANNEL_LAST = 1;
    }
    ReshapeOrder mode = 2;
}

/**
 * A layer that rearranges the dimensions and data of an input.
 *
 * .. code::
 *
 *      y = PermuteLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A sequence of 3-dimensional blobs. ``InputShape = [Seq, C, H, W]``.
 * Output
 *     A sequence of a different length of 3-dimensional blobs.
 *     Shape: ``[InputShape[axis[0]], InputShape[axis[1]],
 *     InputShape[axis[2]], InputShape[axis[3]]]``. Hence output is a sequence of length ``InputShape[axis[0]]``.
 *
 * Examples:
 *
 * - If ``axis`` is set to ``[0, 3, 1, 2]``,
 *   then the output has shape ``[W,C,H]``
 *   and has the same sequence length that of the input.
 *
 * - If ``axis`` is set to ``[3, 1, 2, 0]``,
 *   and the input is a sequence of data
 *   with length ``Seq`` and shape ``[C, 1, 1]``,
 *   then the output is a unit sequence of data with shape ``[C, 1, Seq]``.
 *
 * - If ``axis`` is set to ``[0, 3, 2, 1]``,
 *   the output is a reverse of the input: ``[C, H, W] -> [W, H, C]``.
 *
 * - If ``axis`` is not set, or is set to ``[0, 1, 2, 3]``,
 *   the output is the same as the input.
 */
message PermuteLayerParams {
    /**
     * The order in which to permute the dimensions.
     * Must have length 4 and a permutation of ``[0, 1, 2, 3]``.
     */
    repeated uint64 axis = 1;
}

/**
 * A layer that reorganizes data in the input in specific ways.
 *
 * .. code::
 *
 *      y = ReorganizeDataLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C, H, W]``.
 * Output
 *     A blob with shape ``[C_out, H_out, W_out]``.
 *
 * mode == SPACE_TO_DEPTH
 *  ``[C_out, H_out, W_out]`` : ``[C * blockSize * blockSize, H/blockSize, W/blockSize]``.
 *  blockSize must divide H and W.
 *  Data is moved from the spatial dimensions to the channel dimension. Input is spatially divided into
 *  non-overlapping blocks of size blockSize X blockSize and data from each block is moved into the
 *  channel dimension.
 *
 * mode == DEPTH_TO_SPACE
 *  ``[C_out, H_out, W_out]`` : ``[C/(blockSize * blockSize), H * blockSize, W * blockSize]``.
 *  Square of blockSize must divide C.
 *  Reverse of SPACE_TO_DEPTH. Data is moved from the channel dimension to the spatial dimenions.
 *
 */
message ReorganizeDataLayerParams {

    enum ReorganizationType {
        SPACE_TO_DEPTH = 0;
        DEPTH_TO_SPACE = 1;
    }
    ReorganizationType mode = 1;
    uint64 blockSize = 2; /// must be greater than 1
}

/**
 * A layer that slices the input data along a given axis.
 *
 * .. code::
 *
 *      y = SliceLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[Seq, C, H, W]``.
 * Output
 *     A blob with shape ``[Seq_out, C_out, H_out, W_out]``.
 *
 * Sliced section is taken from the interval ``[startIndex, endIndex)``, i.e.
 * startIndex is inclusive while endIndex is exclusive.
 * stride must be positive and represents the step size for slicing.
 * startIndex must be non-negative. Negative indexing is supported for endIndex: -1 denotes N, -2 denotes N-1
 * and so on, where N is the length of the dimension to be sliced.
 *
 */
message SliceLayerParams {

    uint64 startIndex = 1; /// start of the sliced section. Inclusive.
    int64 endIndex = 2; /// end of sliced section. Exclusive.
    uint64 stride = 3; /// The step size. Must be postive.

    enum SliceAxis {
        CHANNEL_AXIS = 0;
        HEIGHT_AXIS = 1;
        WIDTH_AXIS = 2;
    }
    SliceAxis axis = 4;
}

/**
 * A layer that reduces the input using a specified operation.
 *
 * .. code::
 *
 *      y = ReduceLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C, H, W]``.
 * Output
 *     A blob whose shape depends on the value of axis, the dimension(s) along which reduction is performed.
 *     if axis == C   : ``[1, H, W]``
 *     if axis == H   : ``[C, 1, W]``
 *     if axis == W   : ``[C, H, 1]``
 *     if axis == HW  : ``[C, 1, 1]``
 *     if axis == CHW : ``[1, 1, 1]`` [Default]
 */
message ReduceLayerParams {
    /*
     * The following reduction operations are supported
     * and are applied on the specified axis of the input array:
     *
     * ``SUM``
     *     Sum of all elements
     *
     *     .. math:: \sum{x_i}
     *
     * ``AVG``
     *     Sum of all elements divided by the number of elements
     *
     *     .. math:: \dfrac{\sum^n{x_i}}{n}
     *
     * ``PROD``
     *     Product of all elements
     *
     *     .. math:: \prod{x_i}
     *
     * ``LOGSUM``
     *     Sum of the natural logarithm of all elements
     *
     *     .. math:: \sum{\ln{(x_i + \epsilon)}}
     *
     * ``SUMSQUARE``
     *     Sum of squares of all elements
     *
     *     .. math:: \sum{x^2}
     *
     * ``L1``
     *     L1 normalization of all elements
     *
     *     .. math:: ||x||_1 = \sum{|x_i|}
     *
     * ``L2``
     *     L2 normalization of all elements
     *
     *     .. math:: ||x||_2 = \sqrt{\sum{x_i^2}}
     *
     * ``MAX``
     *     Maximum of all elements
     *
     *     .. math:: \text{max}(x_i)
     *
     * ``MIN``
     *     Minumum of all elements
     *
     *     .. math:: \text{min}(x_i)
     *
     * ``ARGMAX``
     *     Argument of the maximum of all elements
     *
     *     .. math:: \text{argmax}(x_i)
     *
     */
    enum ReduceOperation {
        SUM = 0;
        AVG = 1;
        PROD = 2;
        LOGSUM = 3;
        SUMSQUARE = 4;
        L1 = 5;
        L2 = 6;
        MAX = 7;
        MIN = 8;
        ARGMAX = 9; /// only supported with axis = C, H or W.
    }
    ReduceOperation mode = 1; /// Specifies function used to reduce.

    /**
     * Used if mode is ``LOGSUM``.
     * Defaults to ``1e-6`` if not set or is set to ``0``.
     */
    float epsilon = 2;

    enum ReduceAxis {
        CHW = 0;
        HW = 1;
        C = 2;
        H = 3;
        W = 4;
    }

    ReduceAxis axis = 3;

}

/**
 * A layer that crops the spatial dimensions of an input.
 * If two inputs are provided, the shape of the second input is used as the reference shape.
 *
 * .. code::
 *
 *      y = CropLayer(x1) or y = CropLayer(x1,x2)
 *
 * Requires 1 or 2 inputs and produces 1 output.
 *
 * Input
 *     - 1 input case: A blob with shape ``[C, H_in, W_in]``.
 *     - 2 input case: 1st blob with shape ``[C, H_in, W_in]``, 2nd blob with shape ``[C, H_out, W_out]``.
 *
 * Output
 *     A blob with shape ``[C, H_out, W_out]``.
 *
 * If one input is used, output is computed as follows:
 *
 * .. code::
 *
 *      y = x1[:, topCropAmount:H_in - bottomCropAmount, leftCropAmount:W_in - rightCropAmount]
 *
 *      topCropAmount == Height startEdgeSize == borderAmounts[0].startEdgeSize
 *      bottomCropAmount == Height endEdgeSize == borderAmounts[0].endEdgeSize
 *      leftCropAmount == Width startEdgeSize == borderAmounts[1].startEdgeSize
 *      rightCropAmount == Width endEdgeSize == borderAmounts[1].endEdgeSize
 *
 *      H_out = H_in - topCropAmount - bottomCropAmount
 *      W_out = W_in - leftCropAmount - rightCropAmount
 *
 * If two inputs are used, output is computed as follows:
 *
 * .. code::
 *
 *      y = x1[:, offset[0]:offset[0] + H_out, offset[1]:offset[1] + W_out]
 */
message CropLayerParams {
    /**
     * The amounts to be cropped from the input.
     * Used only if a single input is provided.
     */
    BorderAmounts cropAmounts = 1;

    /**
     * The offset amounts.
     * Used only if two inputs are provided.
     * Must be of length 2, in order ``[H, W]``.
     */
    repeated uint64 offset = 5;
}

/**
 * A layer that computes the elementwise average of the inputs.
 *
 * .. code::
 *
 *      y = AverageLayer(x1,x2,...)
 *
 * Requires multiple inputs and produces 1 output.
 *
 * Input
 *     Multiple blobs with broadcastable shapes ``[1]``, ``[C]``, ``[1, H, W]``, or ``[C, H, W]``.
 * Output
 *     A blob with the same shape as each input.
 */
message AverageLayerParams {
}

/**
 * A layer that computes the elementwise maximum over the inputs.
 *
 * .. code::
 *
 *      y = MaxLayer(x1,x2,...)
 *
 * Requires multiple inputs and produces 1 output.
 *
 * Input
 *     Multiple blobs, each with shape ``[C]`` or ``[C, H, W]``.
 * Output
 *     A blob with the same shape as each input.
 */
message MaxLayerParams {
}

/**
 * A layer that computes the elementwise minimum over the inputs.
 *
 * .. code::
 *
 *      y = MinLayer(x1,x2,...)
 *
 * Requires multiple inputs and produces 1 output.
 *
 * Input
 *     Multiple blobs, each with shape ``[C]`` or ``[C, H, W]``.
 * Output
 *     A blob with the same shape as each input.
 */
message MinLayerParams {
}

/**
 * A layer that computes the dot product of two vectors.
 *
 * .. code::
 *
 *      y = DotProductLayer(x1,x2)
 *
 * Requires 2 inputs and produces 1 output.
 *
 * Input
 *     Two blobs with shape ``[C]``.
 * Output
 *     A scalar.
 */
message DotProductLayerParams {
    /**
     * If true, inputs are normalized first,
     * thereby computing the cosine similarity.
     */
    bool cosineSimilarity = 1;
}

/**
 * A layer that performs mean variance normalization.
 *
 * .. code::
 *
 *      y = MeanVarianceNormalizeLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A blob with shape ``[C]`` or ``[C, H, W]``.
 * Output
 *     A blob with the same shape as the input.
 *
 * If ``acrossChannels == true``
 * normalization is performed on flattened input.
 *
 * If ``acrossChannels == false``
 * normalization is performed within a channel,
 * across spatial dimensions.
 */
message MeanVarianceNormalizeLayerParams {
    /**
     * If true, mean and variance are computed across channels.
     */
    bool acrossChannels = 1;

    /**
     * If false, only mean is subtracted.
     */
    bool normalizeVariance = 2;

    /**
     * A small constant to avoid division by 0 while normalizing variance.
     * Defaults to ``1e-6`` if not set or set to ``0``.
     */
    float epsilon = 3;
}

/**
 * A layer that repeats a sequence.
 *
 * .. code::
 *
 *      y = SequenceRepeatLayer(x)
 *
 * Requires 1 input and produces 1 output.
 *
 * Input
 *     A sequence of blobs, i.e. shape is either ``[Seq, C]`` or ``[Seq, C, H, W]``.
 * Output
 *     A sequence of length ``nRepetitions * Seq``
 *     with shape corresponding to the input,
 *     i.e. shape is either ``[nRepetitions * Seq, C]`` or ``[nRepetitions * Seq, C, H, W]``.
 */
message SequenceRepeatLayerParams {
    /**
     * Number of repetitions.
     * Defaults to ``1`` if not set or set to ``0``.
     */
    uint64 nRepetitions = 1;
}

/// Recurrent Layers
/// ----------------

/*
 * The following activations are supported with recurrent layers:
 * - Linear
 * - Sigmoid
 * - Tanh
 * - ReLU
 * - Scaled Hyperbolic Tangent: alpha * tanh(beta * x), currently only supported for alpha = 1.7159, beta = 2/3
 * - Hard Sigmoid: min(max(alpha * x + beta, 0), 1), currently only supported for alpha = 0.2, beta = 0.5
 */

/**
 * A simple recurrent layer.
 *
 * .. code::
 *
 *      y_t = SimpleRecurrentLayer(x_t, y_{t-1})
 *
 * Input
 *    A sequence of vectors of size ``inputVectorSize``
 *    with shape ``[Seq, inputVectorSize]``.
 * Output
 *    A vector of size ``outputVectorSize``. It is either the final output or a sequence of outputs at all time steps.
 *
 * - Output Shape: ``[1,outputVectorSize]`` , if ``sequenceOutput == false``
 * - Output Shape: ``[Seq,outputVectorSize]`` , if ``sequenceOutput == true``
 *
 * This layer is described by the following equation:
 *
 * .. math::
 *     \boldsymbol{y_t} = f(\mathrm{clip}(W \boldsymbol{x_t} + \
 *                                        R \boldsymbol{y_{t-1}} + b))
 *
 * - ``W`` is a 2-dimensional weight matrix
 *   (``[outputVectorSize, inputVectorSize]``, row-major)
 * - ``R`` is a 2-dimensional recursion matrix
 *   (``[outputVectorSize, outputVectorSize]``, row-major)
 * - ``b`` is a 1-dimensional bias vector (``[outputVectorSize]``)
 * - ``f()`` is an activation
 * - ``clip()`` is a function that constrains values between ``[-50.0, 50.0]``
 */
message SimpleRecurrentLayerParams {
    uint64 inputVectorSize = 1; /// The size of the input vectors.
    uint64 outputVectorSize = 2; /// The size of the output vectors.

    /**
    * Activations supported are Linear, Sigmoid, Tanh, ReLU, Scaled Tanh (alpha = 1.71, beta = 2/3), Hard sigmoid (alpha = 0.2, beta = 0.5)
    */
    ActivationParams activation = 10; /// The activation function.

    /**
        If false output is just the result after final state update.
        If true, output is a sequence, containing outputs at all time steps.
    */
    bool sequenceOutput = 15;

    bool hasBiasVector = 20; /// If false, no bias is added.

    WeightParams weightMatrix = 30; /// Weight matrix W.
    WeightParams recursionMatrix = 31; /// Recursion Weight matrix R.
    WeightParams biasVector = 32; /// Bias vector b.

    bool reverseInput = 100;
    // If true, then the node processes the input sequence from right to left
}

/**
 * Gated-Recurrent Unit (GRU) Layer
 *
 * .. code::
 *
 *      y_t = GRULayer(x_t, y_{t-1})
 *
 * Input
 *    A sequence of vectors of size ``inputVectorSize``
 *    with shape ``[Seq, inputVectorSize]``.
 * Output
 *    A vector of size ``outputVectorSize``. It is either the final output or a sequence of outputs at all time steps.
 *
 * - Output Shape: ``[1,outputVectorSize]`` , if ``sequenceOutput == false``
 * - Output Shape: ``[Seq,outputVectorSize]`` , if ``sequenceOutput == true``
 *
 * This layer is described by the following equations:
 *
 * Update Gate
 *     .. math::
 *         \boldsymbol{z_t} = \
 *             f(\mathrm{clip}(W_z \boldsymbol{x_t} + \
 *                             R_z \boldsymbol{y_{t-1}} + b_z)
 *
 * Reset Gate
 *     .. math::
 *         \boldsymbol{r_t} = \
 *             f(\mathrm{clip}(W_r \boldsymbol{x_t} + \
 *                             R_r \boldsymbol{y_{t-1}} + b_r))
 *
 * Cell Memory State
 *     .. math::
 *         \boldsymbol{c_t} = \
 *             \boldsymbol{y_{t-1}} \odot \boldsymbol{r_t}
 *
 * Output Gate
 *     .. math::
 *         \boldsymbol{o_t} = \
 *             g(\mathrm{clip}(W_o \boldsymbol{x_t} + \
 *                             R_o \boldsymbol{c_t} + b_o))
 *
 * Output
 *     .. math::
 *         \boldsymbol{y_t} = \
 *             (1 - \boldsymbol{z_t}) \odot \boldsymbol{o_t} + \
 *              \boldsymbol{z_t} \odot \boldsymbol{y_{t-1}}
 *
 * - ``W_z``, ``W_r``, ``W_o`` are 2-dimensional input weight matrices
 *   (``[outputVectorSize, inputVectorSize]``, row-major)
 * - ``R_z``, ``R_r``, ``R_o`` are 2-dimensional recursion matrices
 *   (``[outputVectorSize, outputVectorSize]``, row-major)
 * - ``b_z``, ``b_r``, ``b_o`` are 1-dimensional bias vectors
 *   (``[outputVectorSize]``)
 * - ``f()``, ``g()`` are activations
 * - ``clip()`` is a function that constrains values between ``[-50.0, 50.0]``
 * - ``⊙`` denotes the elementwise product of matrices
 */
message GRULayerParams {
    uint64 inputVectorSize = 1; /// Size of the input vectors.
    uint64 outputVectorSize = 2; /// Size of the output vectors.

    /**
     * 2 element array representing activations [f(), g()] in that order.
     * Typical values used = [sigmoid, tanh].
     * Activations supported are Linear, Sigmoid, Tanh, ReLU, Scaled Tanh (alpha = 1.71, beta = 2/3), Hard sigmoid (alpha = 0.2, beta = 0.5)
     */
    repeated ActivationParams activations = 10;

    /**
     * If false output is just the result after final state update.
     * If true, output is a sequence, containing outputs at all time steps.
     */
    bool sequenceOutput = 15;

    /**
     * If false, no biases (``b_z``, ``b_r``, ``b_o``) are added.
     */
    bool hasBiasVectors = 20;

    WeightParams updateGateWeightMatrix = 30; /// Weight Matrix W_z.
    WeightParams resetGateWeightMatrix = 31; /// Weight Matrix W_r.
    WeightParams outputGateWeightMatrix = 32; /// Weight Matrix W_o.

    WeightParams updateGateRecursionMatrix = 50; /// Recursion Weight Matrix R_z.
    WeightParams resetGateRecursionMatrix = 51; /// Recursion Weight Matrix R_r.
    WeightParams outputGateRecursionMatrix = 52; /// Recursion Weight Matrix R_o.

    WeightParams updateGateBiasVector = 70; /// Bias vector b_z.
    WeightParams resetGateBiasVector = 71; /// Bias vector b_r.
    WeightParams outputGateBiasVector = 72; /// Bias vector b_o.

    /// If true, then the node processes the input sequence from right to left
    bool reverseInput = 100;
}

/**
 * Long short-term memory (LSTM) parameters.
 *
 * This is described by the following equations:
 *
 * Input Gate
 *     .. math::
 *         \boldsymbol{i_t} = \
 *             f(\mathrm{clip}(W_i \boldsymbol{x_t} + \
 *                             R_i \boldsymbol{y_{t-1}} + \
 *                             p_i \odot c_{t-1} + b_i))
 *
 * Forget Gate
 *     .. math::
 *         \boldsymbol{f_t} = \
 *             f(\mathrm{clip}(W_f \boldsymbol{x_t} + \
 *                             R_f \boldsymbol{y_{t-1}} + \
 *                             p_f \odot c_{t-1} + b_f))
 *
 * Block Input
 *     .. math::
 *         \boldsymbol{z_t} = \
 *             g(\mathrm{clip}(W_z \boldsymbol{x_t} + \
 *                             R_z \boldsymbol{y_{t-1}} + b_z))
 *
 * Cell Memory State
 *     .. math::
 *         \boldsymbol{c_t} = \
 *             \boldsymbol{c_{t-1}} \odot \boldsymbol{f_t} + \
 *             \boldsymbol{i_t} \odot \boldsymbol{z_t}
 *
 * Output Gate
 *     .. math::
 *         \boldsymbol{o_t} = \
 *             f(\mathrm{clip}(W_o \boldsymbol{x_t} + \
 *                             R_o \boldsymbol{y_{t-1}} + \
 *                             p_o \odot c_t + b_o))
 *
 * Output
 *     .. math::
 *         \boldsymbol{y_t} = \
 *             h(\boldsymbol{c_t}) \odot \boldsymbol{o_t}
 *
 * - ``W_i``, ``W_f``, ``W_z``, ``W_o`` are 2-dimensional input weight matrices
 *   (``[outputVectorSize, inputVectorSize]``, row-major)
 * - ``R_i``, ``R_f``, ``R_z``, ``R_o`` are 2-dimensional recursion matrices
 *   (``[outputVectorSize, outputVectorSize]``, row-major)
 * - ``b_i``, ``b_f``, ``b_z``, ``b_o`` are 1-dimensional bias vectors
 *   (``[outputVectorSize]``)
 * - ``p_``, ``p_f``, ``p_o`` are 1-dimensional peephole vectors
 *   (``[outputVectorSize]``)
 * - ``f()``, ``g()``, ``h()`` are activations
 * - ``clip()`` is a function that constrains values between ``[-50.0, 50.0]``
 * - ``⊙`` denotes the elementwise product of matrices
 */
message LSTMParams {
    /**
     * If true, output is a sequence, containing outputs at all time steps.
     * If false, output is just the result after final state update.
     */
    bool sequenceOutput = 10;

    /**
     * If false, no biases (``b_i``, ``b_f``, ``b_z``, ``b_o``) are added.
     */
    bool hasBiasVectors = 20;

    /**
     * If true, a vector of ``1`` values is added to ``b_f``.
     */
    bool forgetBias = 30;

    /**
     * If true, peephole vectors are included.
     */
    bool hasPeepholeVectors = 40;

    /**
     * If the coupled Input and Forget flag is on, the behaviour of
     * ``c_t`` is changed to the following (i.e. forget gate is not used):
     *
     * .. math::
     *     \boldsymbol{c_t} = \
     *         \boldsymbol{c_{t-1}} \odot (1 - \boldsymbol{i_t}) + \
     *         \boldsymbol{i_t} \odot \boldsymbol{z_t}
     *
     */
    bool coupledInputAndForgetGate = 50;

    /**
     * Places a limit on the maximum and minimum values of ``c_t``.
     * c_t = min(c_t, cellClipThreshold)
     * c_t = max(c_t, -cellClipThreshold)
     * If 0, it is set to its default value = 50.0.
     */
    float cellClipThreshold = 60;
}

/**
 * Weights for long short-term memory (LSTM) layers
 */
message LSTMWeightParams {
    WeightParams inputGateWeightMatrix = 1; /// Weight Matrix W_i.
    WeightParams forgetGateWeightMatrix = 2; /// Weight Matrix W_f.
    WeightParams blockInputWeightMatrix = 3; /// Weight Matrix W_z.
    WeightParams outputGateWeightMatrix = 4; /// Weight Matrix W_o.

    WeightParams inputGateRecursionMatrix = 20; /// Recursion Weight Matrix R_i.
    WeightParams forgetGateRecursionMatrix = 21; /// Recursion Weight Matrix R_f.
    WeightParams blockInputRecursionMatrix = 22; /// Recursion Weight Matrix R_z.
    WeightParams outputGateRecursionMatrix = 23; /// Recursion Weight Matrix R_o.

    //biases:
    WeightParams inputGateBiasVector = 40; /// Bias vector b_i.
    WeightParams forgetGateBiasVector = 41; /// Bias vector b_f.
    WeightParams blockInputBiasVector = 42; /// Bias vector b_z.
    WeightParams outputGateBiasVector = 43; /// Bias vector b_o.

    //peepholes:
    WeightParams inputGatePeepholeVector = 60; /// Peephole vector p_i.
    WeightParams forgetGatePeepholeVector = 61; /// Peephole vector p_f.
    WeightParams outputGatePeepholeVector = 62; /// Peephole vector p_o.
}

/**
 * A unidirectional long short-term memory (LSTM) layer.
 *
 * .. code::
 *
 *      (y_t, c_t) = UniDirectionalLSTMLayer(x_t, y_{t-1}, c_{t-1})
 *
 * Input
 *    A sequence of vectors of size ``inputVectorSize``
 *    with shape ``[Seq, inputVectorSize]``.
 * Output
 *    A vector of size ``outputVectorSize``. It is either the final output or a sequence of outputs at all time steps.
 *
 * - Output Shape: ``[1,outputVectorSize]`` , if ``sequenceOutput == false``
 * - Output Shape: ``[Seq,outputVectorSize]`` , if ``sequenceOutput == true``
 *
 */
message UniDirectionalLSTMLayerParams {
    uint64 inputVectorSize = 1;  /// Size of the input vectors.
    uint64 outputVectorSize = 2;  /// Size of the output vectors.

    /**
     * 3 element array representing activations [f(),g(),h()] in that order.
     * Typical values used = [sigmoid, tanh, tanh].
     * Activations supported are Linear, Sigmoid, Tanh, ReLU, Scaled Tanh (alpha = 1.71, beta = 2/3), Hard sigmoid (alpha = 0.2, beta = 0.5)
     */
    repeated ActivationParams activations = 10;

    LSTMParams params = 15;

    LSTMWeightParams weightParams = 20; /// Weights, biases and peepholes.

    /// If true, then the node processes the input sequence from right to left
    bool reverseInput = 100;
}

/**
 * Bidirectional long short-term memory (LSTM) layer
 *
 * .. code::
 *
 *      (y_t, c_t, y_t_reverse, c_t_reverse) = BiDirectionalLSTMLayer(x_t, y_{t-1}, c_{t-1}, y_{t-1}_reverse, c_{t-1}_reverse)
 *
 * Input
 *    A sequence of vectors of size ``inputVectorSize``
 *    with shape ``[Seq, inputVectorSize]``.
 * Output
 *    A vector of size ``2 * outputVectorSize``. It is either the final output or a sequence of outputs at all time steps.
 *
 * - Output Shape: ``[1, 2 * outputVectorSize]`` , if ``sequenceOutput == false``
 * - Output Shape: ``[Seq, 2 * outputVectorSize]`` , if ``sequenceOutput == true``
 *
 * The first LSTM operates on the input sequence in the forward direction.
 * The second LSTM operates on the input sequence in the reverse direction.
 *
 * Example: given the input sequence ``[x_1, x_2, x_3]``,
 * where ``x_i`` are vectors at time index ``i``:
 *
 * The forward LSTM output is ``[yf_1, yf_2, yf_3]``,
 *
 * where ``yf_i`` are vectors of size ``outputVectorSize``:
 *
 * - ``yf_1`` is the output at the end of sequence {``x_1``}
 * - ``yf_2`` is the output at the end of sequence {``x_1``, ``x_2``}
 * - ``yf_3`` is the output at the end of sequence {``x_1``, ``x_2``, ``x_3``}
 *
 * The backward LSTM output: ``[yb_1, yb_2, yb_3]``,
 *
 * where ``yb_i`` are vectors of size ``outputVectorSize``:
 *
 * - ``yb_1`` is the output at the end of sequence {``x_3``}
 * - ``yb_2`` is the output at the end of sequence {``x_3``, ``x_2``}
 * - ``yb_3`` is the output at the end of sequence {``x_3``, ``x_2``, ``x_1``}
 *
 * Output of the bi-dir layer:
 *
 * - if ``sequenceOutput = True`` : { ``[yf_1, yb_3]``,  ``[yf_2, yb_2]``,  ``[yf_3, yb_1]`` }
 * - if ``sequenceOutput = False`` : { ``[yf_3, yb_3]`` }
 */
message BiDirectionalLSTMLayerParams {
    /**
     * Size of the input vectors.
     */
    uint64 inputVectorSize = 1;
    /**
     * Size of the outputs vectors.
     * It is same for both forward and backward LSTMs.
     */
    uint64 outputVectorSize = 2;

    /**
     * 3 element array representing activations [f(),g(),h()] in that order.
     * Typical values used = [sigmoid, tanh, tanh].
     * Activations supported are Linear, Sigmoid, Tanh, ReLU, Scaled Tanh (alpha = 1.71, beta = 2/3), Hard sigmoid (alpha = 0.2, beta = 0.5)
     */
    repeated ActivationParams activationsForwardLSTM = 10;
    /**
     * Currently, backward LSTM activations
     * must be same as the ones for the forward LSTM.
     */
    repeated ActivationParams activationsBackwardLSTM = 11;

    /**
     * Common parameters shared by the forward and backward LSTMs.
     */
    LSTMParams params = 15;

    /**
     * Weights and biases.
     * Must be a length 2 message,
     * for the forward and backward LSTM respectively.
     */
    repeated LSTMWeightParams weightParams = 20;
}

message CustomLayerParams {

    message CustomLayerParamValue {
        oneof value {
            double doubleValue = 10;
            string stringValue = 20;
            int32 intValue = 30;
            int64 longValue = 40;
            bool boolValue = 50;
        }
    }

    string className = 10; // The name of the class (conforming to MLCustomLayer) corresponding to this layer
    repeated WeightParams weights = 20; // Any weights -- these are serialized in binary format and memmapped at runtime
    map<string, CustomLayerParamValue> parameters = 30; // these may be handled as strings, so this should not be large
    string description = 40; // An (optional) description of the layer provided by the model creator. This information is displayed when viewing the model, but does not affect the model's execution on device.

}

/// Neural Network Specializations
/// ------------------------------

/**
 * A neural network specialized as a classifier.
 */
message NeuralNetworkClassifier {
    repeated NeuralNetworkLayer layers = 1;
    repeated NeuralNetworkPreprocessing preprocessing = 2;

    /**
     * Mapping from indexed vector of probabilities to class label
     */
    oneof ClassLabels {
        StringVector stringClassLabels = 100;
        Int64Vector int64ClassLabels = 101;
    }

    /**
     * The name of the output blob which will be used as the predicted
     * probabilities of each class label.
     */
    string labelProbabilityLayerName = 200;
}

/**
 * A neural network specialized as a regressor.
 */
message NeuralNetworkRegressor {
    repeated NeuralNetworkLayer layers = 1;
    repeated NeuralNetworkPreprocessing preprocessing = 2;

}