Crate pcg_rand

source ·
Expand description

An implementation of the PCG random family of random number generators. Details about the PCG generators can be found at pcg-random.org

Currently this library provides several PCG generators:

  • Pcg32 : 64bit LCG with an xorshift and right rotation applied to the output. To improve security only 32bits of the state are reported as output.
  • Pcg32Onseq : Same as Pcg32 but with a fixed sequence. Useful if you don’t care about having multiple streams of random numbers from the same seed.
  • Pcg32Unique : Same as Pcg32 but the sequence is set by the memory location of the RNG This means that multiple Pcg32_unique with the same seed will produce different sequences of numbers. NOTE: This means that you may not get consistant results across runs of your program. If the memory location of your PCG moves for any reason such as the state of the allocator being different you will get a different stream of numbers.

Usage

This crate is on crates.io and can be used by adding the pcg_rand crate to your projects Cargo.toml

[dependencies]
pcg_rand = "0.10.0"

#Typename Nomenclature This library attempts to simplify using the PCG generators by defining easy types for use. The following attempts to help you decode these typenames

Consider the example OneseqXshRr6432. This consists of 4 major parts.

  1. First is the sequence type
  2. Second is the permutation function
  3. Third is the state size in bits
  4. Fourth is the output size in bits

Sequence types

This library provides the following sequence types

  • Setseq: This is a settable stream. The random number stream can be set manually.
  • Unique: This is a unique stream. Each instance of this type will be given a unique stream that cannot be modified.
  • Oneseq: This is one fixed random sequence. It is hardcoded into the library and should be good enough to give good “randomness”.
  • Mcg: This has no random sequence it degenerates the internal LCG into a MCG. This is for speed.

Permutation functions

There are many possible permuation functions that this library can implement. Many of them are composed of several indiviual components. The components that are used are:

  • Xsh: Refers to a High Xorshift function.
  • Rr: Refers to a random rotation. Randomly rotates based on entropy from the state.
  • Rs: Refers to a random shift. Randomly shifts based on entropy from the state.

#How to Use The simple generators work like the other Rng’s from the rand crate. You can create a PCG as follows

extern crate pcg_rand;
extern crate rand;

use rand::{Rng, FromEntropy};
use pcg_rand::Pcg32;

fn main() {
    let mut pcg = Pcg32::from_entropy();

    let x : u32 = pcg.gen();
}

The extended generators can be built in two ways, either by creating one directly, or by building them from a generator at its current state.

extern crate pcg_rand;
extern crate rand;

use pcg_rand::{
    Pcg32Unique,
    extension::{Pcg32Ext, ExtPcg, Ext256}
};
use rand::FromEntropy;

//Create an extended generator explicitly
let ext1 = Pcg32Ext::<Ext256>::from_entropy();

//Create from another PCG
let ext2 : ExtPcg<_,_,_,_,_,Ext256> = ExtPcg::from_pcg(Pcg32Unique::from_entropy());

Modules

Extended PCG generators utilize a simple method to dramatically extend the period of the genrators. In addition to extending the period of the generator it ensures that the generators have K-dimensional equidistribution. This means that the generator will produce every possible K-tuple uniformly.

Structs

A low overhead very simple PCG impementation
A generic PCG structure.

Type Definitions

A helper definition for a simple 32bit PCG which can have multiple random streams
A helper definition for a 32bit PCG which is fast but may lack statistical quality.
A helper definition for a simple 32bit PCG which can have multiple random streams. This version uses 128bits of internal state This makes it potentially slower but it has a longer period. (In testing it appears to be better to use an extended generator Pcg32Ext to get a long period rather than the Pcg32L)
A helper definition for a 32bit PCG which is fast but may lack statistical quality.
A helper definition for a 32bit PCG which hase a fixed good random streamThis version uses 128bits of internal state This makes it potentially slower but it has a longer period.
A helper definition for a 32bit PCG which has a unique random stream for each instanceThis version uses 128bits of internal state This makes it potentially slower but it has a longer period.
A helper definition for a 32bit PCG which hase a fixed good random stream
A helper definition for a 32bit PCG which has a unique random stream for each instance
A helper definition for a simple 64bit PCG which can have multiple random streams
A helper definition for a 64bit PCG which is fast but may lack statistical quality.
A helper definition for a 64bit PCG which hase a fixed good random stream
A helper definition for a 64bit PCG which has a unique random stream for each instance