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.

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)

On this page
Show Source