Class representing a shape that may be partially or totally dynamic. More...

#include <partial_shape.hpp>

Public Types
using	iterator = Dimensions::iterator

using	const_iterator = Dimensions::const_iterator

using	reverse_iterator = Dimensions::reverse_iterator

using	const_reverse_iterator = Dimensions::const_reverse_iterator

Public Member Functions
	PartialShape (std::initializer_list< Dimension > init)
	Constructs a shape with static rank from an initializer list of Dimension. More...

	PartialShape (const std::vector< Dimension > &dimensions)
	Constructs a PartialShape with static rank from a vector of Dimension. More...

	PartialShape (const std::vector< Dimension::value_type > &dimensions)
	Constructs a PartialShape with static rank from a vector of dimensions values. More...

	PartialShape ()
	Constructs a static PartialShape with zero rank (the shape of a scalar).

	PartialShape (const Shape &shape)
	Constructs a static PartialShape from a Shape. More...

bool	is_static () const
	Check if this shape is static. More...

bool	is_dynamic () const
	Check if this shape is dynamic. More...

Rank	rank () const
	Get the rank of the shape. More...

bool	compatible (const PartialShape &s) const
	Check whether this shape is compatible with the argument, i.e., whether it is possible to merge them. More...

bool	same_scheme (const PartialShape &s) const
	Check whether this shape represents the same scheme as the argument. More...

bool	relaxes (const PartialShape &s) const
	Check whether this shape is a relaxation of the argument. More...

bool	refines (const PartialShape &s) const
	Check whether this shape is a refinement of the argument. More...

bool	merge_rank (Rank r)
	Checks that this shape's rank is compatible with `r`, and, if this shape's rank is dynamic and `r` is static, updates this shape to have a rank of `r` with dimensions all dynamic. More...

Shape	to_shape () const
	Convert a static PartialShape to a Shape. More...

bool	all_non_negative () const
	Returns `true` if all static dimensions of the tensor are non-negative, else `false`.

const Dimension &	operator[] (size_t i) const
	Index operator for PartialShape. More...

Dimension &	operator[] (size_t i)
	Index operator for PartialShape. More...

	operator std::vector< Dimension > () const
	Returns a vector of the dimensions. This has no meaning if dynamic.

bool	operator== (const PartialShape &partial_shape) const

bool	operator!= (const PartialShape &partial_shape) const

Shape	get_max_shape () const
	Get the max bounding shape.

Shape	get_min_shape () const
	Get the min bounding shape.

Shape	get_shape () const
	Get the unique shape.

iterator	begin () noexcept
	Returns a read/write iterator that points to the first element in the shape. Iteration is done in ordinary element order.

const_iterator	begin () const noexcept
	Returns a read-only (constant) iterator that points to the first element in the shape. Iteration is done in ordinary element order.

iterator	end () noexcept
	Returns a read/write iterator that points one past the last element in the shape. Iteration is done in ordinary element order.

const_iterator	end () const noexcept
	Returns a read-only (constant) iterator that points one past the last element in the shape. Iteration is done in ordinary element order.

reverse_iterator	rbegin () noexcept
	Returns a read/write reverse iterator that points to the last element in the shape. Iteration is done in reverse element order.

const_reverse_iterator	rbegin () const noexcept
	Returns a read-only (constant) reverse iterator that points to the last element in the shape. Iteration is done in reverse element order.

reverse_iterator	rend () noexcept
	Returns a read/write reverse iterator that points to one before the first element in the shape. Iteration is done in reverse element order.

const_reverse_iterator	rend () const noexcept
	Returns a read-only (constant) reverse iterator that points to one before the first element in the shape. Iteration is done in reverse element order.

const_iterator	cbegin () const noexcept
	Returns a read-only (constant) iterator that points to the first element in the shape. Iteration is done in ordinary element order.

const_iterator	cend () const noexcept
	Returns a read-only (constant) iterator that points one past the last element in the shape. Iteration is done in ordinary element order.

const_reverse_iterator	crbegin () const noexcept
	Returns a read-only (constant) reverse iterator that points to the last element in the shape. Iteration is done in reverse element order.

const_reverse_iterator	crend () const noexcept
	Returns a read-only (constant) reverse iterator that points to one before the first element in the shape. Iteration is done in reverse element order.

Static Public Member Functions
static PartialShape	dynamic (Rank r=Rank::dynamic())
	Construct a PartialShape with the given rank and all dimensions (if any) dynamic. More...

static bool	merge_into (PartialShape &dst, const PartialShape &src)
	Try to merge one shape into another. More...

static bool	broadcast_merge_into (PartialShape &dst, const PartialShape &src, const op::AutoBroadcastSpec &autob)
	Try to merge one shape into another along with implicit broadcasting.

Friends
NGRAPH_API std::ostream &	operator<< (std::ostream &str, const PartialShape &shape)
	Inserts a human-readable representation of a PartialShape into an output stream. More...

