Logical Tensor¶

Overview¶

Logical tensor describes the meta-data of the input or output tensor, like elements data type, number of dimensions, size for each dimension (shape), layout, and the property of the tensor. More…

// enums

enum dnnl_graph_layout_type_t;
enum dnnl_graph_tensor_property_t;

// structs

struct dnnl_graph_logical_tensor_t;

// classes

class dnnl::graph::logical_tensor;

// global functions

dnnl_status_t DNNL_API dnnl_graph_logical_tensor_init(
    dnnl_graph_logical_tensor_t* logical_tensor,
    size_t tid,
    dnnl_data_type_t dtype,
    int32_t ndims,
    dnnl_graph_layout_type_t ltype,
    dnnl_graph_tensor_property_t ptype
    );

dnnl_status_t DNNL_API dnnl_graph_logical_tensor_init_with_dims(
    dnnl_graph_logical_tensor_t* logical_tensor,
    size_t tid,
    dnnl_data_type_t dtype,
    int32_t ndims,
    const dnnl_dims_t dims,
    dnnl_graph_layout_type_t ltype,
    dnnl_graph_tensor_property_t ptype
    );

dnnl_status_t DNNL_API dnnl_graph_logical_tensor_init_with_strides(
    dnnl_graph_logical_tensor_t* logical_tensor,
    size_t tid,
    dnnl_data_type_t dtype,
    int32_t ndims,
    const dnnl_dims_t dims,
    const dnnl_dims_t strides,
    dnnl_graph_tensor_property_t ptype
    );

dnnl_status_t DNNL_API dnnl_graph_logical_tensor_get_mem_size(
    const dnnl_graph_logical_tensor_t* logical_tensor,
    size_t* size
    );

dnnl_status_t DNNL_API dnnl_graph_logical_tensor_is_equal(
    const dnnl_graph_logical_tensor_t* lt1,
    const dnnl_graph_logical_tensor_t* lt2,
    uint8_t* is_equal
    );

// macros

#define DNNL_GRAPH_UNKNOWN_DIM
#define DNNL_GRAPH_UNKNOWN_NDIMS

Detailed Documentation¶

Logical tensor describes the meta-data of the input or output tensor, like elements data type, number of dimensions, size for each dimension (shape), layout, and the property of the tensor.

Each logical tensor has an unique ID. The library uses logical tensor IDs to build up the connections between operations if the output of one operation has the same ID as the input of another operation. The meta-data in a logical tensor may be enriched in the framework graph as it progresses toward final execution. For example, the library doesn’t require detailed shape information at the operation and graph creation stage. But shape information of input logical tensor will be required at partition compilation stage. Logical tensor is not mutable. Users must create a new logical tensor with the same ID to pass any new additional information to oneDNN Graph API. Please note that the library also has unique IDs for operations. The ID should be unique among different logical tensors, but it can have the same value between a logical tensor and an operation.

Global Functions¶

dnnl_status_t DNNL_API dnnl_graph_logical_tensor_init(
    dnnl_graph_logical_tensor_t* logical_tensor,
    size_t tid,
    dnnl_data_type_t dtype,
    int32_t ndims,
    dnnl_graph_layout_type_t ltype,
    dnnl_graph_tensor_property_t ptype
    )

Initializes a logical tensor with id, data type, number of dimensions, layout type, and property.

The logical tensor’s dims are unknown with this interface.

Parameters:

logical_tensor	Output logical tensor.
tid	The unique id of the output logical tensor.
dtype	Elements data type.
ndims	Number of dimensions.
ltype	Layout type of the underlying tensor buffer.
ptype	Tensor property type.

Returns:

dnnl_success on success or a status describing the error otherwise.

dnnl_status_t DNNL_API dnnl_graph_logical_tensor_init_with_dims(
    dnnl_graph_logical_tensor_t* logical_tensor,
    size_t tid,
    dnnl_data_type_t dtype,
    int32_t ndims,
    const dnnl_dims_t dims,
    dnnl_graph_layout_type_t ltype,
    dnnl_graph_tensor_property_t ptype
    )

Initializes a logical tensor with basic information and dims.

The logical tensor’s dimensions and layout will be initialized according to the input arguments.

Note

If dims contains all valid values and layout type is dnnl_graph_layout_type_strided. The strides field in dnnl_graph_logical_tensor_t will be calculated in a row major and contiguous way. Otherwise, Accessing the strides field is an undefined behavior.

Eg. dims (2, 3, 4, 5) will get strides (60, 20, 5, 1)

Parameters:

logical_tensor	Output logical tensor.
tid	The unique id of output logical tensor.
dtype	Elements data type.
ndims	Number of dimensions.
dims	Array of dimensions.
ltype	Layout type of the underlying tensor memory.
ptype	Tensor property type.

Returns:

dnnl_success on success or a status describing the error otherwise.

dnnl_status_t DNNL_API dnnl_graph_logical_tensor_init_with_strides(
    dnnl_graph_logical_tensor_t* logical_tensor,
    size_t tid,
    dnnl_data_type_t dtype,
    int32_t ndims,
    const dnnl_dims_t dims,
    const dnnl_dims_t strides,
    dnnl_graph_tensor_property_t ptype
    )

Initializes a logical tensor with dimensions and strides provided by user.

Note

Once strides are explicitly provided through the API, the layout_type in dnnl_graph_logical_tensor_t can only be dnnl_graph_layout_type_strided or dnnl_graph_layout_type_any.

Parameters:

logical_tensor	Output logical tensor.
tid	The unique id of output logical tensor.
dtype	Elements data type.
ndims	Number of dimensions.
dims	Array of dimensions.
strides	Array of strides.
ptype	Tensor property type.

Returns:

dnnl_success on success or a status describing the error otherwise.

dnnl_status_t DNNL_API dnnl_graph_logical_tensor_get_mem_size(
    const dnnl_graph_logical_tensor_t* logical_tensor,
    size_t* size
    )

Returns the memory size described by the logical tensor.

If it’s a strided layout, the size will be calculated by dims and strides. If it’s an opaque layout, the size will be decided by layout_id.

Parameters:

logical_tensor	Logical tensor.
size	Output memory size in bytes.

Returns:

dnnl_success on success or a status describing the error otherwise.

dnnl_status_t DNNL_API dnnl_graph_logical_tensor_is_equal(
    const dnnl_graph_logical_tensor_t* lt1,
    const dnnl_graph_logical_tensor_t* lt2,
    uint8_t* is_equal
    )

Compares if two logical tenors are equal.

Users can decide accordingly if layout reordering is needed for two logical tensors. The method will return true for below two circumstances:

the two logical tensors are equal regarding each field in the struct, eg. id, ndims, dims, layout type, property, etc.
If all other fields are equal but the layout types in two logical tensors are different, the method will return true when the underlying memory layout is the same. For example, one logical tensor has strided layout type while the other one has opaque layout type, but underneath, both layouts are NHWC, the method will still return true for this case.

Parameters:

lt1	The handle of first logical tensor.
lt2	The handle of second logical tensor.
is_equal	1 if these two logical tensors are equal, 0 otherwise.

Returns:

dnnl_success on success or a status describing the error otherwise.

Macros¶

#define DNNL_GRAPH_UNKNOWN_DIM

A wildcard value for dimensions that are unknown at a tensor or operation creation time.

#define DNNL_GRAPH_UNKNOWN_NDIMS

A wildcard value for number of dimensions which is unknown at a tensor or operation creation time.

Engine enum dnnl_graph_layout_type_t

oneDNN v3.7.0 documentation

Logical Tensor¶

Overview¶

Detailed Documentation¶

Global Functions¶

Macros¶