注意

RAFT 中的向量搜索和聚类算法正在迁移到一个名为 cuVS 的专用向量搜索库。在此迁移期间，我们将继续支持 RAFT 中的向量搜索算法，但在 RAPIDS 24.06 (六月) 版本之后将不再更新。我们计划在 RAPIDS 24.10 (十月) 版本之前完成迁移，并在 24.12 (十二月) 版本中将其从 RAFT 中完全移除。

mdarray: 多维拥有容器

#include <raft/core/mdarray.hpp>

template<typename ...Tn>
bool is_array_interface_v = is_array_interface<Tn...>::value

\brief 布尔值，用于确定可变模板类型 Tn 是否为 raft::array_interface 或派生类型，或任何具有返回 raft::host_mdspan 或 raft::device_mdspan 的成员函数 view() 的类型

template<typename Base>
class array_interface

#include <mdarray.hpp>

用于实现拥有多维数组的接口。

raft::array_interace 是 mdspan 的拥有容器类型的接口。检查 raft::mdarray 的实现，它使用 Curiously Recurring Template Pattern 实现了 raft::array_interface。此接口调用方法 view()，其实现由实现类提供。view() 必须返回类型为 raft::host_mdspan 或 raft::device_mdspan 或从它们派生的任何类型的对象。

子类包括 raft::mdarray< value_type, extents_type, layout_type, typename container_policy_type::template container_policy< MemType > >, raft::mdarray< value_type, matrix_extent< index_type >, LayoutPolicy, ContainerPolicy >

template<typename...>
struct is_array_interface : public std::true_type

#include <mdarray.hpp>

template<typename T1>
struct is_array_interface<T1> : public std::true_type, public raft::detail::is_array_interface<std::remove_const_t<T>>

#include <mdarray.hpp>

template<typename T1, typename ...Tn>
struct is_array_interface<T1, Tn...> : public std::true_type, public std::conditional_t<detail::is_array_interface_v<T1>, is_array_interface<Tn...>, std::false_type>

#include <mdarray.hpp>

template<typename ElementType, typename Extents, typename LayoutPolicy, typename ContainerPolicy>
class mdarray : public raft::array_interface<mdarray<ElementType, Extents, LayoutPolicy, ContainerPolicy>>

#include <mdarray.hpp>

从 c++ mdarray 提案修改而来。

https://isocpp.org/files/papers/D1684R0.html

mdarray 是 mdspan 的容器类型，具有类似的模板参数。然而它们之间存在一些不一致之处。我们做了一些修改以满足我们的需求，如下所示。

• 布局策略不同，raft 中的 mdarray 直接使用 std::experimental::extent，就像 mdspan 一样，而参考实现中的 mdarray 使用可变参数模板。

• 参考实现中的大部分构造函数都被移除，以确保遵循 CUDA 流。请注意，此类别与 CUDA 不耦合，因此仅在设备变体使用时才使用。

• unique_size 未实现，这在提案中仍在进行中。

• 对于容器策略，我们采用提案 [sec 2.4.3] 中记录的另一种方法，这需要一个额外的 make_accessor 方法才能在 mdspan 中使用。容器策略参考实现有多个 access 方法，可以满足 mdarray 和 mdspan 的需求。这对我们来说更困难，因为策略可能包含在 CUDA 内核中不需要的状态。此外，在主机上，我们将实际值的代理作为 device_ref 返回，因此不同的访问方法将具有不同的返回类型，这是不太理想的。

• 出于上述原因，也移除了从具有不同策略类型的其他 mdarray 复制的功能。

公共类型

using view_type = view_type_impl<element_type>

由 view 方法返回的 mdspan 类型。

公共函数

inline RAFT_MDARRAY_CTOR_CONSTEXPR mdarray(raft::resources const &handle, mapping_type const &m, container_policy_type const &cp)

唯一可以创建存储的构造函数，接受 raft::resources 以便设备实现可以确保使用相关的 CUDA 流进行分配。

inline auto view() noexcept

获取一个 mdspan。

inline auto view() const noexcept

获取一个 mdspan<const T>

template<typename ...IndexType>
inline std::enable_if_t<sizeof...(IndexType) == extents_type::rank() && (std::is_convertible_v<IndexType, index_type>&&...)&&std::is_constructible_v<extents_type, IndexType...>, reference> operator()(IndexType&&... indices)

索引运算符，由于它会触发设备与主机之间的复制，请谨慎使用。

template<typename ...IndexType>
inline std::enable_if_t<sizeof...(IndexType) == extents_type::rank() && (std::is_convertible_v<IndexType, index_type>&&...)&&std::is_constructible_v<extents_type, IndexType...> && std::is_constructible<mapping_type, extents_type>::value, const_reference> operator()(IndexType&&... indices) const

索引运算符，由于它会触发设备与主机之间的复制，请谨慎使用。

inline RAFT_INLINE_FUNCTION constexpr auto extent (size_t r) const noexcept -> index_type

维度 r 的范围

设备词汇

#include <raft/core/device_mdarray.hpp>

