Random number generators.

While convenience functions rand, rand-integer and rand-nth are provided, this namespace’s primary feature is the generation of reducible collections of random numbers.

Random numbers are generated by a random number generator, which produces collection of random bytes. The random number generator is created with the rng function. Dunaj provides four rng types, each having its own rng factory:

  • secure-rng - A thread safe secure rng with host-specific algorithm and providers

  • seedable-rng - A thread safe rng with the ability to specify initial seed and with a guarantee that the same seed yields same sequence of items in the first reduction of the rng. Slower compared to other rngs.

  • splittable-rng - A non thread safe rng which is however intended for fork-join tasks, as it is able to split into two separate rngs. Can be seeded with same guarantees as in seedable-rng.

  • thread-local-rng - A fast thread local rng.

The IRngFactory protocol serves as an extension point for custom rngs.

To generate numbers of other types, this namespace provides several transducers to convert a collection of bytes to the collection of integers, floats, etc.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
(ns foo.bar
  (:api dunaj)
  (:require [dunaj.math.random :refer
             [rng secure-rng splittable-rng seedable-rng floats integers]]))

(defn t50
  [x]
  (seq (take 50 x)))
#'foo.bar/t50

;; default rng is thread-local-rng
(t50 (rng))
;;=> (119 115 42 -52 -65 25 -45 -7 -21 32 -63 74 -89 -119 84 -4 -6 -53 62 57 -70 -99 -81 2 32 82 18 -21 -10 1 38 101 -80 -12 40 -54 -52 -96 56 64 1 -66 125 -76 -41 67 23 62 97 -125)

(t50 (rng splittable-rng))
;;=> (-87 68 95 -22 -67 -17 48 -86 -50 -95 125 -43 -113 -9 -103 50 96 52 116 22 111 -35 -31 -3 63 -57 24 13 -126 66 -12 -116 63 -17 73 -108 -34 -43 -42 -115 -126 -103 -24 114 -5 36 -103 54 -116 -94)

;; different values for each call
(t50 (rng splittable-rng))
;;=> (61 2 -5 -70 -58 20 65 -103 107 -95 -100 14 -31 -51 78 -19 23 24 48 -31 -54 -60 48 -78 78 84 53 -7 -1 48 124 89 -90 127 63 -30 73 -82 -94 -82 78 58 79 106 19 25 36 52 25 -116)

;; same sequence of values if seed is given
(t50 (rng splittable-rng :seed 37))
;;=> (77 -63 -96 60 -45 6 -108 57 17 32 44 -11 116 37 -92 -124 56 82 113 -91 -107 -74 -13 34 -39 -17 -84 -63 -81 -57 27 45 -91 -103 -84 -113 -47 -42 48 -11 -4 -23 122 -41 88 41 -117 -74 -14 122)

(t50 (rng splittable-rng :seed 37))
;;=> (77 -63 -96 60 -45 6 -108 57 17 32 44 -11 116 37 -92 -124 56 82 113 -91 -107 -74 -13 34 -39 -17 -84 -63 -81 -57 27 45 -91 -103 -84 -113 -47 -42 48 -11 -4 -23 122 -41 88 41 -117 -74 -14 122)

;; a specific rng algorithm
(t50 (rng secure-rng :algorithm :SHA1PRNG))
;;=> (-5 20 -46 40 86 115 98 110 -16 -37 104 118 115 88 -92 -62 -65 94 66 -114 4 16 21 82 -8 -109 46 -32 121 -19 104 -7 75 10 -31 24 -110 -61 15 101 37 -119 -76 -105 108 80 33 106 -45 33)

(t50 (floats (rng seedable-rng :seed 37)))
;;=> (0.6213673786196462 0.11767774115427432 0.3057012221689267 0.2779979466319322 0.8238345844110927 0.5771493274960889 0.7395583822711226 0.9952175991966816 0.18484649059100977 0.08544077294128793 0.8076774623917103 0.08376394939840692 0.8039344925877363 0.7668491582256233 0.9489120839560206 0.5222732092107184 0.8755060363988736 0.6321842021329726 0.1410453993499785 0.8890007932941834 0.4521905892448751 0.39626789799103623 0.7140972962963366 0.7894629038956209 0.9099697303814941 0.8886949769154551 0.8426470272412888 0.3620634863965546 0.11123478120858488 0.03851544455319644 0.25191815669293727 0.607718766380739 0.5229288199626858 0.927230088846274 0.8856617752046294 0.3127969113719665 0.2970980055897312 0.6851941591606379 0.004689795859532442 0.28154035458318494 0.2902260155893356 0.4567736079618796 0.7653040745123209 0.9057425555667131 0.7918818831463412 0.6951655518660256 0.4755481079449102 0.31551444942865103 0.2090669792787726 0.03427121432525759)

