fastmath.random

Various random and noise functions.

Namespace defines various random number generators (RNGs), different types of random functions, sequence generators and noise functions.

RNGs

You can use a selection of various RNGs defined in Apache Commons Math library.

Currently supported RNGs:

  • :jdk - default java.util.Random
  • :mersenne - MersenneTwister
  • :isaac - ISAAC
  • :well512a, :well1024a, :well19937a, :well19937c, :well44497a, :well44497b - several WELL variants

To create your RNG use rng multimethod. Pass RNG name and (optional) seed. Returned RNG is equipped with RNGProto protocol with methods: irandom, lrandom, frandom drandom, grandom, brandom which return random primitive value with given RNG.

(let [rng (rng :isaac 1337)]
  (irandom rng))

For conveniency default RNG (:jdk) with following functions are created: irand, lrand, frand, drand, grand, brand.

Each prefix denotes returned type:

  • i - int
  • l - long
  • f - float
  • d - double
  • g - gaussian (double)
  • b - boolean

Check individual function for parameters description.

Random Vector Sequences

Couple of functions to generate sequences of numbers or vectors. You can generate sequence of double, Vec2, Vec3 or Vec4 types. Just pass the size to creator function.

To create generator call sequence-generator with generator name and vector size [1,4]. Following generators are available:

  • :halton - Halton low-discrepancy sequence; range [0,1]
  • :sobol - Sobol low-discrepancy sequence; range [0,1]
  • :sphere - uniformly random distributed on unit sphere
  • :gaussian - gaussian distributed (mean=0, stddev=1)
  • :default - uniformly random; range:[0,1]

After creation you get function equivalent to repeatedly.

Noise

List of continuous noise functions (1d, 2d and 3d):

  • :value - value noise
  • :gradient - gradient noise (improved Ken Perlin version)
  • :simplex - simplex noise

First two (:value and :gradient) can use 4 different interpolation types: :none, :linear, :hermite (cubic) and :quintic.

All can be used as into:

Noise creation requires detailed configuration which is simple map of following keys:

  • :seed - seed as integer
  • :noise-type - type of noise: :value, :gradient (default), :simplex
  • :interpolation - type of interpolation (for value and gradient): :none, :linear, :hermite (default) or :quintic
  • :octaves - number of octaves for combined noise (like FBM), default: 6
  • :lacunarity - scaling factor for combined noise, default: 2.00
  • :gain - amplitude scaling factor for combined noise, default: 0.5
  • :normalize? - should be normalized to [0,1] range (true, default) or to [-1,1] range (false)

For usage convenience 3 ready to use functions are prepared. Return is normalized to [0,1] range:

  • noise - Perlin Noise (gradient noise, 6 octaves, quintic interpolation)
  • vnoise - Value Noise (as in Processing, 6 octaves, hermite interpolation)
  • simplex - Simpled Noise (6 octaves)

Discrete Noise

discrete-noise is a 1d or 2d hash function for given integers. Returns double from [0,1] range.

Distribution

Various real and integer distributions. See DistributionProto and RNGProto for functions.

To create distribution call distribution multimethod with name as a keyword and map as parameters.

billow-noise

Examples

Usage

(let [n (billow-noise {:seed 12345, :interpolation :none})]
  (n 0.5 1.1 -1.3))
;;=> 0.16031746031746036

2d noise

brand

Random boolean with Mersenne Twister RNG.

Examples

Usage

(brand)
;;=> false
(brand 0.1)
;;=> false

Count number of true values with probability 0.15

(count (filter true? (repeatedly 100000 (fn* [] (brand 0.15)))))
;;=> 14969

default-rng

Default RNG - JDK

Examples

Usage

(set-seed! default-rng 111)
;;=> org.apache.commons.math3.random.JDKRandomGenerator@4e22d25e
(irandom default-rng)
;;=> -1641157356
(set-seed! default-rng 999)
;;=> org.apache.commons.math3.random.JDKRandomGenerator@4e22d25e
(irandom default-rng)
;;=> -421961713
(set-seed! default-rng 111)
;;=> org.apache.commons.math3.random.JDKRandomGenerator@4e22d25e
(irandom default-rng)
;;=> -1641157356

