namespace ngraph::builder¶

Overview¶

Convenience functions that create addional graph nodes to implement commonly-used recipes, for example auto-broadcast. More…

namespace builder {

// namespaces

namespace ngraph::builder::opset1;

// enums

enum BiasMode;

// classes

class numpy_autobroadcast_incompatible_shapes;

// global functions

OutputVector numpy_broadcast_outputs(const OutputVector& values);

std::shared_ptr<Node> numpy_broadcast(
    const Output<Node>& value,
    const Shape& shape
    );

std::pair<std::shared_ptr<Node>, std::shared_ptr<Node>> numpy_broadcast(const std::pair<Output<Node>, Output<Node>>& args);

OutputVector numpy_broadcast_for_matmul_operation(
    const Output<Node>& left,
    const Output<Node>& right
    );

OutputVector pdpd_broadcast(const OutputVector& inputs, int64_t axis);

std::shared_ptr<Node> calculate_broadcast_axes(
    const Shape& output_shape,
    const Shape& input_shape,
    std::size_t start_match_axis
    );

std::pair<Shape, std::vector<Shape>> get_numpy_broadcast_shapes(const std::vector<Shape>& input_shapes);

std::shared_ptr<Node> make_broadcast_node(
    const Output<Node>& value,
    const Shape& new_shape,
    std::size_t start_match_axis
    );

template <class T>
std::shared_ptr<Node> make_constant(
    const element::Type& type,
    const Shape& shape,
    const T& num
    );

std::shared_ptr<Node> make_constant_from_double(
    const element::Type& type,
    const Shape& shape,
    double num
    );

OutputVector split(
    const Output<Node>& value,
    const std::vector<int64_t>& length_parts,
    int64_t axis = 0
    );

OutputVector split(const Output<Node>& value, int64_t split_parts, int axis = 0);

} // namespace builder

Detailed Documentation¶

Convenience functions that create addional graph nodes to implement commonly-used recipes, for example auto-broadcast.

Global Functions¶

OutputVector numpy_broadcast_outputs(const OutputVector& values)

Broadcast all values, if necessary, to obtain equal shapes according to NumPy’s auto-broadcasting scheme.

There are some shape combinations which the autobroadcast algoritm cannot handle. An exception is thrown when such combinations are provided to this function.

Parameters:

values	Vector of output values.
ngraph::builder::numpy_autobroadcast_incompatible_shapes

Returns:

Vector of broadcasted values.

std::shared_ptr<Node> numpy_broadcast(
    const Output<Node>& value,
    const Shape& shape
    )

Broadcast input value to provided shape using NumPy’s auto-broadcasting rules.

Parameters:

value	Input value
shape	Requested output shape

Returns:

Node producing values with requested shape.

std::pair<std::shared_ptr<Node>, std::shared_ptr<Node>> numpy_broadcast(const std::pair<Output<Node>, Output<Node>>& args)

Wrap two graph values, if necessary, to obtain values with identical shapes, using NumPy’s auto-broadcast rules.

The elements in the std::pair returned by this function correspond to those supplied in the std::pair provided via args.

If args.first and args.second produce identical shapes, then the returned std::pair will have the same value as args.

If args.first and args.second produce different shapes, then this function creates new ngraph::op::Reshape and/or ngraph::op::Broadcast nodes, as needed, to wrap args.first and/or args.second in a manner that yields values with the same shape.

There are some shape combinations which the autobroadcast algoritm cannot handle. An exception is thrown when such combinations are provided to this function.

args.first is not null
args.second is not null
The ngraph::Node objects pointed to by args.first and args.second have not been altered by this function, except by possibly having added consumers of their values.
If an exception was not thrown, then the return value’s first and second elements point to ngraph::Node objects whose output values have the same shape.

Parameters:

ngraph::builder::numpy_autobroadcast_incompatible_shapes

OutputVector numpy_broadcast_for_matmul_operation(
    const Output<Node>& left,
    const Output<Node>& right
    )

Broadcast shape of two nodes to make them compatible for a matrix multiplication.

This function is reflecting broadcasting behaviour of NumPy’s matmul operation. (https://docs.scipy.org/doc/numpy/reference/generated/numpy.matmul.html) This mean that only “stack of matrices” axes are bidirectionally broadcasted. The last two dimension are left untouched.

Parameters:

left	The Node providing data for the left-hand side of matrix multiplication.
right	The Node providing data for the right-hand side of matrix multiplication.

Returns:

The vector containing both outputs broadcasted.

OutputVector pdpd_broadcast(const OutputVector& inputs, int64_t axis)

Cast shape of all input nodes for an element-wise operation that requires shape-compatibility.

Parameters:

inputs	Original list of inputs
axis	Index starting to align

Returns:

pdpd-style broadcasted list of nodes.

std::shared_ptr<Node> calculate_broadcast_axes(
    const Shape& output_shape,
    const Shape& input_shape,
    std::size_t start_match_axis
    )

Generate a list of broadcast axes.

Informally, a broadcast “adds” axes to the input tensor, replicating elements from the input tensor as needed to fill the new dimensions. Function calculate which of the output axes are added in this way.

Parameters:

output_shape	The new shape for the output tensor.
input_shape	The shape of input tensor.
start_match_axis	The axis along which we want to replicate elements. The starting axis position (0-based) int the output shape from which the current shape of the tensor matches the desired new shape.

Returns:

The indices of added axes.

std::pair<Shape, std::vector<Shape>> get_numpy_broadcast_shapes(const std::vector<Shape>& input_shapes)

Calculate the output shape of numpy-style broadcast operation for all input shapes.

This function finds the maximum tensor shape that will be the result of element-wise operation that will be applied to the input shapes vector. The function also prepares the shape of each input for the element-wise operation by left-padding those shapes so that their rank is equal to the left_shape’s rank.

Parameters:

input_shapes

A vector of input shapes for which a common shape should be found

Returns:

A pair that contains the target shape as its first object and a vector of padded input shapes ready to be broadcasted as the second object

std::shared_ptr<Node> make_constant_from_double(
    const element::Type& type,
    const Shape& shape,
    double num
    )

Create constant filled with double value.

If num value exeeds capacity of type, the value is clamped.

Parameters:

type	The type of produced Constant node.
shape	The shape of produced Constant node.
num	The value used to fill Constant node.

Returns:

The Constant node which have expected type, shape and value.

OutputVector split(
    const Output<Node>& value,
    const std::vector<int64_t>& length_parts,
    int64_t axis = 0
    )

Split value on specified axis into multiple parts.

Parameters:

value	The value to be split.
length_parts	The vector defining the lengths of each split part.
axis	The axis we split input node on. Default value is zero axis.

Returns:

The vector containing multiple nodes we split input node into.

OutputVector split(const Output<Node>& value, int64_t split_parts, int axis = 0)

Split node on specified axis into multiple parts.

This implementation supports negative axis values (similar to NumPy indexing). This means that the axis to split on will be counted from the back of the tensor (negative values are subtracted from its rank).

Parameters:

value	The value to split.
split_parts	The number of parts we want to split output at given axis. The length of the axis to split must be divisible by this value.
axis	The axis we split input node on. Default value is zero axis.

Returns:

The vector containing multiple outputs we split input node into.