Matrix Manipulation

2026-03-13

19 min read time

Applies to Linux

Initialization

#include <raft/matrix/init.cuh>

namespace raft::matrix

template<typename math_t, typename extents, typename layout>
void fill(

raft::resources const &handle,

raft::device_mdspan<const math_t, extents, layout> in,

raft::device_mdspan<math_t, extents, layout> out,

raft::host_scalar_view<math_t> scalar

)

set values to scalar in matrix

Template Parameters:

• math_t – data-type upon which the math operation will be performed

• extents – dimension and indexing type used for the input

• layout – layout of the matrix data (must be row or col major)

Parameters:

• handle – [in] raft handle

• in – [in] input matrix

• out – [out] output matrix. The result is stored in the out matrix

• scalar – [in] scalar value to fill matrix elements

template<typename math_t, typename extents, typename layout>
void fill(

raft::resources const &handle,

raft::device_mdspan<math_t, extents, layout> inout,

math_t scalar

)

set values to scalar in matrix

Template Parameters:

• math_t – data-type upon which the math operation will be performed

• extents – dimension and indexing type used for the input

• layout_t – layout of the matrix data (must be row or col major)

Parameters:

• handle – [in] raft handle

• inout – [inout] input matrix

• scalar – [in] scalar value to fill matrix elements

Reverse

#include <raft/matrix/reverse.cuh>

namespace raft::matrix

template<typename m_t, typename idx_t, typename layout_t>
void col_reverse(

raft::resources const &handle,

raft::device_matrix_view<m_t, idx_t, layout_t> inout

)

Reverse the columns of a matrix in place (i.e. first column and last column are swapped)

Parameters:

• handle – [in] raft handle

• inout – [inout] input and output matrix

template<typename m_t, typename idx_t, typename layout_t>
void row_reverse(

raft::resources const &handle,

raft::device_matrix_view<m_t, idx_t, layout_t> inout

)

Reverse the rows of a matrix in place (i.e. first row and last row are swapped)

Parameters:

• handle – [in] raft handle

• inout – [inout] input and output matrix

Threshold

#include <raft/matrix/threshold.cuh>

namespace raft::matrix

template<typename math_t, typename idx_t, typename layout>
void zero_small_values(

raft::resources const &handle,

raft::device_matrix_view<const math_t, idx_t, layout> in,

raft::device_matrix_view<math_t, idx_t, layout> out,

math_t thres = 1e-15

)

sets the small values to zero based on a defined threshold

Template Parameters:

• math_t – data-type upon which the math operation will be performed

• idx_t – integer type used for indexing

• layout – layout of the matrix data (must be row or col major)

Parameters:

• handle – raft handle

• in – [in] input matrix

• out – [out] output matrix. The result is stored in the out matrix

• thres – [in] threshold to set values to zero

template<typename math_t, typename idx_t, typename layout>
void zero_small_values(

raft::resources const &handle,

raft::device_matrix_view<math_t, idx_t, layout> inout,

math_t thres = 1e-15

)

sets the small values to zero in-place based on a defined threshold

Template Parameters:

• math_t – data-type upon which the math operation will be performed

• idx_t – integer type used for indexing

• layout – layout of the matrix data (must be row or col major)

Parameters:

• handle – raft handle

• inout – input matrix and also the result is stored

• thres – threshold

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 idx_t, typename accessor, typename map_xform_t = raft::identity_op>
void gather(

const raft::resources &handle,

raft::mdspan<const matrix_t, raft::matrix_extent<idx_t>, raft::layout_stride, accessor> 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, layout_stride> 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 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

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_stride> 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

Sample Rows

#include <raft/matrix/sample_rows.cuh>

namespace raft::matrix

template<typename T, typename IdxT, typename accessor, typename layout>
void sample_rows(

raft::resources const &res,

random::RngState random_state,

mdspan<const T, matrix_extent<IdxT>, layout, accessor> dataset,

raft::device_matrix_view<T, IdxT> output

)

Select rows randomly from input and copy to output.

The rows are selected randomly. The random sampling method does not guarantee completely unique selection of rows, but it is close to being unique.

Parameters:

• res – RAFT resource handle

• random_state –

• dataset – input dataset

• output – subsampled dataset

template<typename T, typename IdxT, typename accessor, typename layout>
raft::device_matrix<T, IdxT> sample_rows(

raft::resources const &res,

random::RngState random_state,

mdspan<const T, matrix_extent<IdxT>, layout, accessor> dataset,

IdxT n_samples

)

Select rows randomly from input and copy to output.

The rows are selected randomly. The random sampling method does not guarantee completely unique selection of rows, but it is close to being unique.

Parameters:

• res – RAFT resource handle

• random_state –

• dataset – input dataset

• n_samples – number of rows in the returned matrix

Returns:

subsampled dataset

Shift

#include <raft/matrix/shift.cuh>

namespace raft::matrix

template<typename ValueT, typename IdxT>
void shift(

raft::resources const &handle,

raft::device_matrix_view<ValueT, IdxT, row_major> in_out,

size_t k,

std::optional<ValueT> val = std::nullopt,

ShiftDirection shift_direction = ShiftDirection::TOWARDS_END,

ShiftType shift_type = ShiftType::COL

)

In-place operation. Shifts rows or columns to shift_direction by k, and fills the empty values with “val”. If val is std::nullopt, then fills the first k row or columns with its column id or row id, respectively.

Example 1) if we have a row-major 3x4 matrix in_out = [[1,2,3,4], [5,6,7,8], [9,10,11,12]], val=100, k=2, shift_direction = ShiftDirection::TOWARDS_END and shift_type = ShiftType::COL, then we end up with [[100,100,1,2], [100,100,5,6], [100,100,9,10]]. Example 2) if we have a row-major 3x4 matrix in_out = [[1,2,3,4], [5,6,7,8], [9,10,11,12]], val=100, k=1, shift_direction = ShiftDirection::TOWARDS_BEGINNING and shift_type = ShiftType::ROW, then we end up with [[5,6,7,8], [9,10,11,12], [100,100,100,100]] Example 3) if we have a row-major 3x4 matrix in_out = [[1,2,3,4], [5,6,7,8], [9,10,11,12]], k=2, val=std::nullopt, shift_direction = ShiftDirection::TOWARDS_END and shift_type = ShiftType::COL, then we end up with [[0,0,1,2], [1,1,5,6], [2,2,9,10]]. Example 4) if we have a row-major 3x4 matrix in_out = [[1,2,3,4], [5,6,7,8], [9,10,11,12]], k=2, val=std::nullopt, shift_direction = ShiftDirection::TOWARDS_BEGINNING and shift_type = ShiftType::ROW, then we end up with [[9,10,11,12], [0,1,2,3], [0,1,2,3]]

Parameters:

• handle – [in] raft handle

• in_out – [inout] input matrix of size (n_rows x n_cols)

• k – [in] shift size

• val – [in] optional value to fill in the first k rows or columns after shifting. If nullopt, then the row id or column id is used to fill.

• shift_direction – [in] ShiftDirection::TOWARDS_BEGINNING shifts towards the 0th row/col direction, and ShiftDirection::TOWARDS_END shifts towards the (nrow-1)th row/col direction

• shift_type – [in] ShiftType::ROW shifts rows and ShiftType::COL shift columns

template<typename ValueT, typename IdxT>
void shift(

raft::resources const &handle,

raft::device_matrix_view<ValueT, IdxT, row_major> in_out,

raft::device_matrix_view<const ValueT, IdxT> values,

ShiftDirection shift_direction = ShiftDirection::TOWARDS_END,

ShiftType shift_type = ShiftType::COL

)

In-place operation. Shifts all rows or columns to shift_direction based on shape of “values”, and fills the empty space of the in_out matrix with the “values” matrix. If using shift_type=ShiftType::ROW, then “values” should be (k x n_cols) size, which will shift rows to shift_direction by k. If using shift_type=ShiftType::COL, then “values” should be (n_rows x k) size, which will shift columns to shift_direction by k.

Example 1) if we have a row-major 3x4 matrix in_out = [[1,2,3,4], [5,6,7,8], [9,10,11,12]], values=[[100,200], [300,400], [500,600]], shift_direction = ShiftDirection::TOWARDS_END and shift_type = ShiftType::COL, then we end up with [[100,200,1,2], [300,400,5,6], [500,600,9,10]]. Example 2) if we have a row-major 3x4 matrix in_out = [[1,2,3,4], [5,6,7,8], [9,10,11,12]], values=[[100,200,300,400]], shift_direction = ShiftDirection::TOWARDS_BEGINNING and shift_type = ShiftType::ROW, then we end up with [[5,6,7,8], [9,10,11,12], [100,200,300,400]]

Parameters:

• handle – [in] raft handle

• in_out – [inout] input matrix of size (n_rows, n_cols)

• values – [in] value matrix of size (n_rows x k) for shift_type=ShiftType::COL or (k x n_cols) for shift_type=ShiftType::ROW to fill in empty space of in_out after shifting.

• shift_direction – [in] ShiftDirection::TOWARDS_BEGINNING shifts towards the 0th row/col direction, and ShiftDirection::TOWARDS_END shifts towards the (nrow-1)th row/col direction

• shift_type – [in] ShiftType::ROW shifts rows and ShiftType::COL shift columns