GitHub

Helper Utilities

This page groups lower-level tools used by algorithms and model packages.

Numeric helpers

  • log_sum: numerically stable log-sum operations
  • binary_search: utility for sorted-domain lookups
  • logistic: logistic helper used in acceptance rules
  • kldivergence: histogram/function divergence helper
MonteCarloX.log_sum — Function
log_sum(a::T,b::T)

Return result of logarithmic sum $c = \ln(A+B) = a + \ln(1+e^{|b-a|})$ where $C = e^c = A+B = e^a + e^b$.

This is useful for sums that involve elements that span multiple orders of magnitude, e.g., the partition sum that is required as normalization factor during reweighting.

Examples

julia> exp(MonteCarloX.log_sum(log(2.), log(3.)))
5.000000000000001
source
MonteCarloX.binary_search — Function
binary_search(sorted::AbstractVector{T}, value::T)::Int where {T<:Real}

Perform a binary search to return the index i of an sorted array such that sorted[i-1] < value <= sorted[i]

Examples

julia> MonteCarloX.binary_search([1.,2.,3.,4.],2.5)
3
julia> MonteCarloX.binary_search([1,2,3,4],2)
2
source
StatsBase.kldivergence — Function
kldivergence(P::Histogram, Q::Function)

Kullback-Leibler divergence between an empirical distribution (measured) and a reference distribution (analytic)

So far this is defined only for 1-dimensional distributions of type StatsBase.Histogram

source

RNG helper

MutableRandomNumbers is a lightweight utility for deterministic random-number replay and control in workflows that need mutable RNG-like streams.

MonteCarloX.MutableRandomNumbers — Type
MutableRandomNumbers([rng_base=GLOBAL_RNG], size, mode:=static)

Create a MutableRandomNumbers RNG object with a vector of size size containing floating-point randomnumbers initially generated with `rngbase`. Random numbers are then generated sequentially from this vector. The RNG object can be initialized in two modes:

  • :static - then there is an exception thrown once all random numbers are used
  • :dynamic - then there are new random numbers generated on the flow from the (copied) rng

Examples

julia> rng = MutableRandomNumbers(MersenneTwister(1234),100);

julia> x1 = rand(rng, 2)
2-element Array{Float64,1}:
 0.5908446386657102
 0.7667970365022592

julia> rng = MersenneTwister(1234);

julia> x2 = rand(rng, 2)
2-element Array{Float64,1}:
 0.5908446386657102
 0.7667970365022592

julia> x1 == x2
true

Importantly, the random numbers can be accessed and manipulated as in ordinary array objects.

julia> rng[1]
0.5908446386657102
julia> rng[3] = 0.2
julia> rand(rng)
0.2

Use reset! in order to rerun the (manipulated) random number sequence.

julia> reset!(rng)
source
MonteCarloX.reset! — Method
reset!(rng::MutableRandomNumbers, [index::Int=0])

Reset the state of a MutableRandomNumbers object rng to index. Default resets the RNG object to the pre-initial index (0)

source

Event-handler backends

These structures back event selection and queue-based scheduling in continuous-time samplers.

MonteCarloX.ListEventRateSimple — Type
ListEventRateSimple{T}

Simplest event manager for a list of events of type T with a static list of rates.

API implemented

  • length(event_handler)
  • getindex(event_handler, index)
  • setindex!(event_handler, value, index)
source
MonteCarloX.EventQueue — Type
EventQueue{T}([start_time::Float64])

Ordered time-event queue storing (time, event) tuples.

API implemented

  • length(event_handler)
  • getindex(event_handler, index)
  • popfirst!(event_handler)
  • add!(event_handler, tuple_time_event)
  • get_time(event_handler)
  • set_time!(event_handler, time)
source