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 asPcg32
but with a fixed sequence. Useful if you don’t care about having multiple streams of random numbers from the same seed.Pcg32Unique
: Same asPcg32
but the sequence is set by the memory location of the RNG This means that multiplePcg32_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.
- First is the sequence type
- Second is the permutation function
- Third is the state size in bits
- 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§
- 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 Aliases§
- A helper definition for a simple 32bit PCG which can have multiple random streams
- A helper definition for a simple 64bit 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 stream. This 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 instance. This 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 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