discrete-noise

macro

(discrete-noise X Y)(discrete-noise X)

Discrete noise. Parameters:

  • X (long)
  • Y (long, optional)

Returns double value from [0,1] range

Examples

Example calls

(discrete-noise 123 444)
;;=> 0.8660251823561383
(discrete-noise 123 444)
;;=> 0.8660251823561383
(discrete-noise 123 445)
;;=> 0.4702831345937602
(discrete-noise 123)
;;=> 0.28831296287864117

Draw noise for [0-180] range.

distribution

multimethod

Create distribution object.

First parameter is distribution as a :key. Second parameter is a map with configuration. All distributions accept rng under :rng key (default: default-rng) and some of them accept inverse-cumm-accuracy (default set to 1e-9).

Distributions should be called using DistributionProto and RNGProto.

The rest parameters goes as follows:

Real distributions

  • :beta - :alpha (default: 2.0) and :beta (default: 5.0)
  • :cauchy - :mean (default: 0.0) and :scale (default: 1.0)
  • :chi-squared - :degrees-of-freedom (default: 1.0)
  • :empirical - :bean-count (default: 1000) and :data as a sequence
  • :enumerated-real - :data as a sequence and :probabilities as a optional sequence
  • :exponential - :mean (default: 1.0)
  • :f - :numerator-degrees-of-freedom (default: 1.0) and :denominator-degrees-of-freedom (default: 1.0)
  • :gamma - :shape (default: 2.0) and :scale (default: 2.0)
  • :gumbel - :mu (default: 1.0) and :beta (default: 2.0)
  • :laplace - :mu (default: 1.0) and :beta (default: 2.0)
  • :levy - :mu (default: 0.0) and :c (default: 1.0)
  • :logistic - :mu (default: 1.0) and :s (default: 2.0)
  • :log-normal - :scale (default: 1.0) and :shape (default: 1.0)
  • :nakagami - :mu (default: 1.0) and :omega (default: 1.0)
  • :normal - :mu (default: 0.0) and :sd (default: 1.0)
  • :pareto - :scale (default: 1.0) and :shape (default: 1.0)
  • :t - :degrees-of-freedom (default: 1.0)
  • :triangular - :a (default: -1.0), :b (default: 0.0) and :c (default: 1.0)
  • :uniform-real - :lower (default: 0.0) and :upper (default: 1.0)
  • :weibull - :alpha (default: 2.0) and :beta (default: 1.0)

Integer distributions

  • :binomial - :trials (default: 20) and :p (default: 0.5)
  • :enumerated-int - :data and :probabilities as a sequences
  • :geometric - :p (default: 0.5)
  • :hypergeometric - :population-size (default: 100), :number-of-successes (default: 50) and :sample-size (default: 25)
  • :pascal - :r (default: 5) and :p (default: 0.5)
  • :poisson - :p (default: 0.5), :epsilon (default: 1.0e-12), :max-iterations (default: 10000000)
  • :uniform-int - :lower (default: 0) and :upper (default: Integer/MAX_VALUE)
  • :zipf - :number-of-elements (default: 100) and :exponent (default: 3.0)

Examples

Usage

(distribution :beta)
;;=> org.apache.commons.math3.distribution.BetaDistribution@5f4098bd
(distribution :beta {:alpha 1.0, :beta 1.0})
;;=> org.apache.commons.math3.distribution.BetaDistribution@5c38ce9a

PDFs of beta

PDFs of binomial

PDFs of cauchy

PDFs of chi-squared

PDFs of empirical

PDFs of enumerated-int

PDFs of enumerated-real

PDFs of exponential

PDFs of f

PDFs of gamma

PDFs of geometric

PDFs of gumbel

PDFs of hypergeometric

PDFs of laplace

PDFs of levy

PDFs of log-normal

PDFs of logistic

PDFs of nakagami

PDFs of normal

PDFs of pareto

PDFs of pascal

PDFs of poisson

PDFs of t

PDFs of triangular

PDFs of uniform-int

