rand_xoshiro/
lib.rs

1// Copyright 2018-2023 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//! performance and a small state and supersede the previous xorshift-based
12//! generators. However, they are not 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//!   family 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 similarly to the `*StarStar` generators.
65//! See the [xoshiro paper], where the differences are discussed in detail.
66//!
67//! # Example
68//!
69//! To initialize a generator, use the [`SeedableRng`][rand_core::SeedableRng] trait:
70//!
71//! ```
72//! use rand_core::{SeedableRng, RngCore};
73//! use rand_xoshiro::Xoshiro256PlusPlus;
74//!
75//! let mut rng = Xoshiro256PlusPlus::seed_from_u64(0);
76//! let x = rng.next_u64();
77//! ```
78//!
79//! [xoshiro]: http://xoshiro.di.unimi.it/
80//! [xoshiro paper]: http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf
81//! [low linear complexity]: http://xoshiro.di.unimi.it/lowcomp.php
82
83#![doc(
84    html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
85    html_favicon_url = "https://www.rust-lang.org/favicon.ico",
86    html_root_url = "https://docs.rs/rand_xoshiro/0.7.0"
87)]
88#![forbid(unsafe_code)]
89#![deny(missing_docs)]
90#![deny(missing_debug_implementations)]
91#![allow(clippy::unreadable_literal)]
92#![no_std]
93
94#[macro_use]
95mod common;
96mod splitmix64;
97mod xoroshiro128plus;
98mod xoroshiro128plusplus;
99mod xoroshiro128starstar;
100mod xoroshiro64star;
101mod xoroshiro64starstar;
102mod xoshiro128plus;
103mod xoshiro128plusplus;
104mod xoshiro128starstar;
105mod xoshiro256plus;
106mod xoshiro256plusplus;
107mod xoshiro256starstar;
108mod xoshiro512plus;
109mod xoshiro512plusplus;
110mod xoshiro512starstar;
111
112pub use common::Seed512;
113pub use rand_core;
114pub use splitmix64::SplitMix64;
115pub use xoroshiro128plus::Xoroshiro128Plus;
116pub use xoroshiro128plusplus::Xoroshiro128PlusPlus;
117pub use xoroshiro128starstar::Xoroshiro128StarStar;
118pub use xoroshiro64star::Xoroshiro64Star;
119pub use xoroshiro64starstar::Xoroshiro64StarStar;
120pub use xoshiro128plus::Xoshiro128Plus;
121pub use xoshiro128plusplus::Xoshiro128PlusPlus;
122pub use xoshiro128starstar::Xoshiro128StarStar;
123pub use xoshiro256plus::Xoshiro256Plus;
124pub use xoshiro256plusplus::Xoshiro256PlusPlus;
125pub use xoshiro256starstar::Xoshiro256StarStar;
126pub use xoshiro512plus::Xoshiro512Plus;
127pub use xoshiro512plusplus::Xoshiro512PlusPlus;
128pub use xoshiro512starstar::Xoshiro512StarStar;
rand_xoshiro/lib.rs

rand_xoshiro/
lib.rs
