inference-engine/thirdparty/clDNN/api/normalize.hpp

   1 /*
   2 // Copyright (c) 2016 Intel Corporation
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the "License");
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //      http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 */
  16
  17 ///////////////////////////////////////////////////////////////////////////////////////////////////
  18 #pragma once
  19 #include "primitive.hpp"
  20 #include <vector>
  21
  22 namespace cldnn {
  23 /// @addtogroup cpp_api C++ API
  24 /// @{
  25 /// @addtogroup cpp_topology Network Topology
  26 /// @{
  27 /// @addtogroup cpp_primitives Primitives
  28 /// @{
  29
  30 /// @brief Normalizes the input using an L2 norm and multiplies the output with scale value.
  31 /// The scale can be equal for all channels or one scale per channel.
  32 /// @details The L2 norm is computed as:<br>
  33 /// Across spatial mode (across_spatial=true)-<br>
  34 /// norm(i,x,y) = sqrt( &Sigma;( in(f,w,h)^2 ) + epsilon ) where f in range (0,num_of_features), w in range (0,input_width), h in range (0,input_height).<br>
  35 /// The summation is performed over all the pixels in the batch.<br>
  36 /// Within spatial mode (across_spatial=false)-<br>
  37 /// norm(i,x,y) = sqrt( &Sigma;( in(f,x,y)^2 ) + epsilon ) where f in range (0,num_of_features).<br>
  38 /// The summation is performed over this (x,y) position on all the features.<br>
  39 /// @par Algorithm:
  40 ///   out(i,x,y) = ( in(i,x,y) / norm(i,x,y) ) * scale(i)
  41 /// @par Where:
  42 ///   @li out(i,x,y) : value at x, y from i-th feature map after normalization.
  43 ///   @li in(i,x,y) : value at x, y from i-th feature map before normalization.
  44 ///   @li norm(i,x,y) : L2 norm as described above.
  45 ///   @li scale(i) : the scale value of the i-th feature map.
  46 struct normalize : public primitive_base<normalize> {
  47     CLDNN_DECLARE_PRIMITIVE(normalize)
  48
  49     /// @brief Constructs normalize primitive.
  50     /// @param id This primitive id.
  51     /// @param input Input primitive id.
  52     /// @param scale_input Scale input primitive id with values needed for scaling after the normalization.
  53     /// Scale x dimension should be 1 (if all channels have the same scale) or equal to input feature size (one scale per channel).
  54     /// All other dimensions should be 1.
  55     /// @param across_spatial Determines if the normalization is done across or within spatial (see documentation above).
  56     /// @param epsilon Epsilon for not dividing by zero while normalizing.
  57     normalize(const primitive_id& id,
  58               const primitive_id& input,
  59               const primitive_id& scale_input,
  60               const bool across_spatial = true,
  61               const float epsilon = 1e-10f,
  62               const padding& output_padding = padding())
  63         : primitive_base(id, {input}, output_padding),
  64           scale_input(scale_input),
  65           across_spatial(across_spatial),
  66           epsilon(epsilon) {}
  67
  68     /// @brief Scale input primitive id with values needed for scaling after the normalization.
  69     /// Scale x dimension should be 1 (if all channels have the same scale) or equal to input feature size (one scale per channel).
  70     /// All other dimensions should be 1.
  71     primitive_id scale_input;
  72     /// @brief Determines if the normalization is done across or within spatial (see documentation above).
  73     bool across_spatial;
  74     /// @brief Epsilon for not dividing by zero while normalizing.
  75     float epsilon;
  76
  77 protected:
  78     std::vector<std::reference_wrapper<const primitive_id>> get_dependencies() const override { return {scale_input}; }
  79 };
  80 /// @}
  81 /// @}
  82 /// @}
  83 }  // namespace cldnn