This module provides an interface to Pierre Ecuyer's pseudorandom generator
library RngStream, which is a high-quality, long period pseudorandom generator
that can do the neat trick of quickly skipping ahead an arbitrary number of samples
in the stream without actually generating all the samples in between. This
capability is used to implement a stream of random bits that can be split
recursively into 'pseudoindependent' substreams.
- The state of a random generator, as a blob atom.
- A state represented as an ordinary Prolog term that can be written as text.
- A blob representing an operator to advance a state by several steps
- A splittable stream, containing a
state and a
- A floating point number between 0 and 1.
Available but not exported
sample_Beta(+nonneg, +nonneg, -nonneg)//
sample_Discrete(+nonneg, +list(prob), -natural)//
sample_DiscreteF(+nonneg, +array(prob), -natural)//
sample_Dirichlet(+nonneg, +list(nonneg), -list(prob))//
sample_DirichletF(+nonneg, +array(nonneg), -array(prob))//
sample_Stable(+float, +float, -float)//
sample_Binomial(+prob, +natural, -natural)//
prob_Beta(+nonneg, +nonneg, +nonneg, -prob)
prob_Gamma(+nonneg, +float, -prob)
prob_Poisson(+nonneg, +natural, -prob)
prob_Zeta(+nonneg, +natural, -prob)
- - Samer Abdallah (2009--2016)
- with_brs(N:atom, G:dcg(rndstate)) is det
- Runs goal G as a DCG goal with RNG state from a thread-local bactrackable
gobal variable name N.
The final state is stored in the global variable, but any
subsequent failure will restore the previous value. If using in a thread
other than main, you must call init_rnd_state/0 to initialise the global
variable. NB, you will probably want to set the Prolog flag
- init_brs(+Name) is det
- Initialise thread local backtrackable global variable with default RNG state.
- randomise_brs(+Name) is det
- Randomise thread local backtrackable global variable using randomise/1.
- get_rnd_state(-State:state) is det
- Unifies State with the current global RNG state.
- set_rnd_state(+State:state) is det
- Sets the globab RNG state to State.
- init_rnd_state(-State:state) is det
- Unifies State with the state that was set at load time.
- randomise(-State:state) is det
- Returns a truly random state by reading from /dev/random.
- is_rnd_state(+State:state) is semidet
- Succeeds if State is a BLOB atom representing a random generator state.
- with_rnd_state(Cmd:phrase(state)) is nondet
- Runs DCG goal Cmd using the current global RNG state as the initial state
the global RNG state afterwards.
- rnd_state_term(+State:state, -Term:state_term) is det
- rnd_state_term(-State:state, +Term:state_term) is det
- Convert between blob and term representation of random state.
- run_rnd_state(Cmd:phrase(state), +State1:state, -State2:state) is nondet
- run_rnd_state(Cmd:phrase(state), +State1:state_term, -State2:state_term) is nondet
- Runs DCG phrase Cmd as with call_dcg/3, except that, if State1 is in the term representation
state), it is converted to the blob representation (type
state) and the final
state is converted back from term representation to get State2.
- init_jump(+E:integer, -Jump:jump) is det
- Unifies Jump with a BLOB atom representing an operator to jump forwards
2^E steps in the stream of random numbers. The generator has a period
of about 2^191. Operators for jumping ahead by 2^76 and 2^127 are
precomputed and so can be returned faster. The resulting BLOB can be
used with jump/3 to advance any given random generator state.
- double_jump(+Jump1:jump, -Jump2:jump) is det
- Unifies Jump2 with an operator that jumps ahead twice as far Jump1,
ie if Jump1 jumps by 2^E, then Jump2 jumps by 2^(E+1). Jump operators
can be created by init_jump/2 and applied by jump/3.
- jump(+Jump:jump, +State1:state, -State2:state) is det
- Advances random generator state represented in State1 by the number
of steps represented by Jump, unifying State2 with the result.
- See also
- - double_jump/2
- - init_jump/2
- spawn(-New:state, +Orig:state, -Next:state) is det
- Samples enough bits from Orig to specify a new generator state New,
leaving the original generator in Next. If generator states represent
streams of random numbers, then you can think of it as sampling a whole
stream of values instead of just one value.
Note: New is likely to point to a new point in the original stream
far away from Orig and Next, simply because the period of the generator
is so large (about 2^191) but there is no guarantee of this. Therefore, it's
possible (but unlikely) that New might produce a stream that overlaps
significantly with samples drawn from Next. If you need to be sure
that New is a long way from Orig and Next, then use jump/3 instead.
|New||- is the state of the newly created generator.|
|Orig||- is the state of the source generator, the original stream.|
|Next||- is the state of the source generator after extracting New.|
- stream_init(+State:state, +E:integer, -Stream:stream) is det
stream ---> stream(state, integer).
[EXPERIMENTAL] Used to initialise a splittable stream. The idea is that
a stream of random number can be recursively split into many substreams,
each of which will not overlap unless very many samples are drawn.
produces a stream such that the first split jumps 2^76 steps along.
Thus, 2^76 samples can be drawn from either before overlap occurs.
Since the period of the generator is more than 2^190, there can be up to
114 levels of recursive splitting, resulting in up to 2^114 substreams.
|State||- is the initial state of the generator.|
|E||- is a nonnegative integer such that, when the stream is first split,
the new substream begins 2^E steps along the sequence. Subsequent splits
will jump twice as far each time.|
|Stream||- is the new stream (a term)|
- stream_split(+Stream1, -Stream2, -Stream3) is det
- [EXPERIMENTAL] Stream1 is split into independent streams Stream2 and Stream3.
Stream2 is actually the same as Stream1. Stream3 is a window on the same strem,
but starting a long way down the sequence.
- sample_Single_(-Float) is det
- Samples a single precision floating point value in [0,1) using the
internal (global) random generator state. It consumes one 32 bit value
from the generator. This is the fasted way to generate a random value
using this library.
- sample_Double_(-Float) is det
- Samples a double precision floating point value in [0,1) using the
internal (global) random generator state. It consumes two 32 bit values
from the generator.
- mean_log_dirichlet(+Alphas:list(nonneg), -X:list(number)) is det
- Compute the expectation of the component-wise log of a Dirichilet
distributed vector represented as a list.
- log_partition_dirichlet(+Alphas:list(nonneg), -X:number) is det
- Compute the log of the normalisation constant of the Dirichlet PDF with
- kldiv_dirichlet(+A:list(nonneg), +B:list(nonneg), -D:number) is det
The following predicates are exported, but not or incorrectly documented.
- log_prob_dirichlet(Arg1, Arg2, Arg3)
- lngamma(Arg1, Arg2)
- digamma(Arg1, Arg2)