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, elsefalse
.
-
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, elsetrue
.
-
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 withs
, elsefalse
.
-
bool same_scheme(const PartialShape &s) const¶
Check whether this shape represents the same scheme as the argument.
Two shapes
s1
ands2
represent the same scheme ifthey both have dynamic rank, or
they both have static and equal rank
r
, and for everyi
from0
tor-1
,s1[i]
represents the same scheme ass2[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 ass
, elsefalse
.
-
bool relaxes(const PartialShape &s) const¶
Check whether this shape is a relaxation of the argument.
Intuitively, a PartialShape
s1
is said to relaxs2
(or is a relaxation ofs2
) if it is “more permissive” thans2
. In other words,s1
is a relaxation ofs2
if anything you can form by plugging things into the dynamic dimensions ofs2
is also something you can form by plugging things into the dynamic dimensions ofs1
, but not necessarily the other way around.s1.relaxes(s2)
is equivalent tos2.refines(s1)
.Formally, PartialShape
s1
is said to relax PartialShapes2
if:For every
i
from0
tor-1
, eithers1[i]
contains s2[i].
- Parameters
s – The shape which is being compared against this shape.
- Returns
true
if this shape relaxess
, elsefalse
.
-
bool refines(const PartialShape &s) const¶
Check whether this shape is a refinement of the argument.
Intuitively, a PartialShape
s1
is said to relaxs2
(or is a relaxation ofs2
) if it is “less permissive” thans2
. In other words,s1
is a relaxation ofs2
if anything you can form by plugging things into the dynamic dimensions ofs1
is also something you can form by plugging things into the dynamic dimensions ofs2
, but not necessarily the other way around.s1.refines(s2)
is equivalent tos2.relaxes(s1)
.Formally, PartialShape
s1
is said to refine PartialShapes2
if:s2
has dynamic rank, ors1
ands2
both have static rankr
, and for everyi
from0
tor-1
, eithers2[i]
is dynamic, ors1[i]
==s2[i]
.
- Parameters
s – The shape which is being compared against this shape.
- Returns
true
if this shape refiness
, elsefalse
.
-
bool merge_rank(const Rank &r)¶
Checks that this shape’s rank is compatible with
r
, and, if this shape’s rank is dynamic andr
is static, updates this shape to have a rank ofr
with dimensions all dynamic.- Returns
true
if this shape’s rank is compatible withr
, elsefalse
.
-
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
wheres[i] = size_t((*this)[i])
.
-
bool all_non_negative() const¶
Returns
true
if all static dimensions of the tensor are non-negative, elsefalse
.
-
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
i
th 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
i
th Dimension of this shape.
-
inline explicit operator std::vector<Dimension>() const¶
Returns a vector of the dimensions. This has no meaning if dynamic.
-
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.
-
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
intodst
, returningtrue
on success andfalse
on failure. Iffalse
is returned, the effect ondst
is unspecified.To merge two partial shapes
s1
ands2
is to find the most permissive partial shapes
that is no more permissive thans1
ors2
, ifs
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
andsrc
, but overwritesdst
with the result and returnstrue
if merging is successful; if merging is unsuccessful, the function returnsfalse
and may make unspecified changes todst
.- 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, elsefalse
.
-
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 ofshape
into the output stream separated by commas, then inserts}
.
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;
? {} {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
ors2
has dynamic rank, returns PartialShape::dynamic().If
s1 and
s2` both have static rank, and their ranks are unequal, throws std::invalid_argument.If
s1
ands2
both have static rank, and their ranks are equal, returns a new shape whosei
th dimension iss1[i] + s2[i]
.
- Parameters
s1 – Left operand for addition.
s2 – Right operand for addition.
- Throws
std::invalid_argument – If
s1
ands2
have inconsistent ranks.- Returns
The result of elementwise adding
s1
tos2
(see description).