rand

The state for a PCG64 RXS-M-XS pseudorandom generator.

The state for a xoshiro256** pseudorandom generator.

A contextual structure for generating Zipf distributed variates.

Returns an instance of the runtime pseudorandom generator. If no initial state is provided, the PRNG will be lazily initialized with entropy from the system entropy source on first-use.

The cryptographic security of the returned random number generator is directly dependent on the quality of the initialization entropy. Calling reset/create SHOULD be done with no seed/state, or 32-bytes of high-quality entropy.

WARNING:

• The lazy initialization will panic if there is no system entropy

source available.

• While the generator is cryptographically secure, developers SHOULD

prefer crypto.random_generator() for cryptographic use cases such as key generation.

Inputs:

• state: Optional initial PRNG state.

Returns:

• A Generator instance.

Returns a random element from the provided slice. If no generator is provided the global random number generator will be used.

Inputs:

• array: The slice to choose an element from

Returns:

• res: A random element from array

Example:

import "core:math/rand"
import "core:fmt"

choice_example :: proc() {
	data: [4]int = { 1, 2, 3, 4 }
	fmt.println(rand.choice(data[:]))
	fmt.println(rand.choice(data[:]))
	fmt.println(rand.choice(data[:]))
	fmt.println(rand.choice(data[:]))
}

Possible Output:

3
2
2
4

Returns a random set bit from the provided bit_set.

Inputs:

• set: The bit_set to choose a random set bit from

Returns:

• res: The randomly selected bit, or the zero value if ok is false
• ok: Whether the bit_set was not empty and thus res is actually a random set bit

Example:

import "core:math/rand"
import "core:fmt"

choice_bit_set_example :: proc() {
	Flags :: enum {
		A,
		B = 10,
		C,
	}

	fmt.println(rand.choice_bit_set(bit_set[Flags]{}))
	fmt.println(rand.choice_bit_set(bit_set[Flags]{.B}))
	fmt.println(rand.choice_bit_set(bit_set[Flags]{.B, .C}))
	fmt.println(rand.choice_bit_set(bit_set[0..<15]{5, 1, 4}))
}

Possible Output:

A false
B true
C true
5 true

exp_float64 returns a exponential distribution in the range (0, max(f64)], with an exponential distribution who rate parameter is 1 (lambda) and whose mean is 1 (1/lambda).

To produce a distribution with a differetn rate parameter, divide the result by the desired rate parameter

"The Ziggurat Method for Generating Random Variables" Authors: George Marsaglia, Wai Wan Tsang Submitted: 2000-04-15. Published: 2000-10-02. https://www.jstatsoft.org/index.php/jss/article/view/v005i08/ziggurat.pdf [pdf] https://www.jstatsoft.org/article/view/v005i08 [web page]

Generates a random single floating point value in the range [0, 1) using the provided random number generator. If no generator is provided the global random number generator will be used.

Returns:

• val: A random single floating point value in the range [0, 1)

Example:

import "core:math/rand"
import "core:fmt"

float32_example :: proc() {
	fmt.println(rand.float32())
}

Possible Output:

0.043
0.511

Beta Distribution

Required: alpha > 0 and beta > 0

Return values range between 0 and 1

Cauchy-Lorentz Distribution x_0 is the location, gamma is the scale where gamma > 0

Exponential Distribution lambda is 1.0/(desired mean). It should be non-zero. Return values range from 0 to positive infinity if lambda > 0 negative infinity to 0 if lambda <= 0

Gamma Distribution (NOT THE GAMMA FUNCTION)

Required: alpha > 0 and beta > 0

math.pow(x, alpha-1) math.exp(-x / beta) pdf(x) = -------------------------------------------- math.gamma(alpha) math.pow(beta, alpha)

mean is alphabeta, variance is math.pow(alphabeta, 2)

Gompertz Distribution eta is the shape, b is the scale Both eta and b must be > 0

Laplace Distribution b is the scale where b > 0

Log Cauchy-Lorentz Distribution x_0 is the location, gamma is the scale where gamma > 0

Log Normal Distribution

Normal/Gaussian Distribution

Pareto distribution, alpha is the shape parameter. https://wikipedia.org/wiki/Pareto_distribution

Generates a random single floating point value in the range [low, high) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• low: The lower bounds of the value, this value is inclusive
• high: The upper bounds of the value, this value is exclusive

Returns:

• val: A random single floating point value in the range [low, high)

WARNING: Panics if high < low

Example:

import "core:math/rand"
import "core:fmt"

float32_range_example :: proc() {
	fmt.println(rand.float32_range(-10, 300))
}

Possible Output:

15.312
273.15

Triangular Distribution See: http://wikipedia.org/wiki/Triangular_distribution

