struct

Alea::Random

Inherits Struct / Value / Object

Alea::Random provides the interface for distribution sampling, using the xoshiro pseudo random number generators written by Sebastiano Vigna and David Blackman.

seed = 9377
random = Alea::Random.new(seed)
random # => Alea::Random

The default generator is Alea::XSR128, faster than Alea::XSR256, but less capable state. To use the 256-bits version call the constructor like this:

seed = 12345
random = Alea::Random.new(seed, Alea::XSR256)
random.prng # => Alea::XSR256

You can build your own custom PRNG by inheriting Alea::PRNG and implementing #next_u, #next_f and #jump, as they are needed by every other call (except for #jump); then create a new instance of Alea::Random passing you class by its name like above.

The following implementations are taken from numpy.

Constants

DEFAULT = Alea::XSR128

Constructors

new(seed32 : Int, seed64 : Int, prng : Alea::PRNG.class = DEFAULT)

Initializes the PRNG with initial seeds.

@parameters:

seed32: value as input to init. the state of 32-bit generators of prng.
seed64: value as input to init. the state of 64-bit generators of prng.
prng: the PRNG in use by this instance.

@exceptions:

Alea::UndefinedError if any of seed32 or seed64 is negative.

new(seed : Int, prng : Alea::PRNG.class = DEFAULT)

Initializes the PRNG with initial seed.

@parameters:

seed: initial seed as input for generating the state of prng.
prng: the PRNG in use by this instance.

@exceptions:

Alea::UndefinedError if seed is negative.

new(prng : Alea::PRNG.class = DEFAULT)

Initializes the PRNG with initial state readed from system resources.

@parameters:

prng: the PRNG in use by this instance.

new(prng : Alea::PRNG)

Initializes the PRNG with initial instance.

@parameters:

prng: the PRNG instance itself.

Instance methods

beta(*, a, b)

Generate a beta-distributed, pseudo-random Float64 in range [0, 1).

@note: named arguments are mandatory to prevent ambiguity.

@parameters:

a: shape parameter of the distribution; usually mentioned as α.
b: shape parameter of the distribution; usually mentioned as β.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if any of a or b is negative or zero.

beta32(*, a, b)

Generate a beta-distributed, pseudo-random Float32 in range [0, 1).

@note: named arguments are mandatory to prevent ambiguity.

@parameters:

a: shape parameter of the distribution; usually mentioned as α.
b: shape parameter of the distribution; usually mentioned as β.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if any of a or b is negative or zero.

chisq(df)

Generate a chi-square-distributed, pseudo-random Float64.

@parameters:

df: degrees of freedom of the distribution; usually mentioned as k.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if df is negative or zero.

chisq32(df)

Generate a chi-square-distributed, pseudo-random Float32.

@parameters:

df: degrees of freedom of the distribution; usually mentioned as k.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if df is negative or zero.

exp(scale = 1.0) : Float64

Generate a exp-distributed, pseudo-random Float64.

@parameters:

scale: scale parameter of the distribution; usually mentioned as λ^-1.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if scale is negative or zero.

exp32(scale = 1.0_f32) : Float32

Generate a exp-distributed, pseudo-random Float32.

@parameters:

scale: scale parameter of the distribution; usually mentioned as λ^-1.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if scale is negative or zero.

float(min : Number, max : Number) : Float64

Generate a uniform-distributed, pseudo-random Float64 in fixed range.

@parameters:

min: left bound parameter of range of the distribution; usually mentioned as a.
max: right bound parameter of range of the distribution; usually mentioned as b.

float(max : Number) : Float64

Generate a uniform-distributed, pseudo-random Float64 in range [0.0, max).

@parameters:

max: right bound parameter of range of the distribution; usually mentioned as b.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if max is negative or zero.

float(range : Range(Number, Number)) : Float64

Generate a uniform-distributed, pseudo-random Float64 in fixed range.

@parameters:

range: range parameter, inclusive or exclusive, of the distribution:
range.begin: left bound parameter of range of the distribution; usually mentioned as a.
range.end: right bound parameter of range of the distribution; usually mentioned as b.

@notes:

inclusive means [range.begin, range.end].
exclusive means [range.begin, range.end).
see Range from Crystal stdlib.

@examples:

range_in = 10.0..9377.0
range_in # Range(Float64, Float64), end-inclusive

