HostTensorDescriptor Struct Reference

HostTensorDescriptor Struct Reference#

Composable Kernel: HostTensorDescriptor Struct Reference
Public Types | Public Member Functions | Friends | List of all members
HostTensorDescriptor Struct Reference

A descriptor class for host tensors that manages tensor dimensions, strides, and layout. More...

#include <host_tensor.hpp>

Public Types

enum class  ChosenLayout {
  Original ,
  RowMajor ,
  ColumnMajor
}
 
using BaseTensorLayout = ck::tensor_layout::BaseTensorLayout
 
using DefaultLayout = BaseTensorLayout
 

Public Member Functions

template<typename Layout >
 HostTensorDescriptor (std::vector< std::size_t > lens, std::vector< std::size_t > strides, const Layout &layout=DefaultLayout())
 
 HostTensorDescriptor ()
 
template<typename F , typename OrigLayout >
void DispatchChosenLayout (ChosenLayout tag, const OrigLayout &orig, F &&f) const
 
template<typename Layout >
ChosenLayout HandleDefaultLayout (const Layout &)
 
template<typename Layout >
void CalculateStrides (const Layout &layout)
 
template<typename Layout >
void ValidateStrides (const Layout &layout) const
 
template<typename X , typename Layout = DefaultLayout, typename = std::enable_if_t<std::is_convertible_v<X, std::size_t> && std::is_convertible_v<Layout, BaseTensorLayout>>>
 HostTensorDescriptor (const std::initializer_list< X > &lens, const Layout &layout=Layout{})
 
template<typename Layout = DefaultLayout, typename = std::enable_if_t<std::is_convertible_v<Layout, BaseTensorLayout>>>
 HostTensorDescriptor (const std::initializer_list< ck::long_index_t > &lens, const Layout &layout=Layout{})
 
template<typename Lengths , typename Layout = DefaultLayout, typename = std::enable_if_t< (std::is_convertible_v<ck::ranges::range_value_t<Lengths>, std::size_t> || std::is_convertible_v<ck::ranges::range_value_t<Lengths>, ck::long_index_t>) && std::is_convertible_v<Layout, BaseTensorLayout>>>
 HostTensorDescriptor (const Lengths &lens, const Layout &layout=Layout{})
 
template<typename X , typename Y , typename = std::enable_if_t<std::is_convertible_v<X, std::size_t> && std::is_convertible_v<Y, std::size_t>>, typename Layout = DefaultLayout>
 HostTensorDescriptor (const std::initializer_list< X > &lens, const std::initializer_list< Y > &strides, const Layout &layout=Layout{})
 
template<typename Layout = DefaultLayout>
 HostTensorDescriptor (const std::initializer_list< ck::long_index_t > &lens, const std::initializer_list< ck::long_index_t > &strides, const Layout &layout=Layout{})
 
template<typename Strides , typename Layout = DefaultLayout>
 HostTensorDescriptor (const std::initializer_list< std::size_t > &lens, const Strides &strides, const Layout &layout=Layout{})
 
template<typename Lengths , typename Strides , typename Layout = DefaultLayout, typename = std::enable_if_t< ((std::is_convertible_v<ck::ranges::range_value_t<Lengths>, std::size_t> && std::is_convertible_v<ck::ranges::range_value_t<Strides>, std::size_t>) || (std::is_convertible_v<ck::ranges::range_value_t<Lengths>, ck::long_index_t> && std::is_convertible_v<ck::ranges::range_value_t<Strides>, ck::long_index_t>)) && std::is_convertible_v<Layout, BaseTensorLayout>>>
 HostTensorDescriptor (const Lengths &lens, const Strides &strides, const Layout &layout=Layout{})
 
std::size_t GetNumOfDimension () const
 
std::size_t GetElementSize () const
 
std::size_t GetElementSpaceSize () const
 
const std::vector< std::size_t > & GetLengths () const
 
const std::vector< std::size_t > & GetStrides () const
 
template<typename... Is>
std::size_t GetOffsetFromMultiIndex (Is... is) const
 
std::size_t GetOffsetFromMultiIndex (const std::vector< std::size_t > &iss) const
 

Friends

std::ostream & operator<< (std::ostream &os, const HostTensorDescriptor &desc)
 
std::ostream & operator<< (std::ostream &os, ChosenLayout tag)
 

Detailed Description

A descriptor class for host tensors that manages tensor dimensions, strides, and layout.