Circular Data (von Mises) Distribution mean_angle is the in mean angle between 0 and 2pi radians kappa is the concentration parameter which must be >= 0 When kappa is zero, the Distribution is a uniform Distribution over the range 0 to 2pi

Weibull distribution, alpha is the scale parameter, beta is the shape parameter.

Generates a random double floating point value in the range [0, 1) using the provided random number generator. If no generator is provided the global random number generator will be used.

Returns:

• val: A random double floating point value in the range [0, 1)

Example:

import "core:math/rand"
import "core:fmt"

float64_example :: proc() {
	fmt.println(rand.float64())
}

Possible Output:

0.043
0.511

Beta Distribution

Required: alpha > 0 and beta > 0

Return values range between 0 and 1

Cauchy-Lorentz Distribution x_0 is the location, gamma is the scale where gamma > 0

Exponential Distribution lambda is 1.0/(desired mean). It should be non-zero. Return values range from 0 to positive infinity if lambda > 0 negative infinity to 0 if lambda <= 0

Gamma Distribution (NOT THE GAMMA FUNCTION)

Required: alpha > 0 and beta > 0

math.pow(x, alpha-1) math.exp(-x / beta) pdf(x) = -------------------------------------------- math.gamma(alpha) math.pow(beta, alpha)

mean is alphabeta, variance is math.pow(alphabeta, 2)

Gompertz Distribution eta is the shape, b is the scale Both eta and b must be > 0

Laplace Distribution b is the scale where b > 0

Log Cauchy-Lorentz Distribution x_0 is the location, gamma is the scale where gamma > 0

Log Normal Distribution

Normal/Gaussian Distribution

Pareto distribution, alpha is the shape parameter. https://wikipedia.org/wiki/Pareto_distribution

Generates a random double floating point value in the range [low, high) using the provided random number generator. If no generator is provided the global random number generator will be used.

WARNING: Panics if high < low

Inputs:

• low: The lower bounds of the value, this value is inclusive
• high: The upper bounds of the value, this value is exclusive

Returns:

• val: A random double floating point value in the range [low, high)

Example:

import "core:math/rand"
import "core:fmt"

float64_range_example :: proc() {
	fmt.println(rand.float64_range(-10, 300))
}

Possible Output:

15.312
273.15

Triangular Distribution See: http://wikipedia.org/wiki/Triangular_distribution

Circular Data (von Mises) Distribution mean_angle is the in mean angle between 0 and 2pi radians kappa is the concentration parameter which must be >= 0 When kappa is zero, the Distribution is a uniform Distribution over the range 0 to 2pi

Weibull distribution, alpha is the scale parameter, beta is the shape parameter.

Generates a random 127 bit value using the provided random number generator. If no generator is provided the global random number generator will be used. The sign bit will always be set to 0, thus all generated numbers will be positive.

Returns:

• val: A random 127 bit value

Example:

import "core:math/rand"
import "core:fmt"

int127_example :: proc() {
	fmt.println(rand.int127())
}

Possible Output:

10
389

Generates a random 127 bit value in the range [0, n) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• n: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 127 bit value in the range [0, n)

WARNING: Panics if n is less than or equal to 0

Example:

import "core:math/rand"
import "core:fmt"

int127_max_example :: proc() {
	fmt.println(rand.int127_max(16))
}

Possible Output:

6
13

Generates a random signed 128 bit value in the range [lo, hi) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• lo: The lower bound of the generated number, this value is inclusice
• hi: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 128 bit value in the range [lo, hi)

WARNING: Panics if lo is greater or equal to hi

Example:

import "core:math/rand"
import "core:fmt"

int128_range_example :: proc() {
	fmt.println(rand.int128_range(-10,10))
}

Possible Output:

6
-9

Generates a random 31 bit value using the provided random number generator. If no generator is provided the global random number generator will be used. The sign bit will always be set to 0, thus all generated numbers will be positive.

Returns:

• val: A random 31 bit value

Example:

import "core:math/rand"
import "core:fmt"

int31_example :: proc() {
	fmt.println(rand.int31())
}

Possible Output:

10
389

Generates a random 31 bit value in the range [0, n) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• n: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 31 bit value in the range [0, n)

WARNING: Panics if n is less than or equal to 0

Example:

import "core:math/rand"
import "core:fmt"

int31_max_example :: proc() {
	fmt.println(rand.int31_max(16))
}

Possible Output:

6
13

Generates a random signed 32 bit value in the range [lo, hi) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• lo: The lower bound of the generated number, this value is inclusice
• hi: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 32 bit value in the range [lo, hi)

WARNING: Panics if lo is greater or equal to hi

Example:

import "core:math/rand"
import "core:fmt"

int32_range_example :: proc() {
	fmt.println(rand.int32_range(-10,10))
}

