rand_xoshiro/
lib.rs

Help
1// Copyright 2018 Developers of the Rand project.
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9//! This crate implements the [xoshiro] family of pseudorandom number generators
10//! designed by David Blackman and Sebastiano Vigna. They feature high
11//! perfomance and a small state and superseed the previous xorshift-based
12//! generators. However, they are no cryptographically secure and their output
13//! can be predicted by observing a few samples.
14//!
15//! The following generators are implemented:
16//!
17//! # 64-bit generators
18//! - [`Xoshiro256StarStar`]: Recommended for all purposes. Excellent speed and
19//!   a state space (256 bits) large enough for any parallel application.
20//! - [`Xoshiro256Plus`]: Recommended for generating 64-bit floating-point
21//!   numbers. About 15% faster than `Xoshiro256StarStar`, but has a [low linear
22//!   complexity] in the lowest bits (which are discarded when generating
23//!   floats), making it fail linearity tests. This is unlikely to have any
24//!   impact in practise.
25//! - [`Xoroshiro128StarStar`]: An alternative to `Xoshiro256StarStar`, having
26//!   the same speed but using half the state. Only suited for low-scale parallel
27//!   applications.
28//! - [`Xoroshiro128Plus`]: An alternative to `Xoshiro256Plus`, having the same
29//!   speed but using half the state. Only suited for low-scale parallel
30//!   applications. Has a [low linear complexity] in the lowest bits (which are
31//!   discarded when generating floats), making it fail linearity tests. This is
32//!   unlikely to have any impact in practise.
33//! - [`Xoshiro512StarStar`]: An alternative to `Xoshiro256StarStar` with more
34//!   state and the same speed.
35//! - [`Xoshiro512Plus`]: An alternative to `Xoshiro512Plus` with more
36//!   state and the same speed. Has a [low linear complexity] in the lowest bits
37//!   (which are discarded when generating floats), making it fail linearity
38//!   tests. This is unlikely to have any impact in practise.
39//! - [`SplitMix64`]: Recommended for initializing generators of the xoshiro
40//!   familiy from a 64-bit seed. Used for implementing `seed_from_u64`.
41//!
42//! # 32-bit generators
43//! - [`Xoshiro128StarStar`]: Recommended for all purposes. Excellent speed.
44//! - [`Xoshiro128Plus`]: Recommended for generating 32-bit floating-point
45//!   numbers. Faster than `Xoshiro128StarStar`, but has a [low linear
46//!   complexity] in the lowest bits (which are discarded when generating
47//!   floats), making it fail linearity tests. This is unlikely to have any
48//!   impact in practise.
49//! - [`Xoroshiro64StarStar`]: An alternative to `Xoshiro128StarStar`, having
50//!   the same speed but using half the state.
51//! - [`Xoroshiro64Star`]: An alternative to `Xoshiro128Plus`, having the
52//!   same speed but using half the state. Has a [low linear complexity] in the
53//!   lowest bits (which are discarded when generating floats), making it fail
54//!   linearity tests. This is unlikely to have any impact in practise.
55//!
56//! [xoshiro]: http://xoshiro.di.unimi.it/
57//! [low linear complexity]: http://xoshiro.di.unimi.it/lowcomp.php
58//! [`Xoshiro256StarStar`]: ./struct.Xoshiro256StarStar.html
59//! [`Xoshiro256Plus`]: ./struct.Xoshiro256Plus.html
60//! [`Xoroshiro128StarStar`]: ./struct.Xoroshiro128StarStar.html
61//! [`Xoroshiro128Plus`]: ./struct.Xoroshiro128Plus.html
62//! [`Xoshiro512StarStar`]: ./struct.Xoshiro512StarStar.html
63//! [`Xoshiro512Plus`]: ./struct.Xoshiro512Plus.html
64//! [`SplitMix64`]: ./struct.SplitMix64.html
65//! [`Xoshiro128StarStar`]: ./struct.Xoshiro128StarStar.html
66//! [`Xoshiro128Plus`]: ./struct.Xoshiro128Plus.html
67//! [`Xoroshiro64StarStar`]: ./struct.Xoroshiro64StarStar.html
68//! [`Xoroshiro64Star`]: ./struct.Xoroshiro64Star.html
69
70#![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
71       html_favicon_url = "https://www.rust-lang.org/favicon.ico",
72       html_root_url = "https://docs.rs/rand_xoshiro/0.1.0")]
73
74#![deny(missing_docs)]
75#![deny(missing_debug_implementations)]
76#![cfg_attr(feature = "cargo-clippy", allow(unreadable_literal))]
77#![no_std]
78extern crate byteorder;
79extern crate rand_core;
80
81#[macro_use]
82mod common;
83mod splitmix64;
84mod xoshiro128starstar;
85mod xoshiro128plus;
86mod xoshiro256starstar;
87mod xoshiro256plus;
88mod xoshiro512starstar;
89mod xoshiro512plus;
90mod xoroshiro128plus;
91mod xoroshiro128starstar;
92mod xoroshiro64starstar;
93mod xoroshiro64star;
94
95pub use splitmix64::SplitMix64;
96pub use xoshiro128starstar::Xoshiro128StarStar;
97pub use xoshiro128plus::Xoshiro128Plus;
98pub use xoshiro256starstar::Xoshiro256StarStar;
99pub use xoshiro256plus::Xoshiro256Plus;
100pub use common::Seed512;
101pub use xoshiro512starstar::Xoshiro512StarStar;
102pub use xoshiro512plus::Xoshiro512Plus;
103pub use xoroshiro128plus::Xoroshiro128Plus;
104pub use xoroshiro128starstar::Xoroshiro128StarStar;
105pub use xoroshiro64starstar::Xoroshiro64StarStar;
106pub use xoroshiro64star::Xoroshiro64Star;
rand_xoshiro/lib.rs

rand_xoshiro/
lib.rs