template<typename ElementType, typename Extents, typename LayoutPolicy = layout_c_contiguous, typename ContainerPolicy = device_uvector_policy<ElementType>>
using raft::device_mdarray = mdarray<ElementType, Extents, LayoutPolicy, device_accessor<ContainerPolicy>>

具有设备容器策略的 mdarray

模板参数：

• ElementType – 元素的类型

• Extents – 定义形状

• LayoutPolicy – 用于索引跨度和布局顺序的策略

• ContainerPolicy – 存储和访问器策略

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
using raft::device_matrix = device_mdarray<ElementType, matrix_extent<IndexType>, LayoutPolicy>

c-contiguous 设备矩阵的简写。

模板参数：

• ElementType – 矩阵元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
using raft::device_vector = device_mdarray<ElementType, vector_extent<IndexType>, LayoutPolicy>

1 维设备 mdarray 的简写。

模板参数：

• ElementType – 向量元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

template<typename ElementType, typename IndexType = std::uint32_t>
using raft::device_scalar = device_mdarray<ElementType, scalar_extent<IndexType>>

0 维主机 mdarray（标量）的简写。

模板参数：

• ElementType – 标量元素的类型

• IndexType – 范围的索引类型

设备工厂函数

#include <raft/core/device_mdarray.hpp>

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
auto raft::make_device_matrix(raft::resources const &handle, IndexType n_rows, IndexType n_cols)

创建一个 2 维 c-contiguous 设备 mdarray。

模板参数：

• ElementType – 矩阵元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

参数：

• handle – [in] 用于管理昂贵资源的 raft 句柄

• n_rows – [in] 矩阵中的行数

• n_cols – [in] 矩阵中的列数

返回：

raft::device_matrix

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
auto raft::make_device_vector(raft::resources const &handle, IndexType n)

创建一个 1 维设备 mdarray。

模板参数：

• ElementType – 向量元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

参数：

• handle – [in] 用于管理昂贵 cuda 资源的 raft 句柄

• n – [in] 向量中的元素数量

返回：

raft::device_vector

template<typename ElementType, typename IndexType = std::uint32_t>
auto raft::make_device_scalar(raft::resources const &handle, ElementType const &v)

从 v 创建一个设备标量。

模板参数：

• ElementType – 标量元素的类型

• IndexType – 范围的索引类型

参数：

• handle – [in] 用于管理昂贵 cuda 资源的 raft 句柄

• v – [in] 设备上要包装的标量

返回：

raft::device_scalar

主机词汇

#include <raft/core/host_mdarray.hpp>

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
using raft::host_matrix = host_mdarray<ElementType, matrix_extent<IndexType>, LayoutPolicy>

c-contiguous 主机矩阵的简写。

模板参数：

• ElementType – 矩阵元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
using raft::host_vector = host_mdarray<ElementType, vector_extent<IndexType>, LayoutPolicy>

1 维主机 mdarray 的简写。

模板参数：

• ElementType – 向量元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

template<typename ElementType, typename IndexType = std::uint32_t>
using raft::host_scalar = host_mdarray<ElementType, scalar_extent<IndexType>>

0 维主机 mdarray（标量）的简写。

模板参数：

• ElementType – 标量元素的类型

• IndexType – 范围的索引类型

主机工厂函数

#include <raft/core/host_mdarray.hpp>

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous, size_t... Extents>
auto make_host_mdarray(raft::resources &res, extents<IndexType, Extents...> exts)

创建一个主机 mdarray。

模板参数：

• ElementType – 矩阵元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

参数：

• res – [in] 用于管理昂贵资源的 raft 句柄

• exts – [in] 数组的维度（整数序列）

返回：

raft::host_mdarray

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
auto make_host_matrix(raft::resources &res, IndexType n_rows, IndexType n_cols)

创建一个 2 维 c-contiguous 主机 mdarray。

模板参数：

• ElementType – 矩阵元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

参数：

• res – [in] 用于管理昂贵资源的 raft 句柄

• n_rows – [in] 矩阵中的行数

• n_cols – [in] 矩阵中的列数

返回：

raft::host_matrix

template<typename ElementType, typename IndexType = std::uint32_t>
auto make_host_scalar(raft::resources &res, ElementType const &v)

从 v 创建一个主机标量。

模板参数：

• ElementType – 标量元素的类型

• IndexType – 范围的索引类型

参数：

• res – [in] 用于管理昂贵资源的 raft 句柄

• v – [in] 要包装的标量类型

返回：

raft::host_scalar

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
auto make_host_vector(raft::resources &res, IndexType n)

创建一个 1 维主机 mdarray。

模板参数：

• ElementType – 向量元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

参数：

• res – [in] 用于管理昂贵资源的 raft 句柄

• n – [in] 向量中的元素数量

返回：

raft::host_vector

托管词汇

#include <raft/core/managed_mdarray.hpp>

template<typename ElementType, typename Extents, typename LayoutPolicy = layout_c_contiguous, typename ContainerPolicy = managed_uvector_policy<ElementType>>
using raft::managed_mdarray = mdarray<ElementType, Extents, LayoutPolicy, managed_accessor<ContainerPolicy>>