range_ex = 10.0...9377.0
range_ex # Range(Float64, Float64), end-exclusive

random = Alea::Random.new
random.float(range_in) # => 9113.861259040154
random.float(range_ex) # => 7701.2778313581175

@exceptions:

Alea::NaNError if any of the arguments bound is NaN.
Alea::InfinityError if any of the arguments bound is Infinity.
Alea::UndefinedError if range.end is less than range.begin.
Alea::UndefinedError if range is not end-inclusive but bounds are the same.

float

Generate a uniform-distributed, pseudo-random Float64 in range [0.0, 1.0).

@references: #next_f64.

float32(min : Number, max : Number) : Float32

Generate a uniform-distributed, pseudo-random Float32 in fixed range.

@parameters:

min: left bound parameter of range of the distribution; usually mentioned as a.
max: right bound parameter of range of the distribution; usually mentioned as b.

float32(max : Number) : Float32

Generate a uniform-distributed, pseudo-random Float32 in range [0.0, max).

@parameters:

max: right bound parameter of range of the distribution; usually mentioned as b.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if max is negative or zero.

float32(range : Range(Number, Number)) : Float32

Generate a uniform-distributed, pseudo-random Float64 in fixed range.

@parameters:

range: range parameter, inclusive or exclusive, of the distribution:
range.begin: left bound parameter of range of the distribution; usually mentioned as a.
range.end: right bound parameter of range of the distribution; usually mentioned as b.

@notes:

inclusive means [range.begin, range.end].
exclusive means [range.begin, range.end).
see Range from Crystal stdlib.

@examples:

range_in = 10.0..9377.0
range_in # Range(Float64, Float64), end-inclusive

range_ex = 10.0...9377.0
range_ex # Range(Float64, Float64), end-exclusive

random = Alea::Random.new
random.float32(range_in) # => 950.3449
random.float32(range_ex) # => 3455.0183

@exceptions:

Alea::NaNError if any of the arguments bound is NaN.
Alea::InfinityError if any of the arguments bound is Infinity.
Alea::UndefinedError if range.end is less than range.begin.
Alea::UndefinedError if range is not end-inclusive but bounds are the same.

float32

Generate a uniform-distributed, pseudo-random Float32 in range [0.0, 1.0).

@references: #next_f32.

gamma(shape, scale = 1.0)

Generate a gamma-distributed, pseudo-random Float64.

@parameters:

shape: shape parameter of the distribution; usually mentioned as k.
scale: scale parameter of the distribution; usually mentioned as θ.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if any of shape or scale is negative or zero.

gamma32(shape, scale = 1.0)

Generate a gamma-distributed, pseudo-random Float32.

@parameters:

shape: shape parameter of the distribution; usually mentioned as k.
scale: scale parameter of the distribution; usually mentioned as θ.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if any of shape or scale is negative or zero.

laplace(loc = 0.0, scale = 1.0)

Generate a laplace-distributed, pseudo-random Float64.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.
scale: scale parameter of the distribution; usually mentioned as b.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if scale is negative or zero.

laplace32(loc = 0.0_f32, scale = 1.0_f32)

Generate a laplace-distributed, pseudo-random Float32.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.
scale: scale parameter of the distribution; usually mentioned as b.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if scale is negative or zero.

lognormal(loc = 0.0, sigma = 1.0)

Generate a log-normal-distributed, pseudo-random Float64.

@parameters:

loc: centrality parameter, or mean of the underlying normal distribution; usually mentioned as μ.
sigma: scale parameter, or standard deviation of the underlying normal distribution; usually mentioned as σ.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if sigma is negative or zero.

lognormal32(loc = 0.0_f32, sigma = 1.0_f32)

Generate a log-normal-distributed, pseudo-random Float32.

@parameters:

loc: centrality parameter, or mean of the underlying normal distribution; usually mentioned as μ.
sigma: scale parameter, or standard deviation of the underlying normal distribution; usually mentioned as σ.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if sigma is negative or zero.

next_beta(*, a : Float64, b : Float64) : Float64

Generate a beta-distributed, pseudo-random Float64 in range [0, 1). Unparsed version of #beta.

@note: named arguments are mandatory to prevent ambiguity.

@parameters:

a: shape parameter of the distribution; usually mentioned as α.
b: shape parameter of the distribution; usually mentioned as β.

next_beta32(*, a : Float32, b : Float32) : Float32

