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 Arithmetic#

Line-wise Operation#

#include <raft/matrix/linewise_op.cuh>

namespace raft::matrix

template<typename m_t, typename idx_t, typename layout, typename Lambda, typename ...vec_t, typename = raft::enable_if_device_mdspan<vec_t...>>
void linewise_op(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, const bool alongLines, Lambda op, vec_t... vecs)#

Run a function over matrix lines (rows or columns) with a variable number row-vectors or column-vectors. The term line here signifies that the lines can be either columns or rows, depending on the matrix layout. What matters is if the vectors are applied along lines (indices of vectors correspond to indices within lines), or across lines (indices of vectors correspond to line numbers).

Template Parameters:

  • m_t – matrix elements type

  • idx_t – integer type used for indexing

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

  • Lambda – type of lambda function used for the operation

  • vec_t – variadic types of device_vector_view vectors (size m if alongRows, size n otherwise)

Parameters:

  • handle – [in] raft handle for managing resources

  • out – [out] result of the operation; can be same as in; should be aligned the same as in to allow faster vectorized memory transfers.

  • in – [in] input matrix consisting of nLines lines, each lineLen-long.

  • alongLines – [in] whether vectors are indices along or across lines.

  • op – [in] the operation applied on each line: for i in [0..lineLen) and j in [0..nLines): out[j, i] = op(in[j, i], vec1[i], vec2[i], … veck[i]) if alongLines = true out[j, i] = op(in[j, i], vec1[j], vec2[j], … veck[j]) if alongLines = false where matrix indexing is row-major ([j, i] = [i + lineLen * j]). out[i, j] = op(in[i, j], vec1[i], vec2[i], … veck[i]) if alongLines = true out[i, j] = op(in[i, j], vec1[j], vec2[j], … veck[j]) if alongLines = false where matrix indexing is col-major ([i, j] = [i + lineLen * j]).

  • vecs – [in] zero or more vectors to be passed as arguments, size of each vector is alongLines ? lineLen : nLines.

template<typename m_t, typename idx_t, typename layout, typename Lambda, typename ...vec_t, typename = raft::enable_if_device_mdspan<vec_t...>>
void linewise_op(raft::resources const &handle, raft::device_aligned_matrix_view<const m_t, idx_t, layout> in, raft::device_aligned_matrix_view<m_t, idx_t, layout> out, const bool alongLines, Lambda op, vec_t... vecs)#

Power#

#include <raft/matrix/power.cuh>

namespace raft::matrix

template<typename math_t, typename idx_t, typename layout>
void power(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)#

Power of every element in the input matrix.

Template Parameters:

  • math_t – type used for matrix elements

  • idx_t – integer type used for indexing

  • layout – layout of the matrix (row or column major)

Parameters:

  • handle – [in] raft handle

  • in – [in] input matrix

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

template<typename math_t, typename idx_t, typename layout>
void weighted_power(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 scalar)#

Power of every element in the input matrix.

Template Parameters:

  • math_t – type of matrix elements

  • idx_t – integer type used for indexing

  • 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] every element is multiplied with scalar.

template<typename math_t, typename idx_t, typename layout>
void weighted_power(raft::resources const &handle, raft::device_matrix_view<math_t, idx_t, layout> inout, math_t scalar)#

Power of every element in the input matrix (inplace)

Template Parameters:

  • math_t – matrix element type

  • idx_t – integer type used for indexing

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

Parameters:

  • handle – [in] raft handle

  • inout – [inout] input matrix and also the result is stored

  • scalar – [in] every element is multiplied with scalar.

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

Power of every element in the input matrix (inplace)

Template Parameters:

  • math_t – matrix element type

  • idx_t – integer type used for indexing

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

Parameters:

  • handle – [in] raft handle

  • inout – [inout] input matrix and also the result is stored

Ratio#

#include <raft/matrix/ratio.cuh>

namespace raft::matrix

template<typename math_t, typename idx_t, typename layout>
void ratio(raft::resources const &handle, raft::device_matrix_view<const math_t, idx_t, layout> src, raft::device_matrix_view<math_t, idx_t, layout> dest)#

ratio of every element over sum of input vector is calculated

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 – [in]

  • src – [in] input matrix

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

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

ratio of every element over sum of input vector is calculated

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 – [in]

  • inout – [inout] input matrix

Reciprocal#

#include <raft/matrix/reciprocal.cuh>

namespace raft::matrix

template<typename math_t, typename idx_t, typename layout>
void reciprocal(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, raft::host_scalar_view<math_t> scalar, bool setzero = false, math_t thres = 1e-15)#

Reciprocal of every element in the input matrix.

Template Parameters:

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

  • idx_t – integer type used for indexing

Parameters:

  • handle – raft handle

  • in – input matrix and also the result is stored

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

  • scalar – every element is multiplied with scalar

  • setzero – round down to zero if the input is less the threshold

  • thres – the threshold used to forcibly set inputs to zero

template<typename math_t, typename idx_t, typename layout>
void reciprocal(raft::resources const &handle, raft::device_matrix_view<math_t, idx_t, layout> inout, raft::host_scalar_view<math_t> scalar, bool setzero = false, math_t thres = 1e-15)#

Reciprocal of every element in the input matrix (in place)

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 – [in] raft handle to manage resources

  • inout – [inout] input matrix with in-place results

  • scalar – [in] every element is multiplied with scalar

  • setzero – [in] round down to zero if the input is less the threshold

  • thres – [in] the threshold used to forcibly set inputs to zero

Sign-flip#

#include <raft/matrix/sign_flip.cuh>

namespace raft::matrix

template<typename math_t, typename idx_t>
void sign_flip(raft::resources const &handle, raft::device_matrix_view<math_t, idx_t, col_major> inout)#

sign flip stabilizes the sign of col major eigen vectors. The sign is flipped if the column has negative |max|.

Template Parameters:

  • math_t – floating point type used for matrix elements

  • idx_t – integer type used for indexing

Parameters:

  • handle – [in] raft handle

  • inout – [inout] input matrix. Result also stored in this parameter

Square Root#

#include <raft/matrix/sqrt.cuh>

namespace raft::matrix

template<typename math_t, typename idx_t, typename layout>
void sqrt(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)#

Square root of every element in the input matrix.

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 – [in] raft handle

  • in – [in] input matrix and also the result is stored

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

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

Square root of every element in the input matrix (in place)

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 – [in] raft handle

  • inout – [inout] input matrix with in-place results

template<typename math_t, typename idx_t, typename layout>
void weighted_sqrt(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, raft::host_scalar_view<math_t> scalar, bool set_neg_zero = false)#

Square root of every element in the input matrix.

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 – [in] raft handle

  • in – [in] input matrix and also the result is stored

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

  • scalar – [in] every element is multiplied with scalar

  • set_neg_zero – [in] whether to set negative numbers to zero

template<typename math_t, typename idx_t, typename layout>
void weighted_sqrt(raft::resources const &handle, raft::device_matrix_view<math_t, idx_t, layout> inout, raft::host_scalar_view<math_t> scalar, bool set_neg_zero = false)#

Square root of every element in the input matrix (in place)

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 – [in] raft handle

  • inout – [inout] input matrix and also the result is stored

  • scalar – [in] every element is multiplied with scalar

  • set_neg_zero – [in] whether to set negative numbers to zero