Possible Output:

6
-9

Generates a random 63 bit value using the provided random number generator. If no generator is provided the global random number generator will be used. The sign bit will always be set to 0, thus all generated numbers will be positive.

Returns:

• val: A random 63 bit value

Example:

import "core:math/rand"
import "core:fmt"

int63_example :: proc() {
	fmt.println(rand.int63())
}

Possible Output:

10
389

Generates a random 63 bit value in the range [0, n) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• n: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 63 bit value in the range [0, n)

WARNING: Panics if n is less than or equal to 0

Example:

import "core:math/rand"
import "core:fmt"

int63_max_example :: proc() {
	fmt.println(rand.int63_max(16))
}

Possible Output:

6
13

Generates a random signed 64 bit value in the range [lo, hi) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• lo: The lower bound of the generated number, this value is inclusice
• hi: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 64 bit value in the range [lo, hi)

WARNING: Panics if lo is greater or equal to hi

Example:

import "core:math/rand"
import "core:fmt"

int64_range_example :: proc() {
	fmt.println(rand.int64_range(-10,10))
}

Possible Output:

6
-9

Generates a random integer value in the range [0, n) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• n: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random integer value in the range [0, n)

WARNING: Panics if n is less than or equal to 0

Example:

import "core:math/rand"
import "core:fmt"

int_max_example :: proc() {
	fmt.println(rand.int_max(16))
}

Possible Output:

6
13

Generates a random signed integer value in the range [lo, hi) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• lo: The lower bound of the generated number, this value is inclusice
• hi: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random integer value in the range [lo, hi)

WARNING: Panics if lo is greater or equal to hi

Example:

import "core:math/rand"
import "core:fmt"

int_range_example :: proc() {
	fmt.println(rand.int_range(-10,10))
}

Possible Output:

6
-9

norm_float64 returns a normally distributed f64 in the range -max(f64) through +max(f64) inclusive, with a standard normal distribution with a mean of 0 and standard deviation of 1.

sample = norm_float64() * std_dev + mean

Normal distribution

"The Ziggurat Method for Generating Random Variables" Authors: George Marsaglia, Wai Wan Tsang Submitted: 2000-04-15. Published: 2000-10-02. https://www.jstatsoft.org/index.php/jss/article/view/v005i08/ziggurat.pdf [pdf] https://www.jstatsoft.org/article/view/v005i08 [web page]

Returns an instance of the PGC64 RXS-M-XS pseudorandom generator. If no initial state is provided, the PRNG will be lazily initialized with the system timestamp counter on first-use.

WARNING: This random number generator is NOT cryptographically secure, and is additionally known to be flawed. It is only included for backward compatibility with historical releases of Odin. See: https://github.com/odin-lang/Odin/issues/5881

Inputs:

• state: Optional initial PRNG state.

Returns:

• A Generator instance.

Creates a slice of int filled with random values using the provided random number generator. If no generator is provided the global random number generator will be used.

Allocates Using Provided Allocator

Inputs:

• n: The size of the created slice
• allocator: (default: context.allocator)

Returns:

• res: A slice filled with random values
• err: An allocator error if one occured, nil otherwise

Example:

import "base:runtime"
import "core:math/rand"
import "core:fmt"

perm_example :: proc() -> (err: runtime.Allocator_Error) {
	data := rand.perm(4) or_return
	fmt.println(data)
	defer delete(data, context.allocator)

	return
}

Possible Output:

[3, 2, 0, 1]
[1, 0, 2, 3]

Fills a byte slice with random values using the provided random number generator. If no generator is provided the global random number generator will be used. Due to floating point precision there is no guarantee if the upper and lower bounds are inclusive/exclusive with the exact floating point value.

Inputs:

• p: The byte slice to fill

Returns:

• n: The number of bytes generated

Example:

import "core:math/rand"
import "core:fmt"

read_example :: proc() {
	data: [8]byte
	n := rand.read(data[:])
	fmt.println(n)
	fmt.println(data)
}

Possible Output:

8
[32, 4, 59, 7, 1, 2, 2, 119]

Randomizes the ordering of elements for the provided slice. If no generator is provided the global random number generator will be used.

Inputs:

• array: The slice to randomize

Example:

import "core:math/rand"
import "core:fmt"

shuffle_example :: proc() {
	data: [4]int = { 1, 2, 3, 4 }
	fmt.println(data) // the contents are in order
	rand.shuffle(data[:])
	fmt.println(data) // the contents have been shuffled
}

Possible Output:

[1, 2, 3, 4]
[2, 4, 3, 1]

Generates a random 128 bit value using the provided random number generator. If no generator is provided the global random number generator will be used.

Returns:

• val: A random unsigned 128 bit value

Example:

import "core:math/rand"
import "core:fmt"

