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.10 (October) release and they will be removed from RAFT altogether in the 24.12 (December) release.

Matrix Selection#

Copy#

#include <raft/matrix/copy.cuh>

namespace raft::matrix

template<typename m_t, typename idx_t, typename layout> void copy_rows(raft::resources const &handle, raft::device_matrix_view<const m_t, idx_t, layout> in, raft::device_matrix_view<m_t, idx_t, layout> out, raft::device_vector_view<const idx_t, idx_t> indices)#

Copy selected rows of the input matrix into contiguous space.

On exit out[i + k*n_rows] = in[indices[i] + k*n_rows], where i = 0..n_rows_indices-1, and k = 0..n_cols-1.

Parameters:

handle – [in] raft handle
in – [in] input matrix
out – [out] output matrix
indices – [in] of the rows to be copied

template<typename m_t, typename matrix_idx_t> void copy(raft::resources const &handle, raft::device_matrix_view<const m_t, matrix_idx_t, row_major> in, raft::device_matrix_view<m_t, matrix_idx_t, row_major> out)#

copy matrix operation for row major matrices.

Parameters:

handle – [in] raft handle
in – [in] input matrix
out – [out] output matrix

template<typename m_t, typename matrix_idx_t> void copy(raft::resources const &handle, raft::device_matrix_view<const m_t, matrix_idx_t, col_major> in, raft::device_matrix_view<m_t, matrix_idx_t, col_major> out)#

copy matrix operation for column major matrices.

Parameters:

handle – [in] raft handle
in – [in] input matrix
out – [out] output matrix

template<typename m_t, typename idx_t> void trunc_zero_origin(raft::resources const &handle, raft::device_matrix_view<const m_t, idx_t, col_major> in, raft::device_matrix_view<m_t, idx_t, col_major> out)#

copy matrix operation for column major matrices. First n_rows and n_cols of input matrix “in” is copied to “out” matrix.

Parameters:

handle – raft handle for managing resources
in – input matrix
out – output matrix

Diagonal#

#include <raft/matrix/diagonal.cuh>

namespace raft::matrix

template<typename m_t, typename idx_t, typename layout> void set_diagonal(raft::resources const &handle, raft::device_vector_view<const m_t, idx_t> vec, raft::device_matrix_view<m_t, idx_t, layout> matrix)#

Initialize a diagonal matrix with a vector.

Parameters:

handle – [in] raft handle
vec – [in] vector of length k = min(n_rows, n_cols)
matrix – [out] matrix of size n_rows x n_cols

template<typename m_t, typename idx_t, typename layout> void get_diagonal(raft::resources const &handle, raft::device_matrix_view<const m_t, idx_t, layout> matrix, raft::device_vector_view<m_t, idx_t> vec)#

Initialize a diagonal matrix with a vector.

Parameters:

handle – raft handle
matrix – [in] matrix of size n_rows x n_cols
vec – [out] vector of length k = min(n_rows, n_cols)

template<typename m_t, typename idx_t, typename layout> void invert_diagonal(raft::resources const &handle, raft::device_matrix_view<m_t, idx_t, layout> inout)#

Take reciprocal of elements on diagonal of square matrix (in-place)

Parameters:

handle – raft handle
inout – [inout] square input matrix with size len x len

template<typename math_t, typename idx_t, typename layout_t> void eye(const raft::resources &handle, raft::device_matrix_view<math_t, idx_t, layout_t> out)#

create an identity matrix

Template Parameters:

math_t – data-type upon which the math operation will be performed
idx_t – indexing type used for the output
layout_t – layout of the matrix data (must be row or col major)

Parameters:

handle – [in] raft handle
out – [out] output matrix

Gather#

#include <raft/matrix/gather.cuh>

namespace raft::matrix

template<typename InputIteratorT, typename MapIteratorT, typename OutputIteratorT, typename IndexT> void gather(const InputIteratorT in, IndexT D, IndexT N, const MapIteratorT map, IndexT map_length, OutputIteratorT out, cudaStream_t stream)#

Copies rows from a source matrix into a destination matrix according to a map.

For each output row, read the index in the input matrix from the map and copy the row.

Template Parameters:

InputIteratorT – Input iterator type, for the input matrix (may be a pointer type).
MapIteratorT – Input iterator type, for the map (may be a pointer type).
OutputIteratorT – Output iterator type, for the output matrix (may be a pointer type).
IndexT – Index type.

Parameters:

in – Input matrix, dim = [N, D] (row-major)
D – Number of columns of the input/output matrices
N – Number of rows of the input matrix
map – Map of row indices to gather, dim = [map_length]
map_length – The length of ‘map’, number of rows of the output matrix
out – Output matrix, dim = [map_length, D] (row-major)
stream – CUDA stream to launch kernels within

template<typename InputIteratorT, typename MapIteratorT, typename MapTransformOp, typename OutputIteratorT, typename IndexT> void gather(const InputIteratorT in, IndexT D, IndexT N, const MapIteratorT map, IndexT map_length, OutputIteratorT out, MapTransformOp transform_op, cudaStream_t stream)#

Copies rows from a source matrix into a destination matrix according to a transformed map.