Generate a beta-distributed, pseudo-random Float32 in range [0, 1). Unparsed version of #beta32.

@note: named arguments are mandatory to prevent ambiguity.

@parameters:

a: shape parameter of the distribution; usually mentioned as α.
b: shape parameter of the distribution; usually mentioned as β.

next_chisq(df : Int32) : Float64

Generate a chi-square-distributed, pseudo-random Float64. Unparsed version of chisq.

@parameters:

df: degrees of freedom of the distribution; usually mentioned as k.

next_chisq32(df : Int32) : Float32

Generate a chi-square-distributed, pseudo-random Float32. Unparsed version of chisq32.

@parameters:

df: degrees of freedom of the distribution; usually mentioned as k.

next_exp(scale : Float64) : Float64

Generate a exp-distributed, pseudo-random Float64. Unparsed version of exp.

@parameters:

scale: scale parameter of the distribution; usually mentioned as λ^-1.

next_exp

Generate a exp-distributed, pseudo-random Float64. Unparsed version of exp.

@note:

scale is 1.0.

next_exp32(scale : Float32) : Float32

Generate a exp-distributed, pseudo-random Float32. Unparsed version of exp32.

@parameters:

scale: scale parameter of the distribution; usually mentioned as λ^-1.

next_exp32

Generate a exp-distributed, pseudo-random Float32. Unparsed version of exp32.

@note:

scale is 1.0.

next_f32

Returns the next generated Float32.

next_f64

Returns the next generated Float64.

next_float(min : Float64, max : Float64) : Float64

Generate a uniform-distributed, pseudo-random Float64 in fixed range. Unparsed version for #float.

@parameters:

min: left bound parameter of range of the distribution; usually mentioned as a.
max: right bound parameter of range of the distribution; usually mentioned as b.

next_float(max : Float64) : Float64

Generate a uniform-distributed, pseudo-random Float64 in range [0, max). Unparsed version for #float.

@parameters:

max: right bound parameter of range of the distribution; usually mentioned as b.

next_float32(min : Float32, max : Float32) : Float32

Generate a uniform-distributed, pseudo-random Float32 in fixed range. Unparsed version for #float32.

@parameters:

min: left bound parameter of range of the distribution; usually mentioned as a.
max: right bound parameter of range of the distribution; usually mentioned as b.

next_float32(max : Float32) : Float32

Generate a uniform-distributed, pseudo-random Float32 in range [0, max). Unparsed version for #float32.

@parameters:

max: right bound parameter of range of the distribution; usually mentioned as b.

next_gamma(shape : Float64, scale : Float64) : Float64

Generate a gamma-distributed, pseudo-random Float64. Unparsed version of #gamma.

@parameters:

shape: shape parameter of the distribution; usually mentioned as k.
scale: scale parameter of the distribution; usually mentioned as θ.

next_gamma(shape : Float64) : Float64

Generate a gamma-distributed, pseudo-random Float64. Unparsed version of #gamma.

@parameters:

shape: shape parameter of the distribution; usually mentioned as k.

@note:

scale is 1.0.

next_gamma32(shape : Float32, scale : Float32) : Float32

Generate a gamma-distributed, pseudo-random Float32. Unparsed version of #gamma.

@parameters:

shape: shape parameter of the distribution; usually mentioned as k.
scale: scale parameter of the distribution; usually mentioned as θ.

next_gamma32(shape : Float32) : Float32

Generate a gamma-distributed, pseudo-random Float32. Unparsed version of #gamma32.

@parameters:

shape: shape parameter of the distribution; usually mentioned as k.

@note:

scale is 1.0.

next_laplace(loc : Float64, scale : Float64) : Float64

Generate a laplace-distributed, pseudo-random Float64. Unparsed version of laplace.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.
scale: scale parameter of the distribution; usually mentioned as b.

next_laplace(loc : Float64) : Float64

Generate a laplace-distributed, pseudo-random Float64. Unparsed version of laplace.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.

@notes:

scale is 1.0.

next_laplace

Generate a laplace-distributed, pseudo-random Float64. Unparsed version of laplace.

@notes:

loc is 0.0.
scale is 1.0.

next_laplace32(loc : Float32, scale : Float32) : Float32

Generate a laplace-distributed, pseudo-random Float32. Unparsed version of #laplace32.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.
scale: scale parameter of the distribution; usually mentioned as b.

