Random¶
Usage
use Random;
or
import Random;
Submodules
Support for pseudorandom number generation.
This module defines an abstraction for a stream of pseudorandom numbers,
RandomStreamInterface
. Use createRandomStream
to
create such an stream. Each stream supports methods to get the next
random number in the stream (getNext
),
to fast-forward to a specific value in the stream
(skipToNth
and
getNth
), to iterate over random values
possibly in parallel (iterate
), or to
fill an array with random numbers in parallel
(fillRandom
).
The module also provides several standalone convenience functions that can be
used without manually creating a RandomStreamInterface
object.
fillRandom
fills an array with random numbers in parallel
shuffle
randomly re-arranges the elements of an array
permutation
creates a random permutation and stores it in an array.
In these and other methods, generated integer values are uniformly distributed from min(T) to max(T), where T is the integral type and the boundaries are included. Generated floating point values are uniformly distributed in [0.0, 1.0] with the caveat that it currently depends on the RNG whether the boundary values 0.0 and 1.0 can be produced.
Use createRandomStream
or the constructor for a specific RNG
implementation to get a RandomStream. See the documentation for
each RNG implementation for more information:
Note
The RandomStream API (RandomStreamInterface
) is expected to
change.
Warning
The Random module is unstable and may change in the future
- enum RNG { PCG = 1, NPB = 2 }¶
Select between different supported RNG algorithms. See
PCGRandom
andNPBRandom
for details on these algorithms.- enum constant PCG = 1¶
- enum constant NPB = 2¶
- type RandomStream = if defaultRNG == RNG.PCG then PCGRandomStream else NPBRandomStream¶
- proc fillRandom(ref arr: [], seed: int(64) = SeedGenerator.oddCurrentTime, param algorithm = defaultRNG) where isSupportedNumericType(arr.eltType)¶
Fills a rectangular array of numeric elements with pseudorandom values in parallel using a new stream implementing
RandomStreamInterface
created specifically for this call. 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
NPBRandom
only supports real(64), imag(64), and complex(128) numeric types.PCGRandom
supports all primitive numeric types.- Arguments
arr : [] T – The array to be filled, where T is a primitive numeric type. Only rectangular arrays are supported currently.
seed : int(64) – The seed to use for the PRNG. Defaults to oddCurrentTime from
RandomSupport.SeedGenerator
.algorithm :
RNG
– A param indicating which algorithm to use. Defaults todefaultRNG
.
- proc fillRandom(ref arr: [], min: arr.eltType, max: arr.eltType, seed: int(64) = SeedGenerator.oddCurrentTime) where isSupportedNumericType(arr.eltType)
Fills a rectangular array of numeric elements with pseudorandom values in the range [min, max] (inclusive) in parallel using a new
PCGRandom.PCGRandomStream
created specifically for this call. 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.- Arguments
arr : [] T – The array to be filled, where T is a primitive numeric type. Only rectangular arrays are supported currently.
min – The (inclusive) lower bound for the random values used.
max – The (inclusive) upper bound for the random values used.
seed : int(64) – The seed to use for the PRNG. Defaults to oddCurrentTime from
RandomSupport.SeedGenerator
.
- proc shuffle(ref arr: [], seed: int(64) = SeedGenerator.oddCurrentTime, param algorithm = RNG.PCG)¶
Shuffle the elements of a rectangular array into a random order.
- Arguments
arr – a rectangular 1-D non-strided 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 permutation(ref arr: [], seed: int(64) = SeedGenerator.oddCurrentTime, param algorithm = RNG.PCG)¶
Produce a random permutation, storing it in a 1-D 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 1-D non-strided 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 createRandomStream(type eltType, seed: int(64) = SeedGenerator.oddCurrentTime, param parSafe: bool = true, param algorithm = defaultRNG)¶
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¶
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
This RandomStreamInterface is expected to change`.
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 leader-follower iterator framework that would support this idiom (and other cursor-based 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 parallel-safe 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 n-th 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 n-th 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 n-th 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 1-D array,
x
.- Arguments
x – a 1-D 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 1-D 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 non-zero 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 non-zero 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 1-D 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 non-zero 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 non-zero 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 1-D domain,
x
.- Arguments
x – a 1-D 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 1-D 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 non-zero 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 non-zero 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