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 //! - [`Xoshiro256PlusPlus`]: Recommended for all purposes. Excellent speed and 21 //! a state space (256 bits) large enough for any parallel application. 22 //! - [`Xoshiro256Plus`]: Recommended for generating 64-bit floating-point 23 //! numbers. About 15% faster than `Xoshiro256StarStar`, but has a [low linear 24 //! complexity] in the lowest bits (which are discarded when generating 25 //! floats), making it fail linearity tests. This is unlikely to have any 26 //! impact in practise. 27 //! - [`Xoroshiro128StarStar`]: An alternative to `Xoshiro256StarStar`, having 28 //! the same speed but using half the state. Only suited for low-scale parallel 29 //! applications. 30 //! - [`Xoroshiro128PlusPlus`]: An alternative to `Xoshiro256PlusPlus`, having 31 //! the same speed but using half the state. Only suited for low-scale parallel 32 //! applications. 33 //! - [`Xoroshiro128Plus`]: An alternative to `Xoshiro256Plus`, having the same 34 //! speed but using half the state. Only suited for low-scale parallel 35 //! applications. Has a [low linear complexity] in the lowest bits (which are 36 //! discarded when generating floats), making it fail linearity tests. This is 37 //! unlikely to have any impact in practise. 38 //! - [`Xoshiro512StarStar`]: An alternative to `Xoshiro256StarStar` with more 39 //! state and the same speed. 40 //! - [`Xoshiro512PlusPlus`]: An alternative to `Xoshiro256PlusPlus` with more 41 //! state and the same speed. 42 //! - [`Xoshiro512Plus`]: An alternative to `Xoshiro512Plus` with more 43 //! state and the same speed. Has a [low linear complexity] in the lowest bits 44 //! (which are discarded when generating floats), making it fail linearity 45 //! tests. This is unlikely to have any impact in practise. 46 //! - [`SplitMix64`]: Recommended for initializing generators of the xoshiro 47 //! familiy from a 64-bit seed. Used for implementing `seed_from_u64`. 48 //! 49 //! # 32-bit generators 50 //! - [`Xoshiro128StarStar`]: Recommended for all purposes. Excellent speed. 51 //! - [`Xoshiro128PlusPlus`]: Recommended for all purposes. Excellent speed. 52 //! - [`Xoshiro128Plus`]: Recommended for generating 32-bit floating-point 53 //! numbers. Faster than `Xoshiro128StarStar`, but has a [low linear 54 //! complexity] in the lowest bits (which are discarded when generating 55 //! floats), making it fail linearity tests. This is unlikely to have any 56 //! impact in practise. 57 //! - [`Xoroshiro64StarStar`]: An alternative to `Xoshiro128StarStar`, having 58 //! the same speed but using half the state. 59 //! - [`Xoroshiro64Star`]: An alternative to `Xoshiro128Plus`, having the 60 //! same speed but using half the state. Has a [low linear complexity] in the 61 //! lowest bits (which are discarded when generating floats), making it fail 62 //! linearity tests. This is unlikely to have any impact in practise. 63 //! 64 //! The `*PlusPlus` generators perform similarily to the `*StarStar` generators. 65 //! See the [xoshiro paper], where the differences are discussed in detail. 66 //! 67 //! [xoshiro]: http://xoshiro.di.unimi.it/ 68 //! [xoshiro paper]: http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf 69 //! [low linear complexity]: http://xoshiro.di.unimi.it/lowcomp.php 70 71 #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png", 72 html_favicon_url = "https://www.rust-lang.org/favicon.ico", 73 html_root_url = "https://docs.rs/rand_xoshiro/0.4.0")] 74 75 #![deny(missing_docs)] 76 #![deny(missing_debug_implementations)] 77 #![allow(clippy::unreadable_literal)] 78 #![no_std] 79 80 #[macro_use] 81 mod common; 82 mod splitmix64; 83 mod xoshiro128starstar; 84 mod xoshiro128plusplus; 85 mod xoshiro128plus; 86 mod xoshiro256starstar; 87 mod xoshiro256plusplus; 88 mod xoshiro256plus; 89 mod xoshiro512starstar; 90 mod xoshiro512plusplus; 91 mod xoshiro512plus; 92 mod xoroshiro128plus; 93 mod xoroshiro128plusplus; 94 mod xoroshiro128starstar; 95 mod xoroshiro64starstar; 96 mod xoroshiro64star; 97 98 pub use rand_core; 99 pub use splitmix64::SplitMix64; 100 pub use xoshiro128starstar::Xoshiro128StarStar; 101 pub use xoshiro128plusplus::Xoshiro128PlusPlus; 102 pub use xoshiro128plus::Xoshiro128Plus; 103 pub use xoshiro256starstar::Xoshiro256StarStar; 104 pub use xoshiro256plusplus::Xoshiro256PlusPlus; 105 pub use xoshiro256plus::Xoshiro256Plus; 106 pub use common::Seed512; 107 pub use xoshiro512starstar::Xoshiro512StarStar; 108 pub use xoshiro512plusplus::Xoshiro512PlusPlus; 109 pub use xoshiro512plus::Xoshiro512Plus; 110 pub use xoroshiro128plus::Xoroshiro128Plus; 111 pub use xoroshiro128starstar::Xoroshiro128StarStar; 112 pub use xoroshiro128plusplus::Xoroshiro128PlusPlus; 113 pub use xoroshiro64starstar::Xoroshiro64StarStar; 114 pub use xoroshiro64star::Xoroshiro64Star; 115