uint128_example :: proc() {
	fmt.println(rand.uint128())
}

Possible Output:

10
389

Generates a random 128 bit value in the range [0, n) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• n: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 128 bit value in the range [0, n)

WARNING: Panics if n is equal to 0

Example:

import "core:math/rand"
import "core:fmt"

uint128_max_example :: proc() {
	fmt.println(rand.uint128_max(16))
}

Possible Output:

6
13

Generates a random unsigned 128 bit value in the range [lo, hi) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• lo: The lower bound of the generated number, this value is inclusice
• hi: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 128 bit value in the range [lo, hi)

WARNING: Panics if lo is greater or equal to hi

Example:

import "core:math/rand"
import "core:fmt"

uint128_range_example :: proc() {
	fmt.println(rand.uint128_range(5,15))
}

Possible Output:

6
13

Generates a random 32 bit value using the provided random number generator. If no generator is provided the global random number generator will be used.

Returns:

• val: A random unsigned 32 bit value

Example:

import "core:math/rand"
import "core:fmt"

uint32_example :: proc() {
	fmt.println(rand.uint32())
}

Possible Output:

10
389

Generates a random 32 bit value in the range [0, n) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• n: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 32 bit value in the range [0, n)

WARNING: Panics if n is equal to 0

Example:

import "core:math/rand"
import "core:fmt"

uint32_max_example :: proc() {
	fmt.println(rand.uint32_max(16))
}

Possible Output:

6
13

Generates a random unsigned 32 bit value in the range [lo, hi) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• lo: The lower bound of the generated number, this value is inclusice
• hi: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 32 bit value in the range [lo, hi)

WARNING: Panics if lo is greater or equal to hi

Example:

import "core:math/rand"
import "core:fmt"

uint32_range_example :: proc() {
	fmt.println(rand.uint32_range(5,15))
}

Possible Output:

6
13

Generates a random 64 bit value using the provided random number generator. If no generator is provided the global random number generator will be used.

Returns:

• val: A random unsigned 64 bit value

Example:

import "core:math/rand"
import "core:fmt"

uint64_example :: proc() {
	fmt.println(rand.uint64())
}

Possible Output:

10
389

Generates a random 64 bit value in the range [0, n) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• n: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 64 bit value in the range [0, n)

WARNING: Panics if n is equal to 0

Example:

import "core:math/rand"
import "core:fmt"

uint64_max_example :: proc() {
	fmt.println(rand.uint64_max(16))
}

Possible Output:

6
13

Generates a random unsigned 64 bit value in the range [lo, hi) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• lo: The lower bound of the generated number, this value is inclusice
• hi: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random 64 bit value in the range [lo, hi)

WARNING: Panics if lo is greater or equal to hi

Example:

import "core:math/rand"
import "core:fmt"

uint64_range_example :: proc() {
	fmt.println(rand.uint64_range(5,15))
}

Possible Output:

6
13

Generates a random integer value in the range [0, n) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• n: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random integer value in the range [0, n)

WARNING: Panics if n is equal to 0

Example:

import "core:math/rand"
import "core:fmt"

uint_max_example :: proc() {
	fmt.println(rand.uint_max(16))
}

Possible Output:

6
13

Generates a random unsigned integer value in the range [lo, hi) using the provided random number generator. If no generator is provided the global random number generator will be used.

Inputs:

• lo: The lower bound of the generated number, this value is inclusice
• hi: The upper bound of the generated number, this value is exclusive

Returns:

• val: A random integer value in the range [lo, hi)

WARNING: Panics if lo is greater or equal to hi

Example:

import "core:math/rand"
import "core:fmt"

uint_range_example :: proc() {
	fmt.println(rand.uint_range(5,15))
}

Possible Output:

6
13

Returns an instance of the xoshiro256** pseudorandom generator. If no initial state is provided, the PRNG will be lazily initialized with the system timestamp counter on first-use.

WARNING: This random number generator is NOT cryptographically secure.

Inputs:

• state: Optional initial PRNG state.

Returns:

• A Generator instance.

Creates a Zipf variate generator. The generator produces values k ∈ [0, imax] such that P(k) is proportional to (v + k) ** (-s). The parameters must be: s > 1 and v >= 1

W.Hormann, G.Derflinger: "Rejection-Inversion to Generate Variates from Monotone Discrete Distributions" http://eeyore.wu-wien.ac.at/papers/96-04-04.wh-der.ps.gz

Returns a value drawn from the zipf distribution described by the Zipf contextual structure.

Reset the seed used by the context.random_generator.

Inputs:

• seed: The seed value

Example:

import "core:math/rand"
import "core:fmt"

reset_example :: proc() {
	rand.reset(1)
	fmt.println(rand.uint64())
}

Possible Output:

10