PartialShape	operator+ (const PartialShape &s1, const PartialShape &s2)
	Elementwise addition of two PartialShape objects. More...

Detailed Description

Class representing a shape that may be partially or totally dynamic.

XXX: THIS CLASS IS EXPERIMENTAL AND THE ENTIRE DESIGN IS SUBJECT TO CHANGE.

A PartialShape may have:

Dynamic rank. (Informal notation: ?)
Static rank, but dynamic dimensions on some or all axes. (Informal notation examples: {1,2,?,4}, {?,?,?})
Static rank, and static dimensions on all axes. (Informal notation examples: {1,2,3,4}, {6}, {})

Constructor & Destructor Documentation

◆ PartialShape() [1/4]

ngraph::PartialShape::PartialShape ( std::initializer_list< Dimension > init )

Constructs a shape with static rank from an initializer list of Dimension.

Parameters

init	The Dimension values for the constructed shape.

Examples:

PartialShape s{2,3,4};                     // rank=3, all dimensions static
PartialShape s{};                          // rank=0
PartialShape s{2,Dimension::dynamic(),3};  // rank=3, dimension 1 dynamic

◆ PartialShape() [2/4]

ngraph::PartialShape::PartialShape ( const std::vector< Dimension > & dimensions )

Constructs a PartialShape with static rank from a vector of Dimension.

Parameters

dimensions The Dimension values for the constructed shape.

◆ PartialShape() [3/4]

ngraph::PartialShape::PartialShape ( const std::vector< Dimension::value_type > & dimensions )

Constructs a PartialShape with static rank from a vector of dimensions values.

Parameters

dimensions The Dimension values for the constructed shape.

◆ PartialShape() [4/4]

ngraph::PartialShape::PartialShape ( const Shape & shape )

Constructs a static PartialShape from a Shape.

Parameters

shape The Shape to convert into PartialShape.

Member Function Documentation

◆ compatible()

bool ngraph::PartialShape::compatible ( const PartialShape & s ) const

Check whether this shape is compatible with the argument, i.e., whether it is possible to merge them.

Parameters

s	The shape to be checked for compatibility with this shape.

Returns: true if this shape is compatible with s, else false.

Two shapes are compatible if

one or both of them has dynamic rank, or
both shapes have dynamic and equal rank, and their dimensions are elementwise compatible (see Dimension::compatible()).

◆ dynamic()

static PartialShape ngraph::PartialShape::dynamic ( Rank r = Rank::dynamic() )

static

Construct a PartialShape with the given rank and all dimensions (if any) dynamic.

Returns: A PartialShape with the given rank, and all dimensions (if any) dynamic.

◆ is_dynamic()

bool ngraph::PartialShape::is_dynamic ( ) const

inline

Check if this shape is dynamic.

Returns: false if this shape is static, else true.

A shape is considered static if it has static rank, and all dimensions of the shape are static.

◆ is_static()

bool ngraph::PartialShape::is_static ( ) const

Check if this shape is static.

Returns: true if this shape is static, else false.

A shape is considered static if it has static rank, and all dimensions of the shape are static.

◆ merge_into()

static bool ngraph::PartialShape::merge_into	(	PartialShape &	dst,
		const PartialShape &	src
	)

static

Try to merge one shape into another.

Parameters

[in,out]	dst	The shape that `src` will be merged into.
	src	The shape that will be merged into `dst`.

Returns: true if merging succeeds, else false.

Merges src into dst, returning true on success and false on failure. If false is returned, the effect on dst is unspecified.

To merge two partial shapes s1 and s2 is to find the most permissive partial shape s that is no more permissive than s1 or s2, if s exists. For example:

merge(?,?) -> ?
merge(?,{?,?}) -> {?,?}
merge({?,?},{?,?}) -> {?,?}
merge({1,2,3,4},?) -> {1,2,3,4}
merge({1,2},{1,?}) -> {1,2}
merge({1,2,?,?},{1,?,3,?}) -> {1,2,3,?}
merge({1,2,3},{1,2,3}) -> {1,2,3}
 
merge({1,?},{2,?}) fails [dimension 0 constraints are inconsistent]
merge({?,?},{?,?,?}) fails [ranks are inconsistent]

This function (merge_into) performs the "merge" operation described above on dst and src, but overwrites dst with the result and returns true if merging is successful; if merging is unsuccessful, the function returns false and may make unspecified changes to dst.

◆ merge_rank()

bool ngraph::PartialShape::merge_rank ( Rank r )

Checks that this shape's rank is compatible with r, and, if this shape's rank is dynamic and r is static, updates this shape to have a rank of r with dimensions all dynamic.

Returns: true if this shape's rank is compatible with r, else false.

◆ operator[]() [1/2]

Dimension& ngraph::PartialShape::operator[] ( size_t i )

Index operator for PartialShape.

Parameters

i	The index of the dimension being selected.

Returns: A reference to the ith Dimension of this shape.

◆ operator[]() [2/2]

const Dimension& ngraph::PartialShape::operator[] ( size_t i ) const