The HostTensorDescriptor provides a comprehensive interface for describing multi-dimensional tensors with configurable layouts and automatic stride calculation capabilities.

Stride Handling

The descriptor supports multiple stride specification modes:

  1. Explicit Strides: When strides are provided explicitly, they are validated against the specified layout to ensure memory access patterns are correct.
  2. Auto-calculated Strides: When strides are empty or all-zero, they are automatically calculated based on the tensor layout:
    • For RowMajor layout: rightmost dimension has stride 1, others calculated as cumulative products
    • For ColumnMajor layout: similar to RowMajor but with swapped stride positions for last two dimensions
  3. Partial Stride Specification: For GEMM layouts, unknown strides (represented as 0 or negative values) in the last two dimensions can be auto-calculated while preserving higher dimension strides.
  4. Bypass: When using BypassLayoutVerification layout, no stride calculation or validation is performed. That allows to pass in any arbitrary strides including 0.

For more details see CalculateStrides method.

Layout Support

  • GEMM Layouts: Supports RowMajor and ColumnMajor layouts with full validation
  • Convolution Layouts: Recognized but validation is not yet implemented
  • Abstract Layouts: BaseTensorLayout will attempt automatic layout detection for 2D tensors

Limitations

  1. Layout Detection: Automatic layout detection only works reliably for 2D tensors. This is done mostly for legacy GEMM cases to avoid modifying many existing GEMM tests to pass RowMajor/ColumnMajor explicitly. Higher-dimensional tensors with BaseTensorLayout will throw validation errors. For more details see HandleDefaultLayout method.
  2. Stride Validation: Only GEMM layouts (RowMajor/ColumnMajor) have full stride validation. Convolution layouts are accepted but not validated. For more details see ValidateStrides.
  3. GEMM Assumptions: For tensors with more than 2 dimensions, GEMM layout validation assumes the last two dimensions represent the height-width pattern (e.g., BHW or BWH for batched GEMM).
  4. Negative Stride Handling: Negative stride values are interpreted as "unknown" and converted to auto-calculated values only for supported layouts.

Thread Safety

This class is not thread-safe. External synchronization is required for concurrent access.

Usage Examples

// Auto-calculate strides for RowMajor layout
HostTensorDescriptor desc1({4, 3}, ck::tensor_layout::gemm::RowMajor{});
// Explicit strides with validation
HostTensorDescriptor desc2({4, 3}, {3, 1}, ck::tensor_layout::gemm::RowMajor{});
// Partial stride specification (auto-calculate unknown dimension)
HostTensorDescriptor desc3({4, 3}, {0, 1}, ck::tensor_layout::gemm::RowMajor{});
HostTensorDescriptor
A descriptor class for host tensors that manages tensor dimensions, strides, and layout.
Definition: host_tensor.hpp:171
ck::tensor_layout::gemm::RowMajor
Definition: tensor_layout.hpp:26

Member Typedef Documentation

◆ BaseTensorLayout

using HostTensorDescriptor::BaseTensorLayout = ck::tensor_layout::BaseTensorLayout

◆ DefaultLayout

using HostTensorDescriptor::DefaultLayout = BaseTensorLayout

Member Enumeration Documentation

◆ ChosenLayout

enum HostTensorDescriptor::ChosenLayout
strong
Enumerator
Original 
RowMajor 
ColumnMajor 

Constructor & Destructor Documentation

◆ HostTensorDescriptor() [1/9]

template<typename Layout >
HostTensorDescriptor::HostTensorDescriptor ( std::vector< std::size_t >  lens,
std::vector< std::size_t >  strides,
const Layout &  layout = DefaultLayout() 
)
inline

◆ HostTensorDescriptor() [2/9]

HostTensorDescriptor::HostTensorDescriptor ( )
inline

◆ HostTensorDescriptor() [3/9]

template<typename X , typename Layout = DefaultLayout, typename = std::enable_if_t<std::is_convertible_v<X, std::size_t> && std::is_convertible_v<Layout, BaseTensorLayout>>>
HostTensorDescriptor::HostTensorDescriptor ( const std::initializer_list< X > &  lens,
const Layout &  layout = Layout{} 
)
inline

◆ HostTensorDescriptor() [4/9]

template<typename Layout = DefaultLayout, typename = std::enable_if_t<std::is_convertible_v<Layout, BaseTensorLayout>>>
HostTensorDescriptor::HostTensorDescriptor ( const std::initializer_list< ck::long_index_t > &  lens,
const Layout &  layout = Layout{} 
)
inline

