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::HostTensorDescriptor
HostTensorDescriptor(std::vector< std::size_t > lens, std::vector< std::size_t > strides, const Layout &layout=DefaultLayout())
Definition library/utility/host_tensor.hpp:186
ck::tensor_layout::gemm::RowMajor
Definition tensor_operation/gpu/device/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 class 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

◆ 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: