🥮 mooncakes.io

    moonrand

    Reproducible pseudo-random generators, unbiased sampling and the common distributions for MoonBit.

    random
    rng
    prng
    pseudo-random
    chacha
    xoshiro
    xorshift
    pcg
    mersenne-twister
    mt19937
    philox
    threefry
    splitmix
    sfc
    jsf
    lcg
    lfsr
    lxm
    mrg
    well
    squares
    distributions
    sampling
    normal-distribution
    shuffle
    reproducible
    seed
    moonbit
    Download zip
    Version
    0.1.3
    License
    Apache-2.0
    Repository
    Last updated
    9 hours ago
    Downloads
    1K

    #moonrand

    Reproducible pseudo-random numbers: one default generator that needs no configuration, sixty-two more behind it when the algorithm matters, and the sampling and distribution functions Python's random names.

    import {
      "moonbitstack/moonrand",
      "moonbitstack/moonrand/auto",
    }

    test {
      let rng = @moonrand.seeded(b"a seed")
      let roll = @moonrand.randint(rng, 1L, 6L)
      let noise = @moonrand.gauss(rng)
      assert_eq(roll, 5L)
      assert_eq(noise.to_string(), "0.03498079073290354")
    }

    @moonrand.seeded takes any bytes you give it. The same bytes always draw the same numbers, on every backend, so a run that goes wrong can be replayed.

    @auto.rng() asks the operating system for thirty-two bytes and hands them to the same generator, for runs that should not repeat:

    test {
      let rng = @auto.rng() catch { _ => return }
      let x = @moonrand.random(rng)
      assert_true(x >= 0.0 && x < 1.0)
    }

    A host with no entropy source raises Unavailable rather than falling back to a fixed or clock-derived seed, which would hand out a generator that looks random and is not.

    #The default

    StdRngChaCha12, a 256-bit stream cipher used as a generator
    seeded(bytes)a generator over the seed, reproducible
    @auto.rng()a generator over 32 bytes of platform entropy

    A stream cipher is the default because its output is indistinguishable from uniform, it carries the Secure marker, and seeking a million numbers ahead costs one addition to its counter. A stream runs for 2^32 blocks of 64 bytes; past that, seed it again — it never returns to the start on its own.

    #Generators

    Every subpackage holds one family of algorithms, each type implementing the same Rng contract, so anything that draws from Rng works with all of them.

    PackageTypes
    moonrand/chachaChaCha8, ChaCha12, ChaCha20
    moonrand/xoshiroXoshiro256ss, Xoshiro256pp, Xoshiro256p, Xoshiro512ss, Xoshiro512pp, Xoshiro512p, Xoroshiro128p, Xoroshiro128pp, Xoroshiro128ss
    moonrand/pcgPcg32, Pcg64, Pcg64Dxsm
    moonrand/mtMT19937, MT19937_64, Sfmt19937
    moonrand/splitmixSplitMix64
    moonrand/sfcSfc64
    moonrand/jsfJsf64
    moonrand/xorshiftXorshift32, Xorshift64, Xorshift128, Xorshift128Plus, Xorwow
    moonrand/wellWell512, Well1024
    moonrand/lcgLcg64, Lcg48, MinStd, Qcg64, Ccg64, Icg32
    moonrand/chaosLogistic, Tent, Sine, Chebyshev
    moonrand/lfsrLfsr64, Gfsr, Taus88, Lfsr113, Lfsr258
    moonrand/fibAdditiveCongruential, LaggedFibonacci, AddWithCarry, SubtractWithBorrow, Ranlux24, Ranlux48
    moonrand/mrgMrg32k3a
    moonrand/lxmL64X128, L64X256
    moonrand/philoxPhilox4x32, Philox4x64
    moonrand/threefryThreefry4x64, Threefry4x32, Threefry2x64
    moonrand/squaresSquares
    moonrand/classicMiddleSquare, MiddleProduct, MiddleSquareWeyl, CollatzWeyl, Bbs

    Each type takes a seed of the size it announces, expands it through SplitMix64, and offers the reference constructor for a state you already have. The words below are the ones each published algorithm produces from that seed:

    test {
      let rng = @xoshiro.Xoshiro256ss::new(b"any number of bytes")
      assert_eq(rng.next_u64(), 3805413477191604227UL)
      assert_eq(rng.next_u64(), 4654090004589171931UL)
    }

    Generators that can jump say so: jump and long_jump on the xoshiro and LXM families, advance on the counter-based ones — ChaCha, PCG, Philox, Threefry, Squares, SplitMix64, MRG32k3a. Jumping moves the state forward without drawing the words in between:

    test {
      let rng = @xoshiro.Xoshiro256ss::new(b"any number of bytes")
      rng.jump()
      assert_eq(rng.next_u64(), 1157340615618982128UL)
    }

    #Sampling

    Over any Rng, with Python's names:

    FunctionDraw
    random(rng)a real in [0, 1) with exactly 53 bits
    uniform(rng, low, high)a real in [low, high)
    randint(rng, lo, hi)an integer in [lo, hi], closed, unbiased
    randrange(rng, stop, start~, step?)Python's randrange
    getrandbits(rng, k)the low k bits of a word
    choice(rng, items)one element, or None for an empty view
    choices(rng, items, k~, weights?)k elements, in proportion when weighted
    sample(rng, items, k)k distinct elements
    shuffle(rng, items)the array in place

    randint and randrange reject out-of-range draws rather than taking a remainder, so no value is more likely than another, whatever the range.

    test {
      let rng = @moonrand.seeded(b"deal")
      let deck = ["A", "K", "Q", "J"]
      assert_eq(@moonrand.choice(rng, deck), Some("A"))
      @moonrand.shuffle(rng, deck)
      assert_eq(deck, ["A", "J", "Q", "K"])
      assert_eq(@moonrand.sample(rng, deck, 2), ["K", "J"])
    }

    #Distributions

    FunctionDensity
    gauss(rng, mu~, sigma~)normal, by Box-Muller
    normalvariate(rng, mu~, sigma~)normal, by ratio of uniforms
    expovariate(rng, lambda)exponential with rate lambda
    lognormvariate(rng, mu~, sigma~)log-normal
    gammavariate(rng, alpha, beta)gamma, Marsaglia-Tsang
    betavariate(rng, alpha, beta)beta
    poisson(rng, mu)Poisson, multiplication or transformed rejection
    binomialvariate(rng, n, p)the count of successes in n trials
    triangular(rng, low~, high~, mode?)triangular
    vonmisesvariate(rng, mu, kappa)von Mises on the circle
    paretovariate(rng, alpha)Pareto
    weibullvariate(rng, alpha, beta)Weibull

    gauss and normalvariate are two algorithms, not two spellings: they draw from the same generator differently, and a run that swaps one for the other does not reproduce.

    test {
      let rng = @moonrand.seeded(b"dist")
      assert_eq(@moonrand.gauss(rng).to_string(), "-0.0045334408825839735")
      let other = @moonrand.seeded(b"dist")
      assert_eq(@moonrand.normalvariate(other).to_string(), "0.41874563942799287")
    }

    #Writing your own generator

    The contract is three methods, one of which has a body:

    struct Counter {
      mut n : UInt64
    }

    impl @contract.Rng for Counter with fn next_u64(self) -> UInt64 {
      self.n = self.n + 1UL
      self.n * 6364136223846793005UL
    }

    test {
      let rng : Counter = { n: 0UL }
      assert_eq(@moonrand.random(rng).to_string(), "0.3450005159944193")
      assert_eq(@moonrand.randint(rng, 0L, 9L), 7L)
    }

    next_u32, fill and everything above them follow from next_u64. Add impl @contract.Seeded for Counter to rebuild it from a seed, or impl @contract.Secure for Counter when its output is fit for cryptography — Philox and PCG pass statistical tests and are not, so they do not carry it.

    #Licence

    Apache-2.0.

    StdRng

    source
    using @moonbitstack/moonrand/chacha { type ChaCha12 as StdRng }

    The default generator: ChaCha12. Change this one line to change the whole library's default algorithm.

    betavariate

    source
    fn[R : 
    Rng    ] betavariate(r : R, alpha : Double, beta : Double) -> Double

    A beta draw with shape parameters alpha and beta: two gamma draws, taken as a fraction of their sum.

    binomialvariate

    source
    fn[R : 
    Rng    ] binomialvariate(r : R, n : Int64, p : Double) -> Int64

    The number of successes in n trials with success probability p, by inverting the binomial CDF term by term: exact for any n, and linear in the number of successes drawn.

    choice

    source
    fn[R : 
    Rng    , T] choice(r : R, items : ArrayView[T]) -> T?

    One element, or None for an empty view.

    choices

    source
    fn[R : 
    Rng    , T] choices(r : R, items : ArrayView[T], k? : Int, weights? : ArrayView[Double]) -> Array[T]

    k elements with replacement; with weights they are drawn proportionally.

    expovariate

    source
    fn[R : 
    Rng    ] expovariate(r : R, lambd : Double) -> Double

    An exponential draw with rate lambd (mean 1/lambd).

    gammavariate

    source
    fn[R : 
    Rng    ] gammavariate(r : R, alpha : Double, beta : Double) -> Double

    A gamma draw with shape alpha and scale beta, by Marsaglia and Tsang's transform-reject method with the squeeze from their paper (and the Cheng variant for alpha below one).

    gauss

    source
    fn[R : 
    Rng    ] gauss(r : R, mu? : Double, sigma? : Double) -> Double

    A normal draw, scaled to mu and sigma (Box-Muller).

    getrandbits

    source
    fn[R : 
    Rng    ] getrandbits(r : R, k : Int) -> UInt64

    k low bits of the next word; k over 64 returns the whole word.

    lognormvariate

    source
    fn[R : 
    Rng    ] lognormvariate(r : R, mu? : Double, sigma? : Double) -> Double

    A lognormal draw: exp(gauss(mu, sigma)).

    normalvariate

    source
    fn[R : 
    Rng    ] normalvariate(r : R, mu? : Double, sigma? : Double) -> Double

    A normal draw by the ratio-of-uniforms method of Kinderman and Monahan, the one Python's normalvariate uses — a different algorithm from gauss, and a different stream for the same seed.

    paretovariate

    source
    fn[R : 
    Rng    ] paretovariate(r : R, alpha : Double) -> Double

    A Pareto draw with shape alpha: one minus a uniform, raised to -1/alpha.

    poisson

    source
    fn[R : 
    Rng    ] poisson(r : R, mu : Double) -> Int64

    A Poisson draw with mean mu: multiplication for small means, and the transformed-rejection method with a squeeze for large ones, so that a mean of a million costs the same as a mean of a hundred.

    randint

    source
    fn[R : 
    Rng    ] randint(r : R, lo : Int64, hi : Int64) -> Int64

    A uniform integer in the closed interval [lo, hi], unbiased.

    random

    source
    fn[R : 
    Rng    ] random(r : R) -> Double

    A uniform Double in [0, 1), with 53 bits of resolution, as Python's random.random draws it.

    randrange

    source
    fn[R : 
    Rng    ] randrange(r : R, stop : Int64, start? : Int64, step? : Int64) -> Int64

    A uniform integer from range(start, stop, step), as Python's randrange. stop is required; start defaults to 0 and step to 1.

    sample

    source
    fn[R : 
    Rng    , T] sample(r : R, items : ArrayView[T], k : Int) -> Array[T]

    k distinct elements, by a Fisher-Yates partial shuffle.

    seeded

    source
    fn seeded(seed : BytesView) -> 
    ChaCha12

    A StdRng seeded from seed, reproducible for the same seed.

    shuffle

    source
    fn[R : 
    Rng    , T] shuffle(r : R, a : Array[T]) -> Unit

    Shuffle a in place, Fisher-Yates.

    triangular

    source
    fn[R : 
    Rng    ] triangular(r : R, low? : Double, high? : Double, mode? : Double) -> Double

    A triangular draw between low and high with the peak at mode, which defaults to the midpoint. The inverse of the triangular CDF, folded so that one uniform does the work.

    uniform

    source
    fn[R : 
    Rng    ] uniform(r : R, a : Double, b : Double) -> Double

    A uniform Double in [a, b).

    vonmisesvariate

    source
    fn[R : 
    Rng    ] vonmisesvariate(r : R, mu : Double, kappa : Double) -> Double

    A von Mises draw with mean angle mu and concentration kappa, by the Best-Fisher rejection scheme Python's vonmisesvariate uses. Angles come back in [0, 2 pi).

    weibullvariate

    source
    fn[R : 
    Rng    ] weibullvariate(r : R, alpha : Double, beta : Double) -> Double

    A Weibull draw with scale alpha and shape beta, as Python's weibullvariate names them.

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io