next_laplace32(loc : Float32) : Float32

Generate a laplace-distributed, pseudo-random Float32. Unparsed version of #laplace32.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.

@notes:

scale is 1.0.

next_laplace32

Generate a laplace-distributed, pseudo-random Float32. Unparsed version of #laplace32.

@notes:

loc is 0.0.
scale is 1.0.

next_lognormal(loc : Float64, sigma : Float64) : Float64

Generate a log-normal-distributed, pseudo-random Float64. Unparsed version of #lognormal.

@parameters:

loc: centrality parameter, or mean of the underlying normal distribution; usually mentioned as μ.
sigma: scale parameter, or standard deviation of the underlying normal distribution; usually mentioned as σ.

next_lognormal(loc : Float64) : Float64

Generate a log-normal-distributed, pseudo-random Float64. Unparsed version of #lognormal.

@parameters:

loc: centrality parameter, or mean of the underlying normal distribution; usually mentioned as μ.

@notes:

sigma is 1.0.

next_lognormal

Generate a log-normal-distributed, pseudo-random Float64. Unparsed version of #lognormal.

@notes:

loc is 0.0.
sigma is 1.0.

next_lognormal32(loc : Float32, sigma : Float32) : Float32

Generate a log-normal-distributed, pseudo-random Float32. Unparsed version of #lognormal32.

@parameters:

loc: centrality parameter, or mean of the underlying normal distribution; usually mentioned as μ.
sigma: scale parameter, or standard deviation of the underlying normal distribution; usually mentioned as σ.

next_lognormal32(loc : Float32) : Float32

Generate a log-normal-distributed, pseudo-random Float32. Unparsed version of #lognormal32.

@parameters:

loc: centrality parameter, or mean of the underlying normal distribution; usually mentioned as μ.

@notes:

sigma is 1.0.

next_lognormal32

Generate a log-normal-distributed, pseudo-random Float32. Unparsed version of #lognormal32.

@notes:

loc is 0.0.
sigma is 1.0.

next_normal(loc : Float64, sigma : Float64) : Float64

Generate a normal-distributed, pseudo-random Float64. Unparsed version of #normal.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.
sigma: scale parameter, or standard deviation of the distribution; usually mentioned as σ.

next_normal(loc : Float64) : Float64

Generate a normal-distributed, pseudo-random Float64. Unparsed version of #normal.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.

@notes:

sigma is 1.0.

next_normal

Generate a normal-distributed, pseudo-random Float64. Unparsed version of #normal.

@notes:

loc is 0.0.
sigma is 1.0.

next_normal32(loc : Float32, sigma : Float32) : Float32

Generate a normal-distributed, pseudo-random Float32. Unparsed version of #normal32.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.
sigma: scale parameter, or standard deviation of the distribution; usually mentioned as σ.

next_normal32(loc : Float32) : Float32

Generate a normal-distributed, pseudo-random Float32. Unparsed version of #normal32.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.

@notes:

sigma is 1.0.

next_normal32

Generate a normal-distributed, pseudo-random Float32. Unparsed version of #normal32.

@notes:

loc is 0.0.
sigma is 1.0.

next_poisson(lam : Float64) : Int64

Generate a poisson-distributed, pseudo-random Int64. Unparsed version of #poisson.

@parameters:

lam: separation parameter of the distribution; usually mentioned as λ.

next_poisson

Generate a poisson-distributed, pseudo-random Int64. Unparsed version of #poisson.

@notes:

lam is 1.0.

next_u32

Returns the next generated UInt32.

next_u64

Returns the next generated UInt64.

next_uint(min : UInt64, max : UInt64) : UInt64

Generate a uniform-distributed, pseudo-random UInt64 in fixed range. Unparsed version for #uint.

@parameters:

min: left bound parameter of range of the distribution; usually mentioned as a.
max: right bound parameter of range of the distribution; usually mentioned as b.

next_uint(max : UInt64) : UInt64

Generate a uniform-distributed, pseudo-random UInt64 in range [0, max). Unparsed version for #uint.

@parameters:

max: right bound parameter of range of the distribution; usually mentioned as b.

next_uint32(min : UInt32, max : UInt32) : UInt32

Generate a uniform-distributed, pseudo-random UInt32 in fixed range. Unparsed version for #uint32.

@parameters:

