Class ov::PartialShape

class PartialShape

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

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

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