inference-engine/thirdparty/clDNN/api/C/broadcast.h

   1 // Copyright (c) 2019 Intel Corporation
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //      http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 ///////////////////////////////////////////////////////////////////////////////////////////////////
  16 #ifndef BROADCAST_H
  17 #define BROADCAST_H
  18
  19 #include "cldnn.h"
  20
  21
  22 /// @addtogroup c_api C API
  23 /// @{
  24 /// @addtogroup c_topology Network Topology
  25 /// @{
  26 /// @addtogroup c_primitives Primitives
  27 /// @{
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /// @brief Broadcasts input to defined by @p broadcast_sizes output. @p broadcast_axes are used to
  34 ///        reinterpret input (reshape) inside algorithm.
  35 ///
  36 /// @details Takes input, reinterpret it according to @p broadcast_axes
  37 ///          and copies it to output once or multiple times.
  38 /// @n
  39 /// @n Simple example with empty @p broadcast_axes. Lets assume that:
  40 /// @n      <tt>input_sizes = (in_b, in_f, in_y, in_x)</tt>
  41 /// @n      <tt>broadcast_sizes = (bs_b, bs_f, bs_y, bs_x)</tt>
  42 /// @n      <tt>broadcast_axes = () - empty</tt>
  43 /// @n The input is broadcasted on each dimension where <tt>bs_{dim} > in_{dim}</tt> and <tt>bs_{dim}</tt>
  44 ///    is dividable by <tt>in_{dim}</tt> (input is copied <tt>bs_{dim} / in_{dim}</tt> times).
  45 ///    The dimensions where <tt>bs_{dim}</tt> is equal to <tt>in_{dim}</tt> remain unchanged.
  46 /// @n The resulting output will have sizes equal to @p broadcast_sizes and contains values from
  47 ///    input that meet following criteria:
  48 /// @n      <tt>output[(b, f, y, x)] = input[(b % in_b, f % in_f, y % in_y, x % in_x)]</tt>
  49 /// @n where <tt>(b, f, y, x)</tt> is a position of value in a primitive output.
  50 /// @n
  51 /// @n More complicated example with non empty @p broadcast_axes. Lets assume that:
  52 /// @n      <tt>broadcast_sizes = (bs_b, bs_f, bs_y, bs_x)</tt>
  53 /// @n      <tt>broadcast_axes = (2)</tt>
  54 /// @n Taking into account broadcast_axes size (=1) primitive's input must be (4 - 1 = 3):
  55 /// @n      <tt>primitive input = (1, in_b, in_f, in_x)</tt>
  56 /// @n Due to broadcast_axes = (2) primitive will interpret input as:
  57 /// @n      <tt>primitive input(internal representation) = (in_b, in_f, 1, in_x)</tt>
  58 /// @n Now, you can apply broadcast rules from previous example to modified (reinterpreted)
  59 ///    input and output:
  60 /// @n      <tt>input_sizes = (in_b, in_f, 1, in_x)</tt>
  61 /// @n      <tt>output_shape = (bs_b, bs_f, bs_y, bs_x)</tt>
  62 /// @n      <tt>broadcast_axes = () - empty</tt>
  63 /// @n
  64 /// @n@b Requirements:
  65 /// @n - @p broadcast_sizes must be positive on all dimensions.
  66 /// @n - @p broadcast_axes size (dimensions count) must be within (inclusive) range
  67 ///      0 - 4.
  68 /// @n - @p broadcast_axes mustn't have duplicate values.
  69 /// @n - Values of @p broadcast_axes must be within (inclusive) range 0 - 3
  70 /// @n - @p output_shape must be greater (dividable) than or equal to reinterpreted
  71 ///      input on all dimensions.
  72 /// @n Breaking any of these conditions will raise an exception.
  73 CLDNN_BEGIN_PRIMITIVE_DESC(broadcast)
  74 /// @brief Sizes of broadcast. Output size of current primitive will match broadcast sizes (layout type
  75 ///        will not change).
  76 cldnn_tensor broadcast_sizes;
  77 /// @brief Array of axes positions from output shape (0-based, from left to right)
  78 ///        along which broadcast should happen.
  79 cldnn_uint16_t_arr broadcast_axes;
  80
  81 CLDNN_END_PRIMITIVE_DESC(broadcast)
  82
  83
  84 CLDNN_DECLARE_PRIMITIVE_TYPE_ID(broadcast);
  85
  86 #ifdef __cplusplus
  87 }
  88 #endif
  89
  90 /// @}
  91 /// @}
  92 /// @}
  93 #endif // BROADCAST_H