struct dnnl::memory::desc

Intel® oneAPI Deep Neural Network Developer Guide and Reference

Download PDF

ID 768875

Date 2/28/2024

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-FE566909-7AE9-49FF-AF3A-0030E39E36A8

View Details

struct dnnl::memory::desc

Overview

A memory descriptor. More…


#include <dnnl.hpp>

struct desc: public dnnl::handle
{
    // construction

    desc();

    desc(
        const dims& adims,
        data_type adata_type,
        format_tag aformat_tag,
        bool allow_empty = false
        );

    desc(
        const dims& adims,
        data_type adata_type,
        const dims& strides,
        bool allow_empty = false
        );

    desc(dnnl_memory_desc_t md);

    // methods

    desc submemory_desc(
        const dims& adims,
        const dims& offsets,
        bool allow_empty = false
        ) const;

    desc reshape(const dims& adims, bool allow_empty = false) const;
    desc permute_axes(const std::vector<int>& permutation, bool allow_empty = false) const;
    int get_ndims() const;
    memory::dims get_padded_dims() const;
    memory::dims get_padded_offsets() const;
    memory::dim get_submemory_offset() const;
    memory::dims get_strides() const;
    int get_inner_nblks() const;
    memory::dims get_inner_blks() const;
    memory::dims get_inner_idxs() const;
    memory::data_type get_data_type() const;
    memory::format_kind get_format_kind() const;
    memory::dims get_dims() const;
    size_t get_size() const;
    bool is_zero() const;
    bool operator == (const desc& other) const;
    bool operator != (const desc& other) const;
};

Inherited Members


public:
    // methods

    handle<T, traits>& operator = (const handle<T, traits>&);
    handle<T, traits>& operator = (handle<T, traits>&&);
    void reset(T t, bool weak = false);
    T get(bool allow_empty = false) const;
    operator T () const;
    operator bool () const;
    bool operator == (const handle<T, traits>& other) const;
    bool operator != (const handle& other) const;

Detailed Documentation

A memory descriptor.

Construction


desc()

Constructs a zero (empty) memory descriptor.

Such a memory descriptor can be used to indicate absence of an argument.


desc(
    const dims& adims,
    data_type adata_type,
    format_tag aformat_tag,
    bool allow_empty = false
    )

Constructs a memory descriptor.

NOTE:

The logical order of dimensions corresponds to the abc... format tag, and the physical meaning of the dimensions depends both on the primitive that would operate on this memory and the operation context.

Parameters:

adims	Tensor dimensions.
adata_type	Data precision/type.
aformat_tag	Memory format tag.
allow_empty	A flag signifying whether construction is allowed to fail without throwing an exception. In this case a zero memory descriptor will be constructed. This flag is optional and defaults to false.


desc(
    const dims& adims,
    data_type adata_type,
    const dims& strides,
    bool allow_empty = false
    )

Constructs a memory descriptor by strides.

NOTE:

Parameters:

adims	Tensor dimensions.
adata_type	Data precision/type.
strides	Strides for each dimension.
allow_empty	A flag signifying whether construction is allowed to fail without throwing an exception. In this case a zero memory descriptor will be constructed. This flag is optional and defaults to false.


desc(dnnl_memory_desc_t md)

Construct a memory descriptor from a C API dnnl_memory_desc_t handle.

The resulting handle is not weak and the C handle will be destroyed during the destruction of the C++ object.

Parameters:

md	The C API memory descriptor.

Methods


desc submemory_desc(
    const dims& adims,
    const dims& offsets,
    bool allow_empty = false
    ) const

Constructs a memory descriptor for a region inside an area described by this memory descriptor.

Parameters:

adims	Sizes of the region.
offsets	Offsets to the region from the encompassing memory object in each dimension.
allow_empty	A flag signifying whether construction is allowed to fail without throwing an exception. In this case a zero memory descriptor will be returned. This flag is optional and defaults to false.

Returns:

A memory descriptor for the region.


desc reshape(const dims& adims, bool allow_empty = false) const

Constructs a memory descriptor by reshaping an existing one.

The new memory descriptor inherits the data type. This operation is valid only for memory descriptors that have format_kind set to dnnl::memory::format_kind::blocked or dnnl::memory::format_kind::any.

The operation ensures that the transformation of the physical memory format corresponds to the transformation of the logical dimensions. If such transformation is impossible, the function either throws an exception (default) or returns a zero memory descriptor depending on the allow_empty flag.

The reshape operation can be described as a combination of the following basic operations:

