Crate pcg_rand

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.13.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.
  • ’DXsM`: Refers to the Double-Xorshift and Multiply output

§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, SeedableRng};
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::SeedableRng;

//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§

extension
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.
multiplier
numops
outputmix
seeds
stream

Structs§

PCGStateInfo
Pcg32Basic
A low overhead very simple PCG impementation
PcgEngine
A generic PCG structure.

Type Aliases§

McgDXsM6432
McgDXsM12832
McgDXsM12864
McgXshRr6432
McgXshRr12832
McgXshRr12864
McgXshRs6432
McgXshRs12832
McgXshRs12864
OneseqDXsM6432
OneseqDXsM12832
OneseqDXsM12864
OneseqXshRr6432
OneseqXshRr12832
OneseqXshRr12864
OneseqXshRs6432
OneseqXshRs12832
OneseqXshRs12864
Pcg32
A helper definition for a simple 32bit PCG which can have multiple random streams
Pcg64
A helper definition for a simple 64bit PCG which can have multiple random streams
Pcg32Fast
A helper definition for a 32bit PCG which is fast but may lack statistical quality.
Pcg32L
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)
Pcg32LFast
A helper definition for a 32bit PCG which is fast but may lack statistical quality.
Pcg32LOneseq
A helper definition for a 32bit PCG which hase a fixed good random stream. This version uses 128bits of internal state This makes it potentially slower but it has a longer period.
Pcg32LUnique
A helper definition for a 32bit PCG which has a unique random stream for each instance. This version uses 128bits of internal state This makes it potentially slower but it has a longer period.
Pcg32Oneseq
A helper definition for a 32bit PCG which hase a fixed good random stream
Pcg32Unique
A helper definition for a 32bit PCG which has a unique random stream for each instance
Pcg64Fast
A helper definition for a 64bit PCG which is fast but may lack statistical quality.
Pcg64Oneseq
A helper definition for a 64bit PCG which hase a fixed good random stream
Pcg64Unique
A helper definition for a 64bit PCG which has a unique random stream for each instance
SetseqDXsM6432
SetseqDXsM12832
SetseqDXsM12864
SetseqXshRr6432
SetseqXshRr12832
SetseqXshRr12864
SetseqXshRs6432
SetseqXshRs12832
SetseqXshRs12864
UniqueDXsM6432
UniqueDXsM12832
UniqueDXsM12864
UniqueXshRr6432
UniqueXshRr12832
UniqueXshRr12864
UniqueXshRs6432
UniqueXshRs12832
UniqueXshRs12864