# xrandom

Defined in `xtensor/generators/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.

inline default_engine_type &xt::random::get_default_random_engine()

  Returns a reference to the default random number engine.

inline 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>
inline auto xt::random::rand(const S &shape, T lower, T upper, E &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>
inline auto xt::random::randint(const S &shape, T lower, T upper, E &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>
inline auto xt::random::randn(const S &shape, T mean, T std_dev, E &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>
inline auto xt::random::binomial(const S &shape, T trials, D prob, E &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>
inline auto xt::random::geometric(const S &shape, D prob, E &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>
inline auto xt::random::negative_binomial(const S &shape, T k, D prob, E &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>
inline auto xt::random::poisson(const S &shape, D rate, E &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>
inline auto xt::random::exponential(const S &shape, T rate, E &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>
inline auto xt::random::gamma(const S &shape, T alpha, T beta, E &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>
inline auto xt::random::weibull(const S &shape, T a, T b, E &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>
inline auto xt::random::extreme_value(const S &shape, T a, T b, E &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>
inline auto xt::random::lognormal(const S &shape, T mean, T std_dev, E &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>
inline auto xt::random::chi_squared(const S &shape, T deg, E &engine)

  xexpression with specified `shape` containing numbers sampled from the chi-squared random number distribution with `deg` degrees of freedom.

  Numbers are drawn from `std::chi_squared_distribution`.

  Parameters:

    - shape – shape of resulting xexpression

    - deg – 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>
inline auto xt::random::cauchy(const S &shape, T a, T b, E &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>
inline auto xt::random::fisher_f(const S &shape, T m, T n, E &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>
inline auto xt::random::student_t(const S &shape, T n, E &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, E &engine)

  Randomly select n unique elements from xexpression e.

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

  Parameters:

    - e – expression to sample from

    - n – number of elements to sample

    - replace – whether to sample with or without replacement

    - engine – random number engine

  Returns:

    xtensor containing 1D container of sampled elements

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, E &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.

  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

  Returns:

    xtensor containing 1D container of sampled elements

template<class T, class E = random::default_engine_type>
void xt::random::shuffle(xexpression<T> &e, E &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<xtl::integral_concept T, class E = random::default_engine_type>
xtensor<T, 1> xt::random::permutation(T e, E &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 also

  shuffle and returns the result.

  Parameters:

    - e – input xexpression or integer

    - engine – random number engine to use (optional)

  Returns:

    randomly permuted copy of container or arange.