PDFs of uniform-real

PDFs of weibull

PDFs of zipf

DistributionProto

protocol

Get information from distributions.

members

cdf

(cdf d v)(cdf d v1 v2)

Cumulative probability.

Examples

Usage

(cdf (distribution :gamma) 1)
;;=> 0.09020401043104985
(cdf (distribution :gamma) 1 4)
;;=> 0.5037901398591113

icdf

(icdf d p)

Inversed cumulative probability

Examples

Usage

(icdf (distribution :gamma) 0.5)
;;=> 3.3566939800333233

likelihood

(likelihood d vs)

Likelihood of samples

Examples

Usage

(likelihood (distribution :gamma) [10 0.5 0.5 1 2])
;;=> 4.452548659934162E-6

log-likelihood

(log-likelihood d vs)

Log likelihood of samples

Examples

Usage

(log-likelihood (distribution :gamma) [10 0.5 0.5 1 2])
;;=> -12.322033893165353

lower-bound

(lower-bound d)

Lower value

Examples

Usage

(lower-bound (distribution :gamma))
;;=> 0.0

lpdf

(lpdf d v)

Log density

Examples

Usage

(lpdf (distribution :gamma) 1)
;;=> -1.8862943611198908

mean

(mean d)

Mean

Examples

Usage

(mean (distribution :gamma))
;;=> 4.0

pdf

(pdf d v)

Density

Examples

Usage

(pdf (distribution :gamma) 1)
;;=> 0.15163266492815838

probability

(probability d v)

Probability (PMF)

sample

(sample d)

Returns random sample.

Examples

Random value from distribution

(sample (distribution :gamma))
;;=> 1.163090324096224

upper-bound

(upper-bound d)

Higher value

Examples

Usage

(upper-bound (distribution :gamma))
;;=> Infinity

variance

(variance d)

Variance

Examples

Usage

(variance (distribution :gamma))
;;=> 8.0

distributions-list

List of distributions.

Examples

Number and list of distributions

distributions-list
;;=> #{:beta :binomial :cauchy :chi-squared :empirical :enumerated-int
;;=>   :enumerated-real :exponential :f :gamma :geometric :gumbel
;;=>   :hypergeometric :laplace :levy :log-normal :logistic :nakagami :normal
;;=>   :pareto :pascal :poisson :t :triangular :uniform-int :uniform-real
;;=>   :weibull :zipf}
(count distributions-list)
;;=> 28

drand

(drand)(drand mx)(drand mn mx)

Random double number with Mersenne Twister RNG.

Examples

Usage

(drand)
;;=> 0.21008196780785227
(drand 10)
;;=> 3.333885006382933
(drand 10 20)
;;=> 12.863609953680882

fbm-noise

Examples

Usage

(let [n (fbm-noise {:interpolation :linear, :noise-type :value})]
  (n 0.5 1.1 -1.3))
;;=> 0.407153749378963

2d noise

frand

Random float number with Mersenne Twister RNG.

Examples

Usage

(frand)
;;=> 0.1565089
(frand 10)
;;=> 4.953762
(frand 10 20)
;;=> 13.525329

grand

(grand)(grand stddev)(grand mean stddev)

Random gaussian double number with Mersenne Twister RNG.

Examples

Usage

(grand)
;;=> 1.5442389366063856
(grand 10)
;;=> 0.4052294377502962
(grand 10 20)
;;=> 26.121031327562182

interpolations

List of possible noise interpolations as a map of names and values.

Examples

List of names (keys)

(keys interpolations)
;;=> (:none :linear :hermite :quintic)

irand

(irand)(irand mx)(irand mn mx)

Random integer number with Mersenne Twister RNG.

Examples

Usage

(irand)
;;=> 1505610607
(irand 10)
;;=> 1
(irand 10 20)
;;=> 15

lrand

(lrand)(lrand mx)(lrand mn mx)

Random long number with Mersenne Twister RNG.

Examples

Usage

(lrand)
;;=> -8623720365024718743
(lrand 10)
;;=> 7
(lrand 10 20)
;;=> 18

noise

