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#[cfg(feature="serde1")] use serde::{Serialize, Deserialize};
10use rand_core::le::read_u64_into;
11use rand_core::impls::fill_bytes_via_next;
12use rand_core::{RngCore, SeedableRng};
13
14/// A xoroshiro128++ random number generator.
15///
16/// The xoroshiro128++ algorithm is not suitable for cryptographic purposes, but
17/// is very fast and has excellent statistical properties.
18///
19/// The algorithm used here is translated from [the `xoroshiro128plusplus.c`
20/// reference source code](http://xoshiro.di.unimi.it/xoroshiro128plusplus.c) by
21/// David Blackman and Sebastiano Vigna.
22#[allow(missing_copy_implementations)]
23#[derive(Debug, Clone, PartialEq, Eq)]
24#[cfg_attr(feature="serde1", derive(Serialize, Deserialize))]
25pub struct Xoroshiro128PlusPlus {
26 s0: u64,
27 s1: u64,
28}
29
30impl Xoroshiro128PlusPlus {
31 /// Jump forward, equivalently to 2^64 calls to `next_u64()`.
32 ///
33 /// This can be used to generate 2^64 non-overlapping subsequences for
34 /// parallel computations.
35 ///
36 /// ```
37 /// use rand_xoshiro::rand_core::SeedableRng;
38 /// use rand_xoshiro::Xoroshiro128PlusPlus;
39 ///
40 /// let rng1 = Xoroshiro128PlusPlus::seed_from_u64(0);
41 /// let mut rng2 = rng1.clone();
42 /// rng2.jump();
43 /// let mut rng3 = rng2.clone();
44 /// rng3.jump();
45 /// ```
46 pub fn jump(&mut self) {
47 impl_jump!(u64, self, [0x2bd7a6a6e99c2ddc, 0x0992ccaf6a6fca05]);
48 }
49
50 /// Jump forward, equivalently to 2^96 calls to `next_u64()`.
51 ///
52 /// This can be used to generate 2^32 starting points, from each of which
53 /// `jump()` will generate 2^32 non-overlapping subsequences for parallel
54 /// distributed computations.
55 pub fn long_jump(&mut self) {
56 impl_jump!(u64, self, [0x360fd5f2cf8d5d99, 0x9c6e6877736c46e3]);
57 }
58}
59
60impl RngCore for Xoroshiro128PlusPlus {
61 #[inline]
62 fn next_u32(&mut self) -> u32 {
63 self.next_u64() as u32
64 }
65
66 #[inline]
67 fn next_u64(&mut self) -> u64 {
68 let r: u64 = plusplus_u64!(self.s0, self.s1, 17);
69 impl_xoroshiro_u64_plusplus!(self);
70 r
71 }
72
73 #[inline]
74 fn fill_bytes(&mut self, dest: &mut [u8]) {
75 fill_bytes_via_next(self, dest);
76 }
77
78 #[inline]
79 fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), rand_core::Error> {
80 self.fill_bytes(dest);
81 Ok(())
82 }
83}
84
85impl SeedableRng for Xoroshiro128PlusPlus {
86 type Seed = [u8; 16];
87
88 /// Create a new `Xoroshiro128PlusPlus`. If `seed` is entirely 0, it will be
89 /// mapped to a different seed.
90 fn from_seed(seed: [u8; 16]) -> Xoroshiro128PlusPlus {
91 deal_with_zero_seed!(seed, Self);
92 let mut s: [u64; 2] = [0; 2];
93 read_u64_into(&seed, &mut s);
94
95 Xoroshiro128PlusPlus {
96 s0: s[0],
97 s1: s[1],
98 }
99 }
100
101 /// Seed a `Xoroshiro128PlusPlus` from a `u64` using `SplitMix64`.
102 fn seed_from_u64(seed: u64) -> Xoroshiro128PlusPlus {
103 from_splitmix!(seed)
104 }
105}
106
107#[cfg(test)]
108mod tests {
109 use super::*;
110
111 #[test]
112 fn reference() {
113 let mut rng = Xoroshiro128PlusPlus::from_seed(
114 [1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0]);
115 // These values were produced with the reference implementation:
116 // http://xoshiro.di.unimi.it/xoshiro128plusplus.c
117 let expected = [
118 393217, 669327710093319, 1732421326133921491, 11394790081659126983,
119 9555452776773192676, 3586421180005889563, 1691397964866707553,
120 10735626796753111697, 15216282715349408991, 14247243556711267923,
121 ];
122 for &e in &expected {
123 assert_eq!(rng.next_u64(), e);
124 }
125 }
126}
127