ImmutableRNGs.jl

ImmutableRNGs.jl provides immutable RNG keys and counter-backed sequential RNG state for Julia. Keys are small isbits values. A draw from a key is pure and reproducible. Explicit derivation separates independent work without hidden shared state.

This package is experimental 0.1.0-DEV software.

Read the full documentation.

Install

Run import Pkg; Pkg.add(url="https://github.com/BJMCox/ImmutableRNGsTestbed.jl").

The only runtime dependencies are Julia's Random and Serialization standard libraries. Optional extensions provide distribution, parallel, GPU, tracing, and automatic differentiation support.

Example

using ImmutableRNGs, Random

key = Philox4x32(42)
@assert rand(key, UInt64) == rand(key, UInt64)  # immutable replay

simulation_key, cursor_key = splitrng(key)
trial_key = subrng(simulation_key, 17)
trial_value = rand(trial_key, Float64)

cursor = RNGCursor(cursor_key)
first_value, cursor = nextrand(cursor, Float64)
batch, cursor = nextrandn(cursor, Float64, 4)

rng = MutableRNG(cursor)                        # Random.AbstractRNG bridge
die = rand(rng, 1:6)
checkpoint = freeze(rng)                       # immutable continuation
@assert cursor_position(checkpoint) > cursor_position(cursor)

Caveats

An immutable key is not a Random.AbstractRNG. MutableRNG is not thread safe. MutableRNG(key) starts at position zero. Resume with MutableRNG(cursor). Checkpoints validate replay data but do not authenticate or encrypt it. Exact external sampler replay also depends on the sampler environment. Accelerator and integration guarantees cover only the documented versions, generators, operations, and backends.

See the documentation for stream laws, checkpoint formats, generators, accelerator support, integrations, validation, and migration guidance.