(noise x)(noise x y)(noise x y z)

Create improved Perlin Noise.

6 octaves, quintic interpolation.

Examples

Usage

(noise 3.3)
;;=> 0.5698128253968255
(noise 3.3 1.1)
;;=> 0.4333939385295239
(noise 3.3 0.0 -0.1)
;;=> 0.6325949131987302

2d noise

noise-types

List of possible noise types as a map of names and values.

Examples

List of names (keys)

(keys noise-types)
;;=> (:value :gradient :simplex)

random-noise-cfg

(random-noise-cfg)

Create random noise configuration.

Examples

Random configuration

(random-noise-cfg)
;;=> {:gain 0.4616632689024004,
;;=>  :interpolation :none,
;;=>  :lacunarity 2.012690835375836,
;;=>  :noise-type :simplex,
;;=>  :normalize? true,
;;=>  :octaves 5,
;;=>  :seed -1927726348}

Create function

(random-noise-fn)
;;=> fastmath.random$fbm_noise$fn__10742@5949c3a5
(random-noise-fn (random-noise-cfg))
;;=> fastmath.random$fbm_noise$fn__10742@6d16b32f

One

Two

Three

random-noise-fn

(random-noise-fn cfg)(random-noise-fn)

Create random noise function from all possible options.

Optionally provide own configuration cfg. In this case one of 4 different blending methods will be selected.

randval

macro

(randval v1 v2)(randval prob v1 v2)

Retrun value with given probability (default 0.5)

Examples

Usage

(randval :val-one :val-two)
;;=> :val-two
(randval 0.001 :low-probability :high-probability)
;;=> :high-probability

Check probability of nil (should return value around 1000).

(count (filter nil?
               (repeatedly 1000000 (fn* [] (randval 0.001 nil 101)))))
;;=> 1014

ridgedmulti-noise

Examples

Usage

(let [n
      (ridgedmulti-noise
       {:octaves 3, :lacunarity 2.1, :gain 0.7, :noise-type :simplex})]
  (n 0.5 1.1 -1.3))
;;=> 0.5497357888943046

2d noise

rng

multimethod

Create RNG for given name (as keyword) and optional seed. Return object enhanced with RNGProto. See: rngs-list for names.

Examples

Creating

(rng :mersenne)
;;=> org.apache.commons.math3.random.MersenneTwister@4f29208d
(rng :isaac 1234)
;;=> org.apache.commons.math3.random.ISAACRandom@67369634

Using

(irandom (rng :mersenne 999) 15 25)
;;=> 17

RNGProto

protocol

Defines set of random functions for different RNGs or distributions returning primitive values.

members

->seq

(->seq t)(->seq t n)

Returns sequence of random samples limited to optional n values.

Examples

Sequence of random values from distribution

(->seq (distribution :gamma) 5)
;;=> (1.3985071121468868
;;=>  1.9713574080234095
;;=>  1.188915874704579
;;=>  1.5751629265513674
;;=>  3.0898296399038285)

brandom

(brandom t)(brandom t thr)

Boolean random. Returns true or false with equal probability. You can set probability for true setting thr (from [0-1] range).

See brand.

Examples

boolean

(rngproto-snippet brandom ...)
;;=> false

drandom

(drandom t)(drandom t mx)(drandom t mn mx)

Random double.

For RNGs: As default returns random double from [0,1) range. When mx is passed, range is set to [0, mx). When mn is passed, range is set to [mn, mx).

See drand.

For distributions, just returns random double (call without parameters).

Examples

double

(rngproto-snippet drandom ...)
;;=> 0.8127918946621502

Double random value from distribution

(drandom (distribution :gamma))
;;=> 1.7209575348841526

frandom

(frandom t)(frandom t mx)(frandom t mn mx)

Random float.

For RNGs: As default returns random float from [0,1) range. When mx is passed, range is set to [0, mx). When mn is passed, range is set to [mn, mx).

See frand.

For distributions, just returns random float (call without parameters).

Examples

float

(rngproto-snippet frandom ...)
;;=> 0.6211489

Float random value from distribution (sample cast to float)

