# xrandom¶

Defined in xtensor/xrandom.hpp

Warning

xtensor uses a lazy generator for random numbers. You need to assign them or use eval to keep the generated values consistent.

default_engine_type &xt::random::get_default_random_engine()

Returns a reference to the default random number engine.

void xt::random::seed(seed_type seed)

Seeds the default random number generator with seed.

Parameters
• seed: The seed

template<class T, class S, class E = random::default_engine_type>
auto xt::random::rand(const S &shape, T lower = 0, T upper = 1, E &engine = random::get_default_random_engine())

xexpression with specified shape containing uniformly distributed random numbers in the interval from lower to upper, excluding upper.

Numbers are drawn from std::uniform_real_distribution.

Parameters
• shape: shape of resulting xexpression

• lower: lower bound

• upper: upper bound

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class E = random::default_engine_type>
auto xt::random::randint(const S &shape, T lower = 0, T upper = (std::numeric_limits<T>::max)(), E &engine = random::get_default_random_engine())

xexpression with specified shape containing uniformly distributed random integers in the interval from lower to upper, excluding upper.

Numbers are drawn from std::uniform_int_distribution.

Parameters
• shape: shape of resulting xexpression

• lower: lower bound

• upper: upper bound

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class E = random::default_engine_type>
auto xt::random::randn(const S &shape, T mean = 0, T std_dev = 1, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from the Normal (Gaussian) random number distribution with mean mean and standard deviation std_dev.

Numbers are drawn from std::normal_distribution.

Parameters
• shape: shape of resulting xexpression

• mean: mean of normal distribution

• std_dev: standard deviation of normal distribution

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class D = double, class E = random::default_engine_type>
auto xt::random::binomial(const S &shape, T trials = 1, D prob = 0.5, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from the binomial random number distribution for trials trials with probability of success equal to prob.

Numbers are drawn from std::binomial_distribution.

Parameters
• shape: shape of resulting xexpression

• trials: number of Bernoulli trials

• prob: probability of success of each trial

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class D = double, class E = random::default_engine_type>
auto xt::random::geometric(const S &shape, D prob = 0.5, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from a gemoetric random number distribution with probability of success equal to prob for each of the Bernoulli trials.

Numbers are drawn from std::geometric_distribution.

Parameters
• shape: shape of resulting xexpression

• prob: probability of success of each trial

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class D = double, class E = random::default_engine_type>
auto xt::random::negative_binomial(const S &shape, T k = 1, D prob = 0.5, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from a negative binomial random number distribution (also known as Pascal distribution) that returns the number of successes before k trials with probability of success equal to prob for each of the Bernoulli trials.

Numbers are drawn from std::negative_binomial_distribution.

Parameters
• shape: shape of resulting xexpression

• k: number of unsuccessful trials

• prob: probability of success of each trial

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class D = double, class E = random::default_engine_type>
auto xt::random::poisson(const S &shape, D rate = 1.0, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from a Poisson random number distribution with rate rate

Numbers are drawn from std::poisson_distribution.

Parameters
• shape: shape of resulting xexpression

• rate: rate of Poisson distribution

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class E = random::default_engine_type>
auto xt::random::exponential(const S &shape, T rate = 1.0, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from a exponential random number distribution with rate rate

Numbers are drawn from std::exponential_distribution.

Parameters
• shape: shape of resulting xexpression

• rate: rate of exponential distribution

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class E = random::default_engine_type>
auto xt::random::gamma(const S &shape, T alpha = 1.0, T beta = 1.0, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from a gamma random number distribution with shape alpha and scale beta

Numbers are drawn from std::gamma_distribution.

Parameters
• shape: shape of resulting xexpression

• alpha: shape of the gamma distribution

• beta: scale of the gamma distribution

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class E = random::default_engine_type>
auto xt::random::weibull(const S &shape, T a = 1.0, T b = 1.0, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from a Weibull random number distribution with shape a and scale b

Numbers are drawn from std::weibull_distribution.

Parameters
• shape: shape of resulting xexpression

• a: shape of the weibull distribution

• b: scale of the weibull distribution

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class E = random::default_engine_type>
auto xt::random::extreme_value(const S &shape, T a = 0.0, T b = 1.0, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from a extreme value random number distribution with shape a and scale b

Numbers are drawn from std::extreme_value_distribution.

Parameters
• shape: shape of resulting xexpression

• a: shape of the extreme value distribution

• b: scale of the extreme value distribution

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class E = random::default_engine_type>
auto xt::random::lognormal(const S &shape, T mean = 0, T std_dev = 1, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from the Log-Normal random number distribution with mean mean and standard deviation std_dev.

Numbers are drawn from std::lognormal_distribution.

Parameters
• shape: shape of resulting xexpression

• mean: mean of normal distribution

• std_dev: standard deviation of normal distribution

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class E = random::default_engine_type>
auto xt::random::cauchy(const S &shape, T a = 0.0, T b = 1.0, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from a Cauchy random number distribution with peak a and scale b

Numbers are drawn from std::cauchy_distribution.

Parameters
• shape: shape of resulting xexpression

• a: peak of the Cauchy distribution

• b: scale of the Cauchy distribution

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class E = random::default_engine_type>
auto xt::random::fisher_f(const S &shape, T m = 1.0, T n = 1.0, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from a Fisher-f random number distribution with numerator degrees of freedom equal to m and denominator degrees of freedom equal to n

Numbers are drawn from std::fisher_f_distribution.

Parameters
• shape: shape of resulting xexpression

• m: numerator degrees of freedom

• n: denominator degrees of freedom

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class S, class E = random::default_engine_type>
auto xt::random::student_t(const S &shape, T n = 1.0, E &engine = random::get_default_random_engine())

xexpression with specified shape containing numbers sampled from a Student-t random number distribution with degrees of freedom equal to n

Numbers are drawn from std::student_t_distribution.

Parameters
• shape: shape of resulting xexpression

• n: degrees of freedom

• engine: random number engine

Template Parameters
• T: number type to use

template<class T, class E = random::default_engine_type>
xtensor<typename T::value_type, 1> xt::random::choice(const xexpression<T> &e, std::size_t n, bool replace = true, E &engine = random::get_default_random_engine())

Randomly select n unique elements from xexpression e.

Note: this function makes a copy of your data, and only 1D data is accepted.

Return

xtensor containing 1D container of sampled elements

Parameters
• e: expression to sample from

• n: number of elements to sample

• replace: whether to sample with or without replacement

• engine: random number engine

template<class T, class W, class E = random::default_engine_type>
xtensor<typename T::value_type, 1> xt::random::choice(const xexpression<T> &e, std::size_t n, const xexpression<W> &weights, bool replace = true, E &engine = random::get_default_random_engine())

Weighted random sampling.

Randomly sample n unique elements from xexpression e using the discrete distribution parametrized by the weights w. When sampling with replacement, this means that the probability to sample element e[i] is defined as w[i] / sum(w). Without replacement, this only describes the probability of the first sample element. In successive samples, the weight of items already sampled is assumed to be zero.

For weighted random sampling with replacement, binary search with cumulative weights alogrithm is used. For weighted random sampling without replacement, the algorithm used is the exponential sort from Efraimidis and Spirakis (2006) with the weight / randexp(1) trick from Kirill Müller.

Note: this function makes a copy of your data, and only 1D data is accepted.

Return

xtensor containing 1D container of sampled elements

Parameters
• e: expression to sample from

• n: number of elements to sample

• w: expression for the weight distribution. Weights must be positive and real-valued but need not sum to 1.

• replace: set true to sample with replacement

• engine: random number engine

template<class T, class E = random::default_engine_type>
void xt::random::shuffle(xexpression<T> &e, E &engine = random::get_default_random_engine())

Randomly shuffle elements inplace in xcontainer along first axis.

The order of sub-arrays is changed but their contents remain the same.

Parameters
• e: xcontainer to shuffle inplace

• engine: random number engine

template<class T, class E = random::default_engine_type>
std::enable_if_t<xtl::is_integral<T>::value, xtensor<T, 1>> xt::random::permutation(T e, E &engine = random::get_default_random_engine())

Randomly permute a sequence, or return a permuted range.

If the first parameter is an integer, this function creates a new arange(e) and returns it randomly permuted. Otherwise, this function creates a copy of the input, passes it to

See

shuffle and returns the result.

Return

randomly permuted copy of container or arange.

Parameters
• e: input xexpression or integer

• engine: random number engine to use (optional)