1 // Copyright (c) 2019 Intel Corporation
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
7 // http://www.apache.org/licenses/LICENSE-2.0
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.
15 ///////////////////////////////////////////////////////////////////////////////////////////////////
18 #include "../C/broadcast.h"
19 #include "primitive.hpp"
24 /// @addtogroup cpp_api C++ API
26 /// @addtogroup cpp_topology Network Topology
28 /// @addtogroup cpp_primitives Primitives
31 /// @brief Broadcasts input to defined by @p broadcast_sizes output. @p broadcast_axes are used to
32 /// reinterpret input (reshape) inside algorithm.
34 /// @details Takes input, reinterpret it according to @p broadcast_axes
35 /// and copies it to output once or multiple times.
37 /// @n Simple example with empty @p broadcast_axes. Lets assume that:
38 /// @n <tt>input_sizes = (in_b, in_f, in_y, in_x)</tt>
39 /// @n <tt>broadcast_sizes = (bs_b, bs_f, bs_y, bs_x)</tt>
40 /// @n <tt>broadcast_axes = () - empty</tt>
41 /// @n The input is broadcasted on each dimension where <tt>bs_{dim} > in_{dim}</tt> and <tt>bs_{dim}</tt>
42 /// is dividable by <tt>in_{dim}</tt> (input is copied <tt>bs_{dim} / in_{dim}</tt> times).
43 /// The dimensions where <tt>bs_{dim}</tt> is equal to <tt>in_{dim}</tt> remain unchanged.
44 /// @n The resulting output will have sizes equal to @p broadcast_sizes and contains values from
45 /// input that meet following criteria:
46 /// @n <tt>output[(b, f, y, x)] = input[(b % in_b, f % in_f, y % in_y, x % in_x)]</tt>
47 /// @n where <tt>(b, f, y, x)</tt> is a position of value in a primitive output.
49 /// @n More complicated example with non empty @p broadcast_axes. Lets assume that:
50 /// @n <tt>broadcast_sizes = (bs_b, bs_f, bs_y, bs_x)</tt>
51 /// @n <tt>broadcast_axes = (2)</tt>
52 /// @n Taking into account broadcast_axes size (=1) primitive's input must be (4 - 1 = 3):
53 /// @n <tt>primitive input = (1, in_b, in_f, in_x)</tt>
54 /// @n Due to broadcast_axes = (2) primitive will interpret input as:
55 /// @n <tt>primitive input(internal representation) = (in_b, in_f, 1, in_x)</tt>
56 /// @n Now, you can apply broadcast rules from previous example to modified (reinterpreted)
58 /// @n <tt>input_sizes = (in_b, in_f, 1, in_x)</tt>
59 /// @n <tt>output_shape = (bs_b, bs_f, bs_y, bs_x)</tt>
60 /// @n <tt>broadcast_axes = () - empty</tt>
62 /// @n@b Requirements:
63 /// @n - @p broadcast_sizes must be positive on all dimensions.
64 /// @n - @p broadcast_axes size (dimensions count) must be within (inclusive) range
66 /// @n - @p broadcast_axes mustn't have duplicate values.
67 /// @n - Values of @p broadcast_axes must be within (inclusive) range 0 - 3
68 /// @n - @p output_shape must be greater (dividable) than or equal to reinterpreted
69 /// input on all dimensions.
70 /// @n Breaking any of these conditions will raise an exception.
71 struct broadcast : public primitive_base<broadcast, CLDNN_PRIMITIVE_DESC(broadcast)>
73 CLDNN_DECLARE_PRIMITIVE(broadcast)
75 /// @brief Constructs broadcast primitive / layer.
77 /// @param id An identifier of new primitive.
78 /// @param input An identifier of primitive which is an input for newly created
79 /// broadcast primitive.
80 /// @param broadcast_sizes Sizes of broadcast. Output size of current primitive
81 /// will match broadcast sizes (layout type will not change).
82 /// @param broadcast_axes Axes positions (0-based, from left to right) in output_shape
83 /// that are being broadcast. Values of broadcast_axes on remaining
84 /// axes must be greater (dividable) or equal to corresponding input
86 /// @param output_padding Optional padding for output from primitive.
88 const primitive_id& id,
89 const primitive_id& input,
90 const tensor& broadcast_sizes,
91 const std::vector<uint16_t>& broadcast_axes = {},
92 const padding& output_padding = padding()
94 : primitive_base(id, {input}, output_padding),
95 broadcast_sizes(broadcast_sizes),
96 broadcast_axes(broadcast_axes)
100 /// @brief Constructs a copy from C API @CLDNN_PRIMITIVE_DESC{broadcast}
101 broadcast(const dto* dto)
102 : primitive_base(dto),
103 broadcast_sizes(dto->broadcast_sizes),
104 broadcast_axes(uint16_t_arr_to_vector(dto->broadcast_axes))
109 /// @brief Expected sizes of output from broadcast primitive.
110 tensor broadcast_sizes;
111 /// @brief Array of axes positions from output shape (0-based, from left to right)
112 /// along which broadcast should happen.
113 std::vector<uint16_t> broadcast_axes;
116 void update_dto(dto& dto) const override
118 dto.broadcast_sizes = broadcast_sizes;
119 dto.broadcast_axes = uint16_t_vector_to_arr(broadcast_axes);