具有托管容器策略的 mdarray

模板参数：

• ElementType – 元素的类型

• Extents – 定义形状

• LayoutPolicy – 用于索引跨度和布局顺序的策略

• ContainerPolicy – 存储和访问器策略

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
using raft::managed_matrix = managed_mdarray<ElementType, matrix_extent<IndexType>, LayoutPolicy>

c-contiguous 托管矩阵的简写。

模板参数：

• ElementType – 矩阵元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
using raft::managed_vector = managed_mdarray<ElementType, vector_extent<IndexType>, LayoutPolicy>

1 维托管 mdarray 的简写。

模板参数：

• ElementType – 向量元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

template<typename ElementType, typename IndexType = std::uint32_t>
using raft::managed_scalar = managed_mdarray<ElementType, scalar_extent<IndexType>>

0 维主机 mdarray（标量）的简写。

模板参数：

• ElementType – 标量元素的类型

• IndexType – 范围的索引类型

托管工厂

#include <raft/core/managed_mdarray.hpp>

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
auto raft::make_managed_matrix(raft::resources const &handle, IndexType n_rows, IndexType n_cols)

创建一个二维 c-contiguous 托管 mdarray。

模板参数：

• ElementType – 矩阵元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

参数：

• handle – [in] 用于管理昂贵资源的 raft 句柄

• n_rows – [in] 矩阵中的行数

• n_cols – [in] 矩阵中的列数

返回：

raft::managed_matrix

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
auto raft::make_managed_vector(raft::resources const &handle, IndexType n)

创建一个一维托管 mdarray。

模板参数：

• ElementType – 向量元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

参数：

• handle – [in] 用于管理昂贵 cuda 资源的 raft 句柄

• n – [in] 向量中的元素数量

返回：

raft::managed_vector

template<typename ElementType, typename IndexType = std::uint32_t>
auto raft::make_managed_scalar(raft::resources const &handle, ElementType const &v)

从 v 创建一个托管标量。

模板参数：

• ElementType – 标量元素的类型

• IndexType – 范围的索引类型

参数：

• handle – [in] 用于管理昂贵 cuda 资源的 raft 句柄

• v – [输入] 要在托管内存中包装的标量

返回：

raft::managed_scalar

固定内存词汇

#include <raft/core/pinned_mdarray.hpp>

template<typename ElementType, typename Extents, typename LayoutPolicy = layout_c_contiguous, typename ContainerPolicy = pinned_vector_policy<ElementType>>
using raft::pinned_mdarray = mdarray<ElementType, Extents, LayoutPolicy, pinned_accessor<ContainerPolicy>>

使用固定内存容器策略的 mdarray

模板参数：

• ElementType – 元素的类型

• Extents – 定义形状

• LayoutPolicy – 用于索引跨度和布局顺序的策略

• ContainerPolicy – 存储和访问器策略

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
using raft::pinned_matrix = pinned_mdarray<ElementType, matrix_extent<IndexType>, LayoutPolicy>

c-contiguous 固定内存矩阵的简写。

模板参数：

• ElementType – 矩阵元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
using raft::pinned_vector = pinned_mdarray<ElementType, vector_extent<IndexType>, LayoutPolicy>

一维固定内存 mdarray 的简写。

模板参数：

• ElementType – 向量元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

template<typename ElementType, typename IndexType = std::uint32_t>
using raft::pinned_scalar = pinned_mdarray<ElementType, scalar_extent<IndexType>>

0 维主机 mdarray（标量）的简写。

模板参数：

• ElementType – 标量元素的类型

• IndexType – 范围的索引类型

固定内存工厂

#include <raft/core/pinned_mdarray.hpp>

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
auto raft::make_pinned_matrix(raft::resources const &handle, IndexType n_rows, IndexType n_cols)

创建一个二维 c-contiguous 固定内存 mdarray。

模板参数：

• ElementType – 矩阵元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

参数：

• handle – [in] 用于管理昂贵资源的 raft 句柄

• n_rows – [in] 矩阵中的行数

• n_cols – [in] 矩阵中的列数

返回：

raft::pinned_matrix

template<typename ElementType, typename IndexType = std::uint32_t, typename LayoutPolicy = layout_c_contiguous>
auto raft::make_pinned_vector(raft::resources const &handle, IndexType n)

创建一个一维固定内存 mdarray。

模板参数：

• ElementType – 向量元素的类型

• IndexType – 范围的索引类型

• LayoutPolicy – 跨度和布局顺序的策略

参数：

• handle – [in] 用于管理昂贵 cuda 资源的 raft 句柄

• n – [in] 向量中的元素数量

返回：

raft::pinned_vector

template<typename ElementType, typename IndexType = std::uint32_t>
auto raft::make_pinned_scalar(raft::resources const &handle, ElementType const &v)

从 v 创建一个固定内存标量。

模板参数：

• ElementType – 标量元素的类型

• IndexType – 范围的索引类型

参数：

• handle – [in] 用于管理昂贵 cuda 资源的 raft 句柄

• v – [输入] 要在固定内存中包装的标量

返回：

raft::pinned_scalar