For each output row, read the index in the input matrix from the map, apply a transformation to this input index and copy the row.

Template Parameters:

InputIteratorT – Input iterator type, for the input matrix (may be a pointer type).
MapIteratorT – Input iterator type, for the map (may be a pointer type).
MapTransformOp – Unary lambda expression or operator type. MapTransformOp’s result type must be convertible to IndexT.
OutputIteratorT – Output iterator type, for the output matrix (may be a pointer type).
IndexT – Index type.

Parameters:

in – Input matrix, dim = [N, D] (row-major)
D – Number of columns of the input/output matrices
N – Number of rows of the input matrix
map – Map of row indices to gather, dim = [map_length]
map_length – The length of ‘map’, number of rows of the output matrix
out – Output matrix, dim = [map_length, D] (row-major)
transform_op – Transformation to apply to map values
stream – CUDA stream to launch kernels within

template<typename InputIteratorT, typename MapIteratorT, typename StencilIteratorT, typename UnaryPredicateOp, typename OutputIteratorT, typename IndexT> void gather_if(const InputIteratorT in, IndexT D, IndexT N, const MapIteratorT map, StencilIteratorT stencil, IndexT map_length, OutputIteratorT out, UnaryPredicateOp pred_op, cudaStream_t stream)#

Conditionally copies rows from a source matrix into a destination matrix.

For each output row, read the index in the input matrix from the map, read a stencil value, apply a predicate to the stencil value, and if true, copy the row.

Template Parameters:

InputIteratorT – Input iterator type, for the input matrix (may be a pointer type).
MapIteratorT – Input iterator type, for the map (may be a pointer type).
StencilIteratorT – Input iterator type, for the stencil (may be a pointer type).
UnaryPredicateOp – Unary lambda expression or operator type. UnaryPredicateOp’s result type must be convertible to bool type.
OutputIteratorT – Output iterator type, for the output matrix (may be a pointer type).
IndexT – Index type.

Parameters:

in – Input matrix, dim = [N, D] (row-major)
D – Number of columns of the input/output matrices
N – Number of rows of the input matrix
map – Map of row indices to gather, dim = [map_length]
stencil – Sequence of stencil values, dim = [map_length]
map_length – The length of ‘map’ and ‘stencil’, number of rows of the output matrix
out – Output matrix, dim = [map_length, D] (row-major)
pred_op – Predicate to apply to the stencil values
stream – CUDA stream to launch kernels within

template<typename InputIteratorT, typename MapIteratorT, typename StencilIteratorT, typename UnaryPredicateOp, typename MapTransformOp, typename OutputIteratorT, typename IndexT> void gather_if(const InputIteratorT in, IndexT D, IndexT N, const MapIteratorT map, StencilIteratorT stencil, IndexT map_length, OutputIteratorT out, UnaryPredicateOp pred_op, MapTransformOp transform_op, cudaStream_t stream)#

Conditionally copies rows according to a transformed map.

For each output row, read the index in the input matrix from the map, read a stencil value, apply a predicate to the stencil value, and if true, apply a transformation to the input index and copy the row.

Template Parameters:

InputIteratorT – Input iterator type, for the input matrix (may be a pointer type).
MapIteratorT – Input iterator type, for the map (may be a pointer type).
MapTransformOp – Unary lambda expression or operator type. MapTransformOp’s result type must be convertible to IndexT.
StencilIteratorT – Input iterator type, for the stencil (may be a pointer type).
UnaryPredicateOp – Unary lambda expression or operator type. UnaryPredicateOp’s result type must be convertible to bool type.
OutputIteratorT – Output iterator type, for the output matrix (may be a pointer type).
IndexT – Index type.

Parameters:

in – Input matrix, dim = [N, D] (row-major)
D – Number of columns of the input/output matrices
N – Number of rows of the input matrix
map – Map of row indices to gather, dim = [map_length]
stencil – Sequence of stencil values, dim = [map_length]
map_length – The length of ‘map’ and ‘stencil’, number of rows of the output matrix
out – Output matrix, dim = [map_length, D] (row-major)
pred_op – Predicate to apply to the stencil values
transform_op – Transformation to apply to map values
stream – CUDA stream to launch kernels within

template<typename matrix_t, typename map_t, typename idx_t, typename map_xform_t = raft::identity_op> void gather(const raft::resources &handle, raft::device_matrix_view<const matrix_t, idx_t, row_major> in, raft::device_vector_view<const map_t, idx_t> map, raft::device_matrix_view<matrix_t, idx_t, row_major> out, map_xform_t transform_op = raft::identity_op())#

Copies rows from a source matrix into a destination matrix according to a transformed map.

For each output row, read the index in the input matrix from the map, apply a transformation to this input index if specified, and copy the row.

Template Parameters:

matrix_t – Matrix element type
map_t – Integer type of map elements
idx_t – Integer type used for indexing
map_xform_t – Unary lambda expression or operator type. MapTransformOp’s result type must be convertible to idx_t.

Parameters:

handle – [in] raft handle for managing resources
in – [in] Input matrix, dim = [N, D] (row-major)
map – [in] Map of row indices to gather, dim = [map_length]
out – [out] Output matrix, dim = [map_length, D] (row-major)
transform_op – [in] (optional) Transformation to apply to map values

template<typename matrix_t, typename map_t, typename stencil_t, typename unary_pred_t, typename idx_t, typename map_xform_t = raft::identity_op> void gather_if(const raft::resources &handle, raft::device_matrix_view<const matrix_t, idx_t, row_major> in, raft::device_matrix_view<matrix_t, idx_t, row_major> out, raft::device_vector_view<const map_t, idx_t> map, raft::device_vector_view<const stencil_t, idx_t> stencil, unary_pred_t pred_op, map_xform_t transform_op = raft::identity_op())#

Conditionally copies rows according to a transformed map.

For each output row, read the index in the input matrix from the map, read a stencil value, apply a predicate to the stencil value, and if true, apply a transformation if specified to the input index, and copy the row.

Template Parameters:

matrix_t – Matrix element type
map_t – Integer type of map elements
stencil_t – Value type for stencil (input type for the pred_op)
unary_pred_t – Unary lambda expression or operator type. unary_pred_t’s result type must be convertible to bool type.
map_xform_t – Unary lambda expression or operator type. MapTransformOp’s result type must be convertible to idx_t.
idx_t – Integer type used for indexing

Parameters:

handle – [in] raft handle for managing resources
in – [in] Input matrix, dim = [N, D] (row-major)
map – [in] Map of row indices to gather, dim = [map_length]
stencil – [in] Vector of stencil values, dim = [map_length]
out – [out] Output matrix, dim = [map_length, D] (row-major)
pred_op – [in] Predicate to apply to the stencil values
transform_op – [in] (optional) Transformation to apply to map values

template<typename matrix_t, typename map_t, typename idx_t, typename map_xform_t = raft::identity_op> void gather(raft::resources const &handle, raft::device_matrix_view<matrix_t, idx_t, raft::layout_c_contiguous> inout, raft::device_vector_view<const map_t, idx_t, raft::layout_c_contiguous> map, idx_t col_batch_size = 0, map_xform_t transform_op = raft::identity_op())#

In-place gather elements in a row-major matrix according to a map. The map specifies the new order in which rows of the input matrix are rearranged, i.e. for each output row, read the index in the input matrix from the map, apply a transformation to this input index if specified, and copy the row. map[i]. For example, the matrix [[1, 2, 3], [4, 5, 6], [7, 8, 9]] with the map [2, 0, 1] will be transformed to [[7, 8, 9], [1, 2, 3], [4, 5, 6]]. Batching is done on columns and an additional scratch space of shape n_rows * cols_batch_size is created. For each batch, chunks of columns from each row are copied into the appropriate location in the scratch space and copied back to the corresponding locations in the input matrix.

Template Parameters:

matrix_t – Matrix element type
map_t – Integer type of map elements
map_xform_t – Unary lambda expression or operator type. MapTransformOp’s result type must be convertible to idx_t.
idx_t – Integer type used for indexing

Parameters:

handle – [in] raft handle
inout – [inout] input matrix (n_rows * n_cols)
map – [in] Pointer to the input sequence of gather locations
col_batch_size – [in] (optional) column batch size. Determines the shape of the scratch space (map_length, col_batch_size). When set to zero (default), no batching is done and an additional scratch space of shape (map_lengthm, n_cols) is created.
transform_op – [in] (optional) Transformation to apply to map values

Slicing#

#include <raft/matrix/slice.cuh>

namespace raft::matrix

template<typename m_t, typename idx_t, typename layout_t> void slice(raft::resources const &handle, raft::device_matrix_view<const m_t, idx_t, layout_t> in, raft::device_matrix_view<m_t, idx_t, layout_t> out, slice_coordinates<idx_t> coords)#

Slice a matrix (in-place)

Template Parameters:

m_t – type of matrix elements
idx_t – integer type used for indexing

Parameters:

handle – [in] raft handle
in – [in] input matrix
out – [out] output matrix
coords – [in] coordinates of the wanted slice example: Slice the 2nd and 3rd columns of a 4x3 matrix: slice(handle, in, out, {0, 1, 4, 3});

template<typename idx_t> struct slice_coordinates#

Public Members

idx_t row1#: row coordinate of the top-left point of the wanted area (0-based)

idx_t col1#: column coordinate of the top-left point of the wanted area (0-based)

idx_t row2#: row coordinate of the bottom-right point of the wanted area (1-based)

idx_t col2#: column coordinate of the bottom-right point of the wanted area (1-based)

Triangular#

#include <raft/matrix/triangular.cuh>

namespace raft::matrix

template<typename m_t, typename idx_t> void upper_triangular(raft::resources const &handle, raft::device_matrix_view<const m_t, idx_t, col_major> src, raft::device_matrix_view<m_t, idx_t, col_major> dst)#

Copy the upper triangular part of a matrix to another.

Parameters:

handle – [in] raft handle
src – [in] input matrix with a size of n_rows x n_cols
dst – [out] output matrix with a size of kxk, k = min(n_rows, n_cols)