Add a dimension of size 1. This is always possible.
Remove a dimension of size 1. This is possible only if the dimension has no padding (i.e. padded_dims[dim] == dims[dim] && dims[dim] == 1).
Split a dimension into multiple ones. This is possible only if the product of all tensor dimensions stays constant and the dimension being split does not have padding (i.e. padded_dims[dim] = dims[dim]).
Join multiple consecutive dimensions into a single one. As in the cases above, this requires that the dimensions do not have padding and that the memory format is such that in physical memory these dimensions are dense and have the same order as their logical counterparts. This also assumes that these dimensions are not blocked.
- Here, ‘dense’ means: stride for dim[i] == (stride for dim[i + 1]) * dim[i + 1];
- And ‘same order’ means: i < j if and only if stride for dim[j] <= stride for dim[i].

WARNING:

Some combinations of physical memory layout and/or offsets or dimensions may result in a failure to make a reshape.

Parameters:

adims	New dimensions. The product of dimensions must remain constant.
allow_empty	A flag signifying whether construction is allowed to fail without throwing an exception. In this case a zero memory descriptor will be returned. This flag is optional and defaults to false.

Returns:

A new memory descriptor with new dimensions.


desc permute_axes(const std::vector<int>& permutation, bool allow_empty = false) const

Constructs a memory descriptor by permuting axes in an existing one.

The physical memory layout representation is adjusted accordingly to maintain the consistency between the logical and physical parts of the memory descriptor. The new memory descriptor inherits the data type.

The logical axes will be permuted in the following manner:


for (i = 0; i < get_ndims(); i++)
    new_desc.dims()[permutation[i]] = dims()[i];

Example:


std::vector<int> permutation = {1, 0}; // swap the first and
                                       // the second axes
dnnl::memory::desc in_md(
        {2, 3}, data_type, memory::format_tag::ab);
dnnl::memory::desc expect_out_md(
        {3, 2}, data_type, memory::format_tag::ba);

assert(in_md.permute_axes(permutation) == expect_out_md);

Parameters:

permutation	Axes permutation.
allow_empty	A flag signifying whether construction is allowed to fail without throwing an exception. In this case a zero memory descriptor will be returned. This flag is optional and defaults to false.

Returns:

A new memory descriptor with new dimensions.


int get_ndims() const

Returns a number of dimensions of the memory descriptor.

Returns:

A number of dimensions.


memory::dims get_padded_dims() const

Returns padded dimensions of the memory descriptor.

Returns:

A copy of the padded dimensions vector.


memory::dims get_padded_offsets() const

Returns padded offsets of the memory descriptor.

Returns:

A copy of the padded offsets vector.


memory::dim get_submemory_offset() const

Returns a submemory offset of the memory descriptor.

Returns:

A submemory offset.


memory::dims get_strides() const

Returns strides of the memory descriptor.

NOTE:

This API is only applicable to memory descriptors with format kind dnnl_blocked.

Returns:

A copy of the strides vector.

An empty dnnl::memory::dims if the memory descriptor does not have strides.


int get_inner_nblks() const

Returns a number of inner blocks of the memory descriptor.

NOTE:

This API is only applicable to memory descriptors with format kind dnnl_blocked.

Returns:

A number of inner blocks.


memory::dims get_inner_blks() const

Returns inner blocks of the memory descriptor.

NOTE:

This API is only applicable to memory descriptors with format kind dnnl_blocked.

Returns:

A copy of the inner blocks vector.

An empty dnnl::memory::dims if the memory descriptor does not have inner blocks.


memory::dims get_inner_idxs() const

Returns inner indices of the memory descriptor.

NOTE:

This API is only applicable to memory descriptors with format kind dnnl_blocked.

Returns:

A copy of the inner indices vector.

An empty dnnl::memory::dims if the memory descriptor does not have inner indices.


memory::data_type get_data_type() const

Returns the data type of the memory descriptor.

Returns:

The data type.


memory::format_kind get_format_kind() const

Returns the format kind of the memory descriptor.

Returns:

the format kind.


memory::dims get_dims() const

Returns dimensions of the memory descriptor.

Potentially expensive due to the data copy involved.

Returns:

A copy of the dimensions vector.


size_t get_size() const

Returns size of the memory descriptor in bytes.

Returns:

The number of bytes required to allocate a memory buffer for the memory object described by this memory descriptor including the padding area.


bool is_zero() const

Checks whether the memory descriptor is zero (empty).

Returns:

true if the memory descriptor describes an empty memory and false otherwise.


bool operator == (const desc& other) const

An equality operator.

Parameters:

other

Another memory descriptor.

Returns:

Whether this and the other memory descriptors have the same format tag, dimensions, strides, blocking, etc.


bool operator != (const desc& other) const

An inequality operator.

Parameters:

other

Another memory descriptor.

Returns:

Whether this and the other memory descriptors describe different memory.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® oneAPI Deep Neural Network Developer Guide and Reference

struct dnnl::memory::desc

Overview

Detailed Documentation