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 | use rand_core::impls::{fill_bytes_via_next, next_u64_via_u32}; |
10 | use rand_core::le::read_u32_into; |
11 | use rand_core::{RngCore, SeedableRng}; |
12 | #[cfg (feature = "serde" )] |
13 | use serde::{Deserialize, Serialize}; |
14 | |
15 | /// A xoshiro128++ random number generator. |
16 | /// |
17 | /// The xoshiro128++ algorithm is not suitable for cryptographic purposes, but |
18 | /// is very fast and has excellent statistical properties. |
19 | /// |
20 | /// The algorithm used here is translated from [the `xoshiro128plusplus.c` |
21 | /// reference source code](http://xoshiro.di.unimi.it/xoshiro128plusplus.c) by |
22 | /// David Blackman and Sebastiano Vigna. |
23 | #[derive (Debug, Clone, PartialEq, Eq)] |
24 | #[cfg_attr (feature = "serde" , derive(Serialize, Deserialize))] |
25 | pub struct Xoshiro128PlusPlus { |
26 | s: [u32; 4], |
27 | } |
28 | |
29 | impl Xoshiro128PlusPlus { |
30 | /// Jump forward, equivalently to 2^64 calls to `next_u32()`. |
31 | /// |
32 | /// This can be used to generate 2^64 non-overlapping subsequences for |
33 | /// parallel computations. |
34 | /// |
35 | /// ``` |
36 | /// use rand_xoshiro::rand_core::SeedableRng; |
37 | /// use rand_xoshiro::Xoroshiro128PlusPlus; |
38 | /// |
39 | /// let rng1 = Xoroshiro128PlusPlus::seed_from_u64(0); |
40 | /// let mut rng2 = rng1.clone(); |
41 | /// rng2.jump(); |
42 | /// let mut rng3 = rng2.clone(); |
43 | /// rng3.jump(); |
44 | /// ``` |
45 | pub fn jump(&mut self) { |
46 | impl_jump!(u32, self, [0x8764000b, 0xf542d2d3, 0x6fa035c3, 0x77f2db5b]); |
47 | } |
48 | |
49 | /// Jump forward, equivalently to 2^96 calls to `next_u32()`. |
50 | /// |
51 | /// This can be used to generate 2^32 starting points, from each of which |
52 | /// `jump()` will generate 2^32 non-overlapping subsequences for parallel |
53 | /// distributed computations. |
54 | pub fn long_jump(&mut self) { |
55 | impl_jump!(u32, self, [0xb523952e, 0x0b6f099f, 0xccf5a0ef, 0x1c580662]); |
56 | } |
57 | } |
58 | |
59 | impl SeedableRng for Xoshiro128PlusPlus { |
60 | type Seed = [u8; 16]; |
61 | |
62 | /// Create a new `Xoshiro128PlusPlus`. If `seed` is entirely 0, it will be |
63 | /// mapped to a different seed. |
64 | #[inline ] |
65 | fn from_seed(seed: [u8; 16]) -> Xoshiro128PlusPlus { |
66 | deal_with_zero_seed!(seed, Self, 16); |
67 | let mut state: [u32; 4] = [0; 4]; |
68 | read_u32_into(&seed, &mut state); |
69 | Xoshiro128PlusPlus { s: state } |
70 | } |
71 | |
72 | /// Seed a `Xoshiro128PlusPlus` from a `u64` using `SplitMix64`. |
73 | fn seed_from_u64(seed: u64) -> Xoshiro128PlusPlus { |
74 | from_splitmix!(seed) |
75 | } |
76 | } |
77 | |
78 | impl RngCore for Xoshiro128PlusPlus { |
79 | #[inline ] |
80 | fn next_u32(&mut self) -> u32 { |
81 | let result_starstar: u32 = plusplus_u32!(self.s[0], self.s[3]); |
82 | impl_xoshiro_u32!(self); |
83 | result_starstar |
84 | } |
85 | |
86 | #[inline ] |
87 | fn next_u64(&mut self) -> u64 { |
88 | next_u64_via_u32(self) |
89 | } |
90 | |
91 | #[inline ] |
92 | fn fill_bytes(&mut self, dest: &mut [u8]) { |
93 | fill_bytes_via_next(self, dest); |
94 | } |
95 | } |
96 | |
97 | #[cfg (test)] |
98 | mod tests { |
99 | use super::*; |
100 | |
101 | #[test ] |
102 | fn reference() { |
103 | let mut rng = |
104 | Xoshiro128PlusPlus::from_seed([1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0, 4, 0, 0, 0]); |
105 | // These values were produced with the reference implementation: |
106 | // http://xoshiro.di.unimi.it/xoshiro128plusplus.c |
107 | let expected = [ |
108 | 641, 1573767, 3222811527, 3517856514, 836907274, 4247214768, 3867114732, 1355841295, |
109 | 495546011, 621204420, |
110 | ]; |
111 | for &e in &expected { |
112 | assert_eq!(rng.next_u32(), e); |
113 | } |
114 | } |
115 | |
116 | #[test ] |
117 | fn test_jump() { |
118 | let mut rng = |
119 | Xoshiro128PlusPlus::from_seed([1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0, 4, 0, 0, 0]); |
120 | rng.jump(); |
121 | // These values were produced by instrumenting the reference implementation: |
122 | // http://xoshiro.di.unimi.it/xoshiro128plus.c |
123 | assert_eq!(rng.s[0], 2843103750); |
124 | assert_eq!(rng.s[1], 2038079848); |
125 | assert_eq!(rng.s[2], 1533207345); |
126 | assert_eq!(rng.s[3], 44816753); |
127 | } |
128 | |
129 | #[test ] |
130 | fn test_long_jump() { |
131 | let mut rng = |
132 | Xoshiro128PlusPlus::from_seed([1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0, 4, 0, 0, 0]); |
133 | rng.long_jump(); |
134 | // These values were produced by instrumenting the reference implementation: |
135 | // http://xoshiro.di.unimi.it/xoshiro128plus.c |
136 | assert_eq!(rng.s[0], 1611968294); |
137 | assert_eq!(rng.s[1], 2125834322); |
138 | assert_eq!(rng.s[2], 966769569); |
139 | assert_eq!(rng.s[3], 3193880526); |
140 | } |
141 | } |
142 | |