(t50 (integers (rng seedable-rng :seed 37)))
;;=> (2484939960054915017 -1407233582011305665 -2505961012080803273 6132965348399674666 2831527535557967913 8525032873404670349 213163188322748885 8357302471195787806 7547268150782053599 6365694898836923311 9167938836495731085 8094593845933113253 808179090903878980 -2949504918879114769 2579348292390082974 5626912148038115921 2846420815215924342 5658591834581413859 -1112267939480947828 6885535682214371679 5318481830143046625 -6226851833088151567 -6999934874497308872 -3807678080828022440 -890640589789670241 -1473233371126622890 1684028349137180073 969048822483567652 1761443495185153707 -6329966957305534863 -503850290705303299 8533843916042578403 -6766805056743537414 -8379655411398162417 1696426505585444650 -6250910704441475923 -1355519215176065282 -3261270747328271806 -575109016053944716 2098761114244222074 5271798724709642839 -3615338865428272884 6273421780089623733 -6944696891458706220 8875155693088084442 7117896854021488764 -6780461618461832764 -3656054042683587424 4383715093420286071 -8348802904759004167)

(t50 (integers 900 1000 (rng)))
;;=> (952 997 998 970 977 903 911 962 951 988 986 951 916 906 942 902 916 969 983 946 926 905 936 941 972 930 931 944 962 994 936 917 966 910 942 996 968 921 960 977 954 950 903 946 941 988 948 953 954 919)

Primary

rand

Available since version 1.0 (view source)

Usage:
  • (rand)

  • (rand end)

  • (rand begin end)

Type signatures:
  • () → Float+

  • (Float+) → Float+

  • (Float+ ⨯ Float+) → Float+

Returns a random floating point number, with optional begin (inclusive) and end (exclusive) bounds. Default value for begin is 0.0 and default value for end is 1.0.

rand-integer

Available since version 1.0 (view source)

Usage:
  • (rand-integer)

  • (rand-integer end)

  • (rand-integer begin end)

Type signatures:
  • () → Integer+

  • (Integer+) → Integer+

  • (Integer+ ⨯ Integer+) → Integer+

Returns a random integer number, with optional begin (inclusive) and end (exclusive) bounds. One arg version sets begin to 0.

rand-nth

Available since version 1.0 (view source)

Usage:
  • (rand-nth coll)

  • (rand-nth coll rng)

Type signatures:
  • (IIndexed) → Any

  • (IIndexed ⨯ IRed) → Any

Returns a random item of an IIndexed coll. Can supply a custom rng.

See also: rand, rand-integer, sample, rng

rng

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (rng)

  • (rng factory)

  • (rng factory seed)

  • (rng factory key val & keyvals)

Type signatures:
  • () → IRed

  • (IRngFactory) → IRed

  • (IRngFactory ⨯ Integer+) → IRed

  • (IRngFactory ⨯ Keyword ⨯ Any ⨯ (Va Any)) → IRed

Returns a newly created random number generator based on given factory and options (integer seed or key-val options). factory defaults to thread-local-rng.

Returned random number generator is a homogeneous reducible collection, usually with support for batched reduce.

The available options and support for seed is determined by a chosen factory implementation.

secure-rng

Available since version 1.0 (view source)

not referred automatically

VAR of type IRngFactory

A secure random number generator factory.

Is thread safe, may block if amount of entropy provided by system is not sufficient.

Supported options:

  • :strong - if true, ignores :algorithm and :provider and uses default strong rng as specified by the host.

  • :algorithm - rng algorithm (e.g. :NativePRNG or :SHA1PRNG).

  • :provider - rng provider (e.g. :SUN). If set, :algorithm must also be non-nil.

No support for :seed. In case no algorithm is provided, host’s default is used instead.

Options used for the random number generator crated with this factory can be accessed with config.
1
2
3
4
5
6
7
8
9
10
11
(ns foo.bar
  (:api dunaj)
  (:require [dunaj.math.random :refer
             [rng secure-rng splittable-rng seedable-rng floats integers]]))

;; current config for secure-rng
(config (rng secure-rng))
;;=> #dunaj.math.random.SecureRngFactory{:strong nil, :algorithm "NativePRNG", :provider "SUN"}

