Random¶
Usage
use Random;
or
import Random;
Submodules
Support for pseudorandom number generation.
This module provides the randomStream
type that represents a
conceptual stream of random numbers of a particular scalar type. Individual
numbers can be generated with 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
randomStream.skipTo
. Additionally, there are several methods for
generating random numbers from arrays, domains, and ranges.
This module also contains a few toplevel procedures for doing common tasks with pseudorandom numbers:
fillRandom
fills an array with random numbers in parallelshuffle
randomly rearranges the elements of an arraypermute
create a random permutation of an array, domain, or rangechoose
randomly selects an element from an array, domain, or rangesample
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 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
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 threadsafe and typeagnostic random number generator that can be used as a “global” random number generator.
 type RNG = _RNG¶
Warning
‘RNG’ is deprecated; please use the PCG algorithm via the
randomStream
type or the NPB algorithm via theNPBRandom
package moduleSelect between different supported RNG algorithms. See
PCGRandom
andNPBRandom
for details on these algorithms.
 param defaultRNG = _defaultRNG¶
Warning
‘defaultRNG’ is deprecated; please use the PCG algorithm via the
randomStream
type or the NPB algorithm via theNPBRandom
package moduleThe default RNG. The current default is PCG  see
PCGRandom
.
 type RandomStream = if _defaultRNG == _RNG.PCG then PCGRandomStreamInternal else NPBRandom.NPBRandomStream¶
Warning
the RandomStream class is deprecated; please use the
randomStream
record instead
 proc fillRandom(ref arr: [], seed: int(64) = _SeedGenerator.oddCurrentTime, param algorithm = _defaultRNG) where isNumericOrBoolType(arr.eltType)¶
Warning
The overload of fillRandom that accepts an ‘algorithm’ argument is deprecated; please remove the ‘algorithm’ argument
 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
randomStream
. The first arr.size values from the stream will be assigned to the array’s elements in rowmajor order. The parallelization strategy is determined by the array. Arguments:
arr – An array of numeric values
seed – The seed to use to create the
randomStream
 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
randomStream
. The first arr.size values from the stream will be assigned to the array’s elements in rowmajor 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.
 Arguments:
arr – An array of numeric values
 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 newrandomStream
. The first arr.size values from the stream will be assigned to the array’s elements in rowmajor order. The parallelization strategy is determined by the array. Arguments:
arr – An array of numeric values
min – The (inclusive) lower bound for the random values
max – The (inclusive) upper bound for the random values
seed – The seed to use to create the
randomStream
 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 newrandomStream
. The first arr.size values from the stream will be assigned to the array’s elements in rowmajor 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.
 Arguments:
arr – An array of numeric values
min – The (inclusive) lower bound for the random values
max – The (inclusive) upper bound for the random values
 proc shuffle(ref arr: [], seed: int(64) = _SeedGenerator.oddCurrentTime, param algorithm = _RNG.PCG)¶
Warning
The overload of ‘shuffle’ that accepts an ‘algorithm’ argument is deprecated; please remove the ‘algorithm’ argument
Shuffle the elements of a rectangular array into a random order.
 Arguments:
arr – a rectangular 1D nonstrided array
seed – the seed to use when shuffling. Defaults to oddCurrentTime from
RandomSupport.SeedGenerator
.algorithm :
RNG
– A param indicating which algorithm to use. Defaults to PCG.
 proc shuffle(ref arr: [?d], seed: int) where is1DRectangularDomain(d)
Use a new
randomStream
to shuffle an array in place. Arguments:
arr – A nonstrided default rectangular 1D array
seed – The seed to initialize a
randomStream
with
 proc shuffle(ref arr: [?d]) where is1DRectangularDomain(d)
Use a new
randomStream
to shuffle an array in place.Note
a seed will be generated in an implementation specific manner that depends on the current time.
 Arguments:
arr – A nonstrided default rectangular 1D array
 proc permute(const ref arr: [?d] ?t, seed: int) : [] t where is1DRectangularDomain(d)¶
Produce a random permutation of an array’s elements
 Arguments:
arr – A 1D rectangular array
seed – The seed to use when creating the
randomStream
 Returns:
A new array containing each of the values from
arr
in a pseudorandom order.
 proc permute(const ref arr: [?d] ?t) : [] t where is1DRectangularDomain(d)
Produce a random permutation of an array’s elements
 Arguments:
arr – A 1D rectangular array
 Returns:
A new array containing each of the values from
arr
in a pseudorandom order.
 proc permute(d: domain(?), seed: int) : [] d.idxType where is1DRectangularDomain(d)
Produce a random permutation of the indices in a domain.
 Arguments:
d – A 1D rectangular domain
seed – The seed to use when creating the
randomStream
 Returns:
An array containing each of the indices from
d
in a pseudorandom order.
 proc permute(d: domain(?)) : [] d.idxType where is1DRectangularDomain(d)
Produce a random permutation of the indices in a domain.
 Arguments:
d – A 1D rectangular domain
 Returns:
An array containing each of the indices from
d
in a pseudorandom order.
 proc permute(r: range(bounds = boundKind.both, ?), seed: int) : [] r.idxType
Produce a random permutation of the values in a range.
 Arguments:
r – A fully bounded range
seed – The seed to use when creating the
randomStream
 Returns:
An array containing each of the values from
r
in a pseudorandom order.
 proc permute(r: range(bounds = boundKind.both, ?)) : [] r.idxType
Produce a random permutation of the values in a range.
 Arguments:
r – A fully bounded range
 Returns:
An array containing each of the values from
r
in a pseudorandom order.
 proc permutation(ref arr: [], seed: int(64) = _SeedGenerator.oddCurrentTime, param algorithm = _RNG.PCG)¶
Warning
The overload of ‘permutation’ that accepts an ‘algorithm’ argument is deprecated; please remove the ‘algorithm’ argument
Produce a random permutation, storing it in a 1D array. The resulting array will include each value from low..high exactly once, where low and high refer to the array’s domain.
 Arguments:
arr – a rectangular 1D nonstrided array
seed – the seed to use when creating the permutation. Defaults to oddCurrentTime from
RandomSupport.SeedGenerator
.algorithm :
RNG
– A param indicating which algorithm to use. Defaults to PCG.
 proc permutation(ref arr: [?d] ?t, seed: int) where isCoercible(d.idxType, t) && is1DRectangularDomain(d)
Warning
‘permutation(arr, seed)’ is deprecated; please use ‘arr = permutation(arr.domain, seed)’ instead
Use a new
randomStream
to produce a random permutation of an array’s domain. The valuesd.dim(0).low..d.dim(0).high
will appear exactly once in the array in a pseudorandom order. Arguments:
arr – The array to store the permutation in
seed – The seed to use when creating the
randomStream
 proc permutation(ref arr: [?d] ?t) where isCoercible(d.idxType, t) && is1DRectangularDomain(d)
Warning
‘permutation(arr)’ is deprecated; please use ‘arr = permutation(arr.domain)’ instead
Use a new
randomStream
to produce a random permutation of an array’s domain. The valuesd.dim(0).low..d.dim(0).high
will appear exactly once in the array in a pseudorandom order.Note
a seed will be generated in an implementation specific manner that depends on the current time.
 Arguments:
arr – The array to store the permutation in
 proc choose(const ref arr: [?d] ?t) : t where is1DRectangularDomain(d)¶
Choose a random element from an array.
 Arguments:
arr – The 1D rectangular array to choose from
 Returns:
A random element from the array
 proc choose(const ref arr: [?d] ?t, seed: int) : t where is1DRectangularDomain(d)
Choose a random element from an array.
 Arguments:
arr – The 1D rectangular array to choose from
seed – The seed to use when creating the
randomStream
 Returns:
A random element from the array
 proc choose(d: domain(?)) : d.idxType
Choose a random index from a domain.
 Arguments:
d – The 1D rectangular domain to choose from
 Returns:
A random index from the domain
 proc choose(d: domain(?), seed: int) : d.idxType
Choose a random index from a domain.
 Arguments:
d – The 1D rectangular domain to choose from
seed – The seed to use when creating the
randomStream
 Returns:
A random index from the domain
 proc choose(r: range(bounds = boundKind.both, ?)) : r.idxType
Choose a random value from a range.
 Arguments:
r – A fully bounded range to choose from
 Returns:
A random value from the range
 proc choose(r: range(bounds = boundKind.both, ?), seed: int) : r.idxType
Choose a random value from a range.
 Arguments:
r – A fully bounded range to choose from
seed – The seed to use when creating the
randomStream
 Returns:
