Attention

The vector search and clustering algorithms in RAFT are being migrated to a new library dedicated to vector search called cuVS. We will continue to support the vector search algorithms in RAFT during this move, but will no longer update them after the RAPIDS 24.06 (June) release. We plan to complete the migration by RAPIDS 24.08 (August) release.

mdspan: Multi-dimensional Non-owning View#

#include <raft/core/mdspan.hpp>

template<typename ElementType, typename Extents, typename LayoutPolicy = layout_c_contiguous, typename AccessorPolicy = std::experimental::default_accessor<ElementType>> using raft::mdspan = std::experimental::mdspan<ElementType, Extents, LayoutPolicy, AccessorPolicy>#

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous, bool is_host_accessible = false, bool is_device_accessible = true, size_t... Extents> constexpr auto raft::make_mdspan(ElementType *ptr, extents<IndexType, Extents...> exts)#

Create a raft::mdspan.

Template Parameters:

ElementType – the data type of the matrix elements
IndexType – the index type of the extents
LayoutPolicy – policy for strides and layout ordering
is_host_accessible – whether the data is accessible on host
is_device_accessible – whether the data is accessible on device

Parameters:

ptr – Pointer to the data
exts – dimensionality of the array (series of integers)

Returns:

raft::mdspan

template<typename IndexType, typename ...Extents, typename = ensure_integral_extents<Extents...>> constexpr auto raft::make_extents(Extents... exts)#

Create raft::extents to specify dimensionality.

Template Parameters:

IndexType – The type of each dimension of the extents
Extents – Dimensions (a series of integers)

Parameters:

exts – The desired dimensions

Returns:

raft::extents

template<typename Extents, typename Strides> auto raft::make_strided_layout(Extents extents, Strides strides)#

Create a layout_stride mapping from extents and strides.

Parameters:

extents – [in] the dimensionality of the layout
strides – [in] the strides between elements in the layout

Returns:

raft::layout_stride::mapping<Extents>

template<typename Idx, typename IndexType, typename LayoutPolicy, size_t... Exts> RAFT_INLINE_FUNCTION auto unravel_index(Idx idx, extents<IndexType, Exts...> shape, LayoutPolicy const &layout)#

Turns linear index into coordinate. Similar to numpy unravel_index.

auto m = make_host_matrix<float>(7, 6);
auto m_v = m.view();
auto coord = unravel_index(2, m.extents(), typename decltype(m)::layout_type{});
std::apply(m_v, coord) = 2;

Parameters:

idx – The linear index.
shape – The shape of the array to use.
layout – Must be layout_c_contiguous (row-major) in current implementation.

Returns:

A std::tuple that represents the coordinate.

template<typename Extents, typename Strides> auto is_c_contiguous(Extents const &extents, Strides const &strides) -> bool#: Whether the strides imply a c-contiguous layout.

template<typename Extents, typename Strides> auto is_f_contiguous(Extents const &extents, Strides const &strides) -> bool#: Whether the strides imply a f-contiguous layout.

template<class ElementType, class Extents, class Layout, class Accessor> auto make_const_mdspan(mdspan<ElementType, Extents, Layout, Accessor> mds)#

Create a copy of the given mdspan with const element type.

Template Parameters:

ElementType – the const-qualified data type of the mdspan elements
Extents – raft::extents for dimensions
Layout – policy for strides and layout ordering
Accessor – Accessor policy for the input and output

Parameters:

mds – raft::mdspan object

Returns:

raft::mdspan

Device Vocabulary#

#include <raft/core/device_mdspan.hpp>

template<typename ElementType, typename Extents, typename LayoutPolicy = layout_c_contiguous, typename AccessorPolicy = std::experimental::default_accessor<ElementType>> using raft::device_mdspan = mdspan<ElementType, Extents, LayoutPolicy, device_accessor<AccessorPolicy>>#: std::experimental::mdspan with device tag to avoid accessing incorrect memory location.

template<typename T, bool B> struct is_device_mdspan : public std::false_type#

template<typename T> using raft::is_device_mdspan_t = is_device_mdspan<T, is_mdspan_v<T>>#: \brief Boolean to determine if template type T is either raft::device_mdspan or a derived type