(config (rng secure-rng :strong true))
;;=> #dunaj.math.random.SecureRngFactory{:strong true, :algorithm "NativePRNGBlocking", :provider "SUN"}

seedable-rng

Available since version 1.0 (view source)

not referred automatically

VAR of type IRngFactory

A seedable random number generator factory.

Thread safe, but slower compared to other rngs. Supported options:

  • :seed - if not nil, used to seed the generator. It is guaranteed that same seed yields same set of items in the first reduction of the rng.

See also: rng, IRngFactory

splittable-rng

Available since version 1.0 (view source)

not referred automatically

VAR of type IRngFactory

A splittable random number generator factory, useful in fork-join tasks. Split can be performed with dunaj.state/clone function. Random number generators created with this factory are not thread safe.

Supported options:

  • :seed - if not nil, used to seed the generator. It is guaranteed that same seed yields same set of items in the first reduction of the rng.

thread-local-rng

Available since version 1.0 (view source)

not referred automatically

VAR of type IRngFactory

A thread local random number generator factory. Has no options. Is thread local.

See also: rng, IRngFactory

Transducers

booleans

Available since version 1.0 (view source)

not referred automatically

RETURNS TRANSDUCER

Usage:
  • (booleans)

  • (booleans coll)

Type signatures:
  • () → Transducer

  • ([]) → IRed

Returns a transducer for converting collection of random bytes into a collection of random booleans.

See also: rand-integer, integers

floats

Available since version 1.0 (view source)

not referred automatically

RETURNS TRANSDUCER

Usage:
  • (floats)

  • (floats coll)

  • (floats end coll)

  • (floats begin end coll)

Type signatures:
  • () → IRed

  • ([]) → IRed

  • ((Maybe Float+) ⨯ []) → IRed

  • ((Maybe Float+) ⨯ (Maybe Float+) ⨯ []) → IRed

A transducer for converting collection of random bytes into a collection of random floats from the [begin end) inteval, both of which can be nil. Default begin value is 0.0 and default end value is 1.0.

See also: floats*, rand, gaussian

floats*

Available since version 1.0 (view source)

not referred automatically

RETURNS TRANSDUCER

Usage:
  • (floats* begin end)

  • (floats* begin end coll)

Type signatures:
  • ((Maybe Float+) ⨯ (Maybe Float+)) → Transducer

  • ((Maybe Float+) ⨯ (Maybe Float+) ⨯ []) → IRed

A transducer for converting collection of random bytes into a collection of random floats from the [begin end) inteval, both of which can be nil. Default begin value is 0.0 and default end value is 1.0.

See also: floats, rand, gaussian

gaussian

Available since version 1.0 (view source)

not referred automatically

RETURNS TRANSDUCER

Usage:
  • (gaussian)

  • (gaussian coll)

Type signatures:
  • () → Transducer

  • ([]) → IRed

Returns a transducer for converting collection of random bytes into a collection of random floats in normal distribution.

See also: rand, sample, floats

integers

Available since version 1.0 (view source)

not referred automatically

RETURNS TRANSDUCER

Usage:
  • (integers)

  • (integers coll)

  • (integers end coll)

  • (integers begin end coll)

Type signatures:
  • () → IRed

  • ([]) → IRed

  • ((Maybe Integer+) ⨯ []) → IRed

  • ((Maybe Integer+) ⨯ (Maybe Integer+) ⨯ []) → IRed

Returns a transducer for converting collection of random bytes into a collection of random integers from the [begin end) inteval, both of which can be nil. Default begin is set to 0. Ignores begin if end is nil.

integers*

Available since version 1.0 (view source)

not referred automatically

RETURNS TRANSDUCER

Usage:
  • (integers* begin end)

  • (integers* begin end coll)

Type signatures:
  • ((Maybe Integer+) ⨯ (Maybe Integer+)) → Transducer

  • ((Maybe Integer+) ⨯ (Maybe Integer+) ⨯ []) → IRed

Returns a transducer for converting collection of random bytes into a collection of random integers from the [begin end) interval, both of which can be nil. Ignores begin if end is nil.

sample

Available since version 1.0 (view source)

RETURNS TRANSDUCER

Usage:
  • (sample prob)

  • (sample prob coll)

Type signatures:
  • (Float+) → Transducer

  • (Float+ ⨯ []) → IRed

Returns a transducer that randomly filters out step values with probability prob, a value from the interval [0.0 - 1.0].

Other

In this section: default-rng-batch-size

default-rng-batch-size

Available since version 1.0 (view source)

not referred automatically

VAR of type Var

A var holding a default rng batch size.