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 `xoroshiro128starstar.c`
20/// reference source code](http://xoshiro.di.unimi.it/xoroshiro128starstar.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 Xoroshiro128StarStar {
26 s0: u64,
27 s1: u64,
28}
29
30impl Xoroshiro128StarStar {
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::Xoroshiro128StarStar;
39 ///
40 /// let rng1 = Xoroshiro128StarStar::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, [0xdf900294d8f554a5, 0x170865df4b3201fc]);
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, [0xd2a98b26625eee7b, 0xdddf9b1090aa7ac1]);
57 }
58}
59
60impl RngCore for Xoroshiro128StarStar {
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 = starstar_u64!(self.s0);
69 impl_xoroshiro_u64!(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 Xoroshiro128StarStar {
86 type Seed = [u8; 16];
87
88 /// Create a new `Xoroshiro128StarStar`. If `seed` is entirely 0, it will be
89 /// mapped to a different seed.
90 fn from_seed(seed: [u8; 16]) -> Xoroshiro128StarStar {
91 deal_with_zero_seed!(seed, Self);
92 let mut s: [u64; 2] = [0; 2];
93 read_u64_into(&seed, &mut s);
94
95 Xoroshiro128StarStar {
96 s0: s[0],
97 s1: s[1],
98 }
99 }
100
101 /// Seed a `Xoroshiro128StarStar` from a `u64` using `SplitMix64`.
102 fn seed_from_u64(seed: u64) -> Xoroshiro128StarStar {
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 = Xoroshiro128StarStar::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/xoshiro128starstar.c
117 let expected = [
118 5760, 97769243520, 9706862127477703552, 9223447511460779954,
119 8358291023205304566, 15695619998649302768, 8517900938696309774,
120 16586480348202605369, 6959129367028440372, 16822147227405758281,
121 ];
122 for &e in &expected {
123 assert_eq!(rng.next_u64(), e);
124 }
125 }
126}
127