pub use guise_choice::{seed_from_u64, seeded_rng, Seed};
use rand::Rng;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct RngSeed {
pub bytes: Seed,
}
impl RngSeed {
#[must_use]
pub fn from_u64(seed: u64) -> Self {
Self {
bytes: seed_from_u64(seed),
}
}
#[must_use]
pub const fn from_bytes(bytes: Seed) -> Self {
Self { bytes }
}
#[must_use]
pub fn derive(&self, label: &str) -> Self {
let mut state = u64::from_le_bytes([
self.bytes[0],
self.bytes[1],
self.bytes[2],
self.bytes[3],
self.bytes[4],
self.bytes[5],
self.bytes[6],
self.bytes[7],
]);
for byte in label.bytes() {
state = splitmix64(state.wrapping_add(u64::from(byte)));
}
let mut bytes = [0u8; 32];
for chunk in bytes.chunks_mut(8) {
state = splitmix64(state);
chunk.copy_from_slice(&state.to_le_bytes());
}
Self { bytes }
}
}
fn splitmix64(mut x: u64) -> u64 {
x = x.wrapping_add(0x9e3779b97f4a7c15);
let mut z = x;
z = (z ^ (z >> 30)).wrapping_mul(0xbf58476d1ce4e5b9);
z = (z ^ (z >> 27)).wrapping_mul(0x94d049bb133111eb);
z ^ (z >> 31)
}
#[cfg_attr(not(feature = "browser"), allow(dead_code))]
pub(crate) const HUMAN_TIMING_CV_FLOOR: f64 = 0.1;
#[cfg_attr(not(feature = "browser"), allow(dead_code))]
pub(crate) const CV_DRIFT_FLOOR: f64 = 0.03;
#[cfg_attr(not(feature = "human"), allow(dead_code))]
pub(crate) fn standard_normal<R: Rng + ?Sized>(rng: &mut R) -> f64 {
let u1: f64 = rng.gen::<f64>().max(1e-12);
let u2: f64 = rng.gen::<f64>();
(-2.0 * u1.ln()).sqrt() * (std::f64::consts::TAU * u2).cos()
}
#[cfg_attr(not(test), allow(dead_code))]
pub(crate) fn coefficient_of_variation(samples: &[f64]) -> Option<f64> {
if samples.len() < 2 {
return None;
}
let n = samples.len() as f64;
let mean = samples.iter().sum::<f64>() / n;
if mean <= 0.0 {
return None;
}
let variance = samples
.iter()
.map(|x| {
let d = x - mean;
d * d
})
.sum::<f64>()
/ n;
Some(variance.sqrt() / mean)
}
#[cfg(test)]
mod tests {
use super::*;
use rand::{rngs::StdRng, SeedableRng};
#[test]
fn standard_normal_is_finite_and_centered() {
let mut rng = StdRng::seed_from_u64(42);
let n = 10_000;
let samples: Vec<f64> = (0..n).map(|_| standard_normal(&mut rng)).collect();
assert!(samples.iter().all(|sample| sample.is_finite()));
let mean = samples.iter().sum::<f64>() / n as f64;
assert!(mean.abs() < 0.05, "mean too far from zero: {mean}");
let variance = samples
.iter()
.map(|sample| {
let delta = sample - mean;
delta * delta
})
.sum::<f64>()
/ n as f64;
assert!(
(0.90..=1.10).contains(&variance),
"variance should be near one, got {variance}"
);
}
#[test]
fn cv_undefined_for_degenerate_samples() {
assert_eq!(coefficient_of_variation(&[]), None, "empty has no CV");
assert_eq!(
coefficient_of_variation(&[5.0]),
None,
"single point has no CV"
);
assert_eq!(
coefficient_of_variation(&[0.0, 0.0]),
None,
"zero mean makes CV undefined"
);
}
#[test]
fn cv_zero_for_constant_stream() {
let cv = coefficient_of_variation(&[100.0, 100.0, 100.0, 100.0]).unwrap();
assert!(cv.abs() < 1e-9, "constant stream CV {cv} should be 0");
assert!(cv < HUMAN_TIMING_CV_FLOOR);
}
#[test]
fn cv_matches_hand_computed_value() {
let cv = coefficient_of_variation(&[2.0, 3.0, 4.0]).unwrap();
assert!((cv - 0.272_166).abs() < 1e-4, "CV {cv} != hand value");
assert!(
cv >= HUMAN_TIMING_CV_FLOOR,
"spread-out stream clears floor"
);
}
#[allow(clippy::assertions_on_constants)] #[test]
fn cv_drift_floor_below_human_floor() {
assert!(CV_DRIFT_FLOOR < HUMAN_TIMING_CV_FLOOR);
}
#[test]
fn rng_seed_from_u64_is_deterministic() {
let a = RngSeed::from_u64(42);
let b = RngSeed::from_u64(42);
assert_eq!(a, b);
assert_ne!(a.bytes, RngSeed::from_u64(43).bytes);
}
#[test]
fn rng_seed_derive_is_deterministic_and_label_dependent() {
let parent = RngSeed::from_u64(7);
let a = parent.derive("rotation");
let b = parent.derive("rotation");
let c = parent.derive("behavior");
assert_eq!(a, b);
assert_ne!(
a.bytes, c.bytes,
"different labels must derive different seeds"
);
}
#[test]
fn seeded_rng_from_seed_reproduces_samples() {
let seed = RngSeed::from_u64(99);
let mut rng_a = seeded_rng(&seed.bytes);
let mut rng_b = seeded_rng(&seed.bytes);
assert_eq!(rng_a.gen::<u64>(), rng_b.gen::<u64>());
}
#[test]
fn derive_produces_independent_streams() {
let parent = RngSeed::from_u64(5);
let mut rng_a = seeded_rng(&parent.derive("a").bytes);
let mut rng_b = seeded_rng(&parent.derive("b").bytes);
let samples_a: Vec<u64> = (0..64).map(|_| rng_a.gen()).collect();
let samples_b: Vec<u64> = (0..64).map(|_| rng_b.gen()).collect();
assert_ne!(samples_a, samples_b);
}
}