jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation for random (#17015)

Browse source 
* Improve documentation for random

Use runnableExamples
Minor changes

* Apply suggestions

Remove echo
Use RNG in more places

* Fix skipRandomNumbers example
This commit is contained in:
konsumlamm 2021-02-12 15:10:12 +01:00 • committed by GitHub
commit f57774e1e7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 168 additions and 185 deletions
Download patch file Download diff file Expand all files Collapse all files

309
lib/pure/random.nim
View file

@ -7,9 +7,9 @@
# distribution, for details about the copyright. # distribution, for details about the copyright.
# #
## Nim's standard random number generator. ## Nim's standard random number generator (RNG).
## ##
## Its implementation is based on the ``xoroshiro128+`` ## Its implementation is based on the `xoroshiro128+`
## (xor/rotate/shift/rotate) library. ## (xor/rotate/shift/rotate) library.
## * More information: http://xoroshiro.di.unimi.it ## * More information: http://xoroshiro.di.unimi.it
## * C implementation: http://xoroshiro.di.unimi.it/xoroshiro128plus.c ## * C implementation: http://xoroshiro.di.unimi.it/xoroshiro128plus.c
@ -19,39 +19,34 @@
## Basic usage ## Basic usage
## =========== ## ===========
## ##
## To get started, here are some examples: runnableExamples:
## # Call randomize() once to initialize the default random number generator.
## .. code-block:: # If this is not called, the same results will occur every time these
## # examples are run.
## import random randomize()
##
## # Call randomize() once to initialize the default random number generator # Pick a number in 0..100.
## # If this is not called, the same results will occur every time these let num = rand(100)
## # examples are run doAssert num in 0..100
## randomize()
## # Roll a six-sided die.
## # Pick a number between 0 and 100 let roll = rand(1..6)
## let num = rand(100) doAssert roll in 1..6
## echo num
## # Pick a marble from a bag.
## # Roll a six-sided die let marbles = ["red", "blue", "green", "yellow", "purple"]
## let roll = rand(1..6) let pick = sample(marbles)
## echo roll doAssert pick in marbles
##
## # Pick a marble from a bag # Shuffle some cards.
## let marbles = ["red", "blue", "green", "yellow", "purple"] var cards = ["Ace", "King", "Queen", "Jack", "Ten"]
## let pick = sample(marbles) shuffle(cards)
## echo pick doAssert cards.len == 5
##
## # Shuffle some cards ## These examples all use the default RNG. The
## var cards = ["Ace", "King", "Queen", "Jack", "Ten"] ## `Rand type <#Rand>`_ represents the state of an RNG.
## shuffle(cards)
## echo cards
##
## These examples all use the default random number generator. The
## `Rand type<#Rand>`_ represents the state of a random number generator.
## For convenience, this module contains a default Rand state that corresponds ## For convenience, this module contains a default Rand state that corresponds
## to the default random number generator. Most procs in this module which do ## to the default RNG. Most procs in this module which do
## not take in a Rand parameter, including those called in the above examples, ## not take in a Rand parameter, including those called in the above examples,
## use the default generator. Those procs are **not** thread-safe. ## use the default generator. Those procs are **not** thread-safe.
## ##
@ -59,10 +54,10 @@
## The `randomize proc <#randomize>`_ can be called to initialize the default ## The `randomize proc <#randomize>`_ can be called to initialize the default
## generator with a seed based on the current time, and it only needs to be ## generator with a seed based on the current time, and it only needs to be
## called once before the first usage of procs from this module. If ## called once before the first usage of procs from this module. If
## ``randomize`` is not called, then the default generator will always produce ## `randomize` is not called, the default generator will always produce
## the same results. ## the same results.
## ##
## Generators that are independent of the default one can be created with the ## RNGs that are independent of the default one can be created with the
## `initRand proc <#initRand,int64>`_. ## `initRand proc <#initRand,int64>`_.
## ##
## Again, it is important to remember that this module must **not** be used for ## Again, it is important to remember that this module must **not** be used for
@ -70,19 +65,17 @@
## ##
## See also ## See also
## ======== ## ========
## * `std/sysrand module<sysrand.html>`_ for cryptographically secure pseudorandom number generator ## * `std/sysrand module <sysrand.html>`_ for a cryptographically secure pseudorandom number generator
## * `mersenne module <mersenne.html>`_ for the Mersenne Twister random number generator
## * `math module <math.html>`_ for basic math routines ## * `math module <math.html>`_ for basic math routines
## * `mersenne module<mersenne.html>`_ for the Mersenne Twister random number
## generator
## * `stats module <stats.html>`_ for statistical analysis ## * `stats module <stats.html>`_ for statistical analysis
## * `list of cryptographic and hashing modules ## * `list of cryptographic and hashing modules <lib.html#pure-libraries-hashing>`_
## <lib.html#pure-libraries-hashing>`_
## in the standard library ## in the standard library
import algorithm, math import std/[algorithm, math]
import std/private/since import std/private/since
include "system/inclrtl" include system/inclrtl
{.push debugger: off.} {.push debugger: off.}
when defined(js): when defined(js):
@ -100,7 +93,7 @@ type
## Create a new Rand state using the `initRand proc <#initRand,int64>`_. ## Create a new Rand state using the `initRand proc <#initRand,int64>`_.
## ##
## The module contains a default Rand state for convenience. ## The module contains a default Rand state for convenience.
## It corresponds to the default random number generator's state. ## It corresponds to the default RNG's state.
## The default Rand state always starts with the same values, but the ## The default Rand state always starts with the same values, but the
## `randomize proc <#randomize>`_ can be used to seed the default generator ## `randomize proc <#randomize>`_ can be used to seed the default generator
## with a value based on the current time. ## with a value based on the current time.
@ -130,9 +123,9 @@ proc rotl(x, k: Ui): Ui =
result = (x shl k) or (x shr (Ui(64) - k)) result = (x shl k) or (x shr (Ui(64) - k))
proc next*(r: var Rand): uint64 = proc next*(r: var Rand): uint64 =
## Computes a random ``uint64`` number using the given state. ## Computes a random `uint64` number using the given state.
## ##
## See also: ## **See also:**
## * `rand proc<#rand,Rand,Natural>`_ that returns an integer between zero and ## * `rand proc<#rand,Rand,Natural>`_ that returns an integer between zero and
## a given upper bound ## a given upper bound
## * `rand proc<#rand,Rand,range[]>`_ that returns a float ## * `rand proc<#rand,Rand,range[]>`_ that returns a float
@ -145,6 +138,7 @@ proc next*(r: var Rand): uint64 =
doAssert r.next() == 138_744_656_611_299'u64 doAssert r.next() == 138_744_656_611_299'u64
doAssert r.next() == 979_810_537_855_049_344'u64 doAssert r.next() == 979_810_537_855_049_344'u64
doAssert r.next() == 3_628_232_584_225_300_704'u64 doAssert r.next() == 3_628_232_584_225_300_704'u64
let s0 = r.a0 let s0 = r.a0
var s1 = r.a1 var s1 = r.a1
result = s0 + s1 result = s0 + s1
@ -155,8 +149,8 @@ proc next*(r: var Rand): uint64 =
proc skipRandomNumbers*(s: var Rand) = proc skipRandomNumbers*(s: var Rand) =
## The jump function for the generator. ## The jump function for the generator.
## ##
## This proc is equivalent to 2^64 calls to `next<#next,Rand>`_, and it can ## This proc is equivalent to `2^64` calls to `next <#next,Rand>`_, and it can
## be used to generate 2^64 non-overlapping subsequences for parallel ## be used to generate `2^64` non-overlapping subsequences for parallel
## computations. ## computations.
## ##
## When multiple threads are generating random numbers, each thread must ## When multiple threads are generating random numbers, each thread must
@ -171,34 +165,30 @@ proc skipRandomNumbers*(s: var Rand) =
## Rand state to a thread, call this proc before passing it to the next one. ## Rand state to a thread, call this proc before passing it to the next one.
## By using the Rand state this way, the subsequences of random numbers ## By using the Rand state this way, the subsequences of random numbers
## generated in each thread will never overlap as long as no thread generates ## generated in each thread will never overlap as long as no thread generates
## more than 2^64 random numbers. ## more than `2^64` random numbers.
## ##
## The following example below demonstrates this pattern: ## **See also:**
##
## .. code-block::
## # Compile this example with --threads:on
## import random
## import threadpool
##
## const spawns = 4
## const numbers = 100000
##
## proc randomSum(rand: Rand): int =
## var r = rand
## for i in 1..numbers:
## result += rand(1..10)
##
## var r = initRand(2019)
## var vals: array[spawns, FlowVar[int]]
## for val in vals.mitems:
## val = spawn(randomSum(r))
## r.skipRandomNumbers()
##
## for val in vals:
## echo ^val
##
## See also:
## * `next proc<#next,Rand>`_ ## * `next proc<#next,Rand>`_
runnableExamples("--threads:on"):
import std/[random, threadpool]
const spawns = 4
const numbers = 100000
proc randomSum(r: Rand): int =
var r = r
for i in 1..numbers:
result += r.rand(0..10)
var r = initRand(2019)
var vals: array[spawns, FlowVar[int]]
for val in vals.mitems:
val = spawn randomSum(r)
r.skipRandomNumbers()
for val in vals:
doAssert abs(^val - numbers * 5) / numbers < 0.1
when defined(js): when defined(js):
const helper = [0xbeac0467u32, 0xd86b048bu32] const helper = [0xbeac0467u32, 0xd86b048bu32]
else: else:
@ -218,9 +208,8 @@ proc skipRandomNumbers*(s: var Rand) =
proc rand*(r: var Rand; max: Natural): int {.benign.} = proc rand*(r: var Rand; max: Natural): int {.benign.} =
## Returns a random integer in the range `0..max` using the given state. ## Returns a random integer in the range `0..max` using the given state.
## ##
## See also: ## **See also:**
## * `rand proc<#rand,int>`_ that returns an integer using the default ## * `rand proc<#rand,int>`_ that returns an integer using the default RNG
## random number generator
## * `rand proc<#rand,Rand,range[]>`_ that returns a float ## * `rand proc<#rand,Rand,range[]>`_ that returns a float
## * `rand proc<#rand,Rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_ ## * `rand proc<#rand,Rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_
## that accepts a slice ## that accepts a slice
@ -230,6 +219,7 @@ proc rand*(r: var Rand; max: Natural): int {.benign.} =
doAssert r.rand(100) == 0 doAssert r.rand(100) == 0
doAssert r.rand(100) == 96 doAssert r.rand(100) == 96
doAssert r.rand(100) == 66 doAssert r.rand(100) == 66
if max == 0: return if max == 0: return
while true: while true:
let x = next(r) let x = next(r)
@ -242,10 +232,9 @@ proc rand*(max: int): int {.benign.} =
## If `randomize <#randomize>`_ has not been called, the sequence of random ## If `randomize <#randomize>`_ has not been called, the sequence of random
## numbers returned from this proc will always be the same. ## numbers returned from this proc will always be the same.
## ##
## This proc uses the default random number generator. Thus, it is **not** ## This proc uses the default RNG. Thus, it is **not** thread-safe.
## thread-safe.
## ##
## See also: ## **See also:**
## * `rand proc<#rand,Rand,Natural>`_ that returns an integer using a ## * `rand proc<#rand,Rand,Natural>`_ that returns an integer using a
## provided state ## provided state
## * `rand proc<#rand,float>`_ that returns a float ## * `rand proc<#rand,float>`_ that returns a float
@ -257,23 +246,23 @@ proc rand*(max: int): int {.benign.} =
doAssert rand(100) == 0 doAssert rand(100) == 0
doAssert rand(100) == 96 doAssert rand(100) == 96
doAssert rand(100) == 66 doAssert rand(100) == 66
rand(state, max) rand(state, max)
proc rand*(r: var Rand; max: range[0.0 .. high(float)]): float {.benign.} = proc rand*(r: var Rand; max: range[0.0 .. high(float)]): float {.benign.} =
## Returns a random floating point number in the range `0.0..max` ## Returns a random floating point number in the range `0.0..max`
## using the given state. ## using the given state.
## ##
## See also: ## **See also:**
## * `rand proc<#rand,float>`_ that returns a float using the default ## * `rand proc<#rand,float>`_ that returns a float using the default RNG
## random number generator
## * `rand proc<#rand,Rand,Natural>`_ that returns an integer ## * `rand proc<#rand,Rand,Natural>`_ that returns an integer
## * `rand proc<#rand,Rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_ ## * `rand proc<#rand,Rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_
## that accepts a slice ## that accepts a slice
## * `rand proc<#rand,typedesc[T]>`_ that accepts an integer or range type ## * `rand proc<#rand,typedesc[T]>`_ that accepts an integer or range type
runnableExamples: runnableExamples:
var r = initRand(234) var r = initRand(234)
let f = r.rand(1.0) let f = r.rand(1.0) # 8.717181376738381e-07
## f = 8.717181376738381e-07
let x = next(r) let x = next(r)
when defined(js): when defined(js):
result = (float(x) / float(high(uint32))) * max result = (float(x) / float(high(uint32))) * max
@ -287,10 +276,9 @@ proc rand*(max: float): float {.benign.} =
## If `randomize <#randomize>`_ has not been called, the sequence of random ## If `randomize <#randomize>`_ has not been called, the sequence of random
## numbers returned from this proc will always be the same. ## numbers returned from this proc will always be the same.
## ##
## This proc uses the default random number generator. Thus, it is **not** ## This proc uses the default RNG. Thus, it is **not** thread-safe.
## thread-safe.
## ##
## See also: ## **See also:**
## * `rand proc<#rand,Rand,range[]>`_ that returns a float using a ## * `rand proc<#rand,Rand,range[]>`_ that returns a float using a
## provided state ## provided state
## * `rand proc<#rand,int>`_ that returns an integer ## * `rand proc<#rand,int>`_ that returns an integer
@ -299,8 +287,8 @@ proc rand*(max: float): float {.benign.} =
## * `rand proc<#rand,typedesc[T]>`_ that accepts an integer or range type ## * `rand proc<#rand,typedesc[T]>`_ that accepts an integer or range type
runnableExamples: runnableExamples:
randomize(234) randomize(234)
let f = rand(1.0) let f = rand(1.0) # 8.717181376738381e-07
## f = 8.717181376738381e-07
rand(state, max) rand(state, max)
proc rand*[T: Ordinal or SomeFloat](r: var Rand; x: HSlice[T, T]): T = proc rand*[T: Ordinal or SomeFloat](r: var Rand; x: HSlice[T, T]): T =
@ -309,9 +297,9 @@ proc rand*[T: Ordinal or SomeFloat](r: var Rand; x: HSlice[T, T]): T =
## ##
## Allowed types for `T` are integers, floats, and enums without holes. ## Allowed types for `T` are integers, floats, and enums without holes.
## ##
## See also: ## **See also:**
## * `rand proc<#rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_ ## * `rand proc<#rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_
## that accepts a slice and uses the default random number generator ## that accepts a slice and uses the default RNG
## * `rand proc<#rand,Rand,Natural>`_ that returns an integer ## * `rand proc<#rand,Rand,Natural>`_ that returns an integer
## * `rand proc<#rand,Rand,range[]>`_ that returns a float ## * `rand proc<#rand,Rand,range[]>`_ that returns a float
## * `rand proc<#rand,typedesc[T]>`_ that accepts an integer or range type ## * `rand proc<#rand,typedesc[T]>`_ that accepts an integer or range type
@ -320,8 +308,8 @@ proc rand*[T: Ordinal or SomeFloat](r: var Rand; x: HSlice[T, T]): T =
doAssert r.rand(1..6) == 4 doAssert r.rand(1..6) == 4
doAssert r.rand(1..6) == 4 doAssert r.rand(1..6) == 4
doAssert r.rand(1..6) == 6 doAssert r.rand(1..6) == 6
let f = r.rand(-1.0 .. 1.0) let f = r.rand(-1.0 .. 1.0) # 0.8741183448756229
## f = 0.8741183448756229
when T is SomeFloat: when T is SomeFloat:
result = rand(r, x.b - x.a) + x.a result = rand(r, x.b - x.a) + x.a
else: # Integers and Enum types else: # Integers and Enum types
@ -335,10 +323,9 @@ proc rand*[T: Ordinal or SomeFloat](x: HSlice[T, T]): T =
## If `randomize <#randomize>`_ has not been called, the sequence of random ## If `randomize <#randomize>`_ has not been called, the sequence of random
## numbers returned from this proc will always be the same. ## numbers returned from this proc will always be the same.
## ##
## This proc uses the default random number generator. Thus, it is **not** ## This proc uses the default RNG. Thus, it is **not** thread-safe.
## thread-safe.
## ##
## See also: ## **See also:**
## * `rand proc<#rand,Rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_ ## * `rand proc<#rand,Rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_
## that accepts a slice and uses a provided state ## that accepts a slice and uses a provided state
## * `rand proc<#rand,int>`_ that returns an integer ## * `rand proc<#rand,int>`_ that returns an integer
@ -349,6 +336,7 @@ proc rand*[T: Ordinal or SomeFloat](x: HSlice[T, T]): T =
doAssert rand(1..6) == 4 doAssert rand(1..6) == 4
doAssert rand(1..6) == 4 doAssert rand(1..6) == 4
doAssert rand(1..6) == 6 doAssert rand(1..6) == 6
result = rand(state, x) result = rand(state, x)
proc rand*[T: SomeInteger](t: typedesc[T]): T = proc rand*[T: SomeInteger](t: typedesc[T]): T =
@ -357,10 +345,9 @@ proc rand*[T: SomeInteger](t: typedesc[T]): T =
## If `randomize <#randomize>`_ has not been called, the sequence of random ## If `randomize <#randomize>`_ has not been called, the sequence of random
## numbers returned from this proc will always be the same. ## numbers returned from this proc will always be the same.
## ##
## This proc uses the default random number generator. Thus, it is **not** ## This proc uses the default RNG. Thus, it is **not** thread-safe.
## thread-safe.
## ##
## See also: ## **See also:**
## * `rand proc<#rand,int>`_ that returns an integer ## * `rand proc<#rand,int>`_ that returns an integer
## * `rand proc<#rand,float>`_ that returns a floating point number ## * `rand proc<#rand,float>`_ that returns a floating point number
## * `rand proc<#rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_ ## * `rand proc<#rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_
@ -376,18 +363,18 @@ proc rand*[T: SomeInteger](t: typedesc[T]): T =
doAssert rand(range[1..16]) == 11 doAssert rand(range[1..16]) == 11
doAssert rand(range[1..16]) == 4 doAssert rand(range[1..16]) == 4
doAssert rand(range[1..16]) == 16 doAssert rand(range[1..16]) == 16
when T is range: when T is range:
result = rand(state, low(T)..high(T)) result = rand(state, low(T)..high(T))
else: else:
result = cast[T](state.next) result = cast[T](state.next)
proc sample*[T](r: var Rand; s: set[T]): T = proc sample*[T](r: var Rand; s: set[T]): T =
## Returns a random element from the set ``s`` using the given state. ## Returns a random element from the set `s` using the given state.
## ##
## See also: ## **See also:**
## * `sample proc<#sample,set[T]>`_ that uses the default random number ## * `sample proc<#sample,set[T]>`_ that uses the default RNG
## generator ## * `sample proc<#sample,Rand,openArray[T]>`_ for `openArray`s
## * `sample proc<#sample,Rand,openArray[T]>`_ for openarrays
## * `sample proc<#sample,Rand,openArray[T],openArray[U]>`_ that uses a ## * `sample proc<#sample,Rand,openArray[T],openArray[U]>`_ that uses a
## cumulative distribution function ## cumulative distribution function
runnableExamples: runnableExamples:
@ -396,6 +383,7 @@ proc sample*[T](r: var Rand; s: set[T]): T =
doAssert r.sample(s) == 5 doAssert r.sample(s) == 5
doAssert r.sample(s) == 7 doAssert r.sample(s) == 7
doAssert r.sample(s) == 1 doAssert r.sample(s) == 1
assert card(s) != 0 assert card(s) != 0
var i = rand(r, card(s) - 1) var i = rand(r, card(s) - 1)
for e in s: for e in s:
@ -403,17 +391,16 @@ proc sample*[T](r: var Rand; s: set[T]): T =
dec(i) dec(i)
proc sample*[T](s: set[T]): T = proc sample*[T](s: set[T]): T =
## Returns a random element from the set ``s``. ## Returns a random element from the set `s`.
## ##
## If `randomize <#randomize>`_ has not been called, the order of outcomes ## If `randomize <#randomize>`_ has not been called, the order of outcomes
## from this proc will always be the same. ## from this proc will always be the same.
## ##
## This proc uses the default random number generator. Thus, it is **not** ## This proc uses the default RNG. Thus, it is **not** thread-safe.
## thread-safe.
## ##
## See also: ## **See also:**
## * `sample proc<#sample,Rand,set[T]>`_ that uses a provided state ## * `sample proc<#sample,Rand,set[T]>`_ that uses a provided state
## * `sample proc<#sample,openArray[T]>`_ for openarrays ## * `sample proc<#sample,openArray[T]>`_ for `openArray`s
## * `sample proc<#sample,openArray[T],openArray[U]>`_ that uses a ## * `sample proc<#sample,openArray[T],openArray[U]>`_ that uses a
## cumulative distribution function ## cumulative distribution function
runnableExamples: runnableExamples:
@ -422,14 +409,14 @@ proc sample*[T](s: set[T]): T =
doAssert sample(s) == 5 doAssert sample(s) == 5
doAssert sample(s) == 7 doAssert sample(s) == 7
doAssert sample(s) == 1 doAssert sample(s) == 1
sample(state, s) sample(state, s)
proc sample*[T](r: var Rand; a: openArray[T]): T = proc sample*[T](r: var Rand; a: openArray[T]): T =
## Returns a random element from ``a`` using the given state. ## Returns a random element from `a` using the given state.
## ##
## See also: ## **See also:**
## * `sample proc<#sample,openArray[T]>`_ that uses the default ## * `sample proc<#sample,openArray[T]>`_ that uses the default RNG
## random number generator
## * `sample proc<#sample,Rand,openArray[T],openArray[U]>`_ that uses a ## * `sample proc<#sample,Rand,openArray[T],openArray[U]>`_ that uses a
## cumulative distribution function ## cumulative distribution function
## * `sample proc<#sample,Rand,set[T]>`_ for sets ## * `sample proc<#sample,Rand,set[T]>`_ for sets
@ -439,18 +426,18 @@ proc sample*[T](r: var Rand; a: openArray[T]): T =
doAssert r.sample(marbles) == "blue" doAssert r.sample(marbles) == "blue"
doAssert r.sample(marbles) == "yellow" doAssert r.sample(marbles) == "yellow"
doAssert r.sample(marbles) == "red" doAssert r.sample(marbles) == "red"
result = a[r.rand(a.low..a.high)] result = a[r.rand(a.low..a.high)]
proc sample*[T](a: openArray[T]): T = proc sample*[T](a: openArray[T]): T =
## Returns a random element from ``a``. ## Returns a random element from `a`.
## ##
## If `randomize <#randomize>`_ has not been called, the order of outcomes ## If `randomize <#randomize>`_ has not been called, the order of outcomes
## from this proc will always be the same. ## from this proc will always be the same.
## ##
## This proc uses the default random number generator. Thus, it is **not** ## This proc uses the default RNG. Thus, it is **not** thread-safe.
## thread-safe.
## ##
## See also: ## **See also:**
## * `sample proc<#sample,Rand,openArray[T]>`_ that uses a provided state ## * `sample proc<#sample,Rand,openArray[T]>`_ that uses a provided state
## * `sample proc<#sample,openArray[T],openArray[U]>`_ that uses a ## * `sample proc<#sample,openArray[T],openArray[U]>`_ that uses a
## cumulative distribution function ## cumulative distribution function
@ -461,28 +448,29 @@ proc sample*[T](a: openArray[T]): T =
doAssert sample(marbles) == "blue" doAssert sample(marbles) == "blue"
doAssert sample(marbles) == "yellow" doAssert sample(marbles) == "yellow"
doAssert sample(marbles) == "red" doAssert sample(marbles) == "red"
result = a[rand(a.low..a.high)] result = a[rand(a.low..a.high)]
proc sample*[T, U](r: var Rand; a: openArray[T]; cdf: openArray[U]): T = proc sample*[T, U](r: var Rand; a: openArray[T]; cdf: openArray[U]): T =
## Returns an element from ``a`` using a cumulative distribution function ## Returns an element from `a` using a cumulative distribution function
## (CDF) and the given state. ## (CDF) and the given state.
## ##
## The ``cdf`` argument does not have to be normalized, and it could contain ## The `cdf` argument does not have to be normalized, and it could contain
## any type of elements that can be converted to a ``float``. It must be ## any type of elements that can be converted to a `float`. It must be
## the same length as ``a``. Each element in ``cdf`` should be greater than ## the same length as `a`. Each element in `cdf` should be greater than
## or equal to the previous element. ## or equal to the previous element.
## ##
## The outcome of the `cumsum<math.html#cumsum,openArray[T]>`_ proc and the ## The outcome of the `cumsum<math.html#cumsum,openArray[T]>`_ proc and the
## return value of the `cumsummed<math.html#cumsummed,openArray[T]>`_ proc, ## return value of the `cumsummed<math.html#cumsummed,openArray[T]>`_ proc,
## which are both in the math module, can be used as the ``cdf`` argument. ## which are both in the math module, can be used as the `cdf` argument.
## ##
## See also: ## **See also:**
## * `sample proc<#sample,openArray[T],openArray[U]>`_ that also utilizes ## * `sample proc<#sample,openArray[T],openArray[U]>`_ that also utilizes
## a CDF but uses the default random number generator ## a CDF but uses the default RNG
## * `sample proc<#sample,Rand,openArray[T]>`_ that does not use a CDF ## * `sample proc<#sample,Rand,openArray[T]>`_ that does not use a CDF
## * `sample proc<#sample,Rand,set[T]>`_ for sets ## * `sample proc<#sample,Rand,set[T]>`_ for sets
runnableExamples: runnableExamples:
from math import cumsummed from std/math import cumsummed
let marbles = ["red", "blue", "green", "yellow", "purple"] let marbles = ["red", "blue", "green", "yellow", "purple"]
let count = [1, 6, 8, 3, 4] let count = [1, 6, 8, 3, 4]
@ -491,6 +479,7 @@ proc sample*[T, U](r: var Rand; a: openArray[T]; cdf: openArray[U]): T =
doAssert r.sample(marbles, cdf) == "red" doAssert r.sample(marbles, cdf) == "red"
doAssert r.sample(marbles, cdf) == "green" doAssert r.sample(marbles, cdf) == "green"
doAssert r.sample(marbles, cdf) == "blue" doAssert r.sample(marbles, cdf) == "blue"
assert(cdf.len == a.len) # Two basic sanity checks. assert(cdf.len == a.len) # Two basic sanity checks.
assert(float(cdf[^1]) > 0.0) assert(float(cdf[^1]) > 0.0)
# While we could check cdf[i-1] <= cdf[i] for i in 1..cdf.len, that could get # While we could check cdf[i-1] <= cdf[i] for i in 1..cdf.len, that could get
@ -499,27 +488,25 @@ proc sample*[T, U](r: var Rand; a: openArray[T]; cdf: openArray[U]): T =
a[cdf.upperBound(U(u))] a[cdf.upperBound(U(u))]
proc sample*[T, U](a: openArray[T]; cdf: openArray[U]): T = proc sample*[T, U](a: openArray[T]; cdf: openArray[U]): T =
## Returns an element from ``a`` using a cumulative distribution function ## Returns an element from `a` using a cumulative distribution function
## (CDF). ## (CDF).
## ##
## This proc works similarly to ## This proc works similarly to
## `sample[T, U](Rand, openArray[T], openArray[U]) ## `sample <#sample,Rand,openArray[T],openArray[U]>`_.
## <#sample,Rand,openArray[T],openArray[U]>`_.
## See that proc's documentation for more details. ## See that proc's documentation for more details.
## ##
## If `randomize <#randomize>`_ has not been called, the order of outcomes ## If `randomize <#randomize>`_ has not been called, the order of outcomes
## from this proc will always be the same. ## from this proc will always be the same.
## ##
## This proc uses the default random number generator. Thus, it is **not** ## This proc uses the default RNG. Thus, it is **not** thread-safe.
## thread-safe.
## ##
## See also: ## **See also:**
## * `sample proc<#sample,Rand,openArray[T],openArray[U]>`_ that also utilizes ## * `sample proc<#sample,Rand,openArray[T],openArray[U]>`_ that also utilizes
## a CDF but uses a provided state ## a CDF but uses a provided state
## * `sample proc<#sample,openArray[T]>`_ that does not use a CDF ## * `sample proc<#sample,openArray[T]>`_ that does not use a CDF
## * `sample proc<#sample,set[T]>`_ for sets ## * `sample proc<#sample,set[T]>`_ for sets
runnableExamples: runnableExamples:
from math import cumsummed from std/math import cumsummed
let marbles = ["red", "blue", "green", "yellow", "purple"] let marbles = ["red", "blue", "green", "yellow", "purple"]
let count = [1, 6, 8, 3, 4] let count = [1, 6, 8, 3, 4]
@ -528,14 +515,15 @@ proc sample*[T, U](a: openArray[T]; cdf: openArray[U]): T =
doAssert sample(marbles, cdf) == "red" doAssert sample(marbles, cdf) == "red"
doAssert sample(marbles, cdf) == "green" doAssert sample(marbles, cdf) == "green"
doAssert sample(marbles, cdf) == "blue" doAssert sample(marbles, cdf) == "blue"
state.sample(a, cdf) state.sample(a, cdf)
proc gauss*(r: var Rand; mu = 0.0; sigma = 1.0): float {.since: (1, 3).} = proc gauss*(r: var Rand; mu = 0.0; sigma = 1.0): float {.since: (1, 3).} =
## Returns a Gaussian random variate, ## Returns a Gaussian random variate,
## with mean ``mu`` and standard deviation ``sigma`` ## with mean `mu` and standard deviation `sigma`
## using the given state. ## using the given state.
# Ratio of uniforms method for normal # Ratio of uniforms method for normal
# http://www2.econ.osaka-u.ac.jp/~tanizaki/class/2013/econome3/13.pdf # https://www2.econ.osaka-u.ac.jp/~tanizaki/class/2013/econome3/13.pdf
const K = sqrt(2 / E) const K = sqrt(2 / E)
var var
a = 0.0 a = 0.0
@ -548,13 +536,12 @@ proc gauss*(r: var Rand; mu = 0.0; sigma = 1.0): float {.since: (1, 3).} =
proc gauss*(mu = 0.0, sigma = 1.0): float {.since: (1, 3).} = proc gauss*(mu = 0.0, sigma = 1.0): float {.since: (1, 3).} =
## Returns a Gaussian random variate, ## Returns a Gaussian random variate,
## with mean ``mu`` and standard deviation ``sigma``. ## with mean `mu` and standard deviation `sigma`.
## ##
## If `randomize <#randomize>`_ has not been called, the order of outcomes ## If `randomize <#randomize>`_ has not been called, the order of outcomes
## from this proc will always be the same. ## from this proc will always be the same.
## ##
## This proc uses the default random number generator. Thus, it is **not** ## This proc uses the default RNG. Thus, it is **not** thread-safe.
## thread-safe.
result = gauss(state, mu, sigma) result = gauss(state, mu, sigma)
proc initRand*(seed: int64): Rand = proc initRand*(seed: int64): Rand =
@ -563,22 +550,20 @@ proc initRand*(seed: int64): Rand =
## `seed` must not be zero. Providing a specific seed will produce ## `seed` must not be zero. Providing a specific seed will produce
## the same results for that seed each time. ## the same results for that seed each time.
## ##
## The resulting state is independent of the default random number ## The resulting state is independent of the default RNG's state.
## generator's state.
## ##
## See also: ## **See also:**
## * `initRand proc<#initRand>`_ that uses the current time ## * `initRand proc<#initRand>`_ that uses the current time
## * `randomize proc<#randomize,int64>`_ that accepts a seed for the default ## * `randomize proc<#randomize,int64>`_ that accepts a seed for the default RNG
## random number generator ## * `randomize proc<#randomize>`_ that initializes the default RNG using the current time
## * `randomize proc<#randomize>`_ that initializes the default random
## number generator using the current time
runnableExamples: runnableExamples:
from times import getTime, toUnix, nanosecond from std/times import getTime, toUnix, nanosecond
var r1 = initRand(123) var r1 = initRand(123)
let now = getTime() let now = getTime()
var r2 = initRand(now.toUnix * 1_000_000_000 + now.nanosecond) var r2 = initRand(now.toUnix * 1_000_000_000 + now.nanosecond)
doAssert seed != 0 # 0 causes `rand(int)` to always return 0 for example. doAssert seed != 0 # 0 causes `rand(int)` to always return 0 for example.
result.a0 = Ui(seed shr 16) result.a0 = Ui(seed shr 16)
result.a1 = Ui(seed and 0xffff) result.a1 = Ui(seed and 0xffff)
@ -590,32 +575,33 @@ proc randomize*(seed: int64) {.benign.} =
## `seed` must not be zero. Providing a specific seed will produce ## `seed` must not be zero. Providing a specific seed will produce
## the same results for that seed each time. ## the same results for that seed each time.
## ##
## See also: ## **See also:**
## * `initRand proc<#initRand,int64>`_ that initializes a Rand state ## * `initRand proc<#initRand,int64>`_ that initializes a Rand state
## with a given seed ## with a given seed
## * `randomize proc<#randomize>`_ that uses the current time instead ## * `randomize proc<#randomize>`_ that uses the current time instead
## * `initRand proc<#initRand>`_ that initializes a Rand state using ## * `initRand proc<#initRand>`_ that initializes a Rand state using
## the current time ## the current time
runnableExamples: runnableExamples:
from times import getTime, toUnix, nanosecond from std/times import getTime, toUnix, nanosecond
randomize(123) randomize(123)
let now = getTime() let now = getTime()
randomize(now.toUnix * 1_000_000_000 + now.nanosecond) randomize(now.toUnix * 1_000_000_000 + now.nanosecond)
state = initRand(seed) state = initRand(seed)
proc shuffle*[T](r: var Rand; x: var openArray[T]) = proc shuffle*[T](r: var Rand; x: var openArray[T]) =
## Shuffles a sequence of elements in-place using the given state. ## Shuffles a sequence of elements in-place using the given state.
## ##
## See also: ## **See also:**
## * `shuffle proc<#shuffle,openArray[T]>`_ that uses the default ## * `shuffle proc<#shuffle,openArray[T]>`_ that uses the default RNG
## random number generator
runnableExamples: runnableExamples:
var cards = ["Ace", "King", "Queen", "Jack", "Ten"] var cards = ["Ace", "King", "Queen", "Jack", "Ten"]
var r = initRand(678) var r = initRand(678)
r.shuffle(cards) r.shuffle(cards)
doAssert cards == ["King", "Ace", "Queen", "Ten", "Jack"] doAssert cards == ["King", "Ace", "Queen", "Ten", "Jack"]
for i in countdown(x.high, 1): for i in countdown(x.high, 1):
let j = r.rand(i) let j = r.rand(i)
swap(x[i], x[j]) swap(x[i], x[j])
@ -626,34 +612,32 @@ proc shuffle*[T](x: var openArray[T]) =
## If `randomize <#randomize>`_ has not been called, the order of outcomes ## If `randomize <#randomize>`_ has not been called, the order of outcomes
## from this proc will always be the same. ## from this proc will always be the same.
## ##
## This proc uses the default random number generator. Thus, it is **not** ## This proc uses the default RNG. Thus, it is **not** thread-safe.
## thread-safe.
## ##
## See also: ## **See also:**
## * `shuffle proc<#shuffle,Rand,openArray[T]>`_ that uses a provided state ## * `shuffle proc<#shuffle,Rand,openArray[T]>`_ that uses a provided state
runnableExamples: runnableExamples:
var cards = ["Ace", "King", "Queen", "Jack", "Ten"] var cards = ["Ace", "King", "Queen", "Jack", "Ten"]
randomize(678) randomize(678)
shuffle(cards) shuffle(cards)
doAssert cards == ["King", "Ace", "Queen", "Ten", "Jack"] doAssert cards == ["King", "Ace", "Queen", "Ten", "Jack"]
shuffle(state, x) shuffle(state, x)
when not defined(nimscript) and not defined(standalone): when not defined(nimscript) and not defined(standalone):
import times import std/times
proc initRand(): Rand = proc initRand(): Rand =
## Initializes a new Rand state with a seed based on the current time. ## Initializes a new Rand state with a seed based on the current time.
## ##
## The resulting state is independent of the default random number generator's state. ## The resulting state is independent of the default RNG's state.
## ##
## **Note:** Does not work for NimScript or the compile-time VM. ## **Note:** Does not work for NimScript or the compile-time VM.
## ##
## See also: ## See also:
## * `initRand proc<#initRand,int64>`_ that accepts a seed for a new Rand state ## * `initRand proc<#initRand,int64>`_ that accepts a seed for a new Rand state
## * `randomize proc<#randomize>`_ that initializes the default random ## * `randomize proc<#randomize>`_ that initializes the default RNG using the current time
## number generator using the current time ## * `randomize proc<#randomize,int64>`_ that accepts a seed for the default RNG
## * `randomize proc<#randomize,int64>`_ that accepts a seed for the default
## random number generator
when defined(js): when defined(js):
let time = int64(times.epochTime() * 1000) and 0x7fff_ffff let time = int64(times.epochTime() * 1000) and 0x7fff_ffff
result = initRand(time) result = initRand(time)
@ -669,12 +653,11 @@ when not defined(nimscript) and not defined(standalone):
## the current time. ## the current time.
## ##
## This proc only needs to be called once, and it should be called before ## This proc only needs to be called once, and it should be called before
## the first usage of procs from this module that use the default random ## the first usage of procs from this module that use the default RNG.
## number generator.
## ##
## **Note:** Does not work for NimScript or the compile-time VM. ## **Note:** Does not work for NimScript or the compile-time VM.
## ##
## See also: ## **See also:**
## * `randomize proc<#randomize,int64>`_ that accepts a seed ## * `randomize proc<#randomize,int64>`_ that accepts a seed
## * `initRand proc<#initRand>`_ that initializes a Rand state using ## * `initRand proc<#initRand>`_ that initializes a Rand state using
## the current time ## the current time