Univariate Random Sampling

Univariate Random Sampling#

2025-10-17

8 min read time

Applies to Linux

#include <raft/random/rng.cuh>

namespace raft::random

template<typename OutputValueType, typename IndexType>
void uniform(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType start,
OutputValueType end
)#

Generate uniformly distributed numbers in the given range.

Template Parameters:

  • OutputValueType – Data type of output random number

  • Index – Data type used to represent length of the arrays

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] the output array

  • start – [in] start of the range

  • end – [in] end of the range

template<typename OutputValueType, typename IndexType>
void uniformInt(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType start,
OutputValueType end
)#

Generate uniformly distributed integers in the given range.

Template Parameters:

  • OutputValueType – Integral type; value type of the output vector

  • IndexType – Type used to represent length of the output vector

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] the output vector of random numbers

  • start – [in] start of the range

  • end – [in] end of the range

template<typename OutputValueType, typename IndexType>
void normal(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType mu,
OutputValueType sigma
)#

Generate normal distributed numbers with a given mean and standard deviation.

Template Parameters:

  • OutputValueType – data type of output random number

  • IndexType – data type used to represent length of the arrays

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] the output array

  • mu – [in] mean of the distribution

  • sigma – [in] std-dev of the distribution

template<typename OutputValueType, typename IndexType>
void normalInt(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType mu,
OutputValueType sigma
)#

Generate normal distributed integers.

Template Parameters:

  • OutputValueType – Integral type; value type of the output vector

  • IndexType – Integral type of the output vector’s length

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] the output array

  • mu – [in] mean of the distribution

  • sigma – [in] standard deviation of the distribution

template<typename OutputValueType, typename IndexType>
void normalTable(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<const OutputValueType, IndexType> mu_vec,
std::variant<raft::device_vector_view<const OutputValueType, IndexType>, OutputValueType> sigma,
raft::device_matrix_view<OutputValueType, IndexType, raft::row_major> out
)#

Generate normal distributed table according to the given set of means and scalar standard deviations.

Each row in this table conforms to a normally distributed n-dim vector whose mean is the input vector and standard deviation is the corresponding vector or scalar. Correlations among the dimensions itself are assumed to be absent.

Template Parameters:

  • OutputValueType – data type of output random number

  • IndexType – data type used to represent length of the arrays

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • mu_vec – [in] mean vector (of length out.extent(1))

  • sigma – [in] Either the standard-deviation vector (of length out.extent(1)) of each component, or a scalar standard deviation for all components.

  • out – [out] the output table

template<typename OutputValueType, typename IndexType>
void fill(
raft::resources const &handle,
RngState &rng_state,
OutputValueType val,
raft::device_vector_view<OutputValueType, IndexType> out
)#

Fill a vector with the given value.

Template Parameters:

  • OutputValueType – Value type of the output vector

  • IndexType – Integral type used to represent length of the output vector

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • val – [in] value with which to fill the output vector

  • out – [out] the output vector

template<typename OutputValueType, typename IndexType, typename Type>
void bernoulli(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
Type prob
)#

Generate bernoulli distributed boolean array.

Template Parameters:

  • OutputValueType – Type of each element of the output vector; must be able to represent boolean values (e.g., bool)

  • IndexType – Integral type of the output vector’s length

  • Type – Data type in which to compute the probabilities

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] the output vector

  • prob – [in] coin-toss probability for heads

template<typename OutputValueType, typename IndexType>
void scaled_bernoulli(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType prob,
OutputValueType scale
)#

Generate bernoulli distributed array and applies scale.

Template Parameters:

  • OutputValueType – Data type in which to compute the probabilities

  • IndexType – Integral type of the output vector’s length

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] the output vector

  • prob – [in] coin-toss probability for heads

  • scale – [in] scaling factor

template<typename OutputValueType, typename IndexType = int>
void gumbel(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType mu,
OutputValueType beta
)#

Generate Gumbel distributed random numbers.

Note

https://en.wikipedia.org/wiki/Gumbel_distribution

Template Parameters:

  • OutputValueType – data type of output random number

  • IndexType – data type used to represent length of the arrays

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] output array

  • mu – [in] mean value

  • beta – [in] scale value

template<typename OutputValueType, typename IndexType>
void lognormal(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType mu,
OutputValueType sigma
)#

Generate lognormal distributed numbers.

Template Parameters:

  • OutputValueType – data type of output random number

  • IndexType – data type used to represent length of the arrays

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] the output array

  • mu – [in] mean of the distribution

  • sigma – [in] standard deviation of the distribution

template<typename OutputValueType, typename IndexType = int>
void logistic(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType mu,
OutputValueType scale
)#

Generate logistic distributed random numbers.

Template Parameters:

  • OutputValueType – data type of output random number

  • IndexType – data type used to represent length of the arrays

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] output array

  • mu – [in] mean value

  • scale – [in] scale value

template<typename OutputValueType, typename IndexType>
void exponential(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType lambda
)#

Generate exponentially distributed random numbers.

Template Parameters:

  • OutputValueType – data type of output random number

  • IndexType – data type used to represent length of the arrays

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] output array

  • lambda – [in] the exponential distribution’s lambda parameter

template<typename OutputValueType, typename IndexType>
void rayleigh(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType sigma
)#

Generate rayleigh distributed random numbers.

Template Parameters:

  • OutputValueType – data type of output random number

  • IndexType – data type used to represent length of the arrays

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] output array

  • sigma – [in] the distribution’s sigma parameter

template<typename OutputValueType, typename IndexType>
void laplace(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutputValueType, IndexType> out,
OutputValueType mu,
OutputValueType scale
)#

Generate laplace distributed random numbers.

Template Parameters:

  • OutputValueType – data type of output random number

  • IndexType – data type used to represent length of the arrays

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] output array

  • mu – [in] the mean

  • scale – [in] the scale

template<typename OutType, typename WeightType, typename IndexType>
std::enable_if_t<std::is_integral_v<OutType>> discrete(
raft::resources const &handle,
RngState &rng_state,
raft::device_vector_view<OutType, IndexType> out,
raft::device_vector_view<const WeightType, IndexType> weights
)#

Generate random integers, where the probability of i is weights[i]/sum(weights)

Usage example: 

#include <raft/core/device_mdarray.hpp>
#include <raft/core/resources.hpp>
#include <raft/random/rng.cuh>

raft::resources handle;
...
raft::random::RngState rng(seed);
auto indices = raft::make_device_vector<int>(handle, n_samples);
raft::random::discrete(handle, rng, indices.view(), weights);

Template Parameters:

  • OutType – integer output type

  • WeightType – weight type

  • IndexType – data type used to represent length of the arrays

Parameters:

  • handle – [in] raft handle for resource management

  • rng_state – [in] random number generator state

  • out – [out] output array

  • weights – [in] weight array