template<typename T> using raft::is_input_device_mdspan_t = is_device_mdspan<T, is_input_mdspan_v<T>>#

template<typename T> using raft::is_output_device_mdspan_t = is_device_mdspan<T, is_output_mdspan_v<T>>#

template<typename ...Tn> using raft::enable_if_device_mdspan = std::enable_if_t<is_device_mdspan_v<Tn...>>#

template<typename ...Tn> using raft::enable_if_input_device_mdspan = std::enable_if_t<is_input_device_mdspan_v<Tn...>>#

template<typename ...Tn> using raft::enable_if_output_device_mdspan = std::enable_if_t<is_output_device_mdspan_v<Tn...>>#

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous> using raft::device_matrix_view = device_mdspan<ElementType, matrix_extent<IndexType>, LayoutPolicy>#

Shorthand for c-contiguous device matrix view.

Template Parameters:

ElementType – the data type of the matrix elements
IndexType – the index type of the extents
LayoutPolicy – policy for strides and layout ordering

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous> using raft::device_vector_view = device_mdspan<ElementType, vector_extent<IndexType>, LayoutPolicy>#

Shorthand for 1-dim device mdspan.

Template Parameters:

ElementType – the data type of the vector elements
IndexType – the index type of the extents
LayoutPolicy – policy for strides and layout ordering

template<typename ElementType, typename IndexType = std::uint32_t> using raft::device_scalar_view = device_mdspan<ElementType, scalar_extent<IndexType>>#

Shorthand for 0-dim host mdspan (scalar).

Template Parameters:

ElementType – the data type of the scalar element
IndexType – the index type of the extents

Device Factories#

#include <raft/core/device_mdspan.hpp>

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous> auto constexpr raft::make_device_matrix_view(ElementType *ptr, IndexType n_rows, IndexType n_cols)#

Create a 2-dim c-contiguous mdspan instance for device pointer. It’s expected that the given layout policy match the layout of the underlying pointer.

Template Parameters:

ElementType – the data type of the matrix elements
LayoutPolicy – policy for strides and layout ordering
IndexType – the index type of the extents

Parameters:

ptr – [in] on device to wrap
n_rows – [in] number of rows in pointer
n_cols – [in] number of columns in pointer

template<typename ElementType, typename IndexType, typename LayoutPolicy = layout_c_contiguous> auto constexpr raft::make_device_vector_view(ElementType *ptr, IndexType n)#

Create a 1-dim mdspan instance for device pointer.

Template Parameters:

ElementType – the data type of the vector elements
IndexType – the index type of the extents
LayoutPolicy – policy for strides and layout ordering

Parameters:

ptr – [in] on device to wrap
n – [in] number of elements in pointer

Returns:

raft::device_vector_view

template<typename ElementType, typename IndexType = std::uint32_t> auto constexpr raft::make_device_scalar_view(ElementType *ptr)#

Create a 0-dim (scalar) mdspan instance for device value.

Template Parameters:

ElementType – the data type of the matrix elements
IndexType – the index type of the extents

Parameters:

ptr – [in] on device to wrap

Managed Vocabulary#

#include <raft/core/managed_mdspan.hpp>

template<typename ElementType, typename Extents, typename LayoutPolicy = layout_c_contiguous, typename AccessorPolicy = std::experimental::default_accessor<ElementType>> using raft::managed_mdspan = mdspan<ElementType, Extents, LayoutPolicy, managed_accessor<AccessorPolicy>>#: std::experimental::mdspan with managed tag to indicate host/device accessibility

template<typename T, bool B> struct is_managed_mdspan : public std::false_type#

template<typename T> using raft::is_managed_mdspan_t = is_managed_mdspan<T, is_mdspan_v<T>>#: \brief Boolean to determine if template type T is either raft::managed_mdspan or a derived type

template<typename T> using raft::is_input_managed_mdspan_t = is_managed_mdspan<T, is_input_mdspan_v<T>>#

template<typename T> using raft::is_output_managed_mdspan_t = is_managed_mdspan<T, is_output_mdspan_v<T>>#

template<typename ...Tn> using raft::enable_if_managed_mdspan = std::enable_if_t<is_managed_mdspan_v<Tn...>>#