(frandom (distribution :gamma))
;;=> 3.6556783

grandom

(grandom t)(grandom t std)(grandom t mean std)

Random double from gaussian distribution. As default returns random double from N(0,1). When std is passed, N(0,std) is used. When mean is passed, distribution is set to N(mean, std).

See grand.

Examples

gaussian double

(rngproto-snippet grandom ...)
;;=> 0.4249215360484422

irandom

(irandom t)(irandom t mx)(irandom t mn mx)

Random integer.

For RNGs: As default returns random integer from full integer range. When mx is passed, range is set to [0, mx). When mn is passed, range is set to [mn, mx).

See irand.

For distributions, just returns random integer (call without parameters).

Examples

integer

(rngproto-snippet irandom ...)
;;=> -102638675

Integer random value from distribution (sample cast to int)

(irandom (distribution :gamma))
;;=> 4

lrandom

(lrandom t)(lrandom t mx)(lrandom t mn mx)

Random long.

For RNGs: As default returns random long from full long range. When mx is passed, range is set to [0, mx). When mn is passed, range is set to [mn, mx).

See lrand.

For distributions, just returns random long (call without parameters).

Examples

long

(rngproto-snippet lrandom ...)
;;=> -3605302057052543534

Long random value from distribution (sample cast to long)

(lrandom (distribution :gamma))
;;=> 0

set-seed!

(set-seed! t v)

Sets seed. Returns RNG or distribution itself.

Examples

Set seed for the RNG object

(let [rng (rng :isaac)]
  (set-seed! rng 1234)
  (irandom rng 10 15))
;;=> 10

;; Test: ok.

rngs-list

List of all possible RNGs.

Examples

Contains

(sort rngs-list)
;;=> (:isaac :jdk :mersenne
;;=>         :well1024a :well19937a
;;=>         :well19937c :well44497a
;;=>         :well44497b :well512a)

sequence-generator

multimethod

Create Sequence generator. See sequence-generators-list for names. Parameter size describes number of dimensions (1-4).

Values are from following values:

  • :halton, :sobol, :default - range [0-1]
  • :gaussian - from N(0,1) distribution
  • :sphere - from surface of unit sphere (ie. euclidean distance from origin equals 1.0)

Examples

Usage (2d)

(let [gen (sequence-generator :halton 2)] (take 5 (gen)))
;;=> (#vec2 [0.0, 0.0]
;;=>  #vec2 [0.5, 0.6666666666666666]
;;=>  #vec2 [0.25, 0.3333333333333333]
;;=>  #vec2 [0.75, 0.2222222222222222]
;;=>  #vec2 [0.125, 0.8888888888888888])

Usage (1d)

(let [gen (sequence-generator :sobol 1)] (take 5 (gen)))
;;=> (0.0 0.5 0.75 0.25 0.375)

Halton plot (1000 samples)

Sobol plot (1000 samples)

Sphere plot (1000 samples)

Gaussian plot (1000 samples)

Default plot (1000 samples)

sequence-generators-list

List of random sequence generator. See sequence-generator.

Examples

Generator names.

(sort sequence-generators-list)
;;=> (:default :gaussian :halton :sobol :sphere)

simplex

(simplex x)(simplex x y)(simplex x y z)

Create Simplex noise. 6 octaves.

Examples

Usage

(simplex 3.3)
;;=> 0.355835517382857
(simplex 3.3 1.1)
;;=> 0.5342550241173722
(simplex 3.3 0.0 -0.1)
;;=> 0.399842115095695

2d noise

single-noise

Examples

Usage

(let [n (single-noise {:interpolation :linear})] (n 0.5 1.1 -1.3))
;;=> 0.627

2d noise

vnoise

(vnoise x)(vnoise x y)(vnoise x y z)

Value Noise.

6 octaves, Hermite interpolation (cubic, h01).

Examples

Usage

(vnoise 3.3)
;;=> 0.5898348391800006
(vnoise 3.3 1.1)
;;=> 0.464545093971326
(vnoise 3.3 0.0 -0.1)
;;=> 0.6356973809698646

2d noise