inference-engine/thirdparty/clDNN/api/CPP/softmax.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 "../C/softmax.h"
  20 #include "primitive.hpp"
  21
  22 namespace cldnn
  23 {
  24 /// @addtogroup cpp_api C++ API
  25 /// @{
  26 /// @addtogroup cpp_topology Network Topology
  27 /// @{
  28 /// @addtogroup cpp_primitives Primitives
  29 /// @{
  30
  31 /// @brief Normalizes results so they sum to 1.
  32 /// @details
  33 /// @par Algorithm:
  34 ///   b = e^a/sum(N-1; j=0; e^j)
  35 /// @par Where:
  36 ///   @li N : number of values to normalize
  37 ///   @li b : value after normalization
  38 ///   @li a : value before normalization
  39 struct softmax : public primitive_base<softmax, CLDNN_PRIMITIVE_DESC(softmax)>
  40 {
  41     CLDNN_DECLARE_PRIMITIVE(softmax)
  42
  43     /// @brief Enum type to specify softmax's normalization scope (see #dimension).
  44     enum dimension_t
  45     {
  46         normalize_f = cldnn_softmax_normalize_f,
  47         normalize_x = cldnn_softmax_normalize_x,
  48         normalize_y = cldnn_softmax_normalize_y,
  49         normalize_fyx = cldnn_softmax_normalize_fyx,
  50     };
  51
  52     /// @brief Constructs softmax primitive.
  53     /// @param id This primitive id.
  54     /// @param input Input primitive id.
  55     /// @param dimension Defines a scope of normalization (see #dimension).
  56     softmax(
  57         const primitive_id& id,
  58         const primitive_id& input,
  59         const dimension_t dimension = normalize_fyx,
  60         const padding& output_padding = padding()
  61     )
  62         :primitive_base(id, {input}, output_padding)
  63         , dimension(dimension)
  64     {}
  65
  66     /// @brief Constructs a copy from C API @CLDNN_PRIMITIVE_DESC{softmax}
  67     softmax(const dto* dto)
  68         :primitive_base(dto)
  69         , dimension(static_cast<dimension_t>(dto->dimension))
  70     {}
  71
  72     /// @brief Defines a scope of a single softmax normalization.
  73     /// @details
  74     /// Being given a 4-dimensional input, which consists of b,f,y,x dimensions, softmax normalizes data which are divided into multiple independent sets.
  75     /// Specific behaviour is determined by this parameter, as follows:
  76     /// - when set to @link softmax::dimension_t softmax::normalize_x @endlink each input row is normalized independently,
  77     /// - when set to @link softmax::dimension_t softmax::normalize_y @endlink each input column is normalized independently,
  78     /// - when set to @link softmax::dimension_t softmax::normalize_f @endlink each in-depth vector of input is normalized independently,
  79     /// - when set to @link softmax::dimension_t softmax::normalize_fyx @endlink each 3d image within input is normalized independently,
  80     dimension_t dimension;
  81
  82 private:
  83     void update_dto(dto& dto) const override
  84     {
  85         dto.dimension = static_cast<cldnn_softmax_dimension>(dimension);
  86     }
  87 };
  88 /// @}
  89 /// @}
  90 /// @}
  91 }