Random v0.1.0

Pseudorandom number generators and distributions

Installation

Add Random to the [Dependencies] table of your package's Rux.toml:

[Dependencies]
Random = { Namespace = "Rux", Version = "0.1.0" }

Standard packages are declared by hand: the registry does not serve them, so rux add Rux/Random cannot add them.

Dependencies

Core 0.1.0
Entropy 0.1.0
Math 0.1.0

Guide

Pseudorandom number generators and distributions.

Not for keys, tokens or anything an adversary would like to guess. These generators are fast and reproducible, which is the opposite of what secrecy needs: anyone who sees enough output can reconstruct the state and predict the rest. For randomness that must not be guessed, use Rux/Entropy.

What it provides

Generators — Xoshiro256 and Pcg64Dxsm, each seedable explicitly so a run is reproducible, or from Rux/Entropy when it should not be.
A generator contract — RandomGenerator, which everything else is written against, so a caller's own generator works with all of it.
Uniform values — integers of every width, floats in the unit interval, and bounded draws that are unbiased rather than merely close, using Lemire's method instead of a modulo.
Distributions — normal, exponential, gamma, beta, Bernoulli, binomial, Poisson and weighted choice, built on exact reductions rather than on approximations that drift in the tail.
Sampling — shuffling, choosing an index, weighted choice, and reservoir sampling for a stream whose length is not known in advance.

Index

Interfaces

Name	Summary
`RandomGenerator`	A source of uniformly distributed 64-bit words.

Types

Name	Summary
`SplitMix64`	The seeding generator: a fast mixer with a 64-bit state, used to spread one seed over a larger one.
`Pcg64Dxsm`	A PCG64-DXSM generator.
`Reservoir<T>`	A reservoir sample being built.
`Xoshiro256`	A Xoshiro256** generator.

Functions

Name	Summary
`Binomial<G>`	The number of successes in `trials` independent trials each succeeding with probability `probability`.
`Poisson<G>`	The number of events in one interval when they arrive independently at the given mean rate.
`Bernoulli<G>`	A coin that comes up `true` with probability `probability`.
`Exponential<G>`	A value from the exponential distribution with rate one.
`ExponentialWithRate<G>`	A value from the exponential distribution with the given rate.
`NormalPair<G>`	A pair of independent standard normal values.
`Normal<G>`	A single standard normal value: mean zero, standard deviation one.
`NormalWith<G>`	A normal value with the given mean and standard deviation.
`FillBytes<G>`	Fills `into` with random bytes.
`NextUint32<G>`	The next 32-bit word: the low half of a 64-bit one.
`NextUint16<G>`	The next 16-bit word.
`NextUint8<G>`	The next 8-bit word.
`NextUint128<G>`	The next 128-bit word, high half drawn first.
`NextFloat64<G>`	A `float64` uniformly distributed in `[0, 1)`.
`NextFloat32<G>`	A `float32` uniformly distributed in `[0, 1)`, from the top 24 bits.
`Gamma<G>`	A value from the gamma distribution with the given shape and unit scale.
`GammaWithScale<G>`	A value from the gamma distribution with the given shape and scale.
`Beta<G>`	A value from the beta distribution with the two given shapes, in `[0, 1]`.
`Offer<G, T>`	Offers `item` to `reservoir`.
`Shuffle<G, T>`	Shuffles `items` into a uniformly random order.
`ChooseIndex<G>`	A uniformly chosen index below `count`, or `count` itself when there is nothing to choose from.
`WeightedIndex<G>`	An index chosen in proportion to `weights`.
`XoshiroFromEntropy`	A `Xoshiro256` seeded from the operating system's entropy.
`PcgFromEntropy`	A `Pcg64Dxsm` seeded from the operating system's entropy, on the default stream.
`PcgFromEntropyWithStream`	A `Pcg64Dxsm` seeded from entropy on the stream `stream` selects.
`UniformBelow<G>`	A uniform value in `[0, bound)`.
`UniformInRange<G>`	A uniform value in `[low, high]`, both ends included.
`UniformInSignedRange<G>`	A uniform signed value in `[low, high]`, both ends included.
`UniformFloatInRange<G>`	A uniform `float64` in `[low, high)`.

Constants

Name	Summary
`DirectMethodLimit`	Below this the direct methods are cheaper than the reductions, and above it they stop being practical.
`PcgMultiplier`	The multiplier used by both the state step and the output function.

XxHash64

xxHash64 over a stream of bytes, in as many writes as the caller has.

RandomGenerator

A source of uniformly distributed 64-bit words.

Edit this page on GitHub