Capricious
Being able to calculate random values is useful for a variety of tasks, not least as test data. Capricious provides a more convenient interface to the standard pseudorandom number generators available on the JVM.
All terms and types are defined in the capricious
package:
import
capricious
.
*
Generating random values
A random instance of some type, Type
can be constructed by calling,
val
randomInt
=
random
[
Int
]
(
)
val
randomBoolean
=
random
[
Boolean
]
(
)
or, if the type can be inferred from the context, just,
val
randomChar
:
Char
=
random
(
)
Random values can only be generated for certain types, but this includes most
primitive types, and any type for which an Randomizable
typeclass instance
exists.
A value generated with random
should be unpredictable, since it will be
determined from a random 64bit value provided by the JVM’s default random
number generator. This is, however, only a pseudorandom number generator, and
the sequence it produces will be deterministic, albeit difficult to predict.
Repeatability
Randomness is useful, but it can undermine repeatability. So a more finegrained mechanism is available for generating random values with the same probability distribution, but using different random number generators (RNGs), including seeded RNGs which will produce a repeatable sequence of values each time.
The code which will generate random values of this form must be delimited in a
stochastic
block. Within this block, new random values can be generated by
calling arbitrary
in much the same way as we called random
before.
But in order to construct a new stochastic
block, a random number generator
should be specified, with a seed value if necessary. For now, we will used the
default random number generator, with a specified seed value.
For example,
given
Seed
=
Seed
(
12L
)
import
randomNumberGenerators
.
seeded
def
main
(
)
:
Unit
=
stochastic
:
println
(
arbitrary
[
Int
]
(
)
)
println
(
arbitrary
[
Char
]
(
)
)
Note that the sequence of random values generated within a stochastic block will be deterministic, so long as the code is deterministic. This is generally true for singlethreaded code, but concurrency can introduce nondeterminism, since multiple threads could cause random values to be generated in a different order across threads, each time the code is run.
Therefore, it is important to
initiate a new stochastic
block for each thread, using a seed generated from
the parent thread, like so:
import
parasite
.
*
given
Seed
=
Seed
(
42L
)
import
randomNumberGenerators
.
seeded
def
main
(
)
:
Unit
=
stochastic
:
val
seed1
:
Seed
=
arbitrary
(
)
val
seed2
:
Seed
=
arbitrary
(
)
val
async1
=
Async
:
seed1
.
stochastic
:
println
(
arbitrary
[
Int
]
)
val
async2
=
Async
:
seed2
.
stochastic
:
println
(
arbitrary
[
Int
]
)
async1
.
await
(
)
async2
.
await
(
)
Generating random Double
s
Random Double
s can be generated only if a probability distribution is
specified. Since Double
s are a 64bit approximation of the set of real
numbers, which is an infinite set, there is no clear answer for what
probability each possible Double
value should have of being chosen randomly.
Hence, several options are provided, which can be selected by importing them as
contextual values:

import randomDistributions.gaussian
 the Gaussian distribution with mean,0
, and variance,1

import randomDistributions.uniformUnitInterval
 uniform across the interval[0, 1]

import randomDistributions.uniformSymmetricUnitInterval
 uniform across the interval[1, 1]

import randomDistributions.binary
 uniform across the 64bit binary representations of IEEE 754 doubleprecision values 
given Distribution = Gamma(shape, scale)
 a Gamma distribution with a specified shape (k) and scale (θ) 
given Distribution = Gaussian(mean, standardDeviation)
 a Gaussian (normal) distribution with specified mean (x̄) and standard deviation (σ) 
given Distribution = UniformDistribution(start, end)
 a uniform distribution in the range[start, end]
Random sources
Several (pseudo)random number generators are available, sometimes in seeded and unseeded variants:

import randomNumberGenerators.unseeded
 a “standard” generator, with no seed 
import randomNumberGenerators.seeded
 a “standard” generator, requiring a contextualSeed
instance 
import randomNumberGenerators.secureUnseeded
 a “secure” generator, with no seed 
import randomNumberGenerators.secureSeeded
 a “secure” generator, requiring a contextualSeed
instance 
import randomNumberGenerators.stronglySecure
 a “strongly secure” generator, which cannot be seeded
Those generators which require a seed value can define it, as a Long
value, with:
given
Seed
=
Seed
(
23956242374982L
)
or as a byte array of arbitrary length, for example,
given
Seed
=
Seed
(
Bytes
(
78
,
124
,
19
,
3
,
52
,
99
,
112
,
89
,
8
,
7
,
12
)
)
though different random number generators may only use as much of the seed value as they need.
The Randomizable
Typeclass
The typeclass, Randomizable
, will produce random instances of its type parameter. Given instances are
predefined for a few basic types, but custom instances can be constructed by implementing the trait:
trait
Randomizable
:
type
Self
def
from
(
random
:
Random
)
:
Self
We can define a new instance for a type, say Color
, with a simple given
definition such as:
given
Color
is
Randomizable
=
rnd
=>
Color
(
rnd
[
Byte
]
(
)
,
rnd
[
Byte
]
(
)
,
rnd
[
Byte
]
(
)
)
In this example we generate three Byte
values from the Random
instance,
rnd
, supplied.
An implementation of Randomizable
’s from
method should call its rnd
parameter’s methods as many times as necessary to construct a new, arbitrary
instance of Self
. Although random, the instance of Self
should depend
deterministically on the values produced by random
(and should not take
randomness from any other source).
Random sequences
If a type ValueType
is Randomizable
, then List[ValueType]
and
IArray[ValueType]
are also Randomizable
, provided a RandomSize
instance
is in scope, for example by importing,
import
randomization
.
sizes
.
uniformUpto1000
Instances of RandomSize
exist for other powers of 10, up to 100000
.
It’s also possible to construct random Set[ValueType]
s in the same way, but
their sizes may be smaller due to deduplication. For example, whatever the
range of RandomSize
, a Set[Boolean]
would never have more than two elements,
true
and false
.
Product and Sum types
Capricious can construct random instances of product types such as case classes
and enumeration cases, and sum types like enum
s and sealed traits, as long as
each field of the product and variant of the sum has a valid Randomizable
instance.
This genericderivation functionality works thanks to Wisteria.