1 //*****************************************************************************
2 // Copyright 2017-2020 Intel Corporation
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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 //*****************************************************************************
22 #include "ngraph/except.hpp"
23 #include "ngraph/node.hpp"
24 #include "ngraph/op/broadcast.hpp"
30 class numpy_autobroadcast_incompatible_shapes : public ngraph::ngraph_error
33 numpy_autobroadcast_incompatible_shapes(const ngraph::Shape& shape1,
34 const ngraph::Shape& shape2);
37 const ngraph::Shape m_shape1;
38 const ngraph::Shape m_shape2;
40 static std::string error_str(const ngraph::Shape& shape1, const ngraph::Shape& shape2);
44 /// \brief Broadcast all values, if necessary, to obtain equal shapes according
45 /// to NumPy's auto-broadcasting scheme.
47 /// \note There are some shape combinations which the autobroadcast algoritm cannot
48 /// handle. An exception is thrown when such combinations are provided to this
51 /// \param values Vector of output values.
53 /// \exception ngraph::builder::numpy_autobroadcast_incompatible_shapes
55 /// \return Vector of broadcasted values.
57 NGRAPH_DEPRECATED("This builder was deprecated.")
58 OutputVector numpy_broadcast_outputs(const OutputVector& values);
61 /// \brief Broadcast input value to provided shape using NumPy's auto-broadcasting
64 /// \param value Input value
65 /// \param shape Requested output shape
67 /// \return Node producing values with requested shape.
69 NGRAPH_DEPRECATED("This builder was deprecated.")
70 std::shared_ptr<Node> numpy_broadcast(const Output<Node>& value, const Shape& shape);
72 /// \brief Wrap two graph values, if necessary, to obtain values with identical shapes,
73 /// using NumPy's auto-broadcast rules.
75 /// The elements in the std::pair returned by this function correspond to those supplied
76 /// in the std::pair provided via \p args.
78 /// If \p args.first and \p args.second produce identical shapes, then the returned
79 /// std::pair will have the same value as \p args.
81 /// If \p args.first and \p args.second produce different shapes, then this function creates
82 /// new ngraph::op::Reshape and/or ngraph::op::Broadcast nodes, as needed, to wrap
83 /// \p args.first and/or \p args.second in a manner that yields values with the same shape.
85 /// There are some shape combinations which the autobroadcast algoritm cannot handle.
86 /// An exception is thrown when such combinations are provided to this function.
89 /// - \p args.first is not null
90 /// - \p args.second is not null
93 /// - The ngraph::Node objects pointed to by \p args.first and \p args.second have not been
94 /// altered by this function, except by possibly having added consumers of their values.
96 /// - If an exception was not thrown, then the return value's \p first and \p second
97 /// elements point to ngraph::Node objects whose output values have the same shape.
99 /// \exception ngraph::builder::numpy_autobroadcast_incompatible_shapes
100 NGRAPH_DEPRECATED("This builder was deprecated.")
101 std::pair<std::shared_ptr<Node>, std::shared_ptr<Node>>
102 numpy_broadcast(const std::pair<Output<Node>, Output<Node>>& args);
104 /// Create a new \p NodeType node, and any additional nodes required to simulate NumPy-style
105 /// autobroadcast semantics. Intended for binary operations such as "Add".
107 /// \param [in] operand1_reshapeable The first operand to supply to the \p NodeType
108 /// constructor. Subject to being wrapped with additional
109 /// nodes required for autobroadcasting. Must not be null.
111 /// \param [in] operand2_reshapeable The second operand to supply to the \p NodeType
112 /// constructor. Subject to being wrapped with additional
113 /// nodes required for autobroadcasting. Must not be null.
115 /// \return The sink node of any/all nodes created by this function. Will never be null.
117 /// \exception ngraph::builder::numpy_autobroadcast_incompatible_shapes
118 template <typename NodeType>
119 NGRAPH_DEPRECATED("This builder was deprecated.")
120 std::shared_ptr<NodeType> make_with_numpy_broadcast(
121 const Output<Node>& operand1_reshapeable, const Output<Node>& operand2_reshapeable)
123 NGRAPH_SUPPRESS_DEPRECATED_START
124 auto shaped_op1_op2 = numpy_broadcast({operand1_reshapeable, operand2_reshapeable});
125 return std::make_shared<NodeType>(shaped_op1_op2.first, shaped_op1_op2.second);
126 NGRAPH_SUPPRESS_DEPRECATED_END
129 /// Create a new \p NodeType node, and any additional nodes required to simulate NumPy-style
130 /// autobroadcast semantics. Intended for non-binary operations such as "Select", where
131 /// precisely the second and third operands are subject to autobroadcast semantics.
133 /// \param [in] operand1 This operand is not subject to autobraodcast logic, and will be
134 /// passed as-is as the first argument to the \p NodeType constructor.
136 /// \param [in] operand2_reshapeable The second operand to supply to the \p NodeType
137 /// constructor. Subject to being wrapped with additional
138 /// nodes required for autobroadcasting. Must not be null.
140 /// \param [in] operand3_reshapeable The third operand to supply to the \p NodeType
141 /// constructor. Subject to being wrapped with additional
142 /// nodes required for autobroadcasting. Must not be null.
144 /// \return The sink node of any/all nodes created by this function. Will never be null.
146 /// \exception ngraph::builder::numpy_autobroadcast_incompatible_shapes
147 template <typename NodeType>
148 NGRAPH_DEPRECATED("This builder was deprecated.")
149 std::shared_ptr<Node> make_with_numpy_broadcast(const Output<Node>& operand1,
150 const Output<Node>& operand2_reshapeable,
151 const Output<Node>& operand3_reshapeable)
153 NGRAPH_SUPPRESS_DEPRECATED_START
154 auto shaped_op2_op3 = numpy_broadcast({operand2_reshapeable, operand3_reshapeable});
155 return std::make_shared<NodeType>(
156 operand1, shaped_op2_op3.first, shaped_op2_op3.second);
157 NGRAPH_SUPPRESS_DEPRECATED_END
160 /// \brief Broadcast shape of two nodes to make them compatible for a matrix
163 /// \note This function is reflecting broadcasting behaviour of NumPy's `matmul`
165 /// (https://docs.scipy.org/doc/numpy/reference/generated/numpy.matmul.html)
166 /// This mean that only \"stack of matrices\" axes are bidirectionally
167 /// broadcasted. The last two dimension are left untouched.
169 /// \param[in] left The Node providing data for the left-hand side of matrix
171 /// \param[in] right The Node providing data for the right-hand side of matrix
174 /// \return The vector containing both outputs broadcasted.
176 NGRAPH_DEPRECATED("This builder was deprecated.")
177 OutputVector numpy_broadcast_for_matmul_operation(const Output<Node>& left,
178 const Output<Node>& right);
180 /// \brief Cast shape of all input nodes for an element-wise operation that requires
181 /// shape-compatibility
183 /// \param inputs Original list of inputs
184 /// \param axis Index starting to align
186 /// \return pdpd-style broadcasted list of nodes.
187 NGRAPH_DEPRECATED("This builder was deprecated.")
188 OutputVector pdpd_broadcast(const OutputVector& inputs, int64_t axis);
190 /// \brief Generate a list of broadcast axes.
192 /// \details Informally, a broadcast "adds" axes to the input tensor, replicating
193 /// elements from the input tensor as needed to fill the new dimensions.
194 /// Function calculate which of the output axes are added in this way.
196 /// \param output_shape The new shape for the output tensor.
197 /// \param input_shape The shape of input tensor.
198 /// \param start_match_axis The axis along which we want to replicate elements.
199 /// The starting axis position (0-based) int the output
200 /// shape from which the current shape of the tensor
201 /// matches the desired new shape.
203 /// \return The indices of added axes.
204 NGRAPH_DEPRECATED("This builder was deprecated.")
205 AxisSet calculate_broadcast_axes(const Shape& output_shape,
206 const Shape& input_shape,
207 std::size_t start_match_axis);
210 /// \brief Calculate the output shape of numpy-style broadcast operation for all input
213 /// This function finds the maximum tensor shape that will be the result of
214 /// element-wise operation that will be applied to the input shapes vector.
215 /// The function also prepares the shape of each input for the element-wise
216 /// operation by left-padding those shapes so that their rank is equal to the
217 /// left_shape's rank.
219 /// \param input_shapes A vector of input shapes for which a common shape should be
222 /// \return A pair that contains the target shape as its first object and a vector of
223 /// padded input shapes ready to be broadcasted as the second object
225 NGRAPH_DEPRECATED("This builder was deprecated.")
226 std::pair<Shape, std::vector<Shape>>
227 get_numpy_broadcast_shapes(const std::vector<Shape>& input_shapes);
229 /// \brief Generate a list of broadcast along axes.
231 /// \details Broadcast "adds" elements along axes to the input tensor, replicating
232 /// elements from the input tensor as needed to fill the new dimensions.
233 /// Function calculate which of the output axes are added in this way.
235 /// This function will attempt to match shapes, assuming the current shape
236 /// matches the rightmost positions of the desired new shape. This behaviour
237 /// is similar to NumPy's broadcasting.
239 /// \param output_shape The new shape for the output tensor.
240 /// \param input_shape The shape of input tensor.
242 /// \return The indices of added axes.
243 NGRAPH_DEPRECATED("This builder was deprecated.")
244 inline AxisSet calculate_broadcast_axes(const Shape& output_shape, const Shape& input_shape)
246 NGRAPH_SUPPRESS_DEPRECATED_START
247 return calculate_broadcast_axes(
248 output_shape, input_shape, output_shape.size() - input_shape.size());
249 NGRAPH_SUPPRESS_DEPRECATED_END
252 NGRAPH_DEPRECATED("This builder was deprecated.")
253 inline std::shared_ptr<Node> make_broadcast_node(const Output<Node>& output,
256 NGRAPH_SUPPRESS_DEPRECATED_START
257 return std::make_shared<op::Broadcast>(
258 output, new_shape, calculate_broadcast_axes(new_shape, output.get_shape()));
259 NGRAPH_SUPPRESS_DEPRECATED_END
262 NGRAPH_DEPRECATED("This builder was deprecated.")
263 inline std::shared_ptr<Node> make_broadcast_node(const Output<Node>& value,
264 const Shape& new_shape,
265 std::size_t start_match_axis)
267 NGRAPH_SUPPRESS_DEPRECATED_START
268 return std::make_shared<op::Broadcast>(
271 calculate_broadcast_axes(new_shape, value.get_shape(), start_match_axis));
272 NGRAPH_SUPPRESS_DEPRECATED_END
278 /// \brief Broadcast right node to left node's shape using legacy scheme.
280 /// \param[in] left The left hand side node of binary operation.
281 /// \param[in] right The right hand side node of binary operation. The one
282 /// to be broadcasted.
283 /// \param[in] start_match_axis The axis index starting mutually equal shapes
286 /// \return The Output object connected to node producing broadcasted right node.
288 Output<Node> legacy_broadcast_for_binary_operation(const Output<Node>& left,
289 const Output<Node>& right,
290 size_t start_match_axis);
293 /// \brief Reconstructs axes mapping vector for Broadcast:v1 operation.
295 /// \param[in] output_shape The output shape of Broadcast operation.
296 /// \param[in] broadcast_axes The broadcast axes used for Broadcast:v0 operator.
298 /// \return The vector with axes indexes mapping .
300 std::vector<std::size_t> get_axes_mapping(const Shape& output_shape,
301 const AxisSet& broadcast_axes);
304 /// \brief Creates Node returning the axes mapping for Broadcast:v1 operation.
306 /// \param[in] output_shape The output shape of Broadcast operation.
307 /// \param[in] input_shape The input shape.
308 /// \param[in] start_match_axis The axis index at which input shape starts to be
309 /// identical as the output shape.
311 /// \return Returns the Output object pointing to node with the axes mapping.
313 Output<Node> get_axes_mapping_output(const Shape& output_shape,
314 const Shape& input_shape,
315 std::size_t start_match_axis);
318 /// \brief Creates Node returning the axes mapping for Broadcast:v1 operation.
320 /// \param[in] output_shape The output shape of Broadcast operation.
321 /// \param[in] broadcast_axes The broadcast axes used for Broadcast:v0 operator.
323 /// \return The Output object with Node returning axes mapping.
325 Output<Node> get_axes_mapping_output(const Shape& output_shape,
326 const AxisSet& broadcast_axes);
328 Output<Node> make_broadcast(const Output<Node>& node,
329 const Shape& target_shape,
330 const AxisSet& broadcast_axes);
332 Output<Node> make_broadcast(const Output<Node>& node,
333 const Shape& target_shape,
334 std::size_t start_match_axis);
336 } // namespace opset1
337 } // namespace builder
338 } // namespace ngraph