class ov::PartialShape

Overview

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

#include <partial_shape.hpp>

class PartialShape
{
public:
    // typedefs

    typedef Dimensions::iterator iterator;
    typedef Dimensions::const_iterator const_iterator;
    typedef Dimensions::reverse_iterator reverse_iterator;
    typedef Dimensions::const_reverse_iterator const_reverse_iterator;

    // construction

    PartialShape(std::initializer_list<Dimension> init);
    PartialShape(std::vector<Dimension> dimensions);
    PartialShape(const std::vector<Dimension::value_type>& dimensions);
    PartialShape();
    PartialShape(const Shape& shape);
    PartialShape(const std::string& shape);

    // methods

    bool is_static() const;
    bool is_dynamic() const;
    Rank rank() const;
    bool compatible(const PartialShape& s) const;
    bool same_scheme(const PartialShape& s) const;
    bool relaxes(const PartialShape& s) const;
    bool refines(const PartialShape& s) const;
    bool merge_rank(Rank r);
    Shape to_shape() const;
    bool all_non_negative() const;
    const Dimension& operator [] (size_t i) const;
    Dimension& operator [] (size_t i);
    operator std::vector< Dimension > () const;
    bool operator == (const PartialShape& partial_shape) const;
    bool operator != (const PartialShape& partial_shape) const;
    Shape get_max_shape() const;
    Shape get_min_shape() const;
    Shape get_shape() const;
    iterator begin();
    const_iterator begin() const;
    iterator end();
    const_iterator end() const;
    reverse_iterator rbegin();
    const_reverse_iterator rbegin() const;
    reverse_iterator rend();
    const_reverse_iterator rend() const;
    const_iterator cbegin() const;
    const_iterator cend() const;
    const_reverse_iterator crbegin() const;
    const_reverse_iterator crend() const;
    void resize(size_t count);
    size_t size() const;
    iterator insert(iterator position, const Dimension& val);
    void insert(iterator position, size_t n, const Dimension& val);

    template <class InputIterator>
    void insert(
        iterator position,
        InputIterator first,
        InputIterator last
        );

    void reserve(size_t n);
    void push_back(const Dimension& val);
    std::string to_string() const;
    static PartialShape dynamic(Rank r = Rank::dynamic());
    static bool merge_into(PartialShape& dst, const PartialShape& src);

    static bool broadcast_merge_into(
        PartialShape& dst,
        const PartialShape& src,
        const ov::op::AutoBroadcastSpec& autob
        );
};

Detailed Documentation

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

Construction

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.

Methods

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.

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.

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

Parameters:

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.

const Dimension& operator [] (size_t i) const

Index operator for PartialShape.

Parameters:

i

The index of the dimension being selected.

Returns:

A reference to the i th Dimension of this shape.

Dimension& operator [] (size_t i)

Index operator for PartialShape.

Parameters:

i

The index of the dimension being selected.

Returns:

A reference to the i th Dimension of this shape.

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.

iterator begin()

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

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

iterator end()

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

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

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

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

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

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

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

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

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

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.

void resize(size_t count)

Resizes dimensions container to contain count elements.

size_t size() const

Returns size of dimension vector. Requires rank to be static.

iterator insert(iterator position, const Dimension& val)

Returns a read/write iterator that points to the inserted element in the shape.

void insert(iterator position, size_t n, const Dimension& val)

Inserts count copies of the value before position.

template <class InputIterator>
void insert(
    iterator position,
    InputIterator first,
    InputIterator last
    )

Inserts elements from range [first, last) before position.

void reserve(size_t n)

Requests that the dimensions vector capacity be enough to contain n elements.

void push_back(const Dimension& val)

push element to the end of partial shape

std::string to_string() const

String representation of PartialShape.

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

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.