Class ov::PartialShape¶

class PartialShape¶

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

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}, {})

Public Functions

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

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

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

Parameters: init – The Dimension values for the constructed shape.

PartialShape(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(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()¶: Constructs a static PartialShape with zero rank (the shape of a scalar).

PartialShape(const Shape &shape)¶

Constructs a static PartialShape from a PartialShape.

Parameters: shape – The PartialShape to convert into PartialShape.

PartialShape(const std::string &shape)¶

Constructs a static PartialShape from a string.

Parameters: shape – The string to parse into PartialShape.

bool is_static() const¶

Check if this shape is static.

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

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

inline bool is_dynamic() const¶

Check if this shape is dynamic.

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

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

inline Rank rank() const¶

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.

bool compatible(const PartialShape &s) const¶

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

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()).

Parameters: s – The shape to be checked for compatibility with this shape.
Returns: true if this shape is compatible with s, else false.

bool same_scheme(const PartialShape &s) const¶

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

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()).

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.

bool relaxes(const PartialShape &s) const¶

Check whether this shape is a relaxation of the argument.

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].

Parameters: s – The shape which is being compared against this shape.
Returns: true if this shape relaxes s, else false.

bool refines(const PartialShape &s) const¶

Check whether this shape is a refinement of the argument.

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].

Parameters: s – The shape which is being compared against this shape.
Returns: true if this shape refines s, else false.

bool merge_rank(const 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.

Shape to_shape() const¶

Convert a static PartialShape to a PartialShape.

Throws: std::invalid_argument – If this PartialShape is dynamic.
Returns: A new PartialShape s where s[i] = size_t((*this)[i]).

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

Dimension &operator[](std::ptrdiff_t i)¶

Index operator for PartialShape, with bound checking.

Parameters: i – The index of the dimension being selected in range [-rank, rank).
Returns: A reference to the ith Dimension of this shape.

const Dimension &operator[](std::ptrdiff_t i) const¶

Index operator for PartialShape, with bound checking.

Parameters: i – The index of the dimension being selected in range [-rank, rank).
Returns: A reference to the ith Dimension of this shape.

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

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.

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

inline 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.

inline 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.

inline 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.

inline 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.

inline 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.

inline 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.

inline 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.

inline 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.

inline 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.

inline 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.

inline 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.

inline void resize(size_t count)¶: Resizes dimensions container to contain count elements.

inline size_t size() const¶: Returns size of dimension vector. Requires rank to be static.

inline iterator insert(iterator position, const Dimension &val)¶: Returns a read/write iterator that points to the inserted element in the shape.

inline void insert(iterator position, size_t n, const Dimension &val)¶: Inserts count copies of the value before position.

template<class InputIterator> inline void insert(iterator position, InputIterator first, InputIterator last)¶: Inserts elements from range [first, last) before position.

inline void reserve(size_t n)¶: Requests that the dimensions vector capacity be enough to contain n elements.

inline void push_back(const Dimension &val)¶: push element to the end of partial shape

template<class ...Args> inline void emplace_back(Args&&... args)¶: emplace element to the end of partial shape

std::string to_string() const¶: String representation of PartialShape.

Public Static Functions

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

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.

static bool merge_into(PartialShape &dst, const PartialShape &src)¶

Try to merge one shape into another.

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.

Parameters

dst – [inout] The shape that src will be merged into.
src – The shape that will be merged into dst.

Returns

true if merging succeeds, else false.

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

Friends

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

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

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}

Parameters

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

Returns

A reference to str after insertion.

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

Elementwise addition of two PartialShape objects.

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].

Parameters

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

Throws

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

Returns

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