min: left bound parameter of range of the distribution; usually mentioned as a.
max: right bound parameter of range of the distribution; usually mentioned as b.

next_uint32(max : UInt32) : UInt32

Generate a uniform-distributed, pseudo-random UInt32 in range [0, max). Unparsed version for #uint32.

@parameters:

max: right bound parameter of range of the distribution; usually mentioned as b.

normal(loc = 0.0, sigma = 1.0)

Generate a normal-distributed, pseudo-random Float64.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.
sigma: scale parameter, or standard deviation of the distribution; usually mentioned as σ.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if sigma is negative or zero.

normal32(loc = 0.0, sigma = 1.0) : Float32

Generate a normal-distributed, pseudo-random Float32.

@parameters:

loc: centrality parameter, or mean of the distribution; usually mentioned as μ.
sigma: scale parameter, or standard deviation of the distribution; usually mentioned as σ.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if sigma is negative or zero.

poisson(lam = 1.0)

Generate a poisson-distributed, pseudo-random Int64.

@parameters:

lam: separation parameter of the distribution; usually mentioned as λ.

@exceptions:

Alea::NaNError if any of the arguments is NaN.
Alea::InfinityError if any of the arguments is Infinity.
Alea::UndefinedError if lam is negative or zero.

prng

The PRNG in use by this struct.

uint(min : Number, max : Number) : UInt64

Generate a uniform-distributed, pseudo-random UInt64 in fixed range.

@parameters:

min: left bound parameter of range of the distribution; usually mentioned as a.
max: right bound parameter of range of the distribution; usually mentioned as b.

uint(max : Number) : UInt64

Generate a uniform-distributed, pseudo-random UInt64 in range [0, max).

@parameters:

max: right bound parameter of range of the distribution; usually mentioned as b.

@exceptions:

Alea::UndefinedError if max is negative or zero.

uint(range : Range(Number, Number)) : UInt64

Generate a uniform-distributed, pseudo-random UInt64 in fixed range.

@parameters:

range: range parameter, inclusive or exclusive, of the distribution:
range.begin: left bound parameter of range of the distribution; usually mentioned as a.
range.end: right bound parameter of range of the distribution; usually mentioned as b.

@notes:

inclusive means [range.begin, range.end].
exclusive means [range.begin, range.end).
see Range from Crystal stdlib.

@examples:

range_in = 10..9377
range_in # Range(Int32, Int32), end-inclusive

range_ex = 10...9377
range_ex # Range(Int32, Int32), end-exclusive

random = Alea::Random.new
random.uint(range_in) # => 2640
random.uint(range_ex) # => 527

@exceptions:

Alea::UndefinedError if range.end is less than range.begin.
Alea::UndefinedError if range is not end-inclusive but bounds are the same.

uint

Generate a uniform-distributed, pseudo-random UInt64.

@references: #next_u64.

uint32(min : Number, max : Number) : UInt32

Generate a uniform-distributed, pseudo-random UInt32 in fixed range.

@parameters:

min: left bound parameter of range of the distribution; usually mentioned as a.
max: right bound parameter of range of the distribution; usually mentioned as b.

uint32(max : Number) : UInt32

Generate a uniform-distributed, pseudo-random UInt32 in range [0, max).

@parameters:

max: right bound parameter of range of the distribution; usually mentioned as b.

@exceptions:

Alea::UndefinedError if max is negative or zero.

uint32(range : Range(Number, Number)) : UInt32

Generate a uniform-distributed, pseudo-random UInt32 in fixed range.

@parameters:

range: range parameter, inclusive or exclusive, of the distribution:
range.begin: left bound parameter of range of the distribution; usually mentioned as a.
range.end: right bound parameter of range of the distribution; usually mentioned as b.

@notes:

inclusive means [range.begin, range.end].
exclusive means [range.begin, range.end).
see Range from Crystal stdlib.

@examples:

range_in = 10..9377
range_in # Range(Int32, Int32), end-inclusive

range_ex = 10...9377
range_ex # Range(Int32, Int32), end-exclusive

random = Alea::Random.new
random.uint32(range_in) # => 9260
random.uint32(range_ex) # => 153

@exceptions:

Alea::UndefinedError if range.end is less than range.begin.
Alea::UndefinedError if range is not end-inclusive but bounds are the same.

uint32

Generate a uniform-distributed, pseudo-random UInt32.

@references: #next_u32.