vendor/rand_xoshiro/src/xoroshiro128starstar.rs

   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};
  10 use rand_core::le::read_u64_into;
  11 use rand_core::impls::fill_bytes_via_next;
  12 use 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))]
  25 pub struct Xoroshiro128StarStar {
  26     s0: u64,
  27     s1: u64,
  28 }
  29
  30 impl 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
  60 impl 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 = 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
  85 impl 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 = [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)]
 108 mod 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 }