.. default-domain:: chpl .. module:: Random :synopsis: Support for pseudorandom number generation. Random ====== **Usage** .. code-block:: chapel use Random; or .. code-block:: chapel import Random; **Submodules** .. toctree:: :maxdepth: 1 :glob: Random/* Support for pseudorandom number generation. This module provides the :record:`randomStream` type that represents a conceptual stream of random numbers of a particular scalar type. Individual numbers can be generated with :proc:`randomStream.next`, or an iterable sequence of numbers can be generated by providing a domain argument to ``next``. The stream's position in its sequence can be updated with :proc:`randomStream.skipTo`. Additionally, there are several methods for generating random numbers from arrays, domains, and ranges. This module also contains a few top-level procedures for doing common tasks with pseudorandom numbers: * :proc:`fillRandom` fills an array with random numbers in parallel * :proc:`shuffle` randomly re-arranges the elements of an array * :proc:`permute` create a random permutation of an array, domain, or range * :proc:`choose` randomly selects an element from an array, domain, or range * :proc:`sample` randomly samples elements from an array, domain, or range These procedures will create a temporary ``randomStream`` and then call the corresponding method on it. For repeated use of one or more of the above operations, it is recommended to create a :record:``randomStream`` and call the relevant method on it repeatedly. Seed Generation --------------- The :record:`randomStream` type can be initialized with a seed value. Any two ``randomStream``'s initialized with the same seed value will produce identical sequences of random numbers. When not provided explicitly, a seed value will be generated in an implementation specific manner which is designed to minimize the chance that two distinct ``randomStream``'s will have the same seed. Future Work ----------- In a future release, we intend to use Chapel's interface features to define one or more interfaces for random streams. At that point, the :record:`randomStream` type will be an implementation of the interface(s) for generating a seedable stream of random numbers. We'd also like to experiment with adding a thread-safe and type-agnostic random number generator that can be used as a "global" random number generator. Random Procedures and Types --------------------------- .. function:: proc fillRandom(ref arr: [] ?t, seed: int) where isNumericOrBoolType(t) && arr.isRectangular() Fill a rectangular array of numeric values with pseudorandom values in parallel using a new :record:`randomStream`. The first `arr.size` values from the stream will be assigned to the array's elements in row-major order. The parallelization strategy is determined by the array. :arg arr: An array of numeric values :arg seed: The seed to use to create the ``randomStream`` .. function:: proc fillRandom(ref arr: [] ?t) where isNumericOrBoolType(t) && arr.isRectangular() Fill a rectangular array of numeric values with pseudorandom values in parallel using a new :record:`randomStream`. The first `arr.size` values from the stream will be assigned to the array's elements in row-major order. The parallelization strategy is determined by the array. .. note:: a seed will be generated in an implementation specific manner that depends on the current time. :arg arr: An array of numeric values .. function:: proc fillRandom(ref arr: [] ?t, min: t, max: t, seed: int) where isNumericOrBoolType(t) && arr.isRectangular() Fill a rectangular array of numeric values with pseudorandom values in the range [``min``, ``max``] (inclusive) in parallel using a new :record:`randomStream`. The first `arr.size` values from the stream will be assigned to the array's elements in row-major order. The parallelization strategy is determined by the array. :arg arr: An array of numeric values :arg min: The (inclusive) lower bound for the random values :arg max: The (inclusive) upper bound for the random values :arg seed: The seed to use to create the ``randomStream`` .. function:: proc fillRandom(ref arr: [] ?t, min: t, max: t) where isNumericOrBoolType(t) && arr.isRectangular() Fill a rectangular array of numeric values with pseudorandom values in the range [``min``, ``max``] (inclusive) in parallel using a new :record:`randomStream`. The first `arr.size` values from the stream will be assigned to the array's elements in row-major order. The parallelization strategy is determined by the array. .. note:: a seed will be generated in an implementation specific manner that depends on the current time. :arg arr: An array of numeric values :arg min: The (inclusive) lower bound for the random values :arg max: The (inclusive) upper bound for the random values .. function:: proc shuffle(ref arr: [?d], seed: int) where d.isRectangular() Use a new :record:`randomStream` to shuffle an array in place. :arg arr: A rectangular array to shuffle :arg seed: The seed to initialize a ``randomStream`` with .. function:: proc shuffle(ref arr: [?d]) where d.isRectangular() Use a new :record:`randomStream` to shuffle an array in place. :arg arr: A rectangular array to shuffle .. function:: proc permute(const ref arr: [?d] ?t, seed: int): [] t where d.isRectangular() Produce a random permutation of an array's elements :arg arr: A rectangular array :arg seed: The seed to use when creating the ``randomStream`` :return: A new array containing each of the values from ``arr`` in a pseudo-random order. .. function:: proc permute(const ref arr: [?d] ?t): [] t where d.isRectangular() Produce a random permutation of an array's elements :arg arr: A rectangular array :return: A new array containing each of the values from ``arr`` in a pseudo-random order. .. function:: proc permute(d: domain(?), seed: int): [] d.fullIdxType where d.isRectangular() Produce a random permutation of the indices in a domain. :arg d: A rectangular domain :arg seed: The seed to use when creating the ``randomStream`` :return: An array containing each of the indices from ``d`` in a pseudo-random order. .. function:: proc permute(d: domain(?)): [] d.fullIdxType where d.isRectangular() Produce a random permutation of the indices in a domain. :arg d: A rectangular domain :return: An array containing each of the indices from ``d`` in a pseudo-random order. .. function:: proc permute(r: range(bounds = boundKind.both, ?), seed: int): [] r.idxType Produce a random permutation of the values in a range. :arg r: A fully bounded range :arg seed: The seed to use when creating the ``randomStream`` :return: An array containing each of the values from ``r`` in a pseudo-random order. .. function:: proc permute(r: range(bounds = boundKind.both, ?)): [] r.idxType Produce a random permutation of the values in a range. :arg r: A fully bounded range :return: An array containing each of the values from ``r`` in a pseudo-random order. .. function:: proc choose(const ref arr: [?d] ?t): t where d.isRectangular() Choose a random element from an array. :arg arr: The rectangular array to choose from :return: A random element from the array .. function:: proc choose(const ref arr: [?d] ?t, seed: int): t where d.isRectangular() Choose a random element from an array. :arg arr: The rectangular array to choose from :arg seed: The seed to use when creating the ``randomStream`` :return: A random element from the array .. function:: proc choose(d: domain(?)): d.fullIdxType where d.isRectangular() Choose a random index from a domain. :arg d: The rectangular domain to choose from :return: A random index from the domain .. function:: proc choose(d: domain(?), seed: int): d.fullIdxType where d.isRectangular() Choose a random index from a domain. :arg d: The rectangular domain to choose from :arg seed: The seed to use when creating the ``randomStream`` :return: A random index from the domain .. function:: proc choose(r: range(bounds = boundKind.both, ?)): r.idxType Choose a random value from a range. :arg r: A fully bounded range to choose from :return: A random value from the range .. function:: proc choose(r: range(bounds = boundKind.both, ?), seed: int): r.idxType Choose a random value from a range. :arg r: A fully bounded range to choose from :arg seed: The seed to use when creating the ``randomStream`` :return: A random value from the range .. function:: proc sample(const ref arr: [?d] ?t, n: int, withReplacement = false): [] t throws where d.isRectangular() Randomly sample ``n`` elements from an array. :arg arr: The rectangular array to sample from :arg n: The number of elements to sample :arg withReplacement: Whether or not to sample with replacement :return: A zero-based 1D array of ``n`` random elements sampled from the array :throws IllegalArgumentError: If ``n < 1`` or if ``n > arr.size`` and ``withReplacement=false``. If ``arr`` is empty. .. function:: proc sample(const ref arr: [?d] ?t, n: int, withReplacement = false, seed: int): [] t throws where d.isRectangular() Randomly sample ``n`` elements from an array. :arg arr: The rectangular array to sample from :arg n: The number of elements to sample :arg withReplacement: Whether or not to sample with replacement :arg seed: The seed to use when creating the ``randomStream`` :return: A zero-based 1D array of ``n`` random elements sampled from the array :throws IllegalArgumentError: If ``n < 1`` or if ``n > arr.size`` and ``withReplacement=false``. If ``arr`` is empty. .. function:: proc sample(const ref arr: [?d] ?t, n: int, const ref weights: [?dw] ?wt, withReplacement = false): [] t throws where is1DRectangularDomain(d) && is1DRectangularDomain(dw) && isRealType(wt) Randomly sample ``n`` elements from an array, where each array element has a corresponding weight. Elements with relatively larger weights are more likely to be sampled. :arg arr: The 1D rectangular array to sample from :arg n: The number of elements to sample :arg weights: An array of real-valued weights corresponding to the elements in ``arr`` :arg withReplacement: Whether or not to sample with replacement :return: A zero-based 1D array of ``n`` random elements sampled from the array :throws IllegalArgumentError: If ``n < 1`` or if ``n > arr.size`` and ``withReplacement=false``. If ``arr`` is empty. If ``weights`` does not have the same size as ``arr``. .. function:: proc sample(const ref arr: [?d] ?t, n: int, const ref weights: [?dw] ?wt, withReplacement = false, seed: int): [] t throws where is1DRectangularDomain(d) && is1DRectangularDomain(dw) && isRealType(wt) Randomly sample ``n`` elements from an array, where each array element has a corresponding weight. Elements with relatively larger weights are more likely to be sampled. :arg arr: The 1D rectangular array to sample from :arg n: The number of elements to sample :arg weights: An array of real-valued weights corresponding to the elements in ``arr`` :arg withReplacement: Whether or not to sample with replacement :arg seed: The seed to use when creating the ``randomStream`` :return: A zero-based 1D array of ``n`` random elements sampled from the array :throws IllegalArgumentError: If ``n < 1`` or if ``n > arr.size`` and ``withReplacement=false``. If ``arr`` is empty. If ``weights`` does not have the same size as ``arr``. .. function:: proc sample(d: domain(?), n: int, withReplacement = false): [] d.fullIdxType throws where d.isRectangular() Randomly sample ``n`` indices from a domain. :arg d: The rectangular domain to sample from :arg n: The number of indices to sample :arg withReplacement: Whether or not to sample with replacement :return: A zero-based 1D array of ``n`` random indices sampled from the domain :throws IllegalArgumentError: If ``n < 1`` or if ``n > arr.size`` and ``withReplacement=false``. If ``d`` is empty. .. function:: proc sample(d: domain(?), n: int, withReplacement = false, seed: int): [] d.fullIdxType throws where d.isRectangular() Randomly sample ``n`` indices from a domain. :arg d: The rectangular domain to sample from :arg n: The number of indices to sample :arg withReplacement: Whether or not to sample with replacement :arg seed: The seed to use when creating the ``randomStream`` :return: A zero-based 1D array of ``n`` random indices sampled from the domain :throws IllegalArgumentError: If ``n < 1`` or if ``n > arr.size`` and ``withReplacement=false``. If ``d`` is empty. .. function:: proc sample(d: domain(?), n: int, const ref weights: [?dw] ?wt, withReplacement = false): [] d.idxType throws where is1DRectangularDomain(d) && is1DRectangularDomain(dw) && isRealType(wt) Randomly sample ``n`` indices from a domain, where each index has a corresponding weight. Indices with relatively larger weights are more likely to be sampled. :arg d: The 1D rectangular domain to sample from :arg n: The number of indices to sample :arg weights: An array of real-valued weights corresponding to the indices in ``d`` :arg withReplacement: Whether or not to sample with replacement :return: A zero-based 1D array of ``n`` random indices sampled from the domain :throws IllegalArgumentError: If ``n < 1`` or if ``n > d.size`` and ``withReplacement=false``. If ``d`` is empty. If ``weights`` does not have the same size as ``d``. .. function:: proc sample(d: domain(?), n: int, const ref weights: [?dw] ?wt, withReplacement = false, seed: int): [] d.idxType throws where is1DRectangularDomain(d) && is1DRectangularDomain(dw) && isRealType(wt) Randomly sample ``n`` indices from a domain, where each index has a corresponding weight. Indices with relatively larger weights are more likely to be sampled. :arg d: The 1D rectangular domain to sample from :arg n: The number of elements to sample :arg weights: An array of real-valued weights corresponding to the elements in ``d`` :arg withReplacement: Whether or not to sample with replacement :arg seed: The seed to use when creating the ``randomStream`` :return: A zero-based 1D array of ``n`` random indices sampled from the domain :throws IllegalArgumentError: If ``n < 1`` or if ``n > d.size`` and ``withReplacement=false``. If ``d`` is empty. If ``weights`` does not have the same size as ``d``. .. function:: proc sample(r: range(bounds = boundKind.both, ?), n: int, withReplacement = false): [] r.idxType throws Randomly sample ``n`` values from a range. :arg r: A fully bounded range to sample from :arg n: The number of values to sample :arg withReplacement: Whether or not to sample with replacement :return: A zero-based array of ``n`` random values sampled from the range :throws IllegalArgumentError: If ``n < 1`` or if ``n > r.size`` and ``withReplacement=false``. If ``r`` is empty. .. function:: proc sample(r: range(bounds = boundKind.both, ?), n: int, withReplacement = false, seed: int): [] r.idxType throws Randomly sample ``n`` values from a range. :arg r: A fully bounded range to sample from :arg n: The number of values to sample :arg withReplacement: Whether or not to sample with replacement :arg seed: The seed to use when creating the ``randomStream`` :return: A zero-based array of ``n`` random values sampled from the range :throws IllegalArgumentError: If ``n < 1`` or if ``n > r.size`` and ``withReplacement=false``. If ``r`` is empty. .. function:: proc sample(r: range(bounds = boundKind.both, ?), n: int, const ref weights: [?dw] ?wt, withReplacement = false): [] r.idxType throws where is1DRectangularDomain(dw) && isRealType(wt) Randomly sample ``n`` values from a range, where each value has a corresponding weight. Values with relatively larger weights are more likely to be sampled. :arg r: A fully bounded range to sample from :arg n: The number of values to sample :arg weights: An array of real-valued weights corresponding to the values in ``r`` :arg withReplacement: Whether or not to sample with replacement :return: A zero-based array of ``n`` random values sampled from the range :throws IllegalArgumentError: If ``n < 1`` or if ``n > r.size`` and ``withReplacement=false``. If ``r`` is empty. If ``weights`` does not have the same size as ``r``. .. function:: proc sample(r: range(bounds = boundKind.both, ?), n: int, const ref weights: [?dw] ?wt, withReplacement = false, seed: int): [] r.idxType throws where is1DRectangularDomain(dw) && isRealType(wt) Randomly sample ``n`` values from a range, where each value has a corresponding weight. Values with relatively larger weights are more likely to be sampled. :arg r: A fully bounded range to sample from :arg n: The number of values to sample :arg weights: An array of real-valued weights corresponding to the values in ``r`` :arg withReplacement: Whether or not to sample with replacement :arg seed: The seed to use when creating the ``randomStream`` :return: A zero-based array of ``n`` random values sampled from the range :throws IllegalArgumentError: If ``n < 1`` or if ``n > r.size`` and ``withReplacement=false``. If ``r`` is empty. If ``weights`` does not have the same size as ``r``. .. record:: randomStream : writeSerializable A :record:`randomStream` represents a stream of pseudorandom numbers of a particular type. Numeric and bool types are supported. Conceptually it can be thought of as an indexed sequence of numbers ranging from 0 to infinity. Each index in the sequence corresponds to a random number of the specified type. This allows for the generation of random numbers in parallel, where each task involved in the parallel iteration can request random numbers within a particular range and traverse that range of the sequence independently of other tasks (see :proc:`randomStream.next`). Although parallel iteration is supported, the type itself is not thread-safe. In particular, it is not safe to call methods such as :proc:`next` or :proc:`fill` on the same ``randomStream`` from multiple tasks concurrently. When multiple tasks need to generate random numbers concurrently, a couple of approaches can be taken (other than using a parallel safe lock to protect the ``randomStream``): * Use the randomStream's parallel iteration methods: .. code-block:: chapel var A: [1..n] int; var rs = new randomStream(int); forall (r, a) in zip(rs.next(A.domain), A) do a = r; * Create a random stream for each task using task-private variables: .. code-block:: chapel var A: [1..n] int; forall a in A with (var rs = new randomStream(int)) do a = rs.next(); The ``randomStream`` provides several methods to generate random numbers or to manipulate arrays using random numbers: * :proc:`randomStream.fill`: fill an array with random numbers * :proc:`randomStream.shuffle`: randomly re-arrange the elements of an array * :proc:`randomStream.permute`: create a random permutation of an array, domain, or range * :proc:`randomStream.choose` randomly sample an element from an array, domain or range * :proc:`randomStream.sample` randomly sample elements from an array, domain, or range (with or without replacement) Note that the module provides top-level counterparts to these methods that internally create a ``randomStream`` and then call the corresponding method on it — convenient for one-off uses. To generate many random numbers, it is generally more efficient to create a ``randomStream`` and call the relevant method on it repeatedly. An individual random number can be generated using :proc:`randomStream.next` which will advance the stream to the next position and return the value at that position. The position of the stream can also be manipulated directly using :proc:`randomStream.skipTo`. When copied, the ``randomStream``'s seed, state, and position in the stream will also be copied. This means that the copy and original will produce the same sequence of random numbers without affecting each others state. .. note:: **Implementation Details:** This stream is implemented using the PCG random number generator algorithm. See http://www.pcg-random.org/ and the paper, `PCG: A Family of Simple Fast Space-Efficient Statistically Good Algorithms for Random Number Generation` by M.E. O'Neill. This record builds upon the :record:`~PCGRandomLib.pcg_setseq_64_xsh_rr_32_rng` PCG RNG which has 64 bits of state and 32 bits of output. While the PCG RNG used here is believed to have good statistical properties, it is not suitable for generating key material for encryption since the output of this RNG may be predictable. Additionally, if statistical properties of the random numbers are very important, another strategy may be required. We have good confidence that the random numbers generated by this record match the C PCG reference implementation and have specifically verified equal output given the same seed. However, this implementation differs from the C PCG reference implementation in how it produces random integers within particular bounds (with :proc:`randomStream.next` using ``min`` and ``max`` arguments). In addition, this implementation directly supports the generation of random ``real`` values, unlike the C PCG implementation. Smaller numbers, such as ``uint(8)`` or ``uint(16)``, are generated from the high-order bits of the 32-bit output. To generate larger numbers, several 32-bit-output RNGs are composed together. Each of these 32-bit RNGs has a different sequence constant and so will be independent and uncorrelated. For example, to generate 128-bit complex numbers, this RNG will use four 32-bit PCG RNGs with different sequence constants. One impact of this approach is that this implementation will only generate 2**64 different complex numbers with a given seed (for example). This record also supports generating integers within particular bounds. When that is required, it uses a strategy different from the PCG reference implementation to support efficient parallel iteration. In particular, when more than 1 random value is required as part of generating a value in a range, conceptually it uses more composed RNGs (as with the 32x2 strategy). Each new value beyond the first that is computed will be computed with a different RNG. This strategy is meant to avoid statistical bias. While we have tested this strategy to our satisfaction, it has not been subject to rigorous analysis and may have undesirable statistical properties. When generating a real, imaginary, or complex number, this implementation uses the strategy of generating a 64-bit unsigned integer and then multiplying it by 2.0**-64 in order to convert it to a floating point number. While this does construct a uniform distribution on rounded floating point values, it leaves out many possible real values (for example, 2**-128). We believe that this strategy has reasonable statistical properties. One side effect of this strategy is that the real number 1.0 can be generated because of rounding. The real number 0.0 can be generated because PCG can produce the value 0 as a random integer. We have tested this implementation with TestU01 (available at http://simul.iro.umontreal.ca/testu01/tu01.html ). We measured our implementation with TestU01 1.2.3 and the Crush suite, which consists of 144 statistical tests. The results were: * no failures for generating uniform reals * 1 failure for generating 32-bit values (which is also true for the reference version of PCG with the same configuration) * 0 failures for generating 64-bit values (which we provided to TestU01 as 2 different 32-bit values since it only accepts 32 bits at a time) * 0 failures for generating bounded integers (which we provided to TestU01 by requesting values in [0..,2**31+2**30+1) until we had two values < 2**31, removing the top 0 bit, and then combining the top 16 bits into the value provided to TestU01). .. attribute:: type eltType Specifies the type of value generated by the random stream. Currently, numeric and bool types are supported. .. attribute:: const seed: int The seed value for the PCG random number generator. .. method:: proc init(type eltType, seed: int) where isNumericOrBoolType(eltType) Create a new ``randomStream`` using the specified seed. .. method:: proc init(type eltType) where isNumericOrBoolType(eltType) Create a new ``randomStream``. A seed value will be generated in an implementation specific manner designed to minimize the chance that two distinct invocations of this initializer will produce the same seed. .. method:: proc ref fill(ref arr: [?d]) where arr.isRectangular() Fill the array with pseudorandom values sampled from this stream in parallel. :arg arr: The rectangular array to be filled .. method:: proc ref fill(ref arr: [?d] ?t, min: t, max: t) where arr.isRectangular() Fill the array with pseudorandom values within a particular range in parallel. Each array element is set to a number in [``min``, ``max``] (inclusive) sampled from this stream. :arg arr: The rectangular array to be filled :arg min: The minimum value to sample :arg max: The maximum value to sample .. method:: proc ref shuffle(ref arr: [?d]) where d.isRectangular() && isCoercible(this.eltType, d.idxType) Randomly rearrange an array using values from this random stream. :arg arr: The array to shuffle. Its domain's ``idxType`` should be coercible from this stream's :type:`eltType`. .. method:: proc ref permute(const ref arr: [?d] ?t): [] t where d.isRectangular() && isCoercible(this.eltType, d.idxType) Produce a random permutation of an array's elements :arg arr: A rectangular array whose domain's ``idxType`` must be coercible from this stream's ``eltType``. :return: A new array (defined over the domain ``d``) containing each of the values from ``arr`` in a pseudo-random order. .. method:: proc ref permute(d: domain(?)): [] d.fullIdxType where d.isRectangular() && isCoercible(this.eltType, d.idxType) Produce a random permutation of the indices in a domain. :arg d: A rectangular domain whose ``idxType`` must be coercible from this stream's ``eltType``. :return: An array (defined over the domain ``d``) containing each of the indices from ``d`` in a pseudo-random order. .. method:: proc ref permute(r: range(bounds = boundKind.both, ?)): [] r.idxType where isCoercible(this.eltType, r.idxType) Produce a random permutation of the values in a range. :arg r: A fully bounded range whose ``idxType`` must be coercible from this stream's ``eltType``. :return: An array (defined over the domain ``{r}``) containing each of the values from ``r`` in a pseudo-random order. .. method:: proc ref choose(const ref arr: [?d] ?t): t where d.isRectangular() && isCoercible(this.eltType, d.idxType) Choose a random element from an array. :arg arr: The rectangular array to choose from. Its domain's ``idxType`` should be coercible from this stream's ``eltType``. :return: A random element from the array .. method:: proc ref choose(d: domain(?)): d.fullIdxType where d.isRectangular() && isCoercible(this.eltType, d.idxType) Choose a random index from a domain. :arg d: The rectangular domain to choose from. Its ``idxType`` should be coercible from this stream's ``eltType``. :return: A random index from the domain .. method:: proc ref choose(r: range(bounds = boundKind.both, ?)): r.idxType where isCoercible(this.eltType, r.idxType) Choose a random value from a range. :arg r: The fully bounded range to choose from. Its ``idxType`` should be coercible from this stream's ``eltType``. :return: A random value from the range .. method:: proc ref sample(const ref arr: [?d] ?t, n: int, withReplacement = false): [] t throws where d.isRectangular() && isCoercible(this.eltType, d.idxType) Sample ``n`` random elements from an array. :arg arr: The rectangular array to sample from. Its domain's ``idxType`` should be coercible from this stream's ``eltType``. :arg n: The number of elements to sample :arg withReplacement: Whether or not to sample with replacement :return: A zero-based 1D array of ``n`` random elements sampled from the array :throws IllegalArgumentError: If ``n < 1`` or if ``n > arr.size`` and ``withReplacement=false``. If ``arr`` is empty. .. method:: proc ref sample(const ref arr: [?d] ?t, n: int, const ref weights: [?dw] ?wt, withReplacement = false): [] t throws where is1DRectangularDomain(d) && isCoercible(this.eltType, wt) Sample ``n`` random elements from an array, where each array element has a corresponding weight. Elements with relatively larger weights are more likely to be sampled. :arg arr: The 1D rectangular array to sample from. Its domain's ``idxType`` should be coercible from this stream's ``eltType``. :arg n: The number of elements to sample :arg weights: An array of weights corresponding to the elements in ``arr`` :arg withReplacement: Whether or not to sample with replacement :return: A zero-based 1D array of ``n`` random elements sampled from the array :throws IllegalArgumentError: If ``n < 1`` or if ``n > arr.size`` and ``withReplacement=false``. If ``arr`` is empty. If ``weights`` does not have the same size as ``arr``. .. method:: proc ref sample(d: domain, n: int, withReplacement = false): [] d.fullIdxType throws where d.isRectangular() && isCoercible(this.eltType, d.idxType) Sample ``n`` random indices from a domain. :arg d: The rectangular domain to sample from. Its ``idxType`` should be coercible from this stream's ``eltType``. :arg n: The number of indices to sample :arg withReplacement: Whether or not to sample with replacement :return: A zero-based 1D array of ``n`` random indices sampled from the domain :throws IllegalArgumentError: If ``n < 1`` or if ``n > arr.size`` and ``withReplacement=false``. If ``d`` is empty. .. method:: proc ref sample(d: domain, n: int, const ref weights: [?dw] ?wt, withReplacement = false): [] d.idxType throws where is1DRectangularDomain(d) && is1DRectangularDomain(dw) && isCoercible(this.eltType, wt) Sample ``n`` random indices from a domain, where each index has a corresponding weight. Indices with relatively larger weights are more likely to be sampled. :arg d: The 1D rectangular domain to sample from. Its ``idxType`` should be coercible from this stream's ``eltType``. :arg n: The number of indices to sample :arg weights: An array of weights corresponding to the indices in ``d`` :arg withReplacement: Whether or not to sample with replacement :return: A zero-based array of ``n`` random indices sampled from the domain :throws IllegalArgumentError: If ``n < 1`` or if ``n > d.size`` and ``withReplacement=false``. If ``d`` is empty. If ``weights`` does not have the same size as ``d``. .. method:: proc ref sample(r: range(bounds = boundKind.both, ?), n: int, withReplacement = false): [] r.idxType throws where isCoercible(this.eltType, r.idxType) Sample ``n`` random values from a range. :arg r: The fully bounded range to sample from. Its ``idxType`` should be coercible from this stream's ``eltType``. :arg n: The number of values to sample :arg withReplacement: Whether or not to sample with replacement :return: A zero-based array of ``n`` random values sampled from the range :throws IllegalArgumentError: If ``n < 1`` or if ``n > arr.size`` and ``withReplacement=false``. If ``r`` is empty. .. method:: proc ref sample(r: range(bounds = boundKind.both, ?), n: int, const ref weights: [?dw] ?wt, withReplacement = false): [] r.idxType throws where is1DRectangularDomain(dw) && isCoercible(this.eltType, wt) Sample ``n`` random values from a range where each value has a corresponding weight. Values with relatively larger weights are more likely to be sampled. :arg r: The fully bounded range to sample from. Its ``idxType`` should be coercible from this stream's ``eltType``. :arg n: The number of values to sample :arg weights: An array of weights corresponding to the values in ``r`` :arg withReplacement: Whether or not to sample with replacement :return: A zero-based array of ``n`` random values sampled from the range :throws IllegalArgumentError: If ``n < 1`` or if ``n > r.size`` and ``withReplacement=false``. If ``r`` is empty. If ``weights`` does not have the same size as ``r``. .. method:: proc ref next(): eltType Get the next value in the random stream and advance its position by one. Generated ``real`` values are in the range ``[0,1]``. Analogously, ``imag`` and ``complex`` numbers are in the range ``[0i,1i]`` and ``[0+0i,1+1i]`` respectively. Generated integers cover the full range of the type. .. method:: proc ref next(min: eltType, max: eltType): eltType Get the next random value from the stream within a given range. Returns a number in [``min``, ``max``] (inclusive). This method will halt if checks are enabled and ``min > max``. .. note:: For integers, this type uses a strategy for generating a value in a particular range that has not been subject to rigorous study and may have statistical problems. For real numbers, this type generates a random value in [max, min] by computing a random value in [0,1] and scaling and shifting that value. Note that not all possible floating point values in the interval [`min`, `max`] can be constructed in this way. :arg min: The minimum value to sample :arg max: The maximum value to sample .. method:: proc ref next(d: domain) Return an iterable object yielding values from the random stream. For example, a rectangular array ``A`` could be filled with random values using: .. code-block:: chapel var rs = new randomStream(int), A: [1..1000] int; forall (a, r) in zip(A, rs.next(A.domain)) do a = r; *Note that :proc:`randomStream.fill` also serves the same purpose.* :arg d: domain associated with the iteration. ``d.size`` values will be yielded by the iterator. When ``d`` is the first argument in a zippered iteration, its parallelization strategy will be used. .. method:: proc ref next(d: domain, min: eltType, max: eltType) Return an iterable object yielding values from the random stream within a given range. :arg d: domain associated with the iteration. ``d.size`` values will be yielded by the iterator. When ``d`` is the first argument in a zippered iteration, its parallelization strategy will be used. :arg min: The minimum value to sample :arg max: The maximum value to sample .. method:: proc ref skipTo(n: int) Advance or rewind the random stream to the ``n``-th position in the pseudorandom sequence (where ``n=0`` is the starting position) This method will halt for negative arguments if checks are enabled. :arg n: The position to skip to .. method:: proc serialize(writer, ref serializer) throws serialize the ``randomStream`` as a record with two fields: ``eltType`` and ``seed``.