◆ HostTensorDescriptor() [5/9]

template<typename Lengths , typename Layout = DefaultLayout, typename = std::enable_if_t< (std::is_convertible_v<ck::ranges::range_value_t<Lengths>, std::size_t> || std::is_convertible_v<ck::ranges::range_value_t<Lengths>, ck::long_index_t>) && std::is_convertible_v<Layout, BaseTensorLayout>>>
HostTensorDescriptor::HostTensorDescriptor ( const Lengths &  lens,
const Layout &  layout = Layout{} 
)
inline

◆ HostTensorDescriptor() [6/9]

template<typename X , typename Y , typename = std::enable_if_t<std::is_convertible_v<X, std::size_t> && std::is_convertible_v<Y, std::size_t>>, typename Layout = DefaultLayout>
HostTensorDescriptor::HostTensorDescriptor ( const std::initializer_list< X > &  lens,
const std::initializer_list< Y > &  strides,
const Layout &  layout = Layout{} 
)
inline

◆ HostTensorDescriptor() [7/9]

template<typename Layout = DefaultLayout>
HostTensorDescriptor::HostTensorDescriptor ( const std::initializer_list< ck::long_index_t > &  lens,
const std::initializer_list< ck::long_index_t > &  strides,
const Layout &  layout = Layout{} 
)
inline

◆ HostTensorDescriptor() [8/9]

template<typename Strides , typename Layout = DefaultLayout>
HostTensorDescriptor::HostTensorDescriptor ( const std::initializer_list< std::size_t > &  lens,
const Strides &  strides,
const Layout &  layout = Layout{} 
)
inline

◆ HostTensorDescriptor() [9/9]

template<typename Lengths , typename Strides , typename Layout = DefaultLayout, typename = std::enable_if_t< ((std::is_convertible_v<ck::ranges::range_value_t<Lengths>, std::size_t> && std::is_convertible_v<ck::ranges::range_value_t<Strides>, std::size_t>) || (std::is_convertible_v<ck::ranges::range_value_t<Lengths>, ck::long_index_t> && std::is_convertible_v<ck::ranges::range_value_t<Strides>, ck::long_index_t>)) && std::is_convertible_v<Layout, BaseTensorLayout>>>
HostTensorDescriptor::HostTensorDescriptor ( const Lengths &  lens,
const Strides &  strides,
const Layout &  layout = Layout{} 
)
inline

Member Function Documentation

◆ CalculateStrides()

template<typename Layout >
void HostTensorDescriptor::CalculateStrides ( const Layout &  layout)
inline

◆ DispatchChosenLayout()

template<typename F , typename OrigLayout >
void HostTensorDescriptor::DispatchChosenLayout ( ChosenLayout  tag,
const OrigLayout &  orig,
F &&  f 
) const
inline

◆ GetElementSize()

std::size_t HostTensorDescriptor::GetElementSize ( ) const

◆ GetElementSpaceSize()

std::size_t HostTensorDescriptor::GetElementSpaceSize ( ) const

◆ GetLengths()

const std::vector<std::size_t>& HostTensorDescriptor::GetLengths ( ) const

◆ GetNumOfDimension()

std::size_t HostTensorDescriptor::GetNumOfDimension ( ) const

◆ GetOffsetFromMultiIndex() [1/2]

std::size_t HostTensorDescriptor::GetOffsetFromMultiIndex ( const std::vector< std::size_t > &  iss) const
inline

◆ GetOffsetFromMultiIndex() [2/2]

template<typename... Is>
std::size_t HostTensorDescriptor::GetOffsetFromMultiIndex ( Is...  is) const
inline

◆ GetStrides()

const std::vector<std::size_t>& HostTensorDescriptor::GetStrides ( ) const

◆ HandleDefaultLayout()

template<typename Layout >
ChosenLayout HostTensorDescriptor::HandleDefaultLayout ( const Layout &  )
inline

◆ ValidateStrides()

template<typename Layout >
void HostTensorDescriptor::ValidateStrides ( const Layout &  layout) const
inline

Friends And Related Function Documentation

◆ operator<< [1/2]

std::ostream& operator<< ( std::ostream &  os,
ChosenLayout  tag 
)
friend

◆ operator<< [2/2]

std::ostream& operator<< ( std::ostream &  os,
const HostTensorDescriptor &  desc 
)
friend
The documentation for this struct was generated from the following file:
  • /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-composable-kernel/checkouts/develop/include/ck/library/utility/host_tensor.hpp