A random value from the range
 proc sample(const ref arr: [?d] ?t, n: int, withReplacement = false) : [] t throws where is1DRectangularDomain(d)¶
Randomly sample
n
elements from an array. Arguments:
arr – The 1D rectangular array to sample from
n – The number of elements to sample
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random elements sampled from the array Throws:
IllegalArgumentError – If
n < 1
or ifn > arr.size
andwithReplacement=false
. Ifarr
is empty.
 proc sample(const ref arr: [?d] ?t, n: int, withReplacement = false, seed: int) : [] t throws where is1DRectangularDomain(d)
Randomly sample
n
elements from an array. Arguments:
arr – The 1D rectangular array to sample from
n – The number of elements to sample
withReplacement – Whether or not to sample with replacement
seed – The seed to use when creating the
randomStream
 Returns:
A zerobased array of
n
random elements sampled from the array Throws:
IllegalArgumentError – If
n < 1
or ifn > arr.size
andwithReplacement=false
. Ifarr
is empty.
 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.
 Arguments:
arr – The 1D rectangular array to sample from
n – The number of elements to sample
weights – An array of realvalued weights corresponding to the elements in
arr
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random elements sampled from the array Throws:
IllegalArgumentError – If
n < 1
or ifn > arr.size
andwithReplacement=false
. Ifarr
is empty. Ifweights
does not have the same size asarr
.
 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.
 Arguments:
arr – The 1D rectangular array to sample from
n – The number of elements to sample
weights – An array of realvalued weights corresponding to the elements in
arr
withReplacement – Whether or not to sample with replacement
seed – The seed to use when creating the
randomStream
 Returns:
A zerobased array of
n
random elements sampled from the array Throws:
IllegalArgumentError – If
n < 1
or ifn > arr.size
andwithReplacement=false
. Ifarr
is empty. Ifweights
does not have the same size asarr
.
 proc sample(d: domain(?), n: int, withReplacement = false) : [] d.idxType throws where is1DRectangularDomain(d)
Randomly sample
n
indices from a domain. Arguments:
d – The 1D rectangular domain to sample from
n – The number of indices to sample
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random indices sampled from the domain Throws:
IllegalArgumentError – If
n < 1
or ifn > arr.size
andwithReplacement=false
. Ifd
is empty.
 proc sample(d: domain(?), n: int, withReplacement = false, seed: int) : [] d.idxType throws where is1DRectangularDomain(d)
Randomly sample
n
indices from a domain. Arguments:
d – The 1D rectangular domain to sample from
n – The number of indices to sample
withReplacement – Whether or not to sample with replacement
seed – The seed to use when creating the
randomStream
 Returns:
A zerobased array of
n
random indices sampled from the domain Throws:
IllegalArgumentError – If
n < 1
or ifn > arr.size
andwithReplacement=false
. Ifd
is empty.
 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.
 Arguments:
d – The 1D rectangular domain to sample from
n – The number of indices to sample
weights – An array of realvalued weights corresponding to the indices in
d
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random indices sampled from the domain Throws:
IllegalArgumentError – If
n < 1
or ifn > d.size
andwithReplacement=false
. Ifd
is empty. Ifweights
does not have the same size asd
.
 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.
 Arguments:
d – The 1D rectangular domain to sample from
n – The number of elements to sample
weights – An array of realvalued weights corresponding to the elements in
d
withReplacement – Whether or not to sample with replacement
seed – The seed to use when creating the
randomStream
 Returns:
A zerobased array of
n
random indices sampled from the domain Throws:
IllegalArgumentError – If
n < 1
or ifn > d.size
andwithReplacement=false
. Ifd
is empty. Ifweights
does not have the same size asd
.
 proc sample(r: range(bounds = boundKind.both, ?), n: int, withReplacement = false) : [] r.idxType throws
Randomly sample
n
values from a range. Arguments:
r – A fully bounded range to sample from
n – The number of values to sample
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random values sampled from the range Throws:
IllegalArgumentError – If
n < 1
or ifn > r.size
andwithReplacement=false
. Ifr
is empty.
 proc sample(r: range(bounds = boundKind.both, ?), n: int, withReplacement = false, seed: int) : [] r.idxType throws
Randomly sample
n
values from a range. Arguments:
r – A fully bounded range to sample from
n – The number of values to sample
withReplacement – Whether or not to sample with replacement
seed – The seed to use when creating the
randomStream
 Returns:
A zerobased array of
n
random values sampled from the range Throws:
IllegalArgumentError – If
n < 1
or ifn > r.size
andwithReplacement=false
. Ifr
is empty.
 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.
 Arguments:
r – A fully bounded range to sample from
n – The number of values to sample
weights – An array of realvalued weights corresponding to the values in
r
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random values sampled from the range Throws:
IllegalArgumentError – If
n < 1
or ifn > r.size
andwithReplacement=false
. Ifr
is empty. Ifweights
does not have the same size asr
.
 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.
 Arguments:
r – A fully bounded range to sample from
n – The number of values to sample
weights – An array of realvalued weights corresponding to the values in
r
withReplacement – Whether or not to sample with replacement
seed – The seed to use when creating the
randomStream
 Returns:
A zerobased array of
n
random values sampled from the range Throws:
IllegalArgumentError – If
n < 1
or ifn > r.size
andwithReplacement=false
. Ifr
is empty. Ifweights
does not have the same size asr
.
 record randomStream : writeSerializable¶
A
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
randomStream.next
).Although parallel iteration is supported, the type itself is not threadsafe. In particular, it is not safe to call methods such as
next
orfill
on the samerandomStream
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 therandomStream
):Use the randomStream’s parallel iteration methods:
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 taskprivate variables:
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:randomStream.fill
: fill an array with random numbersrandomStream.shuffle
: randomly rearrange the elements of an arrayrandomStream.permute
: create a random permutation of an array, domain, or rangerandomStream.choose
randomly sample an element from an array, domain or rangerandomStream.sample
randomly sample elements from an array, domain, or range (with or without replacement)
Note that the module provides toplevel counterparts to these methods that internally create a
randomStream
and then call the corresponding method on it — convenient for oneoff uses. To generate many random numbers, it is generally more efficient to create arandomStream
and call the relevant method on it repeatedly.An individual random number can be generated using
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 usingrandomStream.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.pcgrandom.org/ and the paper, PCG: A Family of Simple Fast SpaceEfficient Statistically Good Algorithms for Random Number Generation by M.E. O’Neill.
This record builds upon the
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
randomStream.getNext
usingmin
andmax
arguments). In addition, this implementation directly supports the generation of randomreal
values, unlike the C PCG implementation.Smaller numbers, such as
uint(8)
oruint(16)
, are generated from the highorder bits of the 32bit output.To generate larger numbers, several 32bitoutput RNGs are composed together. Each of these 32bit RNGs has a different sequence constant and so will be independent and uncorrelated. For example, to generate 128bit complex numbers, this RNG will use four 32bit 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 64bit 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 32bit values (which is also true for the reference version of PCG with the same configuration)
0 failures for generating 64bit values (which we provided to TestU01 as 2 different 32bit 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).
 type eltType¶
Specifies the type of value generated by the random stream. Currently, numeric and bool types are supported.
 const seed : int¶
The seed value for the PCG random number generator.
 proc init(type eltType, seed: int) where isNumericOrBoolType(eltType)¶
Create a new
randomStream
using the specified seed.
 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.
 proc ref fill(ref arr: []) where arr.isRectangular()¶
Fill the array with pseudorandom values sampled from this stream in parallel.
 Arguments:
arr – The rectangular array to be filled
 proc ref fill(ref arr: [] ?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. Arguments:
arr – The rectangular array to be filled
min – The minimum value to sample
max – The maximum value to sample
 proc ref fillRandom(ref arr: [])¶
Warning
‘randomStream.fillRandom’ is deprecated; please use ‘fill’ instead
 proc ref fillRandom(ref arr: [], min, max)
Warning
‘randomStream.fillRandom’ is deprecated; please use ‘fill’ instead
 proc ref shuffle(ref arr: [?d]) where is1DRectangularDomain(d) && isCoercible(this.eltType, d.idxType)¶
Randomly rearrange a 1D array using values from this random stream.
 Arguments:
arr – The array to shuffle. Its domain’s
idxType
should be coercible to this stream’seltType
.
 proc ref permute(const ref arr: [?d] ?t) : [] t where is1DRectangularDomain(d) && isCoercible(this.eltType, d.idxType)¶
Produce a random permutation of an array’s elements
 Arguments:
arr – A 1D rectangular array whose domain’s
idxType
must be coercible from this stream’seltType
. Returns:
A new array containing each of the values from
arr
in a pseudorandom order.
 proc ref permute(d: domain(?)) : [] d.idxType where is1DRectangularDomain(d) && isCoercible(this.eltType, d.idxType)
Produce a random permutation of the indices in a domain.
 Arguments:
d – A 1D rectangular domain whose
idxType
must be coercible from this stream’seltType
. Returns:
An array containing each of the indices from
d
in a pseudorandom order.
 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.
 Arguments:
r – A fully bounded range whose
idxType
must be coercible from this stream’seltType
. Returns:
An array containing each of the values from
r
in a pseudorandom order.
 proc ref permutation(ref arr: [?d] ?t) where isCoercible(this.eltType, d.idxType) && isCoercible(d.idxType, t) && is1DRectangularDomain(d)¶
Warning
‘randomStream.permutation(arr)’ is deprecated; please use ‘arr = randomStream.permutation(arr.domain)’ instead
Produce a random permutation of an array’s domain. The values
d.dim(0).low..d.dim(0).high
will appear exactly once in the array in a pseudorandom order. Arguments:
arr – The array to store the permutation in
 proc ref choose(const ref arr: [?d] ?t) : t where is1DRectangularDomain(d) && isCoercible(this.eltType, d.idxType)¶
Choose a random element from an array.
 Arguments:
arr – The 1D rectangular array to choose from. Its domain’s
idxType
should be coercible from this stream’seltType
. Returns:
A random element from the array
 proc ref choose(d: domain(?)) : d.idxType where is1DRectangularDomain(d) && isCoercible(this.eltType, d.idxType)
Choose a random index from a domain.
 Arguments:
d – The 1D rectangular domain to choose from. Its
idxType
should be coercible from this stream’seltType
. Returns:
A random index from the domain
 proc ref choose(r: range(bounds = boundKind.both, ?)) : r.idxType where isCoercible(this.eltType, r.idxType)
Choose a random value from a range.
 Arguments:
r – The fully bounded range to choose from. Its
idxType
should be coercible from this stream’seltType
. Returns:
A random value from the range
 proc ref sample(const ref arr: [?d] ?t, n: int, withReplacement = false) : [] t throws where is1DRectangularDomain(d) && isCoercible(this.eltType, d.idxType)¶
Sample
n
random elements from an array. Arguments:
arr – The 1D rectangular array to sample from. Its domain’s
idxType
should be coercible from this stream’seltType
.n – The number of elements to sample
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random elements sampled from the array Throws:
IllegalArgumentError – If
n < 1
or ifn > arr.size
andwithReplacement=false
. Ifarr
is empty.
 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.
 Arguments:
arr – The 1D rectangular array to sample from. Its domain’s
idxType
should be coercible from this stream’seltType
.n – The number of elements to sample
weights – An array of weights corresponding to the elements in
arr
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random elements sampled from the array Throws:
IllegalArgumentError – If
n < 1
or ifn > arr.size
andwithReplacement=false
. Ifarr
is empty. Ifweights
does not have the same size asarr
.
 proc ref sample(d: domain, n: int, withReplacement = false) : [] d.idxType throws where is1DRectangularDomain(d) && isCoercible(this.eltType, d.idxType)
Sample
n
random indices from a domain. Arguments:
d – The 1D rectangular domain to sample from. Its
idxType
should be coercible from this stream’seltType
.n – The number of indices to sample
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random indices sampled from the domain Throws:
IllegalArgumentError – If
n < 1
or ifn > arr.size
andwithReplacement=false
. Ifd
is empty.
 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.
 Arguments:
d – The 1D rectangular domain to sample from. Its
idxType
should be coercible from this stream’seltType
.n – The number of indices to sample
weights – An array of weights corresponding to the indices in
d
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random indices sampled from the domain Throws:
IllegalArgumentError – If
n < 1
or ifn > d.size
andwithReplacement=false
. Ifd
is empty. Ifweights
does not have the same size asd
.
 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. Arguments:
r – The fully bounded range to sample from. Its
idxType
should be coercible from this stream’seltType
.n – The number of values to sample
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random values sampled from the range Throws:
IllegalArgumentError – If
n < 1
or ifn > arr.size
andwithReplacement=false
. Ifr
is empty.
 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.
 Arguments:
r – The fully bounded range to sample from. Its
idxType
should be coercible from this stream’seltType
.n – The number of values to sample
weights – An array of weights corresponding to the values in
r
withReplacement – Whether or not to sample with replacement
 Returns:
A zerobased array of
n
random values sampled from the range Throws:
IllegalArgumentError – If
n < 1
or ifn > r.size
andwithReplacement=false
. Ifr
is empty. Ifweights
does not have the same size asr
.
 proc ref choice(const x: [?d], size: ?sizeType = none, replace = true, prob: ?probType = none) throws where is1DRectangularDomain(d) && isCoercible(this.eltType, d.idxType)¶

Return a random sample from a given 1D array,
x
. Arguments:
x – The array to take a sample from.
size – An optional integral value specifying the number of elements to choose, or a domain specifying the dimensions of the sampled array to be filled, otherwise a single element will be chosen.
replace – an optional
bool
specifying whether or not to sample with replacement, i.e. elements will only be chosen up to one time whenreplace=false
.prob – an optional 1D array that contains probabilities of choosing each element of
x
, otherwise elements will be chosen over a uniform distribution.prob
must have integral or real element type, with no negative values and at least one nonzero value. The size must be equal to that ofx.domain
.
 Returns:
An element chosen from
x
ifsize == 1
, or an array of elements chosen fromx
ifsize > 1
orsize
is a domain. Throws:
IllegalArgumentError – if
x.size == 0
, ifx.size != prob.size
, ifprob
contains a negative value, ifprob
has no nonzero values, ifsize < 1  size.size < 1
, ifreplace=false
andsize > x.size  size.size > x.size
 proc ref choice(x: range(?), size: ?sizeType = none, replace = true, prob: ?probType = none) throws where isCoercible(this.eltType, x.idxType)

Return a random sample from a given bounded range,
x
. Arguments:
x – a bounded range with values that will be sampled from.
size – An optional integral value specifying the number of elements to choose, or a domain specifying the dimensions of the sampled array to be filled, otherwise a single element will be chosen.
replace – an optional
bool
specifying whether or not to sample with replacement, i.e. elements will only be chosen up to one time whenreplace=false
.prob – an optional 1D array that contains probabilities of choosing each element of
x
, otherwise elements will be chosen over a uniform distribution.prob
must have integral or real element type, with no negative values and at least one nonzero value. The size must be equal to that ofx
.
 Returns:
An element chosen from
x
ifsize == 1
, or an array of element chosen fromx
ifsize > 1
orsize
is a domain. Throws:
IllegalArgumentError – if
x.size == 0
, ifx.size != prob.size
, ifprob
contains a negative value, ifprob
has no nonzero values, ifsize < 1  size.size < 1
, ifreplace=false
andsize > x.size  size.size > x.size
 proc ref choice(x: domain, size: ?sizeType = none, replace = true, prob: ?probType = none) throws where is1DRectangularDomain(x) && isCoercible(this.eltType, x.idxType)

Return a random sample from a given 1D domain,
x
. Arguments:
x – a 1D domain with values that will be sampled from.
size – An optional integral value specifying the number of elements to choose, or a domain specifying the dimensions of the sampled array to be filled, otherwise a single element will be chosen.
replace – an optional
bool
specifying whether or not to sample with replacement, i.e. elements will only be chosen up to one time whenreplace=false
.prob – an optional 1D array that contains probabilities of choosing each element of
x
, otherwise elements will be chosen over a uniform distribution.prob
must have integral or real element type, with no negative values and at least one nonzero value. The size must be equal to that ofx
.
 Returns:
An element chosen from
x
ifsize == 1
, or an array of element chosen fromx
ifsize > 1
orsize
is a domain. Throws:
IllegalArgumentError – if
x.size == 0
, ifx.size != prob.size
, ifprob
contains a negative value, ifprob
has no nonzero values, ifsize < 1  size.size < 1
, ifreplace=false
andsize > x.size  size.size > x.size
.
 proc ref next() : eltType¶
Get the next value in the random stream and advance its position by one.
 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.
 Arguments:
min – The minimum value to sample
max – The maximum value to sample
 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: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.
 Arguments:
d – domain associated with the iteration.
d.size
values will be yielded by the iterator. Whend
is the first argument in a zippered iteration, its parallelization strategy will be used.
 proc ref next(d: domain, min: eltType, max: eltType)
Return an iterable object yielding values from the random stream within a given range.
 Arguments:
d – domain associated with the iteration.
d.size
values will be yielded by the iterator. Whend
is the first argument in a zippered iteration, its parallelization strategy will be used.min – The minimum value to sample
max – The maximum value to sample
 proc ref getNext(min: eltType, max: eltType) : eltType
Warning
randomStream.getNext is deprecated; please use
next
instead
 proc ref skipTo(n: int)¶
Advance or rewind the random stream to the
n
th position in the pseudorandom sequence (wheren=0
is the starting position)This method will halt for negative arguments if checks are enabled.
 Arguments:
n – The position to skip to
 proc ref getNth(n: integral) : eltType throws¶

Advance or rewind the random stream to the
n
th position in the pseudorandom sequence and return the value. This is equivalent toskipToNth
followed bygetNext
. Arguments:
n – The position to skip to and retrieve (must be greater than zero)
 Throws:
IllegalArgumentError – If
n
is negative
 proc ref iterate(D: domain, min: eltType, max: eltType)
Warning
iterate is deprecated; please use
next
instead
 proc serialize(writer, ref serializer) throws¶
serialize the
randomStream
as a record with two fields:eltType
andseed
.
 proc createRandomStream(type eltType, seed: int(64) = _SeedGenerator.oddCurrentTime, param parSafe: bool = true, param algorithm = _defaultRNG)¶
Warning
‘createRandomStream’ is deprecated; please use ‘new randomStream’ instead
Constructs a new stream of random numbers using the specified seed and parallel safety. Ensures that the seed value meets the PRNG’s constraints.
Note
The
NPBRandom
RNG will halt if provided an even seed.PCGRandom
has no restrictions on the provided seed value. Arguments:
eltType : type – The element type to be generated.
seed : int(64) – The seed to use for the PRNG. Defaults to oddCurrentTime from
RandomSupport.SeedGenerator
.parSafe : bool – The parallel safety setting. Defaults to true.
algorithm :
RNG
– A param indicating which algorithm to use. Defaults todefaultRNG
.
 Returns:
an owned RandomStream
 class RandomStreamInterface : writeSerializable¶
Warning
‘RandomStreamInterface’ is deprecated
Models a stream of pseudorandom numbers. This class is defined for documentation purposes and should not be instantiated. See
PCGRandom
andNPBRandom
for RNGs that can be instantiated. To create a random stream, usecreateRandomStream
.Note
At present, different implementations of this interface can vary in whether or not they can generate 0.0 and/or 1.0. (e.g. They can be generated by
PCGRandom
but not byNPBRandom
).Note
We plan to support general serial and parallel iterator methods on
RandomStreamInterface
; however, providing the full suite of iterators is not possible with our current parallel iterator framework. Specifically, ifRandomStreamInterface
is a follower in a zippered iteration context, there is no way for it to update the total number of random numbers generated in a safe/sane/coordinated way. We are exploring a revised leaderfollower iterator framework that would support this idiom (and other cursorbased ones). With Chapel’s recent support for standalone parallel iterators, one could define a standalone parallel iterator forRandomStreamInterface
, but this effort has not yet been taken on.Note
The
RandomStreamInterface
is included here only for documentation and does not help with compilation in any way. In the future, we hope to turn it into an interface. type eltType = real(64)¶
Specifies the type of value generated by the RandomStream. Not all RandomStream implementations support all types.
 param parSafe : bool = true¶
Indicates whether or not the RandomStream needs to be parallelsafe by default. If multiple tasks interact with it in an uncoordinated fashion, this must be set to true. If it will only be called from a single task, or if only one task will call into it at a time, setting to false will reduce overhead related to ensuring mutual exclusion.
 const seed : int(64)¶
The seed value for the PRNG. There may be constraints upon legal values depending on the specific RNG.
 proc getNext() : eltType¶
Returns the next value in the random stream.
 Returns:
The next value in the random stream as type
eltType
.
 proc skipToNth(n: integral) throws¶
Advances/rewinds the stream to the nth value in the sequence. The first value corresponds to n=0. n must be >= 0, otherwise an IllegalArgumentError is thrown.
 Arguments:
n : integral – The position in the stream to skip to. Must be >= 0.
 Throws:
IllegalArgumentError – When called with negative n value.
 proc getNth(n: integral) : eltType throws¶
Advance/rewind the stream to the nth value and return it (advancing the stream by one). n must be >= 0, otherwise an IllegalArgumentError is thrown. This is equivalent to
skipToNth()
followed bygetNext()
. Arguments:
n : integral – The position in the stream to skip to. Must be >= 0.
 Returns:
The nth value in the random stream as type
eltType
. Throws:
IllegalArgumentError – When called with negative n value.
 proc fillRandom(ref arr: [] eltType)¶
Fill the argument array with pseudorandom values. This method is identical to the standalone
fillRandom
procedure, except that it consumes random values from theRandomStreamInterface
object on which it’s invoked rather than creating a new stream for the purpose of the call. Arguments:
arr : []
eltType
– The array to be filled
 proc choice(const x: [], size: ?sizeType = none, replace = true, prob: ?probType = none) throws¶
Returns a random sample from a given 1D array,
x
. Arguments:
x – a 1D array with values that will be sampled from.
size – An optional integral value specifying the number of elements to choose, or a domain specifying the dimensions of the sampled array to be filled, otherwise a single element will be chosen.
replace – an optional
bool
specifying whether or not to sample with replacement, i.e. elements will only be chosen up to one time whenreplace=false
.prob – an optional 1D array that contains probabilities of choosing each element of
x
, otherwise elements will be chosen over a uniform distribution.prob
must have integral or real element type, with no negative values and at least one nonzero value. The size must be equal to that ofx.domain
.
 Returns:
An element chosen from
x
ifsize == 1
, or an array of element chosen fromx
ifsize > 1
orsize
is a domain. Throws:
IllegalArgumentError – if
x.size == 0
, ifx.size != prob.size
, ifprob
contains a negative value, ifprob
has no nonzero values, ifsize < 1  size.size < 1
, ifreplace=false
andsize > x.size  size.size > x.size
 proc choice(x: range(strides = ?), size: ?sizeType = none, replace = true, prob: ?probType = none) throws
Returns a random sample from a given bounded range,
x
. Arguments:
x – a bounded range with values that will be sampled from.
size – An optional integral value specifying the number of elements to choose, or a domain specifying the dimensions of the sampled array to be filled, otherwise a single element will be chosen.
replace – an optional
bool
specifying whether or not to sample with replacement, i.e. elements will only be chosen up to one time whenreplace=false
.prob – an optional 1D array that contains probabilities of choosing each element of
x
, otherwise elements will be chosen over a uniform distribution.prob
must have integral or real element type, with no negative values and at least one nonzero value. The size must be equal to that ofx
.
 Returns:
An element chosen from
x
ifsize == 1
, or an array of element chosen fromx
ifsize > 1
orsize
is a domain. Throws:
IllegalArgumentError – if
x.size == 0
, ifx.size != prob.size
, ifprob
contains a negative value, ifprob
has no nonzero values, ifsize < 1  size.size < 1
, ifreplace=false
andsize > x.size  size.size > x.size
.
 proc choice(x: domain, size: ?sizeType = none, replace = true, prob: ?probType = none) throws
Returns a random sample from a given 1D domain,
x
. Arguments:
x – a 1D dom with values that will be sampled from.
size – An optional integral value specifying the number of elements to choose, or a domain specifying the dimensions of the sampled array to be filled, otherwise a single element will be chosen.
replace – an optional
bool
specifying whether or not to sample with replacement, i.e. elements will only be chosen up to one time whenreplace=false
.prob – an optional 1D array that contains probabilities of choosing each element of
x
, otherwise elements will be chosen over a uniform distribution.prob
must have integral or real element type, with no negative values and at least one nonzero value. The size must be equal to that ofx
.
 Returns:
An element chosen from
x
ifsize == 1
, or an array of element chosen fromx
ifsize > 1
orsize
is a domain. Throws:
IllegalArgumentError – if
x.size == 0
, ifx.size != prob.size
, ifprob
contains a negative value, ifprob
has no nonzero values, ifsize < 1  size.size < 1
, ifreplace=false
andsize > x.size  size.size > x.size
.
 proc iterate(D: domain, type resultType = eltType)¶
Returns an iterable expression for generating D.size random numbers. The RNG state will be immediately advanced by D.size before the iterable expression yields any values.
The returned iterable expression is useful in parallel contexts, including standalone and zippered iteration. The domain will determine the parallelization strategy.
 Arguments:
D – a domain
resultType – the type of number to yield
 Returns:
an iterable expression yielding random resultType values