Index operator for PartialShape.

Parameters

i	The index of the dimension being selected.

Returns: A reference to the ith Dimension of this shape.

◆ rank()

Rank ngraph::PartialShape::rank ( ) const

inline

Get the rank of the shape.

Returns: The rank of the shape. This will be Rank::dynamic() if the rank of the shape is dynamic.

◆ refines()

bool ngraph::PartialShape::refines ( const PartialShape & s ) const

Check whether this shape is a refinement of the argument.

Parameters

s	The shape which is being compared against this shape.

Returns: true if this shape refines s, else false.

Intuitively, a PartialShape s1 is said to relax s2 (or is a relaxation of s2) if it is "less permissive" than s2. In other words, s1 is a relaxation of s2 if anything you can form by plugging things into the dynamic dimensions of s1 is also something you can form by plugging things into the dynamic dimensions of s2, but not necessarily the other way around.

s1.refines(s2) is equivalent to s2.relaxes(s1).

Formally, PartialShape s1 is said to refine PartialShape s2 if:

s2 has dynamic rank, or
s1 and s2 both have static rank r, and for every i from 0 to r-1, either s2[i] is dynamic, or s1[i] == s2[i].

◆ relaxes()

bool ngraph::PartialShape::relaxes ( const PartialShape & s ) const

Check whether this shape is a relaxation of the argument.

Parameters

s	The shape which is being compared against this shape.

Returns: true if this shape relaxes s, else false.

Intuitively, a PartialShape s1 is said to relax s2 (or is a relaxation of s2) if it is "more permissive" than s2. In other words, s1 is a relaxation of s2 if anything you can form by plugging things into the dynamic dimensions of s2 is also something you can form by plugging things into the dynamic dimensions of s1, but not necessarily the other way around.

s1.relaxes(s2) is equivalent to s2.refines(s1).

Formally, PartialShape s1 is said to relax PartialShape s2 if:

For every i from 0 to r-1, either s1[i] contains s2[i].

◆ same_scheme()

bool ngraph::PartialShape::same_scheme ( const PartialShape & s ) const

Check whether this shape represents the same scheme as the argument.

Parameters

s	The shape whose scheme is being compared with this shape.

Returns: true if this shape represents the same scheme as s, else false.

Two shapes s1 and s2 represent the same scheme if

they both have dynamic rank, or
they both have static and equal rank r, and for every i from 0 to r-1, s1[i] represents the same scheme as s2[i] (see Dimension::same_scheme()).

◆ to_shape()

Shape ngraph::PartialShape::to_shape ( ) const

Convert a static PartialShape to a Shape.

Returns: A new Shape s where s[i] = size_t((*this)[i]).

Exceptions

std::invalid_argument If this PartialShape is dynamic.

Friends And Related Function Documentation

◆ operator+

PartialShape operator+	(	const PartialShape &	s1,
		const PartialShape &	s2
	)

friend

Elementwise addition of two PartialShape objects.

Parameters

s1	Left operand for addition.
s2	Right operand for addition.

Returns: The result of elementwise adding s1 to s2 (see description).

Exceptions

std::invalid_argument If s1 and s2 have inconsistent ranks.

If s1 or s2 has dynamic rank, returns PartialShape::dynamic().
If s1 ands2` both have static rank, and their ranks are unequal, throws std::invalid_argument.
If s1 and s2 both have static rank, and their ranks are equal, returns a new shape whose ith dimension is s1[i] + s2[i].

◆ operator<<

NGRAPH_API std::ostream& operator<<	(	std::ostream &	str,
		const PartialShape &	shape
	)

friend

Inserts a human-readable representation of a PartialShape into an output stream.

Parameters

str	The output stream targeted for insertion.
shape	The shape to be inserted into `str`.

Returns: A reference to str after insertion.

The output to the stream is in "informal" notation. In other words:

If shape has dynamic rank, inserts the string ?.
If shape has static rank, inserts the string {, then inserts each dimension of shape into the output stream separated by commas, then inserts }.

Example:

PartialShape s1{PartialShape::dynamic())};
PartialShape s2{};
PartialShape s3{1,Dimension::dynamic(),2,3};
PartialShape s4{2,3,4};
std::cout << s1 << std::endl
          << s2 << std::endl
          << s3 << std::endl
          << s4 << std::endl;

Output:

?
{}
{1,?,2,3}
{2,3,4}

The documentation for this class was generated from the following file:

core/include/ngraph/partial_shape.hpp

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ PartialShape() [1/4]

◆ PartialShape() [2/4]

◆ PartialShape() [3/4]

◆ PartialShape() [4/4]

Member Function Documentation

◆ compatible()

◆ dynamic()

◆ is_dynamic()

◆ is_static()

◆ merge_into()

◆ merge_rank()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ rank()

◆ refines()

◆ relaxes()

◆ same_scheme()

◆ to_shape()

Friends And Related Function Documentation

◆ operator+

◆ operator<<