template<typename ...Tn> using raft::enable_if_input_managed_mdspan = std::enable_if_t<is_input_managed_mdspan_v<Tn...>>#

template<typename ...Tn> using raft::enable_if_output_managed_mdspan = std::enable_if_t<is_output_managed_mdspan_v<Tn...>>#

Managed Factories#

#include <raft/core/managed_mdspan.hpp>

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous, size_t... Extents> auto constexpr raft::make_managed_mdspan(ElementType *ptr, extents<IndexType, Extents...> exts)#

Create a raft::managed_mdspan.

Template Parameters:

ElementType – the data type of the matrix elements
IndexType – the index type of the extents
LayoutPolicy – policy for strides and layout ordering

Parameters:

ptr – Pointer to the data
exts – dimensionality of the array (series of integers)

Returns:

raft::managed_mdspan

Host Vocabulary#

#include <raft/core/host_mdspan.hpp>

template<typename ElementType, typename Extents, typename LayoutPolicy = layout_c_contiguous, typename AccessorPolicy = std::experimental::default_accessor<ElementType>> using raft::host_mdspan = mdspan<ElementType, Extents, LayoutPolicy, host_accessor<AccessorPolicy>>#: std::experimental::mdspan with host tag to avoid accessing incorrect memory location.

template<typename T, bool B> struct is_host_mdspan : public std::false_type#

template<typename T> using raft::is_host_mdspan_t = is_host_mdspan<T, is_mdspan_v<T>>#: \brief Boolean to determine if template type T is either raft::host_mdspan or a derived type

template<typename T> using raft::is_input_host_mdspan_t = is_host_mdspan<T, is_input_mdspan_v<T>>#

template<typename T> using raft::is_output_host_mdspan_t = is_host_mdspan<T, is_output_mdspan_v<T>>#

template<typename ...Tn> using raft::enable_if_host_mdspan = std::enable_if_t<is_input_mdspan_v<Tn...>>#

template<typename ...Tn> using raft::enable_if_input_host_mdspan = std::enable_if_t<is_input_host_mdspan_v<Tn...>>#

template<typename ...Tn> using raft::enable_if_output_host_mdspan = std::enable_if_t<is_output_host_mdspan_v<Tn...>>#

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous> using raft::host_matrix_view = host_mdspan<ElementType, matrix_extent<IndexType>, LayoutPolicy>#

Shorthand for c-contiguous host matrix view.

Template Parameters:

ElementType – the data type of the matrix elements
IndexType – the index type of the extents
LayoutPolicy – policy for strides and layout ordering

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous> using raft::host_vector_view = host_mdspan<ElementType, vector_extent<IndexType>, LayoutPolicy>#

Shorthand for 1-dim host mdspan.

Template Parameters:

ElementType – the data type of the vector elements
IndexType – the index type of the extents

template<typename ElementType, typename IndexType = std::uint32_t> using raft::host_scalar_view = host_mdspan<ElementType, scalar_extent<IndexType>>#

Shorthand for 0-dim host mdspan (scalar).

Template Parameters:

ElementType – the data type of the scalar element
IndexType – the index type of the extents

Host Factories#

#include <raft/core/host_mdspan.hpp>

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous> auto constexpr raft::make_host_matrix_view(ElementType *ptr, IndexType n_rows, IndexType n_cols)#

Create a 2-dim c-contiguous mdspan instance for host pointer. It’s expected that the given layout policy match the layout of the underlying pointer.

Template Parameters:

ElementType – the data type of the matrix elements
IndexType – the index type of the extents
LayoutPolicy – policy for strides and layout ordering

Parameters:

ptr – [in] on host to wrap
n_rows – [in] number of rows in pointer
n_cols – [in] number of columns in pointer

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous> auto constexpr raft::make_host_vector_view(ElementType *ptr, IndexType n)#

Create a 1-dim mdspan instance for host pointer.

Template Parameters:

ElementType – the data type of the vector elements
IndexType – the index type of the extents

Parameters:

ptr – [in] on host to wrap
n – [in] number of elements in pointer

Returns:

raft::host_vector_view

template<typename ElementType, typename IndexType = std::uint32_t> auto constexpr raft::make_host_scalar_view(ElementType *ptr)#

Create a 0-dim (scalar) mdspan instance for host value.

Template Parameters:

ElementType – the data type of the matrix elements
IndexType – the index type of the extents

Parameters:

ptr – [in] on device to wrap

Pinned Vocabulary#

#include <raft/core/pinned_mdspan.hpp>

template<typename ElementType, typename Extents, typename LayoutPolicy = layout_c_contiguous, typename AccessorPolicy = std::experimental::default_accessor<ElementType>> using raft::pinned_mdspan = mdspan<ElementType, Extents, LayoutPolicy, pinned_accessor<AccessorPolicy>>#: std::experimental::mdspan with pinned tag to indicate host/device accessibility

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous> using raft::pinned_matrix_view = pinned_mdspan<ElementType, matrix_extent<IndexType>, LayoutPolicy>#

Shorthand for c-contiguous pinned matrix view.

Template Parameters:

ElementType – the data type of the matrix elements
IndexType – the index type of the extents
LayoutPolicy – policy for strides and layout ordering

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous> using raft::pinned_vector_view = pinned_mdspan<ElementType, vector_extent<IndexType>, LayoutPolicy>#

Shorthand for 1-dim pinned mdspan.

Template Parameters:

ElementType – the data type of the vector elements
IndexType – the index type of the extents
LayoutPolicy – policy for strides and layout ordering

template<typename ElementType, typename IndexType = std::uint32_t> using raft::pinned_scalar_view = pinned_mdspan<ElementType, scalar_extent<IndexType>>#

Shorthand for 0-dim pinned mdspan (scalar).

Template Parameters:

ElementType – the data type of the scalar element
IndexType – the index type of the extents

Pinned Factories#

#include <raft/core/pinned_mdspan.hpp>

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous> auto constexpr raft::make_pinned_matrix_view(ElementType *ptr, IndexType n_rows, IndexType n_cols)#

Create a 2-dim c-contiguous mdspan instance for pinned pointer. It’s expected that the given layout policy match the layout of the underlying pointer.

Template Parameters:

ElementType – the data type of the matrix elements
LayoutPolicy – policy for strides and layout ordering
IndexType – the index type of the extents

Parameters:

ptr – [in] to pinned memory to wrap
n_rows – [in] number of rows in pointer
n_cols – [in] number of columns in pointer

Warning

doxygenfunction: Unable to resolve function “raft::make_pinned_vector_view” with arguments None in doxygen xml output for project “RAFT” from directory: ../../cpp/doxygen/_xml/. Potential matches:

- template<typename ElementType, typename IndexType, typename LayoutPolicy = layout_c_contiguous> auto constexpr make_pinned_vector_view(ElementType *ptr, IndexType n)
- template<typename ElementType, typename IndexType, typename LayoutPolicy = layout_c_contiguous> auto constexpr make_pinned_vector_view(ElementType *ptr, const typename LayoutPolicy::template mapping<vector_extent<IndexType>> &mapping)

template<typename ElementType, typename IndexType = std::uint32_t> auto constexpr raft::make_pinned_scalar_view(ElementType *ptr)#

Create a 0-dim (scalar) mdspan instance for pinned value.

Template Parameters:

ElementType – the data type of the matrix elements
IndexType – the index type of the extents

Parameters:

ptr – [in] to pinned memory to wrap

Validation Routines#

#include <raft/core/mdspan.hpp>

template<typename T, typename = void> struct is_mdspan : public std::false_type#

template<typename T> using raft::is_mdspan_t = is_mdspan<std::remove_const_t<T>>#

template<typename T, typename = void> struct is_input_mdspan : public std::false_type#

template<typename T> using raft::is_input_mdspan_t = is_input_mdspan<T>#

template<typename T, typename = void> struct is_output_mdspan : public std::false_type#

template<typename T> using raft::is_output_mdspan_t = is_output_mdspan<T>#

template<typename ...Tn> using raft::enable_if_mdspan = std::enable_if_t<is_mdspan_v<Tn...>>#

template<typename ...Tn> using raft::enable_if_input_mdspan = std::enable_if_t<is_input_mdspan_v<Tn...>>#

template<typename ...Tn> using raft::enable_if_output_mdspan = std::enable_if_t<is_